commit 4b528c5e75bea5892a63ed5d63d3135d46971503 Author: Damian Johnson atagar@torproject.org 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