aiostem 0.4.7

Asynchronous Tor controller library for asyncio and Python

aiostem is an asyncio python library that provides a controller to connect and interact with the Tor control port. It therefore acts as an alternative to the community-maintained stem controller.

What about Stem?

Stem was not meant to be used with asynchronous python and despite an attempt to support this framework, it has never really worked well and was never merged. Additionally it does not use a true asynchronous connection but instead uses worker threads in order not to break existing code.

The initial goal of aiostem was to offer better support for events, as there can be many of them coming at a high rate and I noticed that stem quickly ran into deadlocks and high CPU usage. Moreover, I feel like stem provides too many high level APIs and it is hard to know exactly what is performed under the hood. It has also become too complex and bloated with legacy code, both for a large range of Python versions and support for old versions of Tor.

Tor v0.4.x has been released for many years now, therefore aiostem focuses the support for Tor v0.4.5 and later, as well as Python 3.10 and later.

Additionally, stem does not provide a low-level API around the control protocol, which means that there is time wasted registering and unregistering events all around. aiostem focuses on a clean implementation of the low level protocol, providing far better performances when dealing with a higher number of events.

However, aiostem is not a drop-in replacement for stem since we do not handle the following features:

• Parsing of server and relay descriptors as in stem.descriptor (we have HS descriptors).

• Higher (and easier) level APIs mixing commands and events in a single call.

• Run a Tor daemon from library calls as in stem.process.

• Download server descriptors as in stem.descriptor.remote.

• Command line interpreter as in stem.interpreter.

• Support for older versions of Tor and Python.

Installation

This package requires Python ≥ 3.10 and pulls a few other packages as dependencies such as pydantic for serialization, deserialization and validation of received data, and cryptography to deal with the various keys used by Tor.

To install the latest version use the following command:

python -m pip install aiostem

Usage

This simple example shows how to use the controller in asynchronous python. No extra thread is involved here, everything runs in the event loop.

It shows how to open a controller, authenticate, subscribe to an event, run a command and wait for the DNS resolution event to complete.

#!/usr/bin/env python

import asyncio
from functools import partial
from aiostem import Controller
from aiostem.event import EventAddrMap

def on_addrmap_event(done, event):
    if isinstance(event, EventAddrMap):
        print(f'{event.original} is at {event.replacement}')
        done.set()

async def main():
    # Simple asyncio event to exit when the event has been received.
    done = asyncio.Event()

    # Create a new controller with the default port (9051).
    async with Controller.from_port() as ctrl:
        # Authenticate automatically with a secure method (on localhost only).
        reply = await ctrl.authenticate()
        reply.raise_for_status()

        # Register a callback for ``ADDRMAP`` events.
        await ctrl.add_event_handler('ADDRMAP', partial(on_addrmap_event, done))

        # Request DNS resolution for ``github.com``.
        # The output here is received as an ``ADDRMAP`` event.
        reply = await ctrl.resolve(['github.com'])
        reply.raise_for_status()

        # Wait until the address is resolved.
        await done.wait()

if __name__ == '__main__':
    asyncio.run(main())

This code, when executed displays the following output:

$ python examples/usage.py
github.com is at 140.82.121.4

For further details, please refer to the documentation.

Contributing

Contributions, bug reports and feedback are very welcome, feel free to open an issue, send a pull request. or start a discussion.

Participants must uphold the Code of Conduct.

aiostem is released under the MIT license.