[Pkg-privacy-commits] [pyptlib] 55/136: Add even more sphinx documentation.
Ximin Luo
infinity0 at moszumanska.debian.org
Sat Aug 22 13:25:07 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 7d9497f88044b0629faf2d14afb0186b2755f77b
Author: George Kadianakis <desnacked at riseup.net>
Date: Sun Oct 7 15:39:05 2012 -0400
Add even more sphinx documentation.
---
.gitignore | 5 ++
README | 25 -------
README.rst | 43 +++++++++++
pyptlib/config.py | 9 +--
sphinx/API.rst | 200 ++++++++++++++++++++++++++++++++++++++++++++++++++++
sphinx/README.rst | 1 +
sphinx/glossary.rst | 75 ++++++++++++++++++++
sphinx/index.rst | 18 +++--
8 files changed, 343 insertions(+), 33 deletions(-)
diff --git a/.gitignore b/.gitignore
index 37279b6..795469c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,3 +8,8 @@ sphinx/modules.rst
# ignore finished sphinx stuff
doc/
+
+
+build/
+dist/
+*egg-info
\ No newline at end of file
diff --git a/README b/README
deleted file mode 100644
index 097bb0c..0000000
--- a/README
+++ /dev/null
@@ -1,25 +0,0 @@
-- What is pyptlib?
-
-pyptlib is a little Python library which understands the 'pluggable
-transport managed-proxy protocol' [0].
-
-- Who is interested in pyptlib?
-
-You might be interested in pyptlib if you have an application that
-obfuscates TCP traffic and you want to integrate it easily with Tor.
-
-- What does pyptlib do?
-
-When pyptlib is initialized by your application, pyptlib communicates
-with Tor and learns which pluggable transports Tor needs, in which
-ports you should listen for connections, in which filesystem directory
-you should keep state, etc.
-Pyptlib then reports that information to your application and your
-application has to follow Tor's wishes.
-
-- How do I use pyptlib?
-
-Read the API file and see the examples/ directory. The source code
-might also be useful.
-
-[0]: https://gitweb.torproject.org/torspec.git/blob_plain/HEAD:/proposals/180-pluggable-transport.txt
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..3cd65b2
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,43 @@
+pyptlib README
+===============
+
+- What is pyptlib?
+
+pyptlib is a little Python library which understands the `pluggable
+transport managed-proxy protocol <https://gitweb.torproject.org/torspec.git/blob_plain/HEAD:/proposals/180-pluggable-transport.txt>`_.
+
+- Who is interested in pyptlib?
+
+You might be interested in pyptlib if you have an application that
+obfuscates TCP traffic and you want to integrate it easily with Tor.
+
+- What does pyptlib do?
+
+pyptlib speaks with Tor and informs your application about which
+pluggable transports Tor needs, in which ports they should listen for
+connections, in which filesystem directory they should keep state, etc.
+
+- What does pyptlib not do?
+
+pyptlib doesn't help your application do networking or obfuscation.
+
+- What does pyptlib expect from an application?
+
+pyptlib assumes that your application is executed by Tor as a
+managed-proxy.
+
+pyptlib assumes that your application acts as a proxy: it listens for
+traffic on a TCP port and pushes the traffic somewhere else.
+
+pyptlib assumes that your application has a SOCKS server when it acts
+as a client. This is needed because Tor needs to dynamically select
+where its data will be pushed to.
+
+- How do I use pyptlib?
+
+Read the documentation, the examples and the source.
+
+- What are these buzzwords?
+
+:file:`glossary.rst`
+
diff --git a/pyptlib/config.py b/pyptlib/config.py
index ebaa8f2..ca31465 100644
--- a/pyptlib/config.py
+++ b/pyptlib/config.py
@@ -148,7 +148,8 @@ class Config(object):
print msg
sys.stdout.flush()
-"""
-Exception thrown when the environment is incomplete or corrupted.
-"""
-class EnvError(Exception): pass
+class EnvError(Exception):
+ """
+ Thrown when the environment is incomplete or corrupted.
+ """
+ pass
diff --git a/sphinx/API.rst b/sphinx/API.rst
new file mode 100644
index 0000000..7ec3725
--- /dev/null
+++ b/sphinx/API.rst
@@ -0,0 +1,200 @@
+API overview
+============
+
+Be sure to read :file:`API.rst` and :file:`glossary.rst` before
+reading this file.
+
+General Overview
+################
+
+Applications begin by initializing pyptlib.
+
+Then pyptlib informs the application about which transports it should
+spawn, in which ports they should listen for connections, etc.
+
+Then the application launches the appropriate transports as
+instructed, and for each transport it reports to pyptlib whether it
+was launched successfully or not. Finally, the application announces
+to pyptlib that it finished launching transports.
+
+From that point and on the application should forget about pyptlib
+and start accepting connections.
+
+Detailed API Overview
+#####################
+
+0) Find if it's a client or a server
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+An application using pyptlib should start by calling
+:func:`pyptlib.util.checkClientMode` to learn whether Tor wants it
+to run as a client or as a server.
+
+1) Get transport information from Tor
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If Tor wants the application to run as a client, the next step is to
+run :func:`pyptlib.client.init`. Otherwise, the application should run
+:func:`pyptlib.server.init`.
+
+:func:`init` expects to be passed a list with the names of the
+transports your application supports.
+
+The application should be prepared for
+:exc:`pyptlib.config.EnvError`, which signifies that the
+environment was not prepared by Tor.
+
+The application should store the return value of the :func:`init`
+function.
+
+Consider an example of the fictional application *rot0r* which
+implements the pluggable transports *rot13* and *rot26*. If
+*rot0r*, in step 1, learned that Tor expects it to act as a client,
+it should now do:
+
+.. code-block::
+ python
+
+ import pyptlib.client
+ import pyptlib.config
+
+ try:
+ managed_info = pyptlib.client.init(["rot13", "rot26"])
+ except pyptlib.config.EnvError, err:
+ print "pyptlib could not bootstrap ('%s')." % str(err)
+
+2) Launch transports
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Client case (skip if you are a server)
+"""""""""""""""""""""""""""""""""""""""""""
+
+If your application is a client, the return value of
+:func:`pyptlib.client.init` is a dictionary of the format:
+
+========== ========== ==========
+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.
+========== ========== ==========
+
+Your application should then use the *transports* key to learn which transports it should launch.
+
+Proceeding with the previous example:
+
+.. code-block::
+ python
+
+ if 'rot13' in managed_info['transports']:
+ launch_rot13_client()
+ if 'rot26' in managed_info['transports']:
+ launch_rot26_client()
+
+
+.. note:: Since the application runs as a client, it should launch a
+ SOCKS server in the upstream side of the proxy.
+
+Server case (skip if you are a client):
+""""""""""""""""""""""""""""""""""""""""""""
+
+If your application is a server, the return value of
+:func:`pyptlib.server.init` is a dictionary of the format:
+
+========== ========== ==========
+Key Type Value
+========== ========== ==========
+state_loc string Directory where the managed proxy should dump its state files (if needed).
+orport tuple (ip,port) tuple pointing to Tor's ORPort.
+ext_orport tuple (ip,port) tuple pointing to Tor's Extended ORPort. None if Extended ORPort is not supported.
+transports dict A dictionary 'transport => (ip,port)' where 'transport' is the name of the transport that should be spawned, and '(ip,port)' is the location where the transport should bind. The dictionary can be empty.
+========== ========== ==========
+
+Your application should then use the *transports* key and attempt to
+launch the appropriate transports. Furthermore, since the application
+runs as a server, it should push data to Tor's ORPort. The TCP/IP
+location of the ORPort is provided in the *orport* key.
+
+Proceeding with the previous example:
+
+.. code-block::
+ python
+
+ if 'rot13' in managed_info['transports']:
+ launch_rot13_server(managed_info['transports']['rot13'], managed_info['orport'])
+ if 'rot26' in managed_info['transports']:
+ launch_rot26_server(managed_info['transports']['rot26'], managed_info['orport'])
+
+3) Report results back to Tor.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For every transport that the application launches, it reports to
+pyptlib whether it was launched successfully or not. This way, Tor is
+informed on whether a transport is expected to work or not.
+
+Client case (skip if you are a server):
+""""""""""""""""""""""""""""""""""""""""""""
+
+Everytime a transport is successfully launched, the application calls
+:func:`pyptlib.client.reportSuccess` with the name of the transport
+that was launched, the address where it is listening for connections,
+and the SOCKS version that the upstream SOCKS server supports.
+
+For example, if *rot13* was launched successfully, waits for
+connections in '127.0.0.1:42042' and supports SOCKSv4, the appropriate
+call would be:
+
+.. code-block::
+ python
+
+ pyptlib.client.reportSuccess('rot13', 5, ('127.0.0.1', 42042))
+
+Everytime a transport failed to launch, the application calls
+:func:`pyptlib.client.reportFailure` with the name of the transport
+and a message.
+
+For example, if *rot26* failed to launch, the appropriate call
+would be:
+
+.. code-block::
+ python
+
+ pyptlib.client.reportFailure('rot26', 'Could not bind to 127.0.0.1:666 (Operation not permitted)')
+
+Server case (skip if you are a client):
+""""""""""""""""""""""""""""""""""""""""""""
+
+Everytime a transport is successfully launched, the application calls
+:func:`pyptlib.server.reportSuccess` with the name of the transport
+that was launched, and the address where it is listening for connections.
+
+For example, if *rot13* was launched successfully and waits for
+connections in '127.0.0.1:42042', the appropriate call would be:
+
+.. code-block::
+ python
+
+ pyptlib.server.reportSuccess('rot13', ('127.0.0.1', 42042))
+
+Everytime a transport failed to launch, the application calls
+:func:`pyptlib.server.reportFailure` with the name of the transport
+and a message.
+
+For example, if *rot26* failed to launch, the appropriate call
+would be:
+
+.. code-block::
+ python
+
+ pyptlib.server.reportFailure('rot26', 'Could not bind to 127.0.0.1:666 (Operation not permitted)')
+
+4) Stop using pyptlib and start accepting connections
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When the application finishes launching connections, it should call
+:func:`pyptlib.client.reportEnd` (or
+:func:`pyptlib.server.reportEnd`), to announce to pyptlib that all
+transports were launched. This way, Tor knows that it can start
+pushing traffic to the application.
+
+After this point, pyptlib has no other use.
diff --git a/sphinx/README.rst b/sphinx/README.rst
new file mode 120000
index 0000000..89a0106
--- /dev/null
+++ b/sphinx/README.rst
@@ -0,0 +1 @@
+../README.rst
\ No newline at end of file
diff --git a/sphinx/glossary.rst b/sphinx/glossary.rst
new file mode 100644
index 0000000..e351c34
--- /dev/null
+++ b/sphinx/glossary.rst
@@ -0,0 +1,75 @@
+Pluggable transports glossary
+"""""""""""""""""""""""""""""
+
+pluggable transport (sometimes also called 'transport')
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Pluggable transports obfuscate network traffic.
+
+Specifically, pluggable transports transform the Tor traffic flow
+between the client and the bridge. This way, censors who monitor
+traffic between the client and the bridge see innocent-looking
+transformed traffic instead of the actual Tor traffic.
+
+pluggable transport proxy
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Pluggable transport proxies are programs that implement pluggable
+transports. They also implement the networking system that a pluggable
+transport needs (so that it can proxy data).
+
+obfsproxy
+^^^^^^^^^
+
+`obfsproxy <https://www.torproject.org/projects/obfsproxy.html.en>`_
+is a pluggable transport proxy written in C. It implements the `obfs2
+<https://gitweb.torproject.org/obfsproxy.git/blob/HEAD:/doc/obfs2/protocol-spec.txt>`_
+pluggable transport.
+
+
+upstream/downstream
+^^^^^^^^^^^^^^^^^^^
+
+The upstream side of a pluggable transport proxy is the side that
+communicates with Tor. Upstream data is non-obfuscated.
+
+The downstream side of a pluggable transport proxy is the side that
+communicates with the other pluggable transport proxy. Downstream data
+is obfuscated.
+
+client-mode / server-mode
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A pluggable transport is a client if it has a Tor client in its
+upstream side.
+
+A pluggable transport is a server if it has a Tor bridge in its
+upstream side.
+
+external-mode proxy
+^^^^^^^^^^^^^^^^^^^
+
+A pluggable transport proxy is in external-mode if the user explicitly
+configures it using its command-line interface.
+
+managed-mode proxy
+^^^^^^^^^^^^^^^^^^
+
+A pluggable transport proxy is in managed-mode if it's launched and
+managed by Tor using the managed-proxy configuration protocol. The
+managed-proxy configuration protocol is defined in the `pluggable
+transport specification
+<https://gitweb.torproject.org/torspec.git/blob/HEAD:/proposals/180-pluggable-transport.txt>`_.
+
+pyptlib
+^^^^^^^
+
+pyptlib is a library that implements the managed-proxy configuration
+protocol and makes it easier for application to be used as managed
+proxies.
+
+extended orport
+^^^^^^^^^^^^^^^
+
+Extended ORPort is an non-implemented feature of Tor that allows a
+pluggable transport proxy to communicate with Tor in real-time.
diff --git a/sphinx/index.rst b/sphinx/index.rst
index 30ba6b3..c765fef 100644
--- a/sphinx/index.rst
+++ b/sphinx/index.rst
@@ -6,10 +6,17 @@
Welcome to pyptlib!
===================================
-pyptlib is a little Python library which understands the 'pluggable
-transport managed-proxy protocol'.
+pyptlib is a little Python library that makes the job of writing
+pluggable transports easier.
+.. toctree::
+ :maxdepth: 2
+
+ README
+ API
+ glossary
+
:mod:`pyptlib.client`
----------------------
@@ -21,8 +28,11 @@ Client-side pyptlib API.
Server-side pyptlib API.
-.. toctree::
- :maxdepth: 2
+:mod:`pyptlib.util`
+----------------------
+
+pyptlib utilities.
+
Indices and tables
==================
--
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