[Pkg-privacy-commits] [pyptlib] 38/136: Documentation has been added at the module, class, and method levels.
Ximin Luo
infinity0 at moszumanska.debian.org
Sat Aug 22 13:25:04 UTC 2015
This is an automated email from the git hooks/post-receive script.
infinity0 pushed a commit to branch master
in repository pyptlib.
commit 60c86adac11888d407d00e1bc55d9b1056dab3c8
Author: Brandon Wiley <brandon at blanu.net>
Date: Wed Jul 18 14:58:29 2012 -0500
Documentation has been added at the module, class, and method levels.
---
src/__init__.py | 3 --
src/examples/server.py | 2 ++
src/pyptlib/client.py | 39 +++++++++++++++++--------
src/pyptlib/config.py | 65 ++++++++++++++++++++++++++++-------------
src/pyptlib/easy/client.py | 25 ++++++++++++++--
src/pyptlib/easy/server.py | 25 ++++++++++++++--
src/pyptlib/easy/util.py | 6 +++-
src/pyptlib/server.py | 72 +++++++++++++++++++++++++++-------------------
8 files changed, 167 insertions(+), 70 deletions(-)
diff --git a/src/__init__.py b/src/__init__.py
deleted file mode 100644
index e0e3e1a..0000000
--- a/src/__init__.py
+++ /dev/null
@@ -1,3 +0,0 @@
-#!/usr/bin/python
-# -*- coding: utf-8 -*-
-
diff --git a/src/examples/server.py b/src/examples/server.py
index daa5878..b4e686c 100755
--- a/src/examples/server.py
+++ b/src/examples/server.py
@@ -1,6 +1,8 @@
#!/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
diff --git a/src/pyptlib/client.py b/src/pyptlib/client.py
index 0186aac..6683f37 100644
--- a/src/pyptlib/client.py
+++ b/src/pyptlib/client.py
@@ -1,6 +1,11 @@
#!/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')
diff --git a/src/pyptlib/config.py b/src/pyptlib/config.py
index f3e71b1..79f23a7 100644
--- a/src/pyptlib/config.py
+++ b/src/pyptlib/config.py
@@ -1,6 +1,11 @@
#!/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
-
-
diff --git a/src/pyptlib/easy/client.py b/src/pyptlib/easy/client.py
index b11f4a5..5ccb3a3 100644
--- a/src/pyptlib/easy/client.py
+++ b/src/pyptlib/easy/client.py
@@ -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()
-
-
diff --git a/src/pyptlib/easy/server.py b/src/pyptlib/easy/server.py
index f73c379..9912173 100644
--- a/src/pyptlib/easy/server.py
+++ b/src/pyptlib/easy/server.py
@@ -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()
-
-
diff --git a/src/pyptlib/easy/util.py b/src/pyptlib/easy/util.py
index 04eccde..fa0ec81 100644
--- a/src/pyptlib/easy/util.py
+++ b/src/pyptlib/easy/util.py
@@ -1,11 +1,15 @@
#!/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
diff --git a/src/pyptlib/server.py b/src/pyptlib/server.py
index 1aee58e..ce95bc4 100644
--- a/src/pyptlib/server.py
+++ b/src/pyptlib/server.py
@@ -1,6 +1,11 @@
#!/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)
-
-
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-privacy/packages/pyptlib.git
More information about the Pkg-privacy-commits
mailing list