congressgov 1.0.0

Python SDK for the Congress.gov API — models, middleware services, and generated HTTP client

congressgov

Python SDK for the Congress.gov API — typed Pydantic models, high-level services, and query extensions.

Community client for the official Congress.gov API specification (not affiliated with the Library of Congress). PyPI package: congressgov · This repo: congressgov-python

Features

• Typed models — Pydantic validation for bills, members, committees, and more
• Middleware 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 middleware.async_api

Requirements

• Python 3.13+
• A free Congress.gov API key

Installation

pip install congressgov

Full install (all optional runtime features):

pip install congressgov[all]

From source (development):

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

API key

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

from middleware 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):

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

Async

from middleware.async_api import AsyncBill

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

Architecture

flowchart TB
  subgraph app [Your application]
    UserCode[Your code]
  end
  subgraph congressgov [congressgov]
    MW[middleware services]
    MD[models]
    CL[congress_gov_api_client]
  end
  API[Congress.gov API v3]
  UserCode --> MW
  MW --> MD
  MW --> CL
  CL --> API

Layer	Package	Role
Client	congress_gov_api_client	Generated HTTP calls
Middleware	middleware	get, search, extensions
Models	models	Parsed, validated data

Optional features

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

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]	generate-all, validate-spec (maintainers)
viz	pip install congressgov[viz]	Matplotlib helpers in export visualization

Details: docs/ADVANCED.md. Architecture: docs/ARCHITECTURE.md.

Regenerating from OpenAPI

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

poetry install --with codegen
poetry run validate-spec
poetry run generate-all

Stepwise: 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 middleware/async_api/bill.py and cached_bill.py

Full workflow: docs/CODEGEN.md

Documentation

Guide	Contents
docs/USAGE.md	Getting started, async, errors, congressional record types
docs/VERSIONING.md	SemVer, deprecations, stability scope
docs/REFERENCE.md	Services, client, models, extensions
docs/ADVANCED.md	Caching, batch, export, rate limits
docs/ARCHITECTURE.md	Core vs extras, generated vs hand-maintained
docs/CODEGEN.md	OpenAPI code generation (maintainers)
docs/PUBLISHING.md	PyPI trusted publishing (maintainers)
docs/API_COVERAGE.md	OpenAPI path coverage matrix (maintainers)

Contributing

See CONTRIBUTING.md. Security: SECURITY.md. Releases: CHANGELOG.md.

License

Apache-2.0