### Install Wheel Files

Source: https://github.com/meejah/txtorcon/blob/main/docs/installing.rst

Procedure to upgrade setuptools and pip before installing a local wheel file.

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

--------------------------------

### Install and Serve Onion Service

Source: https://github.com/meejah/txtorcon/blob/main/README.rst

Commands to install txtorcon on Debian/Ubuntu and start a web server as an onion service.

```shell-session
$ sudo apt-get install --install-suggests python3-txtorcon
$ twistd -n web --port "onion:80" --path ~/public_html
```

--------------------------------

### Install from Debian Backports

Source: https://github.com/meejah/txtorcon/blob/main/docs/installing.rst

Commands to add the wheezy-backports repository and install the package as root.

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

--------------------------------

### Basic txtorcon Usage Example

Source: https://github.com/meejah/txtorcon/blob/main/docs/introduction.rst

A foundational example demonstrating how to interact with the Tor control port using txtorcon.

```python
from twisted.internet import reactor, defer
from txtorcon import connect, launch


@defer.inlineCallbacks
def setup(tor):
    print("Connected to Tor version {}".format(tor.version))
    state = yield tor.create_state()
    print("This Tor has {} circuits.".format(len(state.circuits)))

    # create a hidden service
    hs = yield tor.create_onion_service(80, [8080])
    print("Created hidden service: {}".format(hs.hostname))


# either launch a new Tor or connect to an existing one
# d = launch(reactor, tor_binary='/usr/bin/tor')
d = connect(reactor)
d.addCallback(setup)
reactor.run()
```

--------------------------------

### Set Up Development Environment

Source: https://github.com/meejah/txtorcon/blob/main/docs/installing.rst

Commands to clone the repository, create a virtual environment, and install development dependencies.

```shell-session
$ 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
```

--------------------------------

### Install Txtorcon Dependencies with pip (User)

Source: https://github.com/meejah/txtorcon/blob/main/docs/installing.rst

Installs core Txtorcon dependencies and development tools using pip for the current user. This is an alternative to system-wide installation.

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

--------------------------------

### Install and Run Onion Service via twistd

Source: https://github.com/meejah/txtorcon/blob/main/docs/introduction.rst

Use the shell to install txtorcon and launch a web server as an onion service using Twisted's twistd.

```shell-session
$ sudo apt-get install --install-suggests python-txtorcon
$ twistd web --port "onion:80" --path ~/public_html
```

--------------------------------

### Verify SHA256 Checksums via Shell

Source: https://github.com/meejah/txtorcon/blob/main/docs/release-checklist.rst

Example of how to verify checksums using a heredoc and sha256sum.

```bash
cat <<EOF | sha256sum --check
910ff3216035de0a779cfc167c0545266ff1f26687b163fc4655f298aca52d74 txtorcon-0.10.0-py3-none-any.whl
c93f3d0f21d53c6b4c1521fc8d9dc2c9aff4a9f60497becea207d1738fa78279  txtorcon-0.10.0.tar.gz
EOF
```

--------------------------------

### Install Txtorcon Dependencies with pip (Requirements Files)

Source: https://github.com/meejah/txtorcon/blob/main/docs/installing.rst

Installs Txtorcon dependencies by referencing requirement files. This method is useful for managing project-specific dependencies.

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

--------------------------------

### Install Txtorcon Dependencies with apt-get

Source: https://github.com/meejah/txtorcon/blob/main/docs/installing.rst

Installs core Txtorcon dependencies and development tools using apt-get on Debian/Ubuntu systems. Ensure you are running these commands as root.

```shell
# 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
```

--------------------------------

### Traverse and Close Circuits

Source: https://github.com/meejah/txtorcon/blob/main/docs/guide.rst

Example script demonstrating how to iterate through circuits, print router IDs, and close streams and circuits.

```python
.. literalinclude:: ../examples/close_all_circuits.py
```

--------------------------------

### Launch Tor with Hidden Service Endpoint

Source: https://github.com/meejah/txtorcon/blob/main/docs/examples.rst

Uses txtorcon.TCP4HiddenServiceEndpoint to start Tor with a hidden service. This allows creating services accessible only through Tor.

```python
import txtorcon
from twisted.internet import reactor, endpoints


def main(reactor):
    # Define the hidden service endpoint
    # This will create a hidden service and listen on the specified port
    hidden_service_endpoint = txtorcon.TCP4HiddenServiceEndpoint(reactor, 'localhost', 80, 'my_hidden_service')

    # Launch Tor and configure the hidden service
    d = txtorcon.launch_tor(reactor, config=
        [('HiddenServiceDir', 'hs_data'),
         ('HiddenServicePort', '80 127.0.0.1:8000')]) # Example config

    def cb_launch(tor_process):
        print('Tor launched. Hidden service configured.')
        # You would typically start your application's listening service here
        # For example: reactor.listenTCP(8000, MyServiceFactory())
        return tor_process

    d.addCallback(cb_launch)
    d.addBoth(lambda _: reactor.stop())
    return d


if __name__ == '__main__':
    reactor.callWhenRunning(lambda: main(reactor))
    reactor.run()

```

--------------------------------

### Get Single INFO Key

Source: https://github.com/meejah/txtorcon/blob/main/docs/releases.rst

Retrieves a single INFO key from Tor asynchronously. Returns the value directly instead of a dictionary.

```python
await self.get_info_single('Key')
```

--------------------------------

### Get Single GETCONF Key

Source: https://github.com/meejah/txtorcon/blob/main/docs/releases.rst

Retrieves a single GETCONF key from Tor asynchronously. Returns the value directly instead of a dictionary.

```python
await self.get_conf_single('Key')
```

--------------------------------

### Connect and Get Tor Info

Source: https://context7.com/meejah/txtorcon/llms.txt

Connects to Tor using a UNIX socket and retrieves various information including version, circuit status, and traffic statistics. Requires Twisted and Txtorcon libraries.

```python
from twisted.internet.task import react
from twisted.internet.defer import inlineCallbacks
from twisted.internet.endpoints import UNIXClientEndpoint
import txtorcon

@react
@inlineCallbacks
def main(reactor):
    tor = yield txtorcon.connect(
        reactor,
        UNIXClientEndpoint(reactor, '/var/run/tor/control')
    )

    proto = tor.protocol

    # Get Tor info
    version = yield proto.get_info('version')
    print("Tor version: {}".format(version))

    # Get multiple info values
    info = yield proto.get_info(
        'status/version/current',
        'status/circuit-established',
        'traffic/read',
        'traffic/written'
    )
    print("Version status: {}".format(info['status/version/current']))
    print("Circuit established: {}".format(info['status/circuit-established']))
    print("Traffic read: {} bytes".format(info['traffic/read']))
    print("Traffic written: {} bytes".format(info['traffic/written']))

    # Add event listeners
    def on_notice(msg):
        print("NOTICE: {}".format(msg))
    yield proto.add_event_listener('NOTICE', on_notice)

    # Issue raw commands
    result = yield proto.queue_command('GETINFO dormant')
    print("Dormant status: {}".format(result))

    # Signal Tor
    yield proto.signal('NEWNYM')  # Get new circuits
    print("Requested new identity (NEWNYM)")
```

--------------------------------

### Build and Use Custom Circuits

Source: https://context7.com/meejah/txtorcon/llms.txt

Demonstrates building a custom circuit, waiting for it to be ready, and then using it to make a web request or establish a TCP stream. Custom circuit selection may affect anonymity.

```python
from twisted.internet.task import react
from twisted.internet.defer import inlineCallbacks
from twisted.internet.endpoints import TCP4ClientEndpoint
from twisted.web.client import readBody
import txtorcon

@react
@inlineCallbacks
def main(reactor):
    tor = yield txtorcon.connect(
        reactor,
        TCP4ClientEndpoint(reactor, '127.0.0.1', 9051)
    )

    config = yield tor.get_config()
    state = yield tor.create_state()

    # Build a circuit (Tor selects the path)
    circ = yield state.build_circuit()
    print("Building circuit {}".format(circ.id))

    # Wait for circuit to be ready
    yield circ.when_built()
    print("Circuit built through: {}".format(
        " -> ".join([r.name for r in circ.path])
    ))

    # Create a web agent using this specific circuit
    socks = config.socks_endpoint(reactor)
    agent = circ.web_agent(reactor, socks)

    # Make a request over this specific circuit
    resp = yield agent.request(b'GET', b'https://check.torproject.org')
    body = yield readBody(resp)
    print("Response via custom circuit: {} bytes".format(len(body)))

    # Or use stream_via for arbitrary TCP connections
    endpoint = circ.stream_via(reactor, 'example.com', 80, socks)
    # Use endpoint.connect(factory) for custom protocols

    # Close the circuit when done
    yield circ.close()
```

--------------------------------

### Prepare Environment and Verify Metadata

Source: https://github.com/meejah/txtorcon/blob/main/docs/release-checklist.rst

Commands to ensure the local repository is up to date and the package metadata is ready for release.

```bash
git checkout main
git pull
```

```bash
python setup.py check -r -s
tox -e readme_render
```

--------------------------------

### Launch Tor and Access Configuration

Source: https://github.com/meejah/txtorcon/blob/main/docs/guide.rst

Launches a Tor instance and demonstrates accessing and modifying its configuration. Configuration changes are applied only when .save() is called.

```python
tor = launch(..)
print("SOCKS ports: {}".format(tor.config.SOCKSPort))
tor.config.ControlPort.append(4321)
tor.config.save()
```

--------------------------------

### Connect to Tor and Build Circuits

Source: https://github.com/meejah/txtorcon/blob/main/README.rst

Demonstrates connecting to a Tor control port, performing web requests, and building a custom circuit.

```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))
```

--------------------------------

### launch

Source: https://github.com/meejah/txtorcon/blob/main/docs/txtorcon-controller.rst

Method to launch a new Tor instance.

```APIDOC
## launch

### Description
Launches a new Tor process and returns a controller instance.
```

--------------------------------

### Get Relay Descriptor Information

Source: https://github.com/meejah/txtorcon/blob/main/docs/examples.rst

Retrieves information about a Tor relay descriptor using Stem's RelayDescriptor class. Requires specifying the relay's nickname or fingerprint.

```python
from stem.descriptor import RelayDescriptor
from stem.descriptor.server_descriptor import ServerDescriptor


def get_relay_info(nickname_or_fingerprint):
    try:
        # Attempt to get a server descriptor
        desc = ServerDescriptor.from_get_info(nickname_or_fingerprint)
        print(f"Nickname: {desc.nickname}")
        print(f"Fingerprint: {desc.fingerprint}")
        print(f"OR Port: {desc.or_port}")
        print(f"Exit Policy: {desc.exit_policy}")
        return desc
    except Exception as e:
        print(f"Error retrieving descriptor for {nickname_or_fingerprint}: {e}")
        return None


if __name__ == '__main__':
    # Replace with a real Tor relay nickname or fingerprint
    relay_identifier = 'YourRelayNicknameOrFingerprint' 
    get_relay_info(relay_identifier)

```

--------------------------------

### Create Ephemeral Onion Services

Source: https://context7.com/meejah/txtorcon/llms.txt

Shows how to create temporary onion services that exist only while the application runs. The private key can be saved to recreate the same .onion address later.

