June 2012 - tor-commits - lists.torproject.org

[flashproxy/master] Catch exceptions that happen during ProxyPair connections.
by dcf＠torproject.org 06 Jun '12

06 Jun '12

commit 07dc549ef49061f153adcbc16f3e4e31643c5607 Author: David Fifield <david(a)bamsoftware.com> Date: Tue Jun 5 22:29:43 2012 -0700 Catch exceptions that happen during ProxyPair connections. --- flashproxy.js | 8 +++++++- 1 files changed, 7 insertions(+), 1 deletions(-) diff --git a/flashproxy.js b/flashproxy.js index 55aedc5..28beb29 100644 --- a/flashproxy.js +++ b/flashproxy.js @@ -437,7 +437,13 @@ function FlashProxy() { this.proxy_pairs.splice(this.proxy_pairs.indexOf(proxy_pair), 1); this.badge.proxy_end(); }.bind(this); - proxy_pair.connect(); + try { + proxy_pair.connect(); + } catch (err) { + puts("ProxyPair: exception while connecting: " + repr(err.message) + "."); + this.die(); + return; + } this.badge.proxy_begin(); };

1 0

[tor/master] use my time machine to fix a few more typos
by arma＠torproject.org 06 Jun '12

06 Jun '12

commit 0ee13dc287320c0b1aeffb0854534ee1d8b561b2 Author: Roger Dingledine <arma(a)torproject.org> Date: Wed Jun 6 00:30:25 2012 -0400 use my time machine to fix a few more typos --- ChangeLog | 10 +++++----- ReleaseNotes | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/ChangeLog b/ChangeLog index c0cf4c1..ceb26da 100644 --- a/ChangeLog +++ b/ChangeLog @@ -201,7 +201,7 @@ Changes in version 0.2.3.16-alpha - 2012-06-05 Fixes bug 5891; bugfix on 0.2.3.6-alpha. Also fixes bug 5508 in a better way. - Don't try to open non-control listeners when DisableNetwork is set. - Previousy, we'd open all listeners, then immediately close them. + Previously, we'd open all listeners, then immediately close them. Fixes bug 5604; bugfix on 0.2.3.9-alpha. - Don't abort the managed proxy protocol if the managed proxy sends us an unrecognized line; ignore it instead. Fixes bug @@ -211,7 +211,7 @@ Changes in version 0.2.3.16-alpha - 2012-06-05 - Fix a compilation issue on GNU Hurd, which doesn't have PATH_MAX. Fixes bug 5355; bugfix on 0.2.3.11-alpha. - Remove bogus definition of "_WIN32" from src/win32/orconfig.h, to - unbreak the MSVC build. Fies bug 5858; bugfix on 0.2.3.12-alpha. + unbreak the MSVC build. Fixes bug 5858; bugfix on 0.2.3.12-alpha. - Resolve numerous small warnings and build issues with MSVC. Resolves bug 5859. @@ -268,7 +268,7 @@ Changes in version 0.2.2.36 - 2012-05-24 - Provide controllers with a safer way to implement the cookie authentication mechanism. With the old method, if another locally running program could convince a controller that it was the Tor - process, then that program could trick the contoller into telling + process, then that program could trick the controller into telling it the contents of an arbitrary 32-byte file. The new "SAFECOOKIE" authentication method uses a challenge-response approach to prevent this attack. Fixes bug 5185; implements proposal 193. @@ -397,7 +397,7 @@ Changes in version 0.2.3.15-alpha - 2012-04-30 - When Tor is built with kernel headers from a recent (last few years) Linux kernel, do not fail to run on older (pre-2.6.28 Linux kernels). Fixes bug 5112; bugfix on 0.2.3.1-alpha. - - Fix cross-compilation isssues with mingw. Bugfixes on 0.2.3.6-alpha + - Fix cross-compilation issues with mingw. Bugfixes on 0.2.3.6-alpha and 0.2.3.12-alpha. - Fix compilation with miniupnpc version 1.6; patch from Anthony G. Basile. Fixes bug 5434; bugfix on 0.2.3.12-alpha. @@ -539,7 +539,7 @@ Changes in version 0.2.3.13-alpha - 2012-03-26 - Provide controllers with a safer way to implement the cookie authentication mechanism. With the old method, if another locally running program could convince a controller that it was the Tor - process, then that program could trick the contoller into telling + process, then that program could trick the controller into telling it the contents of an arbitrary 32-byte file. The new "SAFECOOKIE" authentication method uses a challenge-response approach to prevent this attack. Fixes bug 5185, implements proposal 193. diff --git a/ReleaseNotes b/ReleaseNotes index 98f8034..563f94d 100644 --- a/ReleaseNotes +++ b/ReleaseNotes @@ -42,7 +42,7 @@ Changes in version 0.2.2.36 - 2012-05-24 - Provide controllers with a safer way to implement the cookie authentication mechanism. With the old method, if another locally running program could convince a controller that it was the Tor - process, then that program could trick the contoller into telling + process, then that program could trick the controller into telling it the contents of an arbitrary 32-byte file. The new "SAFECOOKIE" authentication method uses a challenge-response approach to prevent this attack. Fixes bug 5185; implements proposal 193.

