Skip to content
Snippets Groups Projects
Commit 60c86ada authored by Brandon Wiley's avatar Brandon Wiley
Browse files

Documentation has been added at the module, class, and method levels.

parent 7e45afc1
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
src/__init__.py deleted 100644 → 0
+ 0
− 3
View file @ 7e45afc1
#!/usr/bin/python
# -*- coding: utf-8 -*-
src/examples/server.py
+ 2
− 0
View file @ 60c86ada
#!/usr/bin/python
# -*- coding: utf-8 -*-
""" This is an example server which shows how to call the pyptlib.easy high-level API. """
from pyptlib.easy.server import init, reportSucess, reportFailure, \
reportEnd
......
src/pyptlib/client.py
+ 27
− 12
View file @ 60c86ada
#!/usr/bin/python
# -*- coding: utf-8 -*-
"""
The pyptlib.client module contains a low-level API which closely follows the Tor Proposal 180: Pluggable transports for circumvention.
This module inherits from pyptlib.config and contains just the parts of the API which are specific to the client implementations of the protocol.
"""
import os
from pyptlib.config import Config
......@@ -9,10 +14,19 @@ __docformat__ = 'restructuredtext'
class ClientConfig(Config):
"""
The ClientConfig class contains a low-level API which closely follows the Tor Proposal 180: Pluggable transports for circumvention.
This class inherits from pyptlib.config.Config and contains just the parts of the API which are specific to the client implementations of the protocol.
"""
# Public methods
def __init__(self): # throws EnvError
"""
Initialize the ClientConfig object.
This causes the state location, managed transport, and transports version to be set.
"""
Config.__init__(self)
self.transports = self.get('TOR_PT_CLIENT_TRANSPORTS').split(','
......@@ -21,13 +35,10 @@ class ClientConfig(Config):
self.allTransportsEnabled = True
self.transports.remove('*')
# Returns a list of strings representing the client transports reported by Tor. If present, '*' is stripped from this list and used to set allTransportsEnabled to True.
def getClientTransports(self):
return self.transports
""" Returns a list of strings representing the client transports reported by Tor. If present, '*' is stripped from this list and used to set allTransportsEnabled to True. """
# Write a message to stdout specifying a supported transport
# Takes: str, int, (str, int), [str], [str]
return self.transports
def writeMethod( # CMETHOD
self,
......@@ -37,6 +48,10 @@ class ClientConfig(Config):
args,
optArgs,
):
"""
Write a message to stdout specifying a supported transport
Takes: str, int, (str, int), [str], [str]
"""
methodLine = 'CMETHOD %s socks%s %s:%s' % (name, socksVersion,
address[0], address[1])
......@@ -46,15 +61,15 @@ class ClientConfig(Config):
methodLine = methodLine + ' OPT-ARGS=' + args.join(',')
self.emit(methodLine)
# Write a message to stdout specifying that an error occurred setting up the specified method
# Takes: str, str
def writeMethodError(self, name, message): # CMETHOD-ERROR
self.emit('CMETHOD-ERROR %s %s' % (name, message))
"""
Write a message to stdout specifying that an error occurred setting up the specified method
Takes: str, str
"""
# Write a message to stdout specifying that the list of supported transports has ended
self.emit('CMETHOD-ERROR %s %s' % (name, message))
def writeMethodEnd(self): # CMETHODS DONE
self.emit('CMETHODS DONE')
""" Write a message to stdout specifying that the list of supported transports has ended """
self.emit('CMETHODS DONE')
src/pyptlib/config.py
+ 45
− 20
View file @ 60c86ada
#!/usr/bin/python
# -*- coding: utf-8 -*-
"""
The pyptlib.config module contains a low-level API which closely follows the Tor Proposal 180: Pluggable transports for circumvention.
This module contains the parts of the API which are shared by both client and server implementations of the protocol.
"""
import os
import logging
......@@ -8,7 +13,10 @@ __docformat__ = 'restructuredtext'
class Config:
"""
The Config module class a low-level API which closely follows the Tor Proposal 180: Pluggable transports for circumvention.
This class contains the parts of the API which are shared by both client and server implementations of the protocol.
"""
stateLocation = None # TOR_PT_STATE_LOCATION
managedTransportVer = [] # TOR_PT_MANAGED_TRANSPORT_VER
transports = [] # TOR_PT_SERVER_TRANSPORTS or TOR_PT_CLIENT_TRANSPORTS
......@@ -17,60 +25,78 @@ class Config:
# Public methods
def __init__(self): # throws EnvError
""" Initialize the Config object. this causes the state location and managed transport version to be set. """
self.stateLocation = self.get('TOR_PT_STATE_LOCATION')
self.managedTransportVer = \
self.get('TOR_PT_MANAGED_TRANSPORT_VER').split(',')
def checkClientMode(self):
return self.check('TOR_PT_CLIENT_TRANSPORTS')
""" Check to see if the daemon is being run as a client or a server. This is determined by looking for the presence of the TOR_PT_CLIENT_TRANSPORTS environment variable. """
# Returns a string representing the path to the state storage directory (which may not exist, but should be creatable) reported by Tor
return self.check('TOR_PT_CLIENT_TRANSPORTS')
def getStateLocation(self):
return self.stateLocation
""" Return the state location, a string representing the path to the state storage directory (which may not exist, but should be creatable) reported by Tor. """
# Returns a list of strings representing supported versions as reported by Tor
return self.stateLocation
def getManagedTransportVersions(self):
return self.managedTransportVer
""" Return the managed transport versions, a list of strings representing supported versions as reported by Tor. """
# Checks to see if the specified version is included in those reported by Tor
# Returns True if the version is included and False if it is not
return self.managedTransportVer
def checkManagedTransportVersion(self, version):
return version in self.managedTransportVer
"""
Checks to see if the specified version is included in those reported by Tor
Returns True if the version is included and False if it is not
"""
# Returns a bool, True if the transport '*' was specified by Tor, otherwise False.
return version in self.managedTransportVer
def getAllTransportsEnabled(self):
""" Returns a bool, True if the transport '*' was specified by Tor, otherwise False. """
return self.allTransportsEnabled
def checkTransportEnabled(self, transport):
return self.allTransportsEnabled or transport in self.transports
""" Returns a bool, True if either the given transport or the transport '*' was specified by Tor, otherwise False. """
# Write a message to stdout specifying that an error parsing the environment variables has occurred
# Takes: str
return self.allTransportsEnabled or transport in self.transports
def writeEnvError(self, message): # ENV-ERROR
self.emit('ENV-ERROR %s' % message)
"""
Write a message to stdout specifying that an error parsing the environment variables has occurred
Takes: str
"""
# Write a message to stdout specifying that the specified configuration protocol version is supported
# Takes: str
self.emit('ENV-ERROR %s' % message)
def writeVersion(self, version): # VERSION
self.emit('VERSION %s' % version)
"""
Write a message to stdout specifying that the specified configuration protocol version is supported
Takes: str
"""
# Write a message to stdout specifying that none of the specified configuration protocol versions are supported
self.emit('VERSION %s' % version)
def writeVersionError(self): # VERSION-ERROR
"""
Write a message to stdout specifying that none of the specified configuration protocol versions are supported
"""
self.emit('VERSION-ERROR no-version')
# Private methods
def check(self, key):
""" Returns True if the specified environment variable is set, otherwise returns False. """
return key in os.environ
def get(self, key):
""" Attempts to fetch the given key from the environment variables. If it is present, it is returned, otherwise an EnvException is thrown. """
if key in os.environ:
return os.environ[key]
else:
......@@ -85,10 +111,9 @@ class Config:
# Exception thrown when there is an error parsing the configuration parameters provided by Tor in environment variables
class EnvException(Exception):
""" The EnvException exception is thrown whenever a required environment variable is not presented or cannot be parsed. """
message = None
def __init__(self, message):
self.message = message
src/pyptlib/easy/client.py
+ 23
− 2
View file @ 60c86ada
......@@ -4,8 +4,15 @@
from pyptlib.config import EnvException
from pyptlib.client import ClientConfig
""" The pyptlib.easy.client module provides a high-level API for implementing pluggable transport clients. """
def init(transports):
"""
Initialize the pluggable transport by parsing the environment variables and generating output to report any errors.
The given transports are checked against the transports enabled by Tor and a list of matching transports is returned.
The client should then launched all of the transports in the list and report on the success or failure of those launches.
"""
supportedTransportVersion = '1'
try:
......@@ -34,18 +41,32 @@ def reportSuccess(
args,
optArgs,
):
"""
This method should be called to report when a transport has been successfully launched.
It generates output to Tor informing that the transport launched successfully and can be used.
After all transports have been launched, the client should call reportEnd().
"""
config = ClientConfig()
config.writeMethod(name, socksVersion, address, args, optArgs)
def reportFailure(name, message):
"""
This method should be called to report when a transport has failed to launch.
It generates output to Tor informing that the transport failed to launch and cannot be used.
After all transports have been launched, the client should call reportEnd().
"""
config = ClientConfig()
config.writeMethodError(name, message)
def reportEnd():
"""
This method should be called after all transports have been launched.
It generates output to Tor informing that all transports have been launched.
"""
config = ClientConfig()
config.writeMethodEnd()
src/pyptlib/easy/server.py
+ 23
− 2
View file @ 60c86ada
......@@ -4,8 +4,15 @@
from pyptlib.config import EnvException
from pyptlib.server import ServerConfig
""" The pyptlib.easy.client module provides a high-level API for implementing pluggable transport clients. """
def init(transports):
"""
Initialize the pluggable transport by parsing the environment variables and generating output to report any errors.
The given transports are checked against the transports enabled by Tor and a list of matching transports is returned.
The server should then launch all of the transports in the list and report on the success or failure of those launches.
"""
supportedTransportVersion = '1'
try:
......@@ -28,18 +35,32 @@ def init(transports):
def reportSuccess(name, address, options):
"""
This method should be called to report when a transport has been successfully launched.
It generates output to Tor informing that the transport launched successfully and can be used.
After all transports have been launched, the server should call reportEnd().
"""
config = ServerConfig()
config.writeMethod(name, address, options)
def reportFailure(name, message):
"""
This method should be called to report when a transport has failed to launch.
It generates output to Tor informing that the transport failed to launch and cannot be used.
After all transports have been launched, the server should call reportEnd().
"""
config = ServerConfig()
config.writeMethodError(name, message)
def reportEnd():
"""
This method should be called after all transports have been launched.
It generates output to Tor informing that all transports have been launched.
"""
config = ServerConfig()
config.writeMethodEnd()
src/pyptlib/easy/util.py
+ 5
− 1
View file @ 60c86ada
#!/usr/bin/python
# -*- coding: utf-8 -*-
""" The pyptlib.util module contains useful functions that don't fit in anywhere else. """
from pyptlib.config import Config, EnvException
def checkClientMode():
""" Checks to see if the daemon has been launched in client mode or server mode. Returns True if it is in client mode, otherwise False. """
try:
c = Config()
return c.checkClientMode()
return c.checkClientMode()
except EnvException:
return False
src/pyptlib/server.py
+ 42
− 30
View file @ 60c86ada
#!/usr/bin/python
# -*- coding: utf-8 -*-
"""
The pyptlib.client module contains a low-level API which closely follows the Tor Proposal 180: Pluggable transports for circumvention.
This module inherits from pyptlib.config and contains just the parts of the API which are specific to the server implementations of the protocol.
"""
import os
from pyptlib.config import Config
......@@ -9,7 +14,10 @@ __docformat__ = 'restructuredtext'
class ServerConfig(Config):
"""
The ServerConfig class contains a low-level API which closely follows the Tor Proposal 180: Pluggable transports for circumvention.
This class inherits from pyptlib.config.Config and contains just the parts of the API which are specific to the client implementations of the protocol.
"""
extendedServerPort = None # TOR_PT_EXTENDED_SERVER_PORT
ORPort = None # TOR_PT_ORPORT
serverBindAddr = {} # TOR_PT_SERVER_BINADDR
......@@ -17,6 +25,11 @@ class ServerConfig(Config):
# Public methods
def __init__(self): # throws EnvError
"""
Initialize the ClientConfig object.
This causes the state location, managed transport, and transports version to be set.
"""
Config.__init__(self)
self.extendedServerPort = self.get('TOR_PT_EXTENDED_SERVER_PORT'
......@@ -34,35 +47,35 @@ class ServerConfig(Config):
self.allTransportsEnabled = True
self.transports.remove('*')
# Returns a tuple (str,int) representing the address of the Tor server port as reported by Tor
def getExtendedServerPort(self):
return self.extendedServerPort
""" Returns a tuple (str,int) representing the address of the Tor server port as reported by Tor """
# Returns a tuple (str,int) representing the address of the Tor OR port as reported by Tor
return self.extendedServerPort
def getORPort(self):
return self.ORPort
""" Returns a tuple (str,int) representing the address of the Tor OR port as reported by Tor """
# Returns a dict {str: (str,int)} representing the addresses for each transport as reported by Tor
return self.ORPort
def getServerBindAddresses(self):
return self.serverBindAddr
""" Returns a dict {str: (str,int)} representing the addresses for each transport as reported by Tor """
# Returns a list of strings representing the server transports reported by Tor. If present, '*' is stripped from this list and used to set allTransportsEnabled to True.
return self.serverBindAddr
def getServerTransports(self):
""" Returns a list of strings representing the server transports reported by Tor. If present, '*' is stripped from this list and used to set allTransportsEnabled to True. """
return self.transports
# Write a message to stdout specifying a supported transport
# Takes: str, (str, int), MethodOptions
def writeMethod( # SMETHOD
self,
name,
address,
options,
):
"""
Write a message to stdout specifying a supported transport
Takes: str, (str, int), MethodOptions
"""
if options:
self.emit('SMETHOD %s %s:%s %s' % (name, address[0],
......@@ -70,19 +83,21 @@ class ServerConfig(Config):
else:
self.emit('SMETHOD %s %s:%s' % (name, address[0], address[1]))
# Write a message to stdout specifying that an error occurred setting up the specified method
# Takes: str, str
def writeMethodError(self, name, message): # SMETHOD-ERROR
self.emit('SMETHOD-ERROR %s %s' % (name, message))
"""
Write a message to stdout specifying that an error occurred setting up the specified method
Takes: str, str
"""
# Write a message to stdout specifying that the list of supported transports has ended
self.emit('SMETHOD-ERROR %s %s' % (name, message))
def writeMethodEnd(self): # SMETHODS DONE
""" Write a message to stdout specifying that the list of supported transports has ended """
self.emit('SMETHODS DONE')
class MethodOptions:
""" The MethodOptions class represents the method options: FORWARD, ARGS, DECLARE, and USE-EXTENDED-PORT. """
forward = False # FORWARD
args = {} # ARGS
......@@ -91,30 +106,29 @@ class MethodOptions:
# Public methods
def __init__(self):
pass
# Sets forward to True
def setForward(self):
self.forward = True
""" Sets forward to True """
# Adds a key-value pair to args
self.forward = True
def addArg(self, key, value):
self.args[key] = value
""" Adds a key-value pair to args """
# Adds a key-value pair to declare
self.args[key] = value
def addDeclare(self, key, value):
self.declare[key] = value
""" Adds a key-value pair to declare """
# Sets useExtendedPort to True
self.declare[key] = value
def setUserExtendedPort(self):
""" Sets useExtendedPort to True """
self.useExtendedPort = True
def __str__(self):
""" Returns a string representation of the method options. """
options = []
if self.forward:
options.append('FORWARD:1')
......@@ -136,5 +150,3 @@ class MethodOptions:
options.append('USE-EXTENDED-PORT:1')
return ' '.join(options)
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment