pyahmia 0.11.1
Search hidden services on the Tor network.
Requires Python: >=3.12

![PyAhmia Logo](https://raw.githubusercontent.com/rly0nheart/pyahmia/refs/heads/master/img/ahmia.png)

**PyAhmia** uses Ahmia.fi to search for hidden services on the Tor network  
that match with a specified query, without an explicit requirement for Tor.

![PyPI - Version](https://img.shields.io/pypi/v/pyahmia)
![PyPI - Downloads](https://img.shields.io/pepy/dt/pyahmia)
![Code Size](https://img.shields.io/github/languages/code-size/rly0nheart/pyahmia)
![Release Date](https://img.shields.io/github/release-date/rly0nheart/pyahmia)
![Build Status](https://img.shields.io/github/actions/workflow/status/rly0nheart/pyahmia/python-publish.yml)
![License](https://img.shields.io/github/license/rly0nheart/pyahmia)

## Features

- [x] Search Ahmia.fi from the command line
- [x] Export results to CSV
- [x] Enable/Disable routing requests through Tor
- [x] Return results in a clean readable format
- [x] Response caching for faster repeated searches
- [x] Configurable result limits and request timeout

## Installation

**PyAhmia** is available on PyPI and can be installed like so:

```commandline
pip install pyahmia
```

This will install `ahmia` and `pyahmia` as commands.

## Usage

To start searching, you can call `ahmia` (or `pyahmia`) with the specified search query.

*example*:

```commandline
ahmia QUERY
```

### Routing Traffic Through Tor (Optional)

**PyAhmia works without Tor, but you can enable routing traffic through Tor if you want.**

When this is enabled, it will use Ahmia's darknet url instead of the
clearnet variant.

To enable routing through Tor, you can call `ahmia` with the `-t, --use-tor` flag.
This assumes the tor service is running in the background, otherwise, the command will fail before you can say "hidden
wiki".

If Tor is not installed, you can check out the installation scripts located
in [pyahmia/scripts](https://github.com/rly0nheart/pyahmia/tree/master/scripts).

*example*:

```commandline
ahmia QUERY --use-tor
```

### Exporting Output

PyAhmia only supports exporting data to csv files (for now), and in order to export, you'll need to specify the
`-e, --export` flag.
This will export your search results to a file named after your search query.

*example*:

```commandline
ahmia QUERY --export
```

### Filtering Results by Time Period

Results can be filtered by 3 time periods (day, week, month). By default, results will be taken from all time periods (
all). You can change this by using the `-p, --period` option, and pass the time period you want to get results from.

*example*:

```commandline
ahmia QUERY --period week
```

### Limiting Results

By default, PyAhmia displays up to 100 results. You can change this with the `-l, --limit` option.

*example*:

```commandline
ahmia QUERY --limit 50
```

To show all results regardless of the limit, use the `-a, --all` flag.

*example*:

```commandline
ahmia QUERY --all
```

### Caching

PyAhmia caches responses by default to reduce redundant requests. To disable caching, use the `--no-cache` flag.

*example*:

```commandline
ahmia QUERY --no-cache
```

### Request Timeout

You can set a custom timeout (in seconds) for requests using the `--timeout` option. The default is 10 seconds.

*example*:

```commandline
ahmia QUERY --timeout 30
```

## In Conclusion

Don't send too many requests with pyahmia. Be nice to the owners of Ahmia.fi :)

## Contributing

Contributions are welcome!
If you’d like to improve PyAhmia, fix a bug, or add a feature:

1. Fork the repository
2. Create a new branch for your changes
3. Commit and push your changes
4. Open a pull request

Please keep PRs focused and provide a clear description of the problem being solved. Bug reports and feature requests
are also appreciated, just open an issue.

## License

This project is licensed under the MIT License, see
the [LICENSE](https://codeberg.org/rly0nheart/pyahmia/raw/branch/master/LICENSE) file for details.


> [!Note]
> **PyAhmia is not in any way affiliated with Ahmia.fi**