# Installing txtorcon

## Latest Release

txtorcon is on PyPI and in Debian since jessie (thanks to Lunar and now irl!). So, one of these should work:

- install latest release: `pip install txtorcon`

- Debian or Ubuntu: `apt-get install python-txtorcon`

- Watch an asciinema demo for an overview.

Rendered documentation for the latest release is at txtorcon.readthedocs.org. What exists for release-notes are in “Releases”.

If you’re still using wheezy, `python-txtorcon` is also in wheezy-backports. To install, do this as root:

    # echo "deb http://ftp.ca.debian.org/debian/ wheezy-backports main" >> /etc/apt/sources.list
    # apt-get update
    # apt-get install python-txtorcon

It also appears txtorcon is in Gentoo but I don’t use Gentoo (if anyone has a shell-snippet that installs it, send a pull-request). I am told this package also needs a maintainer; see XXX.

Installing the wheel files requires a recent pip and setuptools. At least on Debian, it is important to upgrade setuptools before pip. This procedure appears to work fine:

    virtualenv foo
    . foo/bin/activate
    pip install --upgrade setuptools
    pip install --upgrade pip
    pip install path/to/txtorcon-*.whl

If you get an error like SyntaxError: invalid syntax on txtorcon/test/py3_torstate.py or similar, you have an out-of-date pip or setuptools; see above.

## Compatibility

txtorcon runs all tests cleanly under Python2, Python3 and PyPy on:

> - Debian: “squeeze”, “wheezy” and “jessie”

> - OS X: 10.4 (naif), 10.8 (lukas lueg), 10.9 (kurt neufeld)

> - Fedora 18 (lukas lueg)

> - FreeBSD 10 (enrique fynn) (needed to install “lsof”)

> - RHEL6

> - Reports from other OSes appreciated.

## Tor Configuration

Using Tor’s cookie authentication is the most convenient way to connect; this proves that your user can read a cookie file written by Tor. To enable this, you’ll want to have the following options on in your `torrc`:

    CookieAuthentication 1
    CookieAuthFileGroupReadable 1

Note that “Tor BrowserBundle” is configured this way by default, on port 9151. If you want to use unix sockets to speak to tor (highly recommended) add this to your config (Debian is already set up like this):

    ControlSocketsGroupWritable 1
    ControlSocket /var/run/tor/control

## Source Code

Most people will use the code from https://github.com/meejah/txtorcon The canonical URI is http://fjblvrw2jrxnhtg67qpbzi45r7ofojaoo3orzykesly2j3c2m3htapid.onion I sign tags with my public key (`meejah.asc`)

- `git clone https://github.com/meejah/txtorcon.git`

- `torsocks git clone git://fjblvrw2jrxnhtg67qpbzi45r7ofojaoo3orzykesly2j3c2m3htapid.onion/meejah/txtorcon.git`

Rendered documentation for the latest release is at txtorcon.readthedocs.org.

See Contributions if you wish to contribute back to txtorcon :)

## Development Environment

I like to set up my Python development like this:

    $ git clone https://github.com/meejah/txtorcon.git
    $ echo "if you later fork it on github, do this:"
    $ git remote add -f github git+ssh://git@github.com/<your github handle>/txtorcon.git
    $ cd txtorcon
    $ virtualenv venv
    $ source venv/bin/activate
    (venv)$ pip install --editable .[dev]  # "dev" adds more deps, like Sphinx
    (venv)$ make doc
    (venv)$ make test
    (venv)$ tox  # run all tests, in all supported configs

You can now edit code in the repository as normal. To submit a patch, the easiest way is to “clone” the txtorcon project, then “fork” on github and add a remote called “github” with your copy of the code to which you can push (`git remote add -f github git+ssh://git@github.com/<your github handle>/txtorcon.git`). The `-f` is so you don’t have to run `git fetch` right after.

Now, you can push a new branch you’ve made to GitHub with `git push github branch-name` and then examine it and open a pull-request. This will trigger Travis to run the tests, after which coverage will be produced (and a bot comments on the pull-request). If you require any more changes, the easiest thing to do is just commit them and push them. (If you know how, re-basing/re-arranging/squashing etc is nice to do too). See Contributions for more.

## Integration Tests

There are a couple of simple integration tests using Docker in the `integration/` directory; these make a `debootstrap`-built base image and then do the test inside containers cloned from this – no trusting `https://docker.io` required. See `integration/README` for more information.

If you’re on Debian, there’s a decent chance running `make txtorcon-tester` followed by `make integration` from the root of the checkout will work (the first commands ultimately runs `debootstrap` and some `apt` commands besides `docker` things).

## Dependencies / Requirements

These should have been installed by whichever method you chose above, but are listed here for completeness. You can get all the development requirements with e.g. `pip install txtorcon[dev]`.

- twisted: txtorcon should work with any Twisted 11.1.0 or newer. Twisted 15.4.0+ works with Python3, and so does txtorcon (if you find something broken on Py3 please file a bug).

- automat: “a library for concise, idiomatic Python expression of finite-state automata (particularly deterministic finite-state transducers).”

- ipaddress: a standard module in Python3, but requires installing the backported package on Python2.

- dev only: Sphinx if you want to build the documentation. In that case you’ll also need something called `python-repoze.sphinx.autointerface` (at least in Debian) to build the Interface-derived docs properly.

- dev only: coverage to run the code-coverage metrics.

- dev only cuv’ner for coverage visualization

- dev only: Tox to run different library revisions.

- dev optional: GraphViz is used in the tests (and to generate state-machine diagrams, if you like) but those tests are skipped if “dot” isn’t in your path

In any case, on a Debian wheezy, squeeze or Ubuntu system, this should work (as root):

    # apt-get install -y python-setuptools python-twisted python-ipaddress graphviz tor
    # echo "for development:"
    # apt-get install -y python-sphinx python-repoze.sphinx.autointerface python-coverage libgeoip-dev

Using pip this would be:

    $ pip install --user Twisted ipaddress pygeoip
    $ echo "for development:"
    $ pip install --user GeoIP Sphinx repoze.sphinx.autointerface coverage

or:

    $ pip install -r requirements.txt
    $ pip install -r dev-requirements.txt