1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
|
Metadata-Version: 2.1
Name: txtorcon
Version: 20.0.0
Summary: Twisted-based Tor controller client, with state-tracking and configuration abstractions. https://txtorcon.readthedocs.org https://github.com/meejah/txtorcon
Home-page: https://github.com/meejah/txtorcon
Author: meejah
Author-email: meejah@meejah.ca
License: MIT
Description:
.. _NOTE: see docs/index.rst for the starting-point
.. _ALSO: https://txtorcon.readthedocs.org for rendered docs
.. image:: https://travis-ci.org/meejah/txtorcon.png?branch=master
:target: https://www.travis-ci.org/meejah/txtorcon
:alt: travis
.. image:: https://coveralls.io/repos/meejah/txtorcon/badge.png
:target: https://coveralls.io/r/meejah/txtorcon
:alt: coveralls
.. image:: http://codecov.io/github/meejah/txtorcon/coverage.svg?branch=master
:target: http://codecov.io/github/meejah/txtorcon?branch=master
:alt: codecov
.. image:: https://readthedocs.org/projects/txtorcon/badge/?version=stable
:target: https://txtorcon.readthedocs.io/en/stable
:alt: ReadTheDocs
.. image:: https://readthedocs.org/projects/txtorcon/badge/?version=latest
:target: https://txtorcon.readthedocs.io/en/latest
:alt: ReadTheDocs
.. image:: https://landscape.io/github/meejah/txtorcon/master/landscape.svg?style=flat
:target: https://landscape.io/github/meejah/txtorcon/master
:alt: Code Health
txtorcon
========
- **docs**: https://txtorcon.readthedocs.org or http://timaq4ygg2iegci7.onion
- **code**: https://github.com/meejah/txtorcon
- ``torsocks git clone git://timaq4ygg2iegci7.onion/txtorcon.git``
- MIT-licensed;
- Python 2.7, PyPy 5.0.0+, Python 3.5+;
- depends on
`Twisted`_,
`Automat <https://github.com/glyph/automat>`_,
(and the `ipaddress <https://pypi.python.org/pypi/ipaddress>`_ backport for non Python 3)
Ten Thousand Feet
-----------------
txtorcon is an implementation of the `control-spec
<https://gitweb.torproject.org/torspec.git/blob/HEAD:/control-spec.txt>`_
for `Tor <https://www.torproject.org/>`_ using the `Twisted`_
networking library for `Python <http://python.org/>`_.
This is useful for writing utilities to control or make use of Tor in
event-based Python programs. If your Twisted program supports
endpoints (like ``twistd`` does) your server or client can make use of
Tor immediately, with no code changes. Start your own Tor or connect
to one and get live stream, circuit, relay updates; read and change
config; monitor events; build circuits; create onion services;
etcetera (`ReadTheDocs <https://txtorcon.readthedocs.org>`_).
Some Possibly Motivational Example Code
---------------------------------------
`download <examples/readme.py>`_
(also `python2 style <examples/readme2.py>`_)
.. code:: python
from twisted.internet.task import react
from twisted.internet.defer import inlineCallbacks, ensureDeferred
from twisted.internet.endpoints import UNIXClientEndpoint
import treq
import txtorcon
async def main(reactor):
tor = await txtorcon.connect(
reactor,
UNIXClientEndpoint(reactor, "/var/run/tor/control")
)
print("Connected to Tor version {}".format(tor.version))
url = u'https://www.torproject.org:443'
print(u"Downloading {}".format(repr(url)))
resp = await treq.get(url, agent=tor.web_agent())
print(u" {} bytes".format(resp.length))
data = await resp.text()
print(u"Got {} bytes:\n{}\n[...]{}".format(
len(data),
data[:120],
data[-120:],
))
print(u"Creating a circuit")
state = await tor.create_state()
circ = await state.build_circuit()
await circ.when_built()
print(u" path: {}".format(" -> ".join([r.ip for r in circ.path])))
print(u"Downloading meejah's public key via above circuit...")
config = await tor.get_config()
resp = await treq.get(
u'https://meejah.ca/meejah.asc',
agent=circ.web_agent(reactor, config.socks_endpoint(reactor)),
)
data = await resp.text()
print(data)
@react
def _main(reactor):
return ensureDeferred(main(reactor))
Try It Now On Debian/Ubuntu
---------------------------
For example, serve some files via an onion service (*aka* hidden
service):
.. code-block:: shell-session
$ sudo apt-get install --install-suggests python3-txtorcon
$ twistd -n web --port "onion:80" --path ~/public_html
Read More
---------
All the documentation starts `in docs/index.rst
<docs/index.rst>`_. Also hosted at `txtorcon.rtfd.org
<https://txtorcon.readthedocs.io/en/latest/>`_.
You'll want to start with `the introductions <docs/introduction.rst>`_ (`hosted at RTD
<https://txtorcon.readthedocs.org/en/latest/introduction.html>`_).
.. _Twisted: https://twistedmatrix.com/trac
Keywords: python,twisted,tor,tor controller
Platform: UNKNOWN
Classifier: Framework :: Twisted
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: Internet
Classifier: Topic :: Security
Provides-Extra: dev
|