PyCompTox

A Python interface for the EPA CompTox Dashboard Chemical API.

Overview

PyCompTox provides a simple and intuitive Python interface to interact with the EPA's CompTox Dashboard Chemical, Bioactivity, Exposure, and Hazard API. This package allows you to search for chemicals by name, identifiers (DTXSID, DTXCID, CAS numbers), molecular formulas, mass ranges, and much more.

from pycomptox import Chemical

client = Chemical()
results = client.search_by_exact_value("Bisphenol A")
print(results[0]["dtxsid"])   # DTXSID7020182

Upgrading to 0.7.0? This release fixes 16 methods that could not work at all, and contains breaking changes: caching is now opt-in rather than on by default, CCCData is renamed CCDData, several methods were renamed for consistency, and API failures now raise pycomptox.exceptions types instead of ValueError, and the minimum Python is now 3.12. See the changelog for the full rename table.

Installation

Quick Install

pip install comptox-python

install the latest released version.
Note: do not install the package by pip install pycomptox which is a different package with the old comptox API.

For the latest development version:

# Clone the repository
git clone https://github.com/USEtox/PyCompTox.git
cd PyCompTox

# Install the package
pip install -e .

# Or with development tools
pip install -e ".[dev]"

# Or with docs tools
pip install -e ".[docs]"

PyCompTox now uses modern Python packaging with pyproject.toml. See INSTALLATION.md for detailed installation options.

Optional Dependencies

• dev: Testing and typing helpers (pytest, pytest-cov, pytest-mock, types-requests)
• docs: Documentation build tools (mkdocs, mkdocs-material, mkdocstrings)

pip install -e ".[dev]"

API Key Setup

To use the CompTox Dashboard API, you need an API key. You can obtain one from the CompTox Dashboard API documentation.

Save Your API Key (Recommended)

Save your API key once and it will be automatically loaded for all future sessions:

pycomptox-setup set YOUR_API_KEY

The API key is stored securely in your user's application data directory:

• Windows: %APPDATA%\PyCompTox\api_key.txt
• macOS/Linux: ~/.pycomptox/api_key.txt

Manage Your API Key

# Test if your API key works
pycomptox-setup test

# Show your saved API key (masked)
pycomptox-setup show

# Delete your saved API key
pycomptox-setup delete

Alternative Methods

You can also provide the API key in other ways:

1. Environment Variable: Set COMPTOX_API_KEY environment variable
2. Direct Parameter: Pass api_key parameter when creating the client

API Key Storage

Your API key is stored securely in your user's application data directory:

• Windows: C:\Users\<username>\AppData\Roaming\PyCompTox\api_key.txt
• macOS/Linux: ~/.pycomptox/api_key.txt

The file is created with user-only read permissions on Unix-like systems.

API Documentation

For detailed API documentation, visit:
Chemical, Bioactivity, Exposure, and Hazard.

License

See the LICENSE file for details.

Disclaimer

This package is not officially affiliated with or endorsed by the U.S. Environmental Protection Agency (EPA). It is an independent implementation of a Python client for the publicly available CompTox Dashboard API.
You can find the official Python client from the official USEPA GitHub page.

Also, note that there is another package called pycomptox that is registered on PyPi nder the same name, which is why this package is installed by pip install comptox-python.