congressgov 1.0.0__tar.gz

congressgov-1.0.0/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 CMD0112
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

congressgov-1.0.0/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.3
+Name: congressgov
+Version: 1.0.0
+Summary: Python SDK for the Congress.gov API — models, middleware services, and generated HTTP client
+License: Apache-2.0
+Keywords: congress,congress.gov,government,api,legislation
+Author: CMD0112
+Author-email: CMD0112@users.noreply.github.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: jupyter
+Provides-Extra: viz
+Requires-Dist: anytree (>=2.13.0,<3.0.0)
+Requires-Dist: attrs (>=24.0.0)
+Requires-Dist: beautifulsoup4 (>=4.13.5,<5.0.0)
+Requires-Dist: black (>=23.0.0) ; extra == "codegen"
+Requires-Dist: click (>=8.1.0) ; extra == "codegen"
+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: ipykernel (>=6.30.1,<7.0.0) ; extra == "jupyter"
+Requires-Dist: isort (>=5.12.0) ; extra == "codegen"
+Requires-Dist: jinja2 (>=3.1.0) ; extra == "codegen"
+Requires-Dist: jupyter (>=1.1.1,<2.0.0) ; extra == "jupyter"
+Requires-Dist: matplotlib (>=3.7.0,<4.0.0) ; extra == "viz"
+Requires-Dist: mypy (>=1.13.0) ; extra == "dev"
+Requires-Dist: nbconvert (>=7.16.6,<8.0.0) ; extra == "jupyter"
+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: tenacity (>=8.2.0,<9.0.0)
+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/v3)** — 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
+- **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](https://api.congress.gov/sign-up/)
+
+## Installation
+
+```bash
+pip install congressgov
+```
+
+**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
+# Or: pip install -e ".[dev,all]"
+```
+
+### 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 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):
+
+```bash
+poetry run python examples/quickstart.py
+poetry run python examples/quickstart_async.py
+```
+
+### Async
+
+```python
+from middleware.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 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](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 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](docs/CODEGEN.md)**
+
+## Documentation
+
+| Guide | Contents |
+|-------|----------|
+| [docs/USAGE.md](docs/USAGE.md) | Getting started, async, errors, congressional record types |
+| [docs/VERSIONING.md](docs/VERSIONING.md) | SemVer, deprecations, stability scope |
+| [docs/REFERENCE.md](docs/REFERENCE.md) | Services, client, models, extensions |
+| [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/CODEGEN.md](docs/CODEGEN.md) | OpenAPI code generation (maintainers) |
+| [docs/PUBLISHING.md](docs/PUBLISHING.md) | PyPI trusted publishing (maintainers) |
+| [docs/API_COVERAGE.md](docs/API_COVERAGE.md) | OpenAPI path coverage matrix (maintainers) |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Security: [SECURITY.md](SECURITY.md). Releases: [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+[Apache-2.0](LICENSE)
+

congressgov-1.0.0/README.md

@@ -0,0 +1,159 @@
+# 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/v3)** — 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
+- **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](https://api.congress.gov/sign-up/)
+
+## Installation
+
+```bash
+pip install congressgov
+```
+
+**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
+# Or: pip install -e ".[dev,all]"
+```
+
+### 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 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):
+
+```bash
+poetry run python examples/quickstart.py
+poetry run python examples/quickstart_async.py
+```
+
+### Async
+
+```python
+from middleware.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 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](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 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](docs/CODEGEN.md)**
+
+## Documentation
+
+| Guide | Contents |
+|-------|----------|
+| [docs/USAGE.md](docs/USAGE.md) | Getting started, async, errors, congressional record types |
+| [docs/VERSIONING.md](docs/VERSIONING.md) | SemVer, deprecations, stability scope |
+| [docs/REFERENCE.md](docs/REFERENCE.md) | Services, client, models, extensions |
+| [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/CODEGEN.md](docs/CODEGEN.md) | OpenAPI code generation (maintainers) |
+| [docs/PUBLISHING.md](docs/PUBLISHING.md) | PyPI trusted publishing (maintainers) |
+| [docs/API_COVERAGE.md](docs/API_COVERAGE.md) | OpenAPI path coverage matrix (maintainers) |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Security: [SECURITY.md](SECURITY.md). Releases: [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+[Apache-2.0](LICENSE)

congressgov-1.0.0/codegen/README.md

@@ -0,0 +1,11 @@
+# Code generation package
+
+Maintainer tooling to regenerate the client, models, and middleware from OpenAPI.
+
+**Documentation:** [docs/CODEGEN.md](../docs/CODEGEN.md)
+
+```bash
+poetry install --with codegen
+poetry run validate-spec
+poetry run generate-all
+```

congressgov-1.0.0/codegen/__init__.py

@@ -0,0 +1,19 @@
+"""
+Code generation system for congressgov
+
+This package provides a comprehensive code generation system that generates
+the complete congressgov project from an OpenAPI specification with
+custom extensions.
+
+Features:
+- Generate API clients from OpenAPI specs
+- Generate Pydantic models with custom annotations
+- Generate middleware service classes
+- Generate extension methods with query builders
+- Incremental generation with custom modification preservation
+- Full type safety and validation
+"""
+
+__version__ = "1.0.0"
+
+