```python
from twisted.internet.task import react
from twisted.internet.defer import inlineCallbacks, Deferred
from twisted.internet.endpoints import TCP4ClientEndpoint, TCP4ServerEndpoint
from twisted.web import server, resource
import txtorcon

class HelloWorld(resource.Resource):
    isLeaf = True
    def render_GET(self, request):
        return b"<html>Hello from my Onion Service!</html>"

@react
@inlineCallbacks
def main(reactor):
    tor = yield txtorcon.connect(
        reactor,
        TCP4ClientEndpoint(reactor, "localhost", 9051)
    )

    # Create an ephemeral onion service
    # ports: list of (public_port, local_port) tuples
    onion = yield tor.create_onion_service(
        ports=[(80, 8080)],           # Public port 80 -> local port 8080
        version=3,                     # Use v3 onion addresses
        progress=lambda p, t, s: print(f"Onion setup: {p}% - {s}")
    )

    print("Onion address: {}".format(onion.hostname))
    print("Private key (save to recreate this address):")
    print(onion.private_key)

    # Start local server on port 8080
    local_ep = TCP4ServerEndpoint(reactor, 8080, interface="127.0.0.1")
    yield local_ep.listen(server.Site(HelloWorld()))

    print("Service running at http://{}".format(onion.hostname))

    # To recreate the same address later, pass private_key=
    # onion = yield tor.create_onion_service(
    #     ports=[(80, 8080)],
    #     private_key="ED25519-V3:base64keydata...",
    #     version=3
    # )

    yield Deferred()  # Run forever
```

--------------------------------

### Launch a New Tor Process

Source: https://context7.com/meejah/txtorcon/llms.txt

Launch a new Tor instance programmatically. Specify a data directory for persistence and faster restarts, custom SOCKS ports, and optionally redirect Tor's output. Progress updates during bootstrap are provided via a callback.

```python
from twisted.internet.task import react
from twisted.internet.defer import inlineCallbacks
import txtorcon
import sys

@react
@inlineCallbacks
def main(reactor):
    # Launch a new Tor process with custom data directory
    tor = yield txtorcon.launch(
        reactor,
        data_directory="./tor_data",      # Persist state for faster restarts
        socks_port=9999,                   # Custom SOCKS port
        stdout=sys.stdout,                 # Show Tor's output
        progress_updates=lambda p, t, s: print(f"Bootstrap: {p}% - {s}")
    )

    print("Launched Tor version {}".format(tor.protocol.version))

    # Access the running Tor's state
    state = yield tor.create_state()
    print("Tor PID: {}".format(state.tor_pid))

    # Modify configuration at runtime
    config = yield tor.get_config()
    config.SOCKSPort = ['9876']
    yield config.save()

    # When done, shut down the Tor process
    yield tor.quit()
```

--------------------------------

### Create Filesystem-Based Onion Services

Source: https://context7.com/meejah/txtorcon/llms.txt

Demonstrates creating persistent onion services with keys stored on disk. Tor manages the key files automatically in the specified directory.

```python
from twisted.internet.task import react
from twisted.internet.defer import inlineCallbacks, Deferred
from twisted.internet.endpoints import TCP4ClientEndpoint, TCP4ServerEndpoint
from twisted.web import server, resource
import txtorcon

class MyService(resource.Resource):
    isLeaf = True
    def render_GET(self, request):
        return b"<html>Persistent Onion Service</html>"

@react
@inlineCallbacks
def main(reactor):
    tor = yield txtorcon.connect(
        reactor,
        TCP4ClientEndpoint(reactor, "localhost", 9051)
    )

    # Create filesystem-based onion service
    # Tor stores private key in ./my_hidden_service/
    onion = yield tor.create_filesystem_onion_service(
        ports=[(80, 8787)],               # Public 80 -> local 8787
        onion_service_dir="./my_hidden_service",
        version=3,
        group_readable=False,              # Strict permissions
        progress=lambda p, t, s: print(f"{p}%: {s}")
    )

    print("Service hostname: {}".format(onion.hostname))
    print("Keys stored in: {}".format(onion.dir))

    # Start local web server
    ep = TCP4ServerEndpoint(reactor, 8787, interface="localhost")
    yield ep.listen(server.Site(MyService()))

    yield Deferred()  # Run forever
```

--------------------------------

### Create Twisted Service for Txtorcon Deployment

Source: https://github.com/meejah/txtorcon/blob/main/docs/examples.rst

Provides a template for creating a Twisted Service using a .tac file for deployment with 'twistd'. This service can be configured to use Txtorcon.

```python
from twisted.application import service, internet
from twisted.internet import reactor
import txtorcon


class TxtorconService(service.Service):
    """A Twisted service that uses Txtorcon."""

    def __init__(self, tor_control_port=None):
        self.tor_control_port = tor_control_port
        self.tor_client = None

    def startService(self):
        """Start the Txtorcon client connection."""
        print("Starting Txtorcon service...")
        # Connect to Tor using Txtorcon
        d = txtorcon.TorClientFactory.connect(reactor, port=self.tor_control_port)

        def cb_connect(tor_client):
            self.tor_client = tor_client
            print(f"Connected to Tor control port: {tor_client.protocol.transport.getPeer()}")
            # You can now use self.tor_client to interact with Tor
            # For example, start listening for events or build circuits
            return tor_client

        def eb_connect(failure):
            print(f"Failed to connect to Tor: {failure.getErrorMessage()}")
            # Optionally, stop the service or retry connection
            self.stopService()
            return failure

        d.addCallbacks(cb_connect, eb_connect)

    def stopService(self):
        """Stop the Txtorcon client connection."""
        print("Stopping Txtorcon service...")
        if self.tor_client and self.tor_client.protocol.transport.connected:
            self.tor_client.protocol.transport.loseConnection()
        service.Service.stopService(self)


def makeService(options):
    """Factory function for twistd."""
    # Create the main application service
    application = service.Application("TxtorconApp")

    # Create and start the TxtorconService
    txtorcon_svc = TxtorconService(tor_control_port=options.get('tor_control_port'))
    txtorcon_svc.setServiceParent(application)

    # Example: Add a TCP server endpoint if needed
    # tcp_server = internet.TCPServer(8080, MyHTTPFactory())
    # tcp_server.setServiceParent(application)

    return application

# To run this with twistd:
# 1. Save this code as txtorcon.tac
# 2. Run: twistd -noy txtorcon.tac
# You can pass options like: twistd -noy txtorcon.tac --tor_control_port=9051

```

--------------------------------

### Download Web Page with Custom Circuit

Source: https://github.com/meejah/txtorcon/blob/main/docs/examples.rst

Builds a custom Tor circuit and then uses twisted.web.client.Agent to download a web page using that specific circuit. This allows for more control over the network path.

```python
import txtorcon
from twisted.internet import reactor, defer
from twisted.web.client import Agent


def get_page_on_circuit(agent, url, circuit):
    # Agent needs to be told to use a specific circuit
    # This is typically done by passing the circuit's endpoint to the Agent constructor
    # or by using a specific method if available.
    # The exact mechanism might depend on the Agent's implementation and how it handles circuits.
    # For this example, we assume Agent can be configured to use a specific circuit.
    print(f"Attempting to fetch {url.decode()} on circuit {circuit.id}")
    # Placeholder for actual request using the circuit
    # d = agent.request(b'GET', url, __reactor=reactor, __circuit=circuit) # Conceptual
    d = defer.Deferred()
    reactor.callLater(2, d.callback, b'Simulated response body') # Simulate response
    return d


def main(reactor):
    # Connect to Tor
    d = txtorcon.TorClientFactory.connect(reactor)

    def cb_connect(tor_client):
        # Create an Agent that uses Tor
        agent = Agent(reactor, connect=tor_client.requests_endpoint)

        # Build a new circuit
        d_circuit = tor_client.build_circuit(purpose='general')

        def cb_circuit(circuit):
            print(f"Built circuit: {circuit.id}")
            # Now use the agent with the custom circuit
            return get_page_on_circuit(agent, b'http://example.com', circuit)

        d_circuit.addCallback(cb_circuit)
        return d_circuit

    d.addCallback(cb_connect)
    d.addBoth(lambda _: reactor.stop())
    return d


if __name__ == '__main__':
    reactor.callWhenRunning(lambda: main(reactor))
    reactor.run()

```

--------------------------------

### Create Signed Git Tag

Source: https://github.com/meejah/txtorcon/blob/main/docs/release-checklist.rst

Command to create a GPG-signed tag for the release.

```bash
git tag -s -u meejah@meejah.ca -F release-announce-${VERSION} v${VERSION}
```

--------------------------------

### util.NetLocation

Source: https://github.com/meejah/txtorcon/blob/main/docs/txtorcon-util.rst

Documentation for the NetLocation class.

```APIDOC
## Class txtorcon.util.NetLocation

### Description
Represents network location information within the txtorcon framework.
```

--------------------------------

### IProgressProvider

Source: https://github.com/meejah/txtorcon/blob/main/docs/txtorcon-endpoints.rst

Interface for progress reporting.

```APIDOC
## IProgressProvider

### Description
Interface for progress reporting.

### Interface
`txtorcon.IProgressProvider`
```

--------------------------------

### Create Authenticated Filesystem Onion Endpoint

Source: https://github.com/meejah/txtorcon/blob/main/docs/releases.rst

Creates an endpoint for an authenticated Onion service where the authentication credentials (private keys) are stored in a specified directory. This is useful for persistent Onion services.

```python
await self.create_authenticated_filesystem_onion_endpoint('service_id', 'auth_token', '/path/to/keys')
```

--------------------------------

### build_local_tor_connection

Source: https://github.com/meejah/txtorcon/blob/main/docs/txtorcon-protocol.rst

Builds a local Tor connection.

```APIDOC
## build_local_tor_connection

### Description
Builds a local Tor connection.

### Method
(Not specified, likely a function call)

### Endpoint
(Not applicable, this is a function)

### Parameters
(Parameters not specified in the provided text)

### Request Example
(Not applicable)

### Response
(Response details not specified in the provided text)
```

--------------------------------

### Verify Distribution Signatures

Source: https://github.com/meejah/txtorcon/blob/main/docs/release-checklist.rst

Commands to verify the integrity of the signed distribution files.

```bash
gpg --verify dist/txtorcon-${VERSION}-py3-none-any.whl.asc
gpg --verify dist/txtorcon-${VERSION}.tar.gz.asc
```

--------------------------------

### Create Filesystem Onion Endpoint

Source: https://github.com/meejah/txtorcon/blob/main/docs/releases.rst

Creates an endpoint for a non-authenticated Onion service, using private keys stored in a specified directory. This is suitable for persistent, non-authenticated Onion services.

```python
await self.create_filesystem_onion_endpoint('service_id', '/path/to/keys')
```

--------------------------------

### connect

Source: https://github.com/meejah/txtorcon/blob/main/docs/txtorcon-controller.rst

Method to connect to an existing Tor instance.

```APIDOC
## connect

### Description
Connects to an existing Tor instance via the control port.
```

--------------------------------

### build_tor_connection

Source: https://github.com/meejah/txtorcon/blob/main/docs/txtorcon-protocol.rst

Builds a Tor connection.

```APIDOC
## build_tor_connection

### Description
Builds a Tor connection.

### Method
(Not specified, likely a function call)

### Endpoint
(Not applicable, this is a function)

### Parameters
(Parameters not specified in the provided text)

### Request Example
(Not applicable)

### Response
(Response details not specified in the provided text)
```

--------------------------------

### util.process_from_address

Source: https://github.com/meejah/txtorcon/blob/main/docs/txtorcon-util.rst

Documentation for the process_from_address utility method.

```APIDOC
## Method util.process_from_address

### Description
Retrieves process information based on a provided address.
```

--------------------------------

### Filesystem Onion Service Classes

Source: https://github.com/meejah/txtorcon/blob/main/docs/txtorcon-onion.rst

Classes for managing onion services that persist secret keys to the local disk.

```APIDOC
## Filesystem Onion Service Classes

### Description
Classes for creating and managing onion services that store secret keys on disk.

### Classes
- **FilesystemOnionService**: Implementation for standard filesystem-backed services.
- **FilesystemAuthenticatedOnionService**: Implementation for filesystem-backed services requiring authentication.
- **FilesystemAuthenticatedOnionServiceClient**: Client implementation for filesystem-backed authenticated services.
```

--------------------------------

### Launch a New Tor Instance

Source: https://github.com/meejah/txtorcon/blob/main/docs/examples.rst

Launches a new Tor instance and ensures it exits when the control connection is closed. This is useful for isolated Tor processes.

```python
import txtorcon
from twisted.internet import reactor


def main(reactor):
    # Launch Tor
    d = txtorcon.launch_tor(reactor, tor_cmd=['tor'], data_dir=None, configfile=None)

    def cb_launch(tor_process):
        print('Tor launched with PID: {0}'.format(tor_process.pid))
        # The Tor process will exit when the control connection is closed
        # You can interact with tor_process here if needed
        return tor_process

    d.addCallback(cb_launch)
    # Keep the reactor running until Tor exits
    d.addBoth(lambda _: reactor.stop())
    return d


if __name__ == '__main__':
    reactor.callWhenRunning(lambda: main(reactor))
    reactor.run()

```

--------------------------------

### Manage Tor Circuits and Streams with TorState

Source: https://context7.com/meejah/txtorcon/llms.txt

Use the TorState object to programmatically close circuits and streams, and iterate over network state. Requires a running Tor instance with control port enabled.

```python
from twisted.internet.task import react
from twisted.internet.defer import inlineCallbacks
from twisted.internet.endpoints import UNIXClientEndpoint
import txtorcon

@react
@inlineCallbacks
def main(reactor):
    tor = yield txtorcon.connect(
        reactor,
        UNIXClientEndpoint(reactor, '/var/run/tor/control')
    )
    state = yield tor.create_state()

    # Iterate over all circuits
    print("Current circuits:")
    for circuit in state.circuits.values():
        path = ' -> '.join([r.id_hex[:8] for r in circuit.path])
        print("  Circuit {} ({}): {} - {}".format(
            circuit.id, circuit.state, circuit.purpose, path
        ))

        # List streams on this circuit
        for stream in circuit.streams:
            print("    Stream {} to {}:{}".format(
                stream.id, stream.target_host, stream.target_port
            ))

    # Close a specific circuit (by ID or instance)
    if state.circuits:
        circ = list(state.circuits.values())[0]
        print("Closing circuit {}".format(circ.id))
        yield circ.close()

    # Access routers/relays
    print("\nEntry guards:")
    for name, router in state.entry_guards.items():
        print("  {}: {} ({})".format(name[:8], router.name, router.ip))

    yield tor.quit()
```

--------------------------------

### Configuration and Information Retrieval

Source: https://github.com/meejah/txtorcon/blob/main/docs/releases.rst

APIs for retrieving single configuration values and single information values from Tor.

```APIDOC
## Configuration and Information Retrieval

### Description
Methods to retrieve specific configuration and information values from Tor.

### Methods

#### `get_conf_single`

##### Description
Retrieves a single GETCONF key from Tor.

##### Method
`async`

##### Returns
`str` - The value of the requested GETCONF key.

#### `get_info_single`

##### Description
Retrieves a single INFO key from Tor.

##### Method
`async`

##### Returns
`str` - The value of the requested INFO key.

```

--------------------------------

### Serve Onion Services with Endpoint Strings

Source: https://context7.com/meejah/txtorcon/llms.txt

Use Twisted's endpoint string syntax with the 'onion:' prefix for zero-code Tor integration. Any endpoint-supporting Twisted application can serve onion services with just a configuration change.

```python
from twisted.internet import defer, task, endpoints
from twisted.web import server, resource
import txtorcon

class Simple(resource.Resource):
    isLeaf = True
    def render_GET(self, request):
        return b"<html>Hello via endpoint string!</html>"

@defer.inlineCallbacks
def main(reactor):
    # Create onion service using endpoint string syntax
    # Format: onion:PORT[:key=value...]
    ep = endpoints.serverFromString(reactor, "onion:80:controlPort=9051")

    # Optional: listen for progress updates
    def on_progress(percent, tag, msg):
        print('{:3d}%: {}'.format(percent, msg))
    txtorcon.IProgressProvider(ep).add_progress_listener(on_progress)

    # Start listening (creates the onion service)
    port = yield ep.listen(server.Site(Simple()))

    print("Listening at: {}".format(port.getHost()))
    print("Onion address: {}".format(port.getHost().onion_uri))
    print("Private key: {}".format(port.getHost().onion_key))

    # To recreate with same address, use privateKey= parameter:
    # ep = endpoints.serverFromString(reactor,
    #     "onion:80:privateKey=ED25519-V3\\:base64key...")

    yield defer.Deferred()  # Run forever

task.react(main)
```

--------------------------------

### TorSocksEndpoint Class

Source: https://github.com/meejah/txtorcon/blob/main/docs/txtorcon-socks.rst

Documentation for the TorSocksEndpoint class used for SOCKS endpoints.

```APIDOC
## TorSocksEndpoint Class

.. autoclass:: txtorcon.socks.TorSocksEndpoint
```

--------------------------------

### Iterate Through Tor Configuration Options

Source: https://github.com/meejah/txtorcon/blob/main/docs/guide.rst

Iterates through all available Tor configuration options using the TorConfig object. This helps in discovering supported configuration keys and their current values.

```python
tor = launch(..)
for config_key in tor.config:
    print("{} has value: {}".format(config_key, getattr(tor.config.config_key)))
```

--------------------------------

### Creating Onion Endpoints

Source: https://github.com/meejah/txtorcon/blob/main/docs/guide.rst

Methods for creating Onion Service endpoints using the `.Tor` class or `serverFromString`.

```APIDOC
## Creating Onion Endpoints

### Description
Use factory methods of the `:class:`.Tor` class to create `IStreamServerEndpoint` instances for various Onion Service types. The primary class for creating these is `:class:`.TCPHiddenServiceEndpoint`.

Alternatively, use Twisted's `serverFromString` API with the `onion:` prefix for configuration-based usage without code changes.

### Method
N/A (Factory Methods)

### Endpoint
N/A (Factory Methods)

### Parameters
N/A

### Request Example
N/A

### Response
N/A

## Onion Service Factory Methods

### Description
Factory methods within the `:class:`.Tor` class provide explicit ways to create different types of onion service endpoints.

### Method
- `:meth:`.Tor.create_onion_endpoint`
- `:meth:`.Tor.create_authenticated_onion_endpoint`
- `:meth:`.Tor.create_filesystem_onion_endpoint`
- `:meth:`.Tor.create_authenticated_filesystem_onion_endpoint`

### Endpoint
N/A (These are methods on a `.Tor` instance)

### Parameters
N/A

### Request Example
N/A

### Response
N/A

## Factors for Choosing Service Type

### Description
Consider these factors when deciding between authenticated and non-authenticated services:

- **Non-authenticated**: For public access (e.g., websites) where anyone can access the URL via Tor Browser.
- **Authenticated (Basic)**: For controlled access where users need both the URL and a secret authentication token. Supports many clients.
- **Authenticated (Stealth)**: For highly restricted access where each client requires a unique URL and a secret token. Less scalable, suitable for fewer than 16 clients in recent Tor versions.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### util.delete_file_or_tree

Source: https://github.com/meejah/txtorcon/blob/main/docs/txtorcon-util.rst

Documentation for the delete_file_or_tree utility method.

```APIDOC
## Method util.delete_file_or_tree

### Description
Deletes a specified file or an entire directory tree.
```

--------------------------------

### Clone Repository via Torsocks

Source: https://github.com/meejah/txtorcon/blob/main/README.rst

Command to clone the txtorcon repository over Tor.

```shell-session
torsocks git clone git://fjblvrw2jrxnhtg67qpbzi45r7ofojaoo3orzykesly2j3c2m3htapid.onion/txtorcon.git
```

--------------------------------

### Onion Authentication Async Context Manager (Python 3)

Source: https://github.com/meejah/txtorcon/blob/main/docs/releases.rst

An async context manager that adds an Onion authentication token upon entry and removes it upon exit. This simplifies managing authentication tokens for authenticated Onion services.

```python
async with self.onion_authentication('service_id', 'auth_token'):
    # Use the authenticated onion service
```

--------------------------------

### Connect to an Existing Tor Process

Source: https://context7.com/meejah/txtorcon/llms.txt

Connect to a running Tor instance via its control port using TCP or a Unix socket. This provides a Tor instance for accessing configuration, state, and making client connections.

```python
from twisted.internet.task import react
from twisted.internet.defer import inlineCallbacks
from twisted.internet.endpoints import TCP4ClientEndpoint, UNIXClientEndpoint
import txtorcon

@react
@inlineCallbacks
def main(reactor):
    # Connect via TCP (common for Tor Browser or custom Tor)
    ep = TCP4ClientEndpoint(reactor, "localhost", 9051)
    # Or via Unix socket (common for system Tor on Debian/Ubuntu)
    # ep = UNIXClientEndpoint(reactor, "/var/run/tor/control")

    tor = yield txtorcon.connect(reactor, ep)
    print("Connected to Tor version {}".format(tor.protocol.version))

    # Access configuration
    config = yield tor.get_config()
    print("SOCKS ports: {}".format(config.SOCKSPort))

    # Create state tracker for circuits/streams
    state = yield tor.create_state()
    print("Current circuits: {}".format(len(state.circuits)))

    # Gracefully disconnect
    yield tor.quit()
```

--------------------------------

### Authentication Utility Classes

Source: https://github.com/meejah/txtorcon/blob/main/docs/txtorcon-onion.rst

Utility classes for handling different authentication mechanisms for onion services.

```APIDOC
## Authentication Utility Classes

### Description
Utility classes providing specific authentication strategies.

### Classes
- **AuthBasic**: Implements basic authentication.
- **AuthStealth**: Implements stealth authentication.
```

--------------------------------

### Deprecated Methods

Source: https://github.com/meejah/txtorcon/blob/main/docs/releases.rst

Information about deprecated methods and their replacements.

```APIDOC
## Deprecated Methods

### Description
This section details deprecated methods and their recommended alternatives.

### Deprecated

- `get_global_tor()`

### Wired (Recommended Alternative)

- `txtorcon.get_global_tor_instance`

```

--------------------------------

### Add Event Listener Async Method

Source: https://github.com/meejah/txtorcon/blob/main/docs/releases.rst

Use this async method to add an event listener. It ensures the listener change is known to Tor by awaiting a Deferred. This replaces the older non-async version.

```python
await self.add_event_listener(listener)
```

--------------------------------

### Sign Distribution Artifacts

Source: https://github.com/meejah/txtorcon/blob/main/docs/release-checklist.rst

Commands to generate detached GPG signatures for the distribution files.

```bash
gpg --no-version --detach-sign --armor --local-user meejah@meejah.ca txtorcon-${VERSION}-py3-none-any.whl
gpg --no-version --detach-sign --armor --local-user meejah@meejah.ca txtorcon-${VERSION}.tar.gz
```

--------------------------------

### Generate SHA256 Checksums

Source: https://github.com/meejah/txtorcon/blob/main/docs/release-checklist.rst

Command to calculate the SHA256 checksums for the distribution files.

```bash
sha256sum dist/txtorcon-${VERSION}.tar.gz dist/txtorcon-${VERSION}-py3-none-any.whl
```

--------------------------------

### TorConfig API

Source: https://github.com/meejah/txtorcon/blob/main/docs/txtorcon-config.rst

Interface for interacting with the live Tor configuration.

```APIDOC
## TorConfig

### Description
Provides an interface to read and write the live configuration of a running Tor instance.

### Class
txtorcon.TorConfig
```

--------------------------------

### Onion Service Creation

Source: https://github.com/meejah/txtorcon/blob/main/docs/releases.rst

Methods for creating various types of Onion services, including ephemeral, filesystem-based, authenticated, and non-authenticated services.

```APIDOC
## Onion Service Creation

### Description
APIs for creating and managing Onion services.

### Methods

#### `create_onion_endpoint`

##### Description
Creates a non-authenticated Onion service endpoint.

#### `create_filesystem_onion_endpoint`

##### Description
Creates a non-authenticated Onion service endpoint with configuration stored in a directory.

#### `create_authenticated_onion_endpoint`

##### Description
Creates an authenticated Onion service endpoint.

#### `create_authenticated_filesystem_onion_endpoint`

##### Description
Creates an authenticated Onion service endpoint with configuration stored in a directory.

#### `create_onion_service`

##### Description
Adds a new ephemeral Onion service to Tor (v2 or v3).

#### `create_filesystem_onion_service`

##### Description
Adds a new Onion service to Tor with configuration stored in a provided directory (v2 or v3).

```

--------------------------------

### Download Web Page with Treq

Source: https://github.com/meejah/txtorcon/blob/main/docs/examples.rst

Uses the Treq library to download a web page via Tor. Treq simplifies making HTTP requests.

```python
import txtorcon
import treq
from twisted.internet import reactor, defer


def main(reactor):
    # Connect to Tor
    d = txtorcon.TorClientFactory.connect(reactor)

    def cb_connect(tor_client):
        # Create a Treq Agent that uses Tor
        # Note: treq.client.HTTPClient is deprecated, use treq.client.Agent
        # agent = treq.client.HTTPClient(reactor, connect=tor_client.requests_endpoint)
        # For newer treq versions, you might need to configure it differently
        # This example assumes an older treq or a specific setup.
        # A more modern approach might involve passing the agent directly or using a context manager.
        # For simplicity, we'll use a placeholder for agent creation.
        print("Connected to Tor. Agent setup would go here.")
        # Example of making a request (conceptual):
        # return treq.get('http://example.com', agent=agent).addCallbacks(lambda r: r.text().addCallback(print), print)
        return defer.succeed(None) # Placeholder

    d.addCallback(cb_connect)
    # In a real scenario, you'd add more callbacks here to make the request and process the response.
    d.addBoth(lambda _: reactor.stop())
    return d


if __name__ == '__main__':
    reactor.callWhenRunning(lambda: main(reactor))
    reactor.run()

```

--------------------------------

### Configure Tor for txtorcon

Source: https://github.com/meejah/txtorcon/blob/main/docs/installing.rst

Required settings for torrc to enable cookie authentication and control sockets.

```text
CookieAuthentication 1
CookieAuthFileGroupReadable 1
```

```text
ControlSocketsGroupWritable 1
ControlSocket /var/run/tor/control
```

--------------------------------

### Sign Release Announcement

Source: https://github.com/meejah/txtorcon/blob/main/docs/release-checklist.rst

Command to clear-sign the release announcement email.

```bash
gpg --armor --clearsign -u meejah@meejah.ca release-announce-${VERSION}
```

--------------------------------

### TorProtocolFactory

Source: https://github.com/meejah/txtorcon/blob/main/docs/txtorcon-protocol.rst

Factory for Tor protocols.

```APIDOC
## TorProtocolFactory

### Description
Factory for Tor protocols.

### Method
(Not specified, this is a class)

### Endpoint
(Not applicable, this is a class)

### Parameters
(Class constructor parameters not specified in the provided text)

### Request Example
(Not applicable)

### Response
(Response details not specified in the provided text)
```

--------------------------------

### Create Onion Endpoint

Source: https://github.com/meejah/txtorcon/blob/main/docs/releases.rst

Creates an endpoint for a non-authenticated Onion service. This is a simpler way to establish a connection to an Onion service that does not require client authentication.

```python
await self.create_onion_endpoint('service_id')
```

--------------------------------

### Make Web Requests Through Tor

Source: https://context7.com/meejah/txtorcon/llms.txt

Create a Twisted Web Agent that routes all HTTP(S) requests through Tor. This agent can be used to download content from the clearnet or access .onion sites.

```python
from twisted.internet.task import react
from twisted.internet.defer import inlineCallbacks
from twisted.internet.endpoints import TCP4ClientEndpoint
from twisted.web.client import readBody
import txtorcon

@react
@inlineCallbacks
def main(reactor):
    tor = yield txtorcon.connect(
        reactor,
        TCP4ClientEndpoint(reactor, '127.0.0.1', 9051)
    )

    # Create a web agent that uses Tor
    agent = tor.web_agent()

    # Make requests through Tor
    uri = b'https://www.torproject.org'
    print("Downloading {} via Tor".format(uri))
    resp = yield agent.request(b'GET', uri)

    print("Response status: {}".format(resp.code))
    print("Response length: {} bytes".format(resp.length))

    body = yield readBody(resp)
    print("Body preview: {}..."
.format(body[:200]))

    # Access .onion sites
    onion_uri = b'http://fjblvrw2jrxnhtg67qpbzi45r7ofojaoo3orzykesly2j3c2m3htapid.onion/'
    resp = yield agent.request(b'GET', onion_uri)
    print("Onion service response: {}".format(resp.code))
```

--------------------------------

### Create Authenticated Onion Endpoint

Source: https://github.com/meejah/txtorcon/blob/main/docs/releases.rst

Creates an endpoint for an authenticated Onion service. This method handles the complexities of setting up the connection to an Onion service that requires authentication.

```python
await self.create_authenticated_onion_endpoint('service_id', 'auth_token')
```

--------------------------------

### SOCKS Resolution Functions

Source: https://github.com/meejah/txtorcon/blob/main/docs/txtorcon-socks.rst

Provides documentation for functions related to SOCKS name resolution.

```APIDOC
## SOCKS Resolution Functions

### resolve

.. autofunction:: txtorcon.socks.resolve

### resolve_ptr

.. autofunction:: txtorcon.socks.resolve_ptr
```

--------------------------------

### Queue Tor Control Command

Source: https://github.com/meejah/txtorcon/blob/main/docs/guide.rst

Issue a command to Tor using the control protocol.

```python
yield queue_command("GETINFO version")
```

--------------------------------

### Disallow Streams by Port

Source: https://github.com/meejah/txtorcon/blob/main/docs/examples.rst

Illustrates using IStreamAttacher to prevent Tor from attaching streams to specific exit ports. This is a demonstration of stream control, as Tor has a built-in feature for this.

```python
import txtorcon
from twisted.internet import reactor


class DisallowingStreamAttacher(txtorcon.IStreamAttacher):
    def __init__(self, disallowed_ports):
        self.disallowed_ports = disallowed_ports

    def can_attach(self, stream, circuit):
        # Check if the stream's exit port is in the disallowed list
        if stream.target_port in self.disallowed_ports:
            print(f'Denying stream to {stream.target_addr}:{stream.target_port}')
            # Returning False tells Tor not to attach this stream
            return False
        return True

    def attach_stream(self, stream, circuit):
        # This method is called if can_attach returns True
        # We can choose to close the stream here if needed, but for this example,
        # we'll let it proceed if allowed.
        print(f'Allowing stream to {stream.target_addr}:{stream.target_port}')
        return True


def main(reactor):
    # Connect to Tor
    d = txtorcon.TorClientFactory.connect(reactor)

    def cb_connect(tor_client):
        # Create an instance of our custom stream attacher
        disallowed_ports = {80, 443} # Example: disallow HTTP and HTTPS
        attacher = DisallowingStreamAttacher(disallowed_ports)

        # Register the attacher with TorState
        tor_client.protocol.state.add_stream_attacher(attacher)
        print(f'Stream attacher registered. Disallowing ports: {disallowed_ports}')
        return tor_client

    d.addCallback(cb_connect)
    # Keep the reactor running to monitor streams
    d.addBoth(lambda _: reactor.stop())
    return d


if __name__ == '__main__':
    reactor.callWhenRunning(lambda: main(reactor))
    reactor.run()

```

--------------------------------

### txtorcon.interface Definitions

Source: https://github.com/meejah/txtorcon/blob/main/docs/txtorcon-interface.rst

Overview of the primary interfaces used for interacting with Tor circuits, streams, and the control protocol.

```APIDOC
## Interface Definitions

### IStreamAttacher
Defines the interface for objects that attach streams to circuits.

### IStreamListener
Defines the interface for objects that listen for stream-related events.

### ICircuitListener
Defines the interface for objects that listen for circuit-related events.

### ICircuitContainer
Defines the interface for containers managing circuit objects.

### IRouterContainer
Defines the interface for containers managing router objects.

### ITorControlProtocol
Defines the interface for the Tor control protocol implementation.
```

--------------------------------

### Onion Service Interfaces

Source: https://github.com/meejah/txtorcon/blob/main/docs/txtorcon-onion.rst

Core interfaces for defining onion services and authenticated clients within the txtorcon library.

```APIDOC
## Onion Service Interfaces

### Description
Defines the base interfaces for onion services and authenticated client management.

### Interfaces
- **IOnionService**: Base interface for non-authenticated onion services.
- **IFilesystemOnionService**: Interface for onion services that persist keys to the filesystem.
- **IAuthenticatedOnionClients**: Interface for services supporting authenticated clients.
- **IOnionClient**: Interface representing an authenticated client.
```

--------------------------------

### Download Web Page with Twisted Agent

Source: https://github.com/meejah/txtorcon/blob/main/docs/examples.rst

Uses twisted.web.client.Agent to download a web page via Tor. Ensure Tor is running and accessible.

```python
import txtorcon
from twisted.internet import reactor, defer
from twisted.web.client import Agent
from twisted.web.error import PageNotFoundError


def get_page(agent, url):
    d = agent.request(b'GET', url)

    def cb_request(response):
        print('Status: {0}'.format(response.code))
        d = defer.Deferred()
        response.deliverBody(d)
        return d

    def cb_body(body):
        print('Body: {0}'.format(body.decode('utf-8')))

    def eb_request(failure):
        if failure.check(PageNotFoundError):
            print('Page not found!')
        else:
            print('An error occurred: {0}'.format(failure.getErrorMessage()))

    d.addCallbacks(cb_request, eb_request)
    d.addCallback(cb_body)
    return d


def main(reactor):
    # Connect to Tor
    d = txtorcon.TorClientFactory.connect(reactor)

    def cb_connect(tor_client):
        # Create an Agent that uses Tor
        agent = Agent(reactor, connect=<tor_client.requests_endpoint>)
        return get_page(agent, b'http://example.com')

    d.addCallback(cb_connect)
    return d


if __name__ == '__main__':
    reactor.callWhenRunning(lambda: main(reactor).addBoth(lambda _: reactor.stop()))
    reactor.run()

```