Metadata-Version: 2.3
Name: congressgov
Version: 2.0.5
Summary: Python SDK for the Congress.gov API — services, models, and generated HTTP client
License: Apache-2.0
Keywords: congress,congress.gov,government,api,legislation
Author: ChristianMDevine
Author-email: ChristianMDevine@gmail.com
Requires-Python: >=3.13,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Provides-Extra: all
Provides-Extra: batch
Provides-Extra: cache
Provides-Extra: codegen
Provides-Extra: dev
Provides-Extra: export
Provides-Extra: viz
Requires-Dist: attrs (>=24.0.0)
Requires-Dist: click (>=8.1.0) ; extra == "codegen"
Requires-Dist: deptry (>=0.23.0) ; extra == "dev"
Requires-Dist: diskcache (>=5.4.0,<6.0.0) ; extra == "all"
Requires-Dist: diskcache (>=5.4.0,<6.0.0) ; extra == "cache"
Requires-Dist: httpx (>=0.28.1,<0.29.0)
Requires-Dist: isort (>=5.12.0) ; extra == "codegen"
Requires-Dist: jinja2 (>=3.1.0) ; extra == "codegen"
Requires-Dist: matplotlib (>=3.7.0,<4.0.0) ; extra == "viz"
Requires-Dist: mypy (>=1.13.0) ; extra == "dev"
Requires-Dist: openapi-python-client (>=0.25.3,<0.26.0) ; extra == "codegen"
Requires-Dist: openpyxl (>=3.1.0,<4.0.0) ; extra == "all"
Requires-Dist: openpyxl (>=3.1.0,<4.0.0) ; extra == "export"
Requires-Dist: pandas (>=2.0.0,<3.0.0) ; extra == "all"
Requires-Dist: pandas (>=2.0.0,<3.0.0) ; extra == "export"
Requires-Dist: psutil (>=5.9.0,<6.0.0) ; extra == "all"
Requires-Dist: psutil (>=5.9.0,<6.0.0) ; extra == "batch"
Requires-Dist: pyarrow (>=17.0.0,<19.0.0) ; extra == "all"
Requires-Dist: pyarrow (>=17.0.0,<19.0.0) ; extra == "export"
Requires-Dist: pydantic (>=2.11.7,<3.0.0)
Requires-Dist: pytest (>=8.0.0) ; extra == "dev"
Requires-Dist: python-dateutil (>=2.9.0,<3.0.0)
Requires-Dist: python-dotenv (>=1.0.0) ; extra == "dev"
Requires-Dist: pyyaml (>=6.0) ; extra == "codegen"
Requires-Dist: redis (>=6.4.0,<7.0.0) ; extra == "all"
Requires-Dist: redis (>=6.4.0,<7.0.0) ; extra == "cache"
Requires-Dist: ruff (>=0.9.0) ; extra == "dev"
Requires-Dist: seaborn (>=0.12.0,<1.0.0) ; extra == "viz"
Requires-Dist: sqlalchemy (>=2.0.43,<3.0.0) ; extra == "all"
Requires-Dist: sqlalchemy (>=2.0.43,<3.0.0) ; extra == "cache"
Requires-Dist: tqdm (>=4.65.0,<5.0.0) ; extra == "all"
Requires-Dist: tqdm (>=4.65.0,<5.0.0) ; extra == "batch"
Project-URL: Documentation, https://github.com/CMD0112/congressgov-python#documentation
Project-URL: Homepage, https://github.com/CMD0112/congressgov-python
Project-URL: Repository, https://github.com/CMD0112/congressgov-python
Description-Content-Type: text/markdown

# congressgov

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)

