
pyptlib Package
***************


"client" Module
===============

Public client-side pyptlib API.

class class pyptlib.client.ClientTransportPlugin(config=None, stdout=<open file '<stdout>', mode 'w' at 0x557e6078>)

   Bases: "pyptlib.core.TransportPlugin"

   Runtime process for a client TransportPlugin.

   configType

      alias of "ClientConfig"

   methodName = 'CMETHOD'

   reportMethodSuccess(name, protocol, addrport, args=None, optArgs=None)

      Write a message to stdout announcing that a transport was
      successfully launched.

      Parameters:
         * **name** (*str*) -- Name of transport.

         * **protocol** (*str*) -- Name of protocol to communicate
           using.

         * **addrport** (*tuple*) -- (addr,port) where this transport
           is listening for connections.

         * **args** (*str*) -- ARGS field for this transport.

         * **optArgs** (*str*) -- OPT-ARGS field for this transport.

pyptlib.client.init(supported_transports)

   DEPRECATED. Use ClientTransportPlugin().init() instead.

pyptlib.client.reportEnd()

   DEPRECATED. Use ClientTransportPlugin().reportMethodsEnd() instead.

pyptlib.client.reportFailure(name, message)

   DEPRECATED. Use ClientTransportPlugin().reportMethodError()
   instead.

pyptlib.client.reportSuccess(name, socksVersion, addrport, args=None, optArgs=None)

   DEPRECATED. Use ClientTransportPlugin().reportMethodSuccess()
   instead.


"client_config" Module
======================

Low-level parts of pyptlib that are only useful to clients.

class class pyptlib.client_config.ClientConfig(stateLocation, managedTransportVer=None, transports=None)

   Bases: "pyptlib.config.Config"

   A client-side pyptlib configuration.

   classmethod fromEnv()

      Build a ClientConfig from environment variables.

      Raises :
         "pyptlib.config.EnvError" if environment was incomplete or
         corrupted.


"config" Module
===============

Parts of pyptlib that are useful both to clients and servers.

class class pyptlib.config.Config(stateLocation, managedTransportVer=None, transports=None)

   Bases: "object"

   pyptlib's configuration.

   Variables:
      * **stateLocation** (*string*) -- Location where application
        should store state.

      * **managedTransportVer** (*list*) -- List of managed-proxy
        protocol versions that Tor supports.

      * **transports** (*list*) -- Strings of pluggable transport
        names that Tor wants us to handle.

      * **allTransportsEnabled** (*bool*) -- True if Tor wants us to
        spawn all the transports.

   getAllTransportsEnabled()

      Check if Tor wants the application to spawn all its transpotrs.

      Returns:
         bool -- True if Tor wants the application to spawn all its
         transports.

   getManagedTransportVersions()

      Returns:
         list -- The managed-proxy protocol versions that Tor
         supports.

   getStateLocation()

      Returns:
         string -- The state location.

exception exception pyptlib.config.EnvError(message=None, cause=None)

   Bases: "exceptions.Exception"

   Thrown when the environment is incomplete or corrupted.

pyptlib.config.checkClientMode()

   Read the environment and return true if we are supposed to be a
   client. Return false if we are supposed to be a server.

   Raises :
      "pyptlib.config.EnvError" if the environment was not properly
      set up

pyptlib.config.env_has_k(k, v)

   Default validator for "get_env()".

   Returns:
      str -- The value of the envvar *k* if it is set.

   Raises :
      "ValueError" if *k* was not found.

pyptlib.config.get_env(key, validate=<function env_has_k at 0x8b38f44>)

   Get the value of an environment variable.

   Parameters:
      * **key** (*str*) -- Environment variable key.

      * **validate** (*f*) -- Function that takes a *var* and a
        *value*, and returns a (maybe transformed) value if it is
        valid, or throws an exception. If the environment does not set
        *var*, *value* is passed in as *None*. The default validator
        is "env_has_k()" which passes any value which is set (i.e. not
        *None*).

   Returns:
      str -- The value of the envrionment variable.

   Raises :
      "pyptlib.config.EnvError" if environment variable could not be
      found, or if it did not pass validation.


"server" Module
===============

Public server-side pyptlib API.

class class pyptlib.server.ServerTransportPlugin(config=None, stdout=<open file '<stdout>', mode 'w' at 0x557e6078>)

   Bases: "pyptlib.core.TransportPlugin"

   Runtime process for a server TransportPlugin.

   configType

      alias of "ServerConfig"

   getBindAddresses()

      Returns:
         dict of names of the transports that this plugin can serve,
         each mapped to the (ip,port) where the transport should bind.

      Raises :
         "ValueError" if called before "init()".

   methodName = 'SMETHOD'

   reportMethodSuccess(name, addrport, options)

      Write a message to stdout announcing that a server transport was
      successfully launched.

      Parameters:
         * **name** (*str*) -- Name of transport.

         * **addrport** (*tuple*) -- (addr,port) where this transport
           is listening for connections.

         * **options** (*str*) -- String containting comma-separated
           transport options in key=value form (as they appear in the
           ARGS: SMETHOD option)

