Metadata-Version: 2.4
Name: comptox-python
Version: 0.7.0
Summary: A Python interface for the EPA CompTox Dashboard Chemical API
Author-email: USEtox <usetox@example.com>
Maintainer-email: USEtox <usetox@example.com>
License: MIT
Project-URL: Homepage, https://github.com/USEtox/PyCompTox
Project-URL: Documentation, https://github.com/USEtox/PyCompTox/blob/main/README.md
Project-URL: Repository, https://github.com/USEtox/PyCompTox
Project-URL: Issues, https://github.com/USEtox/PyCompTox/issues
Project-URL: Changelog, https://github.com/USEtox/PyCompTox/blob/main/docs/IMPROVEMENTS_v0.2.0.md
Keywords: comptox,epa,chemistry,toxicology,chemical-data,api-client,cheminformatics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: urllib3>=1.26
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
Requires-Dist: types-requests>=2.31.0; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: isort>=5.13; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: flake8>=7.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.4.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "docs"
Dynamic: license-file

# PyCompTox

[![Python Version](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
[![PyPI version](https://img.shields.io/pypi/v/comptox-python.svg)](https://pypi.org/project/comptox-python/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://github.com/USEtox/PyCompTox/workflows/CI/badge.svg)](https://github.com/USEtox/PyCompTox/actions/workflows/ci.yml)
[![Documentation Status](https://img.shields.io/badge/docs-mkdocs-blue.svg)](https://usetox.github.io/PyCompTox/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

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](https://comptox.epa.gov/) 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.

```python
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](CHANGELOG.md) for the full rename table.

## Installation

### Quick Install

```bash
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:

```bash
# 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](docs/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)

```bash
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](https://www.epa.gov/comptox-tools/computational-toxicology-and-exposure-apis).

### Save Your API Key (Recommended)

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

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

```bash
# 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](https://comptox.epa.gov/ctx-api/docs/chemical.html), [Bioactivity](https://comptox.epa.gov/ctx-api/docs/bioactivity.html), [Exposure](https://comptox.epa.gov/ctx-api/docs/exposure.html), and [Hazard](https://comptox.epa.gov/ctx-api/docs/hazard.html).

## 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](https://github.com/USEPA/ctx-python) from the [official USEPA GitHub page](https://github.com/USEPA).  

Also, note that there is another package called [pycomptox](https://github.com/Kunal627/pycomptox) that is registered on `PyPi` nder the same name, which is why this package is installed by `pip install comptox-python`.
