[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
[tor-commits] [stem/master] Revised API docs for stem.descriptor.export
commit 4b528c5e75bea5892a63ed5d63d3135d46971503
Author: Damian Johnson <atagar@xxxxxxxxxxxxxx>
Date: Thu Oct 25 09:37:01 2012 -0700
Revised API docs for stem.descriptor.export
---
docs/api.rst | 1 +
docs/contents.rst | 2 ++
docs/descriptor/export.rst | 5 +++++
stem/descriptor/export.py | 25 ++++++++++++++++---------
stem/descriptor/reader.py | 18 +++++++++---------
5 files changed, 33 insertions(+), 18 deletions(-)
diff --git a/docs/api.rst b/docs/api.rst
index 0dfe441..25e870b 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -11,4 +11,5 @@ Descriptors
-----------
* `stem.descriptor.reader <descriptor/reader.html>`_ - Reads and parses descriptor files from disk.
+* `stem.descriptor.export <descriptor/export.html>`_ - Exports descriptors to other formats.
diff --git a/docs/contents.rst b/docs/contents.rst
index 7565543..c40ada6 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -8,7 +8,9 @@ Contents
download
tutorial
+ descriptor/export
descriptor/reader
+
types/exit_policy
types/version
diff --git a/docs/descriptor/export.rst b/docs/descriptor/export.rst
new file mode 100644
index 0000000..a39e777
--- /dev/null
+++ b/docs/descriptor/export.rst
@@ -0,0 +1,5 @@
+Descriptor Exporter
+===================
+
+.. automodule:: stem.descriptor.export
+
diff --git a/stem/descriptor/export.py b/stem/descriptor/export.py
index 16a148d..f000a6d 100644
--- a/stem/descriptor/export.py
+++ b/stem/descriptor/export.py
@@ -1,5 +1,12 @@
"""
-Utilities for exporting descriptors to other formats.
+Toolkit for exporting descriptors to other formats.
+
+**Module Overview:**
+
+::
+
+ export_csv - Exports descriptors to a CSV
+ export_csv_file - Writes exported CSV output to a file
"""
import csv
@@ -17,13 +24,13 @@ def export_csv(descriptors, included_fields = (), excluded_fields = (), header =
labelled with a header row. Either 'included_fields' or 'excluded_fields' can
be used for more granular control over its attributes and the order.
- :param Descriptor,list descriptors: descriptor or list of descriptors to be exported
+ :param Descriptor,list descriptors: either a :class:`~stem.descriptor.Descriptor` or list of descriptors to be exported
:param list included_fields: attributes to include in the csv
:param list excluded_fields: attributes to exclude from the csv
- :param bool header: if True then the first line will be a comma separated list of the attribute names
+ :param bool header: if **True** then the first line will be a comma separated list of the attribute names
- :returns: str of the CSV for the descriptors, one per line
- :raises: ValueError if descriptors contain more than one descriptor type
+ :returns: **str** of the CSV for the descriptors, one per line
+ :raises: **ValueError** if descriptors contain more than one descriptor type
"""
output_buffer = cStringIO.StringIO()
@@ -36,13 +43,13 @@ def export_csv_file(output_file, descriptors, included_fields = (), excluded_fie
written directly to a file.
:param file output_file: file to be written to
- :param Descriptor,list descriptors: descriptor or list of descriptors to be exported
+ :param Descriptor,list descriptors: either a :class:`~stem.descriptor.Descriptor` or list of descriptors to be exported
:param list included_fields: attributes to include in the csv
:param list excluded_fields: attributes to exclude from the csv
- :param bool header: if True then the first line will be a comma separated list of the attribute names
+ :param bool header: if **True** then the first line will be a comma separated list of the attribute names
- :returns: str of the CSV for the descriptors, one per line
- :raises: ValueError if descriptors contain more than one descriptor type
+ :returns: **str** of the CSV for the descriptors, one per line
+ :raises: **ValueError** if descriptors contain more than one descriptor type
"""
if isinstance(descriptors, stem.descriptor.Descriptor):
diff --git a/stem/descriptor/reader.py b/stem/descriptor/reader.py
index 809015a..e3d29c5 100644
--- a/stem/descriptor/reader.py
+++ b/stem/descriptor/reader.py
@@ -52,10 +52,10 @@ and picks up where it left off if ran again...
::
- load_processed_files - Loads a listing of processed files.
- save_processed_files - Saves a listing of processed files.
+ load_processed_files - Loads a listing of processed files
+ save_processed_files - Saves a listing of processed files
- DescriptorReader - Iterator for descriptor data on the local file system.
+ DescriptorReader - Iterator for descriptor data on the local file system
|- get_processed_files - provides the listing of files that we've processed
|- set_processed_files - sets our tracking of the files we have processed
|- register_skip_listener - adds a listener that's notified of skipped files
@@ -64,12 +64,12 @@ and picks up where it left off if ran again...
|- __enter__ / __exit__ - manages the descriptor reader thread in the context
+- __iter__ - iterates over descriptor data in unread files
- FileSkipped - Base exception for a file that was skipped.
- |- AlreadyRead - We've already read a file with this last modified timestamp.
- |- ParsingFailure - Contents can't be parsed as descriptor data.
- |- UnrecognizedType - File extension indicates non-descriptor data.
- +- ReadFailed - Wraps an error that was raised while reading the file.
- +- FileMissing - File does not exist.
+ FileSkipped - Base exception for a file that was skipped
+ |- AlreadyRead - We've already read a file with this last modified timestamp
+ |- ParsingFailure - Contents can't be parsed as descriptor data
+ |- UnrecognizedType - File extension indicates non-descriptor data
+ +- ReadFailed - Wraps an error that was raised while reading the file
+ +- FileMissing - File does not exist
"""
from __future__ import with_statement
_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits