commit ecc0e86d46ac2db77d45d46af5ac50168befa6c9 Author: Damian Johnson atagar@torproject.org Date: Sun Jun 3 16:18:00 2012 -0700

Converting stem.version to reStructuredText --- docs/conf.py | 3 +-- docs/index.rst | 5 +++++ stem/version.py | 54 +++++++++++++++++++++++------------------------------- 3 files changed, 29 insertions(+), 33 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py index d07c0cc..a9d4b7d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -28,8 +28,7 @@ needs_sphinx = '1.1' # required for the sphinx-apidoc command # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']

-autoclass_content = 'both' -autodoc_member_order = 'groupwise' +autodoc_member_order = 'bysource' autodoc_default_flags = ['members', 'show-inheritance', 'undoc-members']

# Add any paths that contain templates here, relative to this directory. diff --git a/docs/index.rst b/docs/index.rst index 6cf06ea..c735bf6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,6 +13,11 @@ Stem is a python controller library for `Tor https://www.torproject.org/`_. Li

Used for launching Tor and managing the process.

+:mod:`stem.version` +------------------- + +Parsed versions that can be compared to the requirement for various features. + .. toctree:: :maxdepth: 2

diff --git a/stem/version.py b/stem/version.py index eb0f707..925acf0 100644 --- a/stem/version.py +++ b/stem/version.py @@ -8,14 +8,13 @@ easily parsed and compared, for instance...

...

...

my_version > stem.version.Requirement.CONTROL_SOCKET

True

-get_system_tor_version - gets the version of our system's tor installation -Version - Tor versioning information. - |- __str__ - string representation - +- __cmp__ - compares with another Version - -Requirement - Enumerations for the version requirements of features. - |- GETINFO_CONFIG_TEXT - 'GETINFO config-text' query - +- CONTROL_SOCKET - 'ControlSocket <path>' config option ++----------------------------------------------------------+ +|Requirement | ++=====================+====================================+ +|GETINFO_CONFIG_TEXT |'GETINFO config-text' query | ++---------------------+------------------------------------+ +|CONTROL_SOCKET |'ControlSocket <path>' config option| ++---------------------+------------------------------------+ """

import re @@ -31,14 +30,11 @@ def get_system_tor_version(tor_cmd = "tor"): Queries tor for its version. This is os dependent, only working on linux, osx, and bsd.

- Arguments: - tor_cmd (str) - command used to run tor + :param str tor_cmd: command used to run tor

- Returns: - stem.version.Version provided by the tor command + :returns: :class:`stem.version.Version` provided by the tor command

- Raises: - IOError if unable to query or parse the version + :raises: IOError if unable to query or parse the version """

if not tor_cmd in VERSION_CACHE: @@ -70,27 +66,23 @@ def get_system_tor_version(tor_cmd = "tor"):

class Version: """ - Comparable tor version, as per the 'new version' of the version-spec... - https://gitweb.torproject.org/torspec.git/blob/HEAD:/version-spec.txt + Comparable tor version. These are constructed from strings that conform to + the 'new' style in the `tor version-spec + https://gitweb.torproject.org/torspec.git/blob/HEAD:/version-spec.txt`_, + such as "0.1.4" or "0.2.2.23-alpha (git-7dcd105be34a4f44)". + + :var int major: major version + :var int minor: minor version + :var int micro: micro version + :var int patch: optional patch level (None if undefined) + :var str status: optional status tag without the preceding dash such as 'alpha', 'beta-dev', etc (None if undefined)

- Attributes: - major (int) - major version - minor (int) - minor version - micro (int) - micro version - patch (int) - optional patch level (None if undefined) - status (str) - optional status tag without the preceding dash such as - 'alpha', 'beta-dev', etc (None if undefined) + :param str version_str: version to be parsed + + :raises: ValueError if input isn't a valid tor version """

def __init__(self, version_str): - """ - Parses a valid tor version string, for instance "0.1.4" or - "0.2.2.23-alpha (git-7dcd105be34a4f44)". - - Raises: - ValueError if input isn't a valid tor version - """ - self.version_str = version_str m = re.match(r'^([0-9]+).([0-9]+).([0-9]+)(.[0-9]+)?(-\S*)?$', version_str)