pyptlib.server.init(supported_transports)

   DEPRECATED. Use ServerTransportPlugin().init() instead.

pyptlib.server.reportEnd()

   DEPRECATED. Use ClientTransportPlugin().reportMethodsEnd() instead.

pyptlib.server.reportFailure(name, message)

   DEPRECATED. Use ClientTransportPlugin().reportMethodError()
   instead.

pyptlib.server.reportSuccess(name, addrport, options)

   DEPRECATED. Use ClientTransportPlugin().reportMethodSuccess()
   instead.


"server_config" Module
======================

Low-level parts of pyptlib that are only useful to servers.

class class pyptlib.server_config.ServerConfig(stateLocation, managedTransportVer=None, transports=None, serverBindAddr=None, ORPort=None, extendedORPort=None, authCookieFile=None, serverTransportOptions=None)

   Bases: "pyptlib.config.Config"

   A client-side pyptlib configuration.

   Variables:
      * **ORPort** (*tuple*) -- (ip,port) pointing to Tor's ORPort.

      * **extendedORPort** (*tuple*) -- (ip,port) pointing to Tor's
        Extended ORPort. None if Extended ORPort is not supported.

      * **serverBindAddr** (*dict*) -- A dictionary {<transport> :
        [<addr>, <port>]}, where <transport> is the name of the
        transport that must be spawned, and [<addr>, <port>] is a list
        containing the location where that transport should bind. The
        dictionary can be empty.

      * **authCookieFile** (*string*) -- String representing the
        filesystem path where the Extended ORPort Authentication
        cookie is stored. None if Extended ORPort authentication is
        not supported.

      * **serverTransportOptions** (*dict*) -- Dictionary containing
        user-provided parameters that must be passed to the pluggable
        transports. Example: {'obfs3': {'k':'v'}, 'scramblesuit':
        {'k2' : 'v2', 'k' : 'v'} }

   classmethod fromEnv()

      Build a ServerConfig from environment variables.

      Raises :
         "pyptlib.config.EnvError" if environment was incomplete or
         corrupted.

   getAuthCookieFile()

      Returns:
         "pyptlib.server_config.ServerConfig.authCookieFile"

   getExtendedORPort()

      Returns:
         "pyptlib.server_config.ServerConfig.extendedORPort"

   getORPort()

      Returns:
         "pyptlib.server_config.ServerConfig.ORPort"

   getServerTransportOptions()

      Returns:
         "pyptlib.server_config.ServerConfig.serverTransportOptions"

pyptlib.server_config.get_transport_options_impl(string)

   Parse transport options. :param str optstring: Example input:
   'scramblesuit:k=v;scramblesuit:k2=v2;obs3fs:k=v' :returns:
   {'obfs3': {'k':'v'}, 'scramblesuit': {'k2' : 'v2', 'k' : 'v'} }


"util" Module
=============

Utility functions.

pyptlib.util.parse_addr_spec(spec, defhost=None, defport=None, resolve=False)

   Parse a host:port specification and return a 2-tuple ("host", port)
   as understood by the Python socket functions.

   If resolve is true, then the host in the specification or the
   defhost may be a domain name, which will be resolved. If resolve is
   false, then the host must be a numeric IPv4 or IPv6 address.

   IPv6 addresses must be enclosed in square brackets.

   Returns:
      tuple -- (address, port)

   Raises :
      ValueError if spec is not well formed.

   >>> parse_addr_spec("192.168.0.1:9999")
   ('192.168.0.1', 9999)

   If defhost or defport are given, those parts of the specification
   may be omitted; if so, they will be filled in with defaults. >>>
   parse_addr_spec("192.168.0.2:8888", defhost="192.168.0.1",
   defport=9999) ('192.168.0.2', 8888) >>> parse_addr_spec(":8888",
   defhost="192.168.0.1", defport=9999) ('192.168.0.1', 8888) >>>
   parse_addr_spec("192.168.0.2", defhost="192.168.0.1", defport=9999)
   ('192.168.0.2', 9999) >>> parse_addr_spec("192.168.0.2:",
   defhost="192.168.0.1", defport=9999) ('192.168.0.2', 9999) >>>
   parse_addr_spec(":", defhost="192.168.0.1", defport=9999)
   ('192.168.0.1', 9999) >>> parse_addr_spec("",
   defhost="192.168.0.1", defport=9999) ('192.168.0.1', 9999)
