commit e4014bd0e70fc3af567f6e762d585127141279e6 Author: Damian Johnson atagar@torproject.org Date: Sat Oct 27 15:21:30 2012 -0700

Revised API docs for stem.util.str_tools --- docs/api.rst | 1 + docs/contents.rst | 1 + docs/util/str_tools.rst | 5 +++++ stem/util/str_tools.py | 21 +++++++++++---------- 4 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst index 01c929d..3296228 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -27,4 +27,5 @@ Utilities * `stem.util.conf <util/conf.html>`_ - Configuration file handling. * `stem.util.connection <util/connection.html>`_ - Connection and IP related utilities. * `stem.util.enum <util/enum.html>`_ - Enumeration class. +* `stem.util.str_tools <util/str_tools.html>`_ - String utilities.

diff --git a/docs/contents.rst b/docs/contents.rst index 4cfbe21..f937e77 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -23,4 +23,5 @@ Contents util/conf util/connection util/enum + util/str_tools

diff --git a/docs/util/str_tools.rst b/docs/util/str_tools.rst new file mode 100644 index 0000000..4e15def --- /dev/null +++ b/docs/util/str_tools.rst @@ -0,0 +1,5 @@ +String Utilities +================ + +.. automodule:: stem.util.str_tools + diff --git a/stem/util/str_tools.py b/stem/util/str_tools.py index e0a6d3e..f444760 100644 --- a/stem/util/str_tools.py +++ b/stem/util/str_tools.py @@ -85,9 +85,9 @@ def get_size_label(byte_count, decimal = 0, is_long = False, is_bytes = True): :param int byte_count: number of bytes to be converted :param int decimal: number of decimal digits to be included :param bool is_long: expands units label - :param bool is_bytes: provides units in bytes if true, bits otherwise + :param bool is_bytes: provides units in bytes if **True**, bits otherwise

- :returns: str with human readable representation of the size + :returns: **str** with human readable representation of the size """

if is_bytes: return _get_label(SIZE_UNITS_BYTES, byte_count, decimal, is_long) @@ -118,7 +118,7 @@ def get_time_label(seconds, decimal = 0, is_long = False): :param int decimal: number of decimal digits to be included :param bool is_long: expands units label

- :returns: str with human readable representation of the time + :returns: **str** with human readable representation of the time """

return _get_label(TIME_UNITS, seconds, decimal, is_long) @@ -140,7 +140,7 @@ def get_time_labels(seconds, is_long = False): :param int seconds: number of seconds to be converted :param bool is_long: expands units label

- :returns: list of strings with human readable representations of the time + :returns: **list** of strings with human readable representations of the time """

time_labels = [] @@ -167,9 +167,9 @@ def get_short_time_label(seconds):

:param int seconds: number of seconds to be converted

- :returns: str with the short representation for the time + :returns: **str** with the short representation for the time

- :raises: ValueError if the input is negative + :raises: **ValueError** if the input is negative """

if seconds < 0: @@ -207,9 +207,9 @@ def parse_short_time_label(label):

:param str label: time entry to be parsed

- :returns: int with the number of seconds represented by the label + :returns: **int** with the number of seconds represented by the label

- :raises: ValueError if input is malformed + :raises: **ValueError** if input is malformed """

days, hours, minutes, seconds = '0', '0', '0', '0' @@ -240,10 +240,11 @@ def _get_label(units, count, decimal, is_long): Provides label corresponding to units of the highest significance in the provided set. This rounds down (ie, integer truncation after visible units).

- :param tuple units: type of units to be used for conversion, containing (count_per_unit, short_label, long_label) + :param tuple units: type of units to be used for conversion, containing + (count_per_unit, short_label, long_label) :param int count: number of base units being converted :param int decimal: decimal precision of label - :param bool is_long: uses the long label if true, short label otherwise + :param bool is_long: uses the long label if **True&&, short label otherwise """

# formatted string for the requested number of digits