pyptlib Package — pyptlib 0.0.1 documentation

# pyptlib documentation

## pyptlib Package

## `client` Module

Public client-side pyptlib API.

`pyptlib.client.` `init`(supported_transports)

  Bootstrap client-side managed-proxy mode.

  Call in the beginning of your application.

  Parameters: | supported_transports (list) – Names of the transports that the application supports.
  Returns: | dictionary that contains information for the application.
  Key | Type | Value
  --- | --- | ---
  state_loc | string | Directory where the managed proxy should dump its state files (if needed).
  transports | list | Strings of the names of the transports that should be launched. The list can be empty.
  Raises : | `pyptlib.config.EnvError` if environment was incomplete or corrupted.

`pyptlib.client.` `reportEnd`()

  Report that we are done launching transports.

  Call after you have launched all the transports you could launch.

`pyptlib.client.` `reportFailure`(name, message)

  Report that a client transport failed to launch.

  Always call after failing to launch a transport.

  Parameters: | name (str) – Name of transport. message (str) – Error message.

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

  Report that a client transport was launched succesfully.

  Always call after successfully launching a transport.

  Parameters: | name (str) – Name of transport. socksVersion (int) – The SOCKS protocol version. addrport (tuple) – (addr,port) where this transport is listening for connections. args (str) – ARGS field for this transport. args – OPT-ARGS field for this transport.

## `client_config` Module

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

class `pyptlib.client_config.` `ClientConfig`

  Bases: `pyptlib.config.Config`

  A client-side pyptlib configuration.

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

  `getClientTransports`()

    Return a list of strings representing the client transports reported by Tor.

    If present, the wildcard transport, ‘*’, is stripped from this list and used to set allTransportsEnabled to True.

    Returns: | list of transports

  `writeMethod`(name, socksVersion, addrport, args=None, optArgs=None)

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

    Parameters: | name (str) – Name of transport. socksVersion (int) – The SOCKS protocol version. 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.

  `writeMethodEnd`()

    Write a message to stdout announcing that we finished launching transports..

  `writeMethodError`(name, message)

    Write a message to stdout announcing that we failed to launch a transport.

    Parameters: | name (str) – Name of transport. message (str) – Error message.

## `config` Module

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

class `pyptlib.config.` `Config`

  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.
  Raises : | `pyptlib.config.EnvError` if environment was incomplete or corrupted.

  `allTransportsEnabled` = False
  `check`(key)

    Check the environment for a specific environment variable.

    Parameters: | key (str) – Environment variable key.
    Returns: | bool – True if the environment variable is set.

  `checkClientMode`()

    Check whether Tor wants us to run as a client or as a server.

    Returns: | bool – True if Tor wants us to run as a client.

  `checkManagedTransportVersion`(version)

    Check if Tor supports a specific managed-proxy protocol version.

    Parameters: | version (string) – A managed-proxy protocol version.
    Returns: | bool – True if version is supported.

  `checkTransportEnabled`(transport)

    Check if Tor wants the application to spawn a specific transport.

    Parameters: | transport (string) – The name of a pluggable transport.
    Returns: | bool – True if Tor wants the application to spawn that transport.

  `emit`(msg)

    Announce a message.

    Parameters: | msg (str) – A message.

  `get`(key)

    Get the value of an environment variable.

    Parameters: | key (str) – Environment variable key.
    Returns: | str – The value of the envrionment variable.
    Raises : | `pyptlib.config.EnvError` if environment

    variable could not be found.

  `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.

  `managedTransportVer` = []
  `stateLocation` = None
  `transports` = []
  `writeEnvError`(message)

    Announce that an error occured while parsing the environment.

    Parameters: | message (str) – Error message.

  `writeVersion`(version)

    Announce that a specific managed-proxy protocol version is supported.

    Parameters: | version (str) – A managed-proxy protocol version.

  `writeVersionError`()

    Announce that we could not find a supported managed-proxy protocol version.

exception `pyptlib.config.` `EnvError`

  Bases: `exceptions.Exception`

  Thrown when the environment is incomplete or corrupted.

## `server` Module

Public server-side pyptlib API.

`pyptlib.server.` `init`(supported_transports)

  Bootstrap server-side managed-proxy mode.

  Call in the beginning of your application.

  Parameters: | supported_transports (list) – Names of the transports that the application supports.
  Returns: | dictionary that contains information for the application:
  Raises : | `pyptlib.config.EnvError` if environment was incomplete or corrupted.

`pyptlib.server.` `reportEnd`()

  Report that we are done launching transports.

  Call after you have launched all the transports you could launch.

`pyptlib.server.` `reportFailure`(name, message)

  Report that a server transport failed to launch.

  Always call after failing to launch a transport.

  Parameters: | name (str) – Name of transport. message (str) – Error message.

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

  Report that a server transport was launched succesfully.

  Always call after successfully launching a transport.

  Parameters: | name (str) – Name of transport. addrport (tuple) – (addr,port) where this transport is listening for connections. options (str) – Transport options.

## `server_config` Module

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

class `pyptlib.server_config.` `ServerConfig`

  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.
  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`

  `getServerBindAddresses`()

    Returns: | `pyptlib.server_config.ServerConfig.serverBindAddr`

  `getServerTransports`()

    Returns: | `pyptlib.config.Config.transports`

  `get_addrport`(key)

    Parse an environment variable holding an address:port value.

    Parameters: | key (str) – Environment variable key.
    Returns: | tuple – (address,port)
    Raises : | `pyptlib.config.EnvError` if string was not in address:port format.

  `get_addrport_from_string`(string)

    Parse a string holding an address:port value.

    Parameters: | string (str) – A string.
    Returns: | tuple – (address,port)
    Raises : | `pyptlib.config.EnvError` if string was not in address:port format.

  `writeMethod`(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) – Transport options.

  `writeMethodEnd`()

    Write a message to stdout announcing that we finished launching transports..

  `writeMethodError`(name, message)

    Write a message to stdout announcing that we failed to launch a transport.

    Parameters: | name (str) – Name of transport. message (str) – Error message.

## `util` Module

Utility functions.

`pyptlib.util.` `checkClientMode`()

  Check whether Tor wants us to run as a client or as a server.

  Returns: | bool – True if Tor wants us to run as a client.