
Manual
******

Information available about Tor from its manual. This provides three
methods of getting this information...

* "from_cache()" provides manual content bundled with Stem. This is
  the fastest and most reliable method but only as up-to-date as
  Stem's release.

* "from_man()" reads Tor's local man page for information about it.

* "from_remote()" fetches the latest manual information remotely.
  This is the slowest and least reliable method but provides the most
  recent information about Tor.

Manual information includes arguments, signals, and probably most
usefully the torrc configuration options. For example, say we want a
little script that told us what our torrc options do...

   from stem.manual import Manual
   from stem.util import term

   try:
     print("Downloading tor's manual information, please wait...")
     manual = Manual.from_remote()
     print("  done\n")
   except IOError as exc:
     print("  unsuccessful (%s), using information provided with stem\n" % exc)
     manual = Manual.from_cache()  # fall back to our bundled manual information

   print('Which tor configuration would you like to learn about?  (press ctrl+c to quit)\n')

   try:
     while True:
       requested_option = raw_input('> ').strip()

       if requested_option:
         if requested_option in manual.config_options:
           option = manual.config_options[requested_option]
           print(term.format('%s %s' % (option.name, option.usage), term.Color.GREEN, term.Attr.BOLD))
           print(term.format(option.summary, term.Color.GREEN))  # brief description provided by stem

           print(term.format('\nFull Description:\n', term.Color.GREEN, term.Attr.BOLD))
           print(term.format(option.description + '\n', term.Color.GREEN))
         else:
           print(term.format("Sorry, we don't have any information about %s. Are you sure it's an option?" % requested_option, term.Color.RED))
   except KeyboardInterrupt:
     pass  # user pressed ctrl+c



 [image]



**Module Overview:**

   is_important - Indicates if a configuration option is of particularly common importance.
   download_man_page - Downloads tor's latest man page.

   Manual - Information about Tor available from its manual.
    | |- from_cache - Provides manual information cached with Stem.
    | |- from_man - Retrieves manual information from its man page.
    | +- from_remote - Retrieves manual information remotely from tor's latest manual.
    |
    +- save - writes the manual contents to a given location

New in version 1.5.0.

class stem.manual.ConfigOption(name, category='Unknown', usage='', summary='', description='')

   Bases: "object"

   Tor configuration attribute found in its torrc.

   Variables:
      * **name** (*str*) -- name of the configuration option

      * **category** (*stem.manual.Category*) -- category the config
        option was listed under, this is Category.UNKNOWN if we didn't
        recognize the category

      * **usage** (*str*) -- arguments accepted by the option

      * **summary** (*str*) -- brief description of what the option
        does

      * **description** (*str*) -- longer manual description with
        details

stem.manual.is_important(option)

   Indicates if a configuration option of particularly common
   importance or not.

   Parameters:
      **option** (*str*) -- tor configuration option to check

   Returns:
      **bool** that's **True** if this is an important option and
      **False** otherwise

stem.manual.download_man_page(path=None, file_handle=None, url='https://gitweb.torproject.org/tor.git/plain/doc/tor.1.txt', timeout=20)

   Downloads tor's latest man page from gitweb.torproject.org. This
   method is both slow and unreliable - please see the warnings on
   "from_remote()".

   Parameters:
      * **path** (*str*) -- path to save tor's man page to

      * **file_handle** (*file*) -- file handler to save tor's man
        page to

      * **url** (*str*) -- url to download tor's asciidoc manual
        from

      * **timeout** (*int*) -- seconds to wait before timing out the
        request

   Raises:
      **IOError** if unable to retrieve the manual

class stem.manual.Manual(name, synopsis, description, commandline_options, signals, files, config_options)

   Bases: "object"

   Parsed tor man page. Tor makes no guarantees about its man page
   format so this may not always be compatible. If not you can use the
   cached manual information stored with Stem.

   This does not include every bit of information from the tor manual.
   For instance, I've excluded the 'THE CONFIGURATION FILE FORMAT'
   section. If there's a part you'd find useful then file an issue and
   we can add it.

   Variables:
      * **name** (*str*) -- brief description of the tor command

      * **synopsis** (*str*) -- brief tor command usage

      * **description** (*str*) -- general description of what tor
        does

      * **commandline_options** (*dict*) -- mapping of commandline
        arguments to their descripton

      * **signals** (*dict*) -- mapping of signals tor accepts to
        their description

      * **files** (*dict*) -- mapping of file paths to their
        description

      * **config_options** (*dict*) -- "ConfigOption" tuples for tor
        configuration options

      * **man_commit** (*str*) -- latest tor commit editing the man
        page when this information was cached

      * **stem_commit** (*str*) -- stem commit to cache this manual
        information

   static from_cache(path=None)

      Provides manual information cached with Stem. Unlike
      "from_man()" and "from_remote()" this doesn't have any system
      requirements, and is faster too. Only drawback is that this
      manual content is only as up to date as the Stem release we're
      using.

      Parameters:
         **path** (*str*) -- cached manual content to read, if not
         provided this uses the bundled manual information

      Returns:
         "Manual" with our bundled manual information

      Raises:
         **IOError** if a **path** was provided and we were unable to
         read it

   static from_man(man_path='tor')

      Reads and parses a given man page.

      On OSX the man command doesn't have an '--encoding' argument so
      its results may not quite match other platforms. For instance,
      it normalizes long dashes into '--'.

      Parameters:
         **man_path** (*str*) -- path argument for 'man', for example
         you might want '/path/to/tor/doc/tor.1' to read from tor's
         git repository

      Returns:
         "Manual" for the system's man page

      Raises:
         **IOError** if unable to retrieve the manual

   static from_remote(timeout=60)

      Reads and parses the latest tor man page from
      gitweb.torproject.org. Note that while convenient, this reliance
      on GitWeb means you should alway call with a fallback, such
      as...

         try:
           manual = stem.manual.from_remote()
         except IOError:
           manual = stem.manual.from_cache()

      In addition to our GitWeb dependency this requires 'a2x' which
      is part of asciidoc and... isn't quick. Personally this takes
      ~7.41s, breaking down for me as follows...

         * 1.67s to download tor.1.txt

         * 5.57s to convert the asciidoc to a man page

         * 0.17s for stem to read and parse the manual

      Parameters:
         **timeout** (*int*) -- seconds to wait before timing out the
         request

      Returns:
         latest "Manual" available for tor

      Raises:
         **IOError** if unable to retrieve the manual

   save(path)

      Persists the manual content to a given location.

      Parameters:
         **path** (*str*) -- path to save our manual content to

      Raises:
         **IOError** if unsuccessful