1 0

[stem/master] Ignoring sphinx build output
by atagar＠torproject.org 06 Jun '12

06 Jun '12

commit ff5257f2e848ed84fa3e8e23b60149d464262c0e Author: Damian Johnson <atagar(a)torproject.org> Date: Thu May 31 10:01:30 2012 -0700 Ignoring sphinx build output Build artifacts from sphinx are placed in 'docs/_build/*', so having git ignore it. --- .gitignore | 1 + 1 files changed, 1 insertions(+), 0 deletions(-) diff --git a/.gitignore b/.gitignore index 124fb16..f74e628 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ *.pyc *.swp test/data/ +docs/_build/

1 0

[stem/master] Adding basic stem intro to sphinx index
by atagar＠torproject.org 06 Jun '12

06 Jun '12

commit af83350dcf62f819d8e84c6e34051dc3ff509add Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Jun 2 13:35:12 2012 -0700 Adding basic stem intro to sphinx index --- docs/index.rst | 6 ++++-- stem/__init__.py | 2 -- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 8434a81..3141b2e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,8 +3,10 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to Stem's documentation! -================================ +Welcome to Stem! +================ + +Stem is a python controller library for `Tor <https://www.torproject.org/>`_. Like its predecessor, `TorCtl <https://www.torproject.org/getinvolved/volunteer.html.en#project-torctl>`_, it uses Tor's `control protocol <https://gitweb.torproject.org/torspec.git/blob/HEAD:/control-spec.txt>`_ to help developers program against the Tor process, enabling them to build things similar to `Vidalia <https://www.torproject.org/getinvolved/volunteer.html.en#project-vidalia>`_ and `arm <http://www.atagar.com/arm/>`_. Contents: diff --git a/stem/__init__.py b/stem/__init__.py index 152a7df..61374a6 100644 --- a/stem/__init__.py +++ b/stem/__init__.py @@ -10,5 +10,3 @@ __license__ = 'LGPLv3' __all__ = ["descriptor", "response", "util", "connection", "control", "process", "socket", "version"] - -

1 0

[stem/master] Configuring sphinx documentation attributes
by atagar＠torproject.org 06 Jun '12

06 Jun '12

commit bad7ae65902f648c3127de66a35a95223b6582a6 Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Jun 2 11:41:54 2012 -0700 Configuring sphinx documentation attributes Setting attributes and toggling attributes for the autogenerated sphinx documentation. This seems like a pretty slick tool, though I'm still puzzling out how to make it index all of stem. It seems to only register modules that I explicitely tell it about - I'm probably missing something... Also still deciding between the default and haiku themes. Ruled out the others. --- docs/conf.py | 22 +++++++++++++--------- 1 files changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 1a4ab26..84ee9ed 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -16,7 +16,8 @@ import sys, os # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) + +sys.path.insert(0, os.path.abspath('..')) # -- General configuration ----------------------------------------------------- @@ -39,18 +40,20 @@ source_suffix = '.rst' # The master toctree document. master_doc = 'index' +from stem import __version__, __author__, __contact__ + # General information about the project. project = u'Stem' -copyright = u'2012, Damian Johnson' +copyright = u'2012, %s' % __author__ # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '0.0' +version = __version__[:__version__.rfind(".")] # The full version, including alpha/beta/rc tags. -release = '0.0.1' +release = __version__ # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -92,6 +95,7 @@ pygments_style = 'sphinx' # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. html_theme = 'default' +#html_theme = 'haiku' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -106,7 +110,7 @@ html_theme = 'default' #html_title = None # A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None +html_short_title = 'Stem Docs' # The name of an image file (relative to this directory) to place at the top # of the sidebar. @@ -147,13 +151,13 @@ html_static_path = ['_static'] #html_split_index = False # If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True +html_show_sourcelink = False # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True +html_show_sphinx = False # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True +html_show_copyright = False # If true, an OpenSearch description file will be output, and all pages will # contain a <link> tag referring to it. The value of this option must be the @@ -212,5 +216,5 @@ latex_documents = [ # (source start file, name, description, authors, manual section). man_pages = [ ('index', 'stem', u'Stem Documentation', - [u'Damian Johnson'], 1) + ['%s (%s)' % (__author__, __contact__)], 1) ]