**Python SDK for the [Congress.gov API](https://api.congress.gov)** — typed Pydantic models, high-level services, and query extensions.

Community client for the official [Congress.gov API specification](https://github.com/LibraryOfCongress/api.congress.gov) (not affiliated with the Library of Congress). **PyPI package:** [`congressgov`](https://pypi.org/project/congressgov/) · **This repo:** `congressgov-python`

## Features

- **Typed models** — Pydantic validation for bills, members, committees, and more
- **High-level services** — `Bill`, `Member`, `Committee`, and 15+ other resource classes
- **Query extensions** — `get_actions()`, `filter()`, `group_by()`, and chainable queries on collections
- **Async** — parallel `AsyncBill`, `AsyncMember`, … under `congressgov.async_api`

## Requirements

- Python **3.13+**
- A free [Congress.gov API key](https://api.congress.gov/sign-up/)

## Installation

Requires **2.0.0 or newer** for the current `src/` layout without legacy shims. Use **1.5.x** if you still need `import middleware` / `import models`; **1.0.0** did not ship a `congressgov` module at all.

```bash
pip install "congressgov>=2.0.0"
```

**Full install (all optional runtime features):**

```bash
pip install congressgov[all]
```

**From source (development):**

```bash
git clone https://github.com/CMD0112/congressgov-python.git
cd congressgov-python
poetry install --with dev,cache,export,batch,codegen
# Or: pip install -e ".[dev,all,codegen]"
```

First-time maintainers wiring a new GitHub remote: [docs/GITHUB_SETUP.md](docs/GITHUB_SETUP.md).

### API key

```bash
cp .env.example .env
# Set CONGRESS_API_KEY=your-key-here
```

Or export `CONGRESS_API_KEY` in your shell. The library reads it via `get_client_from_env()`.

## Quick start

```python
from congressgov import Bill, get_client_from_env

client = get_client_from_env()
bill = Bill(client=client).get(congress=118, bill_type="hr", bill_number=1)

print(bill.title)
print(len(bill.get_actions() or []), "actions")
```

Run the sample scripts (with `CONGRESS_API_KEY` set):

```bash
poetry run python examples/quickstart.py
poetry run python examples/quickstart_async.py
```

### Async

```python
from congressgov.async_api import AsyncBill

bill = await AsyncBill(client=client).get(
    congress=118, bill_type="hr", bill_number=1
)
```

## Architecture

```mermaid
flowchart TB
  subgraph app [Your application]
    UserCode[Your code]
  end
  subgraph sdk [congressgov SDK]
    Facade[congressgov facade]
    SVC[services]
    MD[models]
    CL[congressgov._client]
  end
  API[Congress.gov API v3]
  UserCode --> Facade
  Facade --> SVC
  SVC --> MD
  SVC --> CL
  CL --> API
```

| Layer | Import | Role |
|-------|--------|------|
| Facade | `congressgov` | Canonical public API (`Bill`, `Member`, …) |
| Services | `congressgov.services` | High-level API services |
| Models | `congressgov.models` | Parsed, validated data |
| Client | `congressgov.client` or `congressgov._client` | Generated HTTP calls |

## Optional features

Caching, batch jobs, export, and rate limiting require optional extras (lazy-imported from `congressgov`):

| Extra | Install | Enables |
|-------|---------|---------|
| `cache` | `pip install congressgov[cache]` | `CachedBill`, `RedisCache`, `RateLimiter`, … |
| `export` | `pip install congressgov[export]` | `DataExporter`, `PandasIntegration`, … |
| `batch` | `pip install congressgov[batch]` | `BatchProcessor`, … |
| `all` | `pip install congressgov[all]` | All of the above |
| `codegen` | `pip install congressgov[codegen]` | Maintainer deps only; run `python -m codegen` from a git clone |
| `viz` | `pip install congressgov[viz]` | Matplotlib helpers in export visualization |

Details: **[docs/ADVANCED.md](docs/ADVANCED.md)**. Architecture: **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**.

## Regenerating from OpenAPI

The committed client and models are generated from `codegen/config/openapi_spec.yaml`. To regenerate after spec changes:

```bash
poetry install --with codegen
poetry run python -m codegen validate-spec
poetry run python -m codegen generate-all
```

Stepwise: `python -m codegen generate-client`, `generate-models`, `generate-middleware`.

- **Spec:** `codegen/config/openapi_spec.yaml`
- **Config:** `codegen/config/generator_config.yaml`
- **Incremental mode** preserves `# CUSTOM:` blocks in generated files
- **Do not overwrite** hand-maintained `congressgov/services/async_api/bill.py` and `cached_bill.py`

Full workflow: **[docs/CODEGEN.md](docs/CODEGEN.md)** (see **[docs/README.md](docs/README.md)** for the full index).

## Documentation

| Guide | Contents |
|-------|----------|
| [docs/README.md](docs/README.md) | **Documentation index** (start here) |
| [docs/USAGE.md](docs/USAGE.md) | Getting started, async, errors, congressional record types |
| [docs/REFERENCE.md](docs/REFERENCE.md) | Services, client, models, extensions |
| [docs/MEMBERS_QUERY.md](docs/MEMBERS_QUERY.md) | `Members` collection query/filter helpers |
| [docs/ADVANCED.md](docs/ADVANCED.md) | Caching, batch, export, rate limits |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Core vs extras, generated vs hand-maintained |
| [docs/PACKAGE_LAYOUT.md](docs/PACKAGE_LAYOUT.md) | Directory layout, wheel policy, 2.0 `src/` plan |
| [docs/MIGRATION.md](docs/MIGRATION.md) | Import path changes (1.1 → 2.0) |
| [docs/VERSIONING.md](docs/VERSIONING.md) | SemVer, deprecations, stability scope |
| [docs/CODEGEN.md](docs/CODEGEN.md) | OpenAPI code generation (maintainers) |
| [docs/API_COVERAGE.md](docs/API_COVERAGE.md) | OpenAPI path coverage matrix (maintainers) |
| [docs/PUBLISHING.md](docs/PUBLISHING.md) | PyPI trusted publishing (maintainers) |

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Security: [SECURITY.md](SECURITY.md). Releases: [CHANGELOG.md](CHANGELOG.md).

## License

[Apache-2.0](LICENSE)