1 0

[stem/master] Skip recreating unchanged docs
by atagar＠torproject.org 06 Jun '12

06 Jun '12

commit a3a7b2055144ae4ccb06e464510df211fc4fb43a Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Jun 2 19:19:24 2012 -0700 Skip recreating unchanged docs Greatly decreasing the time it takes to generate documentation when pydocs haven't changed. Sphinx is smart enough to avoid running against files whos last-modified timestamp hasn't changed, but not smart enough to check the hash of the content. Hence using rsync to avoid modifying our pydoc derived content unless the pydocs have changed. --- docs/Makefile | 5 +++-- 1 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 2c2cc2e..b868f11 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -37,8 +37,9 @@ clean: -rm -rf $(BUILDDIR)/* html: - @rm -f ./stem.* ./modules.rst - @sphinx-apidoc -o . ../stem + @rm -rf /tmp/stem_docs + @sphinx-apidoc -o /tmp/stem_docs ../stem + @rsync --size-only /tmp/stem_docs/* . $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

1 0

[stem/master] Removing autogenerated rst files via clean target
by atagar＠torproject.org 06 Jun '12

06 Jun '12

commit 241359c043c3ffb2d2d15d24cacad6c9d7fd0ae7 Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Jun 3 13:13:49 2012 -0700 Removing autogenerated rst files via clean target The html target creates some rst files, so removing them when 'make clean' is ran. --- docs/Makefile | 4 ++-- 1 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index b868f11..22f3516 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -35,10 +35,10 @@ help: clean: -rm -rf $(BUILDDIR)/* + @rm -f ./stem.* ./modules.rst html: - @rm -rf /tmp/stem_docs - @sphinx-apidoc -o /tmp/stem_docs ../stem + @sphinx-apidoc -f -o /tmp/stem_docs ../stem @rsync --size-only /tmp/stem_docs/* . $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo

1 0

[stem/master] Generating sphinx docs for all stem modules
by atagar＠torproject.org 06 Jun '12

06 Jun '12

commit 58566d6b2e20899c82206dba50d2aebfa008a96c Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Jun 2 18:55:25 2012 -0700 Generating sphinx docs for all stem modules Using the sphinx-apidoc command to generate documentation for all stem modules. I'm doing this via the make file to simplify the documentation creation process (you still just need to run 'make html'). Also removing the windows make.bat file since I'm not gonna be keeping it up to date. We can resurrect it if someone volunteers to maintain it. --- .gitignore | 2 + docs/Makefile | 2 + docs/conf.py | 2 +- docs/make.bat | 155 --------------------------------------------------------- 4 files changed, 5 insertions(+), 156 deletions(-) diff --git a/.gitignore b/.gitignore index f74e628..c05eb6d 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,6 @@ *.swp test/data/ docs/_build/ +docs/stem.* +docs/modules.rst diff --git a/docs/Makefile b/docs/Makefile index 9c6e6d3..2c2cc2e 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -37,6 +37,8 @@ clean: -rm -rf $(BUILDDIR)/* html: + @rm -f ./stem.* ./modules.rst + @sphinx-apidoc -o . ../stem $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." diff --git a/docs/conf.py b/docs/conf.py index 84ee9ed..c7510c1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -22,7 +22,7 @@ sys.path.insert(0, os.path.abspath('..')) # -- General configuration ----------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' +needs_sphinx = '1.1' # required for the sphinx-apidoc command # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 22e89e2..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,155 +0,0 @@ -@ECHO OFF - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set BUILDDIR=_build -set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . -if NOT "%PAPER%" == "" ( - set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% -) - -if "%1" == "" goto help - -if "%1" == "help" ( - :help - echo.Please use `make ^<target^>` where ^<target^> is one of - echo. html to make standalone HTML files - echo. dirhtml to make HTML files named index.html in directories - echo. singlehtml to make a single large HTML file - echo. pickle to make pickle files - echo. json to make JSON files - echo. htmlhelp to make HTML files and a HTML help project - echo. qthelp to make HTML files and a qthelp project - echo. devhelp to make HTML files and a Devhelp project - echo. epub to make an epub - echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter - echo. text to make text files - echo. man to make manual pages - echo. changes to make an overview over all changed/added/deprecated items - echo. linkcheck to check all external links for integrity - echo. doctest to run all doctests embedded in the documentation if enabled - goto end -) - -if "%1" == "clean" ( - for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i - del /q /s %BUILDDIR%\* - goto end -) - -if "%1" == "html" ( - %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/html. - goto end -) - -if "%1" == "dirhtml" ( - %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. - goto end -) - -if "%1" == "singlehtml" ( - %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. - goto end -) - -if "%1" == "pickle" ( - %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle - echo. - echo.Build finished; now you can process the pickle files. - goto end -) - -if "%1" == "json" ( - %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json - echo. - echo.Build finished; now you can process the JSON files. - goto end -) - -if "%1" == "htmlhelp" ( - %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp - echo. - echo.Build finished; now you can run HTML Help Workshop with the ^ -.hhp project file in %BUILDDIR%/htmlhelp. - goto end -) - -if "%1" == "qthelp" ( - %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp - echo. - echo.Build finished; now you can run "qcollectiongenerator" with the ^ -.qhcp project file in %BUILDDIR%/qthelp, like this: - echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Stem.qhcp - echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Stem.ghc - goto end -) - -if "%1" == "devhelp" ( - %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp - echo. - echo.Build finished. - goto end -) - -if "%1" == "epub" ( - %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub - echo. - echo.Build finished. The epub file is in %BUILDDIR%/epub. - goto end -) - -if "%1" == "latex" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - echo. - echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "text" ( - %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text - echo. - echo.Build finished. The text files are in %BUILDDIR%/text. - goto end -) - -if "%1" == "man" ( - %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man - echo. - echo.Build finished. The manual pages are in %BUILDDIR%/man. - goto end -) - -if "%1" == "changes" ( - %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes - echo. - echo.The overview file is in %BUILDDIR%/changes. - goto end -) - -if "%1" == "linkcheck" ( - %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck - echo. - echo.Link check complete; look for any errors in the above output ^ -or in %BUILDDIR%/linkcheck/output.txt. - goto end -) - -if "%1" == "doctest" ( - %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest - echo. - echo.Testing of doctests in the sources finished, look at the ^ -results in %BUILDDIR%/doctest/output.txt. - goto end -) - -:end

1 0

[stem/master] Converting stem.process to reStructuredText
by atagar＠torproject.org 06 Jun '12

06 Jun '12

commit 6651e8304a3cee2ffed344371c830a6014853201 Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Jun 3 15:38:38 2012 -0700 Converting stem.process to reStructuredText --- docs/conf.py | 4 +++ docs/index.rst | 7 ++++- stem/process.py | 72 +++++++++++++++++++++--------------------------------- 3 files changed, 38 insertions(+), 45 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index c7510c1..d07c0cc 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -28,6 +28,10 @@ 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_default_flags = ['members', 'show-inheritance', 'undoc-members'] + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/docs/index.rst b/docs/index.rst index 3141b2e..6cf06ea 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,7 +8,10 @@ Welcome to Stem! Stem is a python controller library for `Tor <https://www.torproject.org/>`_. Like its predecessor, `TorCtl <https://www.torproject.org/getinvolved/volunteer.html.en#project-torctl>`_, it uses Tor's `control protocol <https://gitweb.torproject.org/torspec.git/blob/HEAD:/control-spec.txt>`_ to help developers program against the Tor process, enabling them to build things similar to `Vidalia <https://www.torproject.org/getinvolved/volunteer.html.en#project-vidalia>`_ and `arm <http://www.atagar.com/arm/>`_. -Contents: +:mod:`stem.process` +------------------- + +Used for launching Tor and managing the process. .. toctree:: :maxdepth: 2 @@ -20,3 +23,5 @@ Indices and tables * :ref:`modindex` * :ref:`search` +*Last updated:* |today| + diff --git a/stem/process.py b/stem/process.py index e004faf..0224e3e 100644 --- a/stem/process.py +++ b/stem/process.py @@ -1,8 +1,11 @@ """ Helper functions for working with tor as a process. -launch_tor - starts up a tor process -launch_tor_with_config - starts a tor process with a custom torrc +:NO_TORRC: + when provided as a torrc_path tor is ran with a blank configuration + +:DEFAULT_INIT_TIMEOUT: + number of seconds before we time out our attempt to start a tor instance """ import re @@ -13,13 +16,8 @@ import subprocess import stem.util.system -# number of seconds before we time out our attempt to start a tor instance -DEFAULT_INIT_TIMEOUT = 90 - -# special parameter that can be set for the torrc_path to run with a blank -# configuration - NO_TORRC = "<no torrc>" +DEFAULT_INIT_TIMEOUT = 90 def launch_tor(tor_cmd = "tor", args = None, torrc_path = None, completion_percent = 100, init_msg_handler = None, timeout = DEFAULT_INIT_TIMEOUT): """ @@ -31,26 +29,19 @@ def launch_tor(tor_cmd = "tor", args = None, torrc_path = None, completion_perce while. Usually this is done in 50 seconds or so, but occasionally calls seem to get stuck, taking well over the default timeout. - Our timeout argument does not work on Windows... - https://trac.torproject.org/projects/tor/ticket/5783 - - Arguments: - tor_cmd (str) - command for starting tor - args (list) - additional arguments for tor - torrc_path (str) - location of the torrc for us to use - completion_percent (int) - percent of bootstrap completion at which - this'll return - init_msg_handler (functor) - optional functor that will be provided with - tor's initialization stdout as we get it - timeout (int) - time after which the attempt to start tor is - aborted, no timeouts are applied if None - - Returns: - subprocess.Popen instance for the tor subprocess - - Raises: - OSError if we either fail to create the tor process or reached a timeout - without success + Note: Timeout argument does not work on Windows (`ticket + <https://trac.torproject.org/5783>`_) + + :param str tor_cmd: command for starting tor + :param list args: additional arguments for tor + :param str torrc_path: location of the torrc for us to use + :param int completion_percent: percent of bootstrap completion at which this'll return + :param functor init_msg_handler: optional functor that will be provided with tor's initialization stdout as we get it + :param int timeout: time after which the attempt to start tor is aborted, no timeouts are applied if None + + :returns: subprocess.Popen instance for the tor subprocess + + :raises: OSError if we either fail to create the tor process or reached a timeout without success """ if stem.util.system.is_windows(): @@ -124,22 +115,15 @@ def launch_tor_with_config(config, tor_cmd = "tor", completion_percent = 100, in configuration. This writes a temporary torrc to disk, launches tor, then deletes the torrc. - Arguments: - config (dict) - configuration options, such as ("ControlPort": "9051") - tor_cmd (str) - command for starting tor - completion_percent (int) - percent of bootstrap completion at which - this'll return - init_msg_handler (functor) - optional functor that will be provided with - tor's initialization stdout as we get it - timeout (int) - time after which the attempt to start tor is - aborted, no timeouts are applied if None - - Returns: - subprocess.Popen instance for the tor subprocess - - Raises: - OSError if we either fail to create the tor process or reached a timeout - without success + :param dict config: configuration options, such as ``{"ControlPort": "9051"}`` + :param str tor_cmd: command for starting tor + :param int completion_percent: percent of bootstrap completion at which this'll return + :param functor init_msg_handler: optional functor that will be provided with tor's initialization stdout as we get it + :param int timeout: time after which the attempt to start tor is aborted, no timeouts are applied if None + + :returns: subprocess.Popen instance for the tor subprocess + + :raises: OSError if we either fail to create the tor process or reached a timeout without success """ torrc_path = tempfile.mkstemp(prefix = "torrc-", text = True)[1]

1 0

[stem/master] Converting stem.version to reStructuredText
by atagar＠torproject.org 06 Jun '12

06 Jun '12

commit ecc0e86d46ac2db77d45d46af5ac50168befa6c9 Author: Damian Johnson <atagar(a)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)

1 0