congress-py 0.1.0__tar.gz

congress_py-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Antonio Alaniz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

congress_py-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: congress-py
+Version: 0.1.0
+Summary: A lightweight Python SDK for interacting with the United States Congress API.
+Author: Antonio Alaniz
+License: MIT
+Project-URL: Homepage, https://github.com/talaniz/congress.py
+Project-URL: Documentation, https://talaniz.github.io/congress.py/
+Project-URL: Repository, https://github.com/talaniz/congress.py
+Project-URL: Issues, https://github.com/talaniz/congress.py/issues
+Project-URL: Changelog, https://github.com/talaniz/congress.py/blob/main/docs/changelog.md
+Keywords: congress,api,legislative,government,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3,>=2.32.3
+Requires-Dist: typer<1,>=0.12.5
+Provides-Extra: dev
+Requires-Dist: codecov<3,>=2.1.13; extra == "dev"
+Requires-Dist: coverage<8,>=7.6.4; extra == "dev"
+Requires-Dist: pytest<9,>=8.3.3; extra == "dev"
+Requires-Dist: pytest-cov<7,>=6.0.0; extra == "dev"
+Requires-Dist: requests-mock<2,>=1.12.1; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs<2,>=1.6.1; extra == "docs"
+Requires-Dist: mkdocs-material<10,>=9.5.49; extra == "docs"
+Requires-Dist: mkdocstrings[python]<1,>=0.27.1; extra == "docs"
+Dynamic: license-file
+
+# congress_py
+
+![Tests](https://github.com/talaniz/congress.py/actions/workflows/python-package.yml/badge.svg)
+
+`congress_py` is an unofficial Python SDK and CLI for reading data from the
+Congress.gov API.
+
+This project is not affiliated with Congress.gov, the Library of Congress,
+Congress, or the U.S. government. It does not provide legal, legislative,
+lobbying, financial, compliance, or policy advice.
+
+## Installation
+
+```bash
+pip install congress-py
+```
+
+### Local Development
+
+```bash
+git clone https://github.com/talaniz/congress.py.git
+cd congress.py
+python3 -m venv .venv
+.venv/bin/python -m pip install -e .
+```
+
+You will need your own Congress.gov API key.
+
+## Documentation
+
+Full documentation is available at:
+
+https://talaniz.github.io/congress.py/
+
+The documentation site includes installation steps, API-key setup, SDK examples,
+CLI examples, API reference, contributing guidance, and the changelog.
+
+## License
+
+MIT

congress_py-0.1.0/README.md

@@ -0,0 +1,40 @@
+# congress_py
+
+![Tests](https://github.com/talaniz/congress.py/actions/workflows/python-package.yml/badge.svg)
+
+`congress_py` is an unofficial Python SDK and CLI for reading data from the
+Congress.gov API.
+
+This project is not affiliated with Congress.gov, the Library of Congress,
+Congress, or the U.S. government. It does not provide legal, legislative,
+lobbying, financial, compliance, or policy advice.
+
+## Installation
+
+```bash
+pip install congress-py
+```
+
+### Local Development
+
+```bash
+git clone https://github.com/talaniz/congress.py.git
+cd congress.py
+python3 -m venv .venv
+.venv/bin/python -m pip install -e .
+```
+
+You will need your own Congress.gov API key.
+
+## Documentation
+
+Full documentation is available at:
+
+https://talaniz.github.io/congress.py/
+
+The documentation site includes installation steps, API-key setup, SDK examples,
+CLI examples, API reference, contributing guidance, and the changelog.
+
+## License
+
+MIT

congress_py-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "congress-py"
+version = "0.1.0"
+description = "A lightweight Python SDK for interacting with the United States Congress API."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "Antonio Alaniz" }
+]
+keywords = ["congress", "api", "legislative", "government", "sdk"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "requests>=2.32.3,<3",
+    "typer>=0.12.5,<1"
+]
+
+[project.urls]
+Homepage = "https://github.com/talaniz/congress.py"
+Documentation = "https://talaniz.github.io/congress.py/"
+Repository = "https://github.com/talaniz/congress.py"
+Issues = "https://github.com/talaniz/congress.py/issues"
+Changelog = "https://github.com/talaniz/congress.py/blob/main/docs/changelog.md"
+
+[project.optional-dependencies]
+dev = [
+    "codecov>=2.1.13,<3",
+    "coverage>=7.6.4,<8",
+    "pytest>=8.3.3,<9",
+    "pytest-cov>=6.0.0,<7",
+    "requests-mock>=1.12.1,<2"
+]
+docs = [
+    "mkdocs>=1.6.1,<2",
+    "mkdocs-material>=9.5.49,<10",
+    "mkdocstrings[python]>=0.27.1,<1"
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["congress_py*"]
+
+[project.scripts]
+congress = "congress_py.cli:run"

congress_py-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

congress_py-0.1.0/src/congress_py/__init__.py

@@ -0,0 +1,8 @@
+"""Public package interface for congress_py."""
+
+__version__ = "0.1.0"
+
+from congress_py.client import CongressClient
+from congress_py.models import Bill, BillAction, BillSummary
+
+__all__ = ["Bill", "BillAction", "BillSummary", "CongressClient"]

congress_py-0.1.0/src/congress_py/cli.py

@@ -0,0 +1,276 @@
+"""Command-line interface for congress_py."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, is_dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+import typer
+
+from congress_py.client import CongressClient
+from congress_py.exceptions import MissingAPIKeyError
+
+CONFIG_DIR = Path.home() / ".congress"
+CONFIG_FILE = CONFIG_DIR / "config.toml"
+MISSING_API_KEY_MESSAGE = (
+    "No Congress.gov API key found. Run congress configure or set CONGRESS_API_KEY."
+)
+
+app = typer.Typer(help="CLI for the Congress.gov API.")
+congress_app = typer.Typer(help="Congress session commands.")
+bills_app = typer.Typer(help="Bill commands.")
+
+
+def _to_jsonable(value: Any) -> Any:
+    if is_dataclass(value):
+        return _to_jsonable(asdict(value))
+    if hasattr(value, "_asdict"):
+        return _to_jsonable(value._asdict())
+    if isinstance(value, dict):
+        return {key: _to_jsonable(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_to_jsonable(item) for item in value]
+    return value
+
+
+def _json_default(value: Any) -> Any:
+    converted = _to_jsonable(value)
+    if converted is not value:
+        return converted
+    raise TypeError(f"Object of type {type(value).__name__} is not JSON serializable")
+
+
+def _print_json(value: Any) -> None:
+    typer.echo(
+        json.dumps(_to_jsonable(value), default=_json_default, indent=2, sort_keys=True)
+    )
+
+
+def _parse_simple_auth_toml(content: str) -> Optional[str]:
+    in_auth_section = False
+
+    for raw_line in content.splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("[") and line.endswith("]"):
+            in_auth_section = line == "[auth]"
+            continue
+        if not in_auth_section or "=" not in line:
+            continue
+
+        key, value = line.split("=", 1)
+        if key.strip() != "api_key":
+            continue
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in {'"', "'"}:
+            value = value[1:-1]
+        return value.strip() or None
+
+    return None
+
+
+def _load_config_api_key(config_file: Optional[Path] = None) -> Optional[str]:
+    if config_file is None:
+        config_file = CONFIG_FILE
+
+    if not config_file.exists():
+        return None
+
+    content = config_file.read_text(encoding="utf-8")
+    try:
+        import tomllib
+    except ModuleNotFoundError:
+        return _parse_simple_auth_toml(content)
+
+    data = tomllib.loads(content)
+    auth = data.get("auth", {})
+    api_key = auth.get("api_key")
+    if isinstance(api_key, str):
+        return api_key.strip() or None
+    return None
+
+
+def _resolve_api_key(explicit_api_key: Optional[str]) -> str:
+    if explicit_api_key:
+        return explicit_api_key
+
+    env_api_key = os.environ.get("CONGRESS_API_KEY")
+    if env_api_key:
+        return env_api_key
+
+    config_api_key = _load_config_api_key()
+    if config_api_key:
+        return config_api_key
+
+    raise MissingAPIKeyError(MISSING_API_KEY_MESSAGE)
+
+
+def _get_client(ctx: typer.Context) -> CongressClient:
+    explicit_api_key = None
+    if ctx.obj:
+        explicit_api_key = ctx.obj.get("api_key")
+
+    try:
+        return CongressClient(api_key=_resolve_api_key(explicit_api_key))
+    except MissingAPIKeyError:
+        typer.echo(MISSING_API_KEY_MESSAGE, err=True)
+        raise typer.Exit(1)
+
+
+def _toml_string(value: str) -> str:
+    return value.replace("\\", "\\\\").replace('"', '\\"')
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    api_key: Optional[str] = typer.Option(
+        None,
+        "--api-key",
+        help=(
+            "Congress.gov API key. Defaults to CONGRESS_API_KEY "
+            "or ~/.congress/config.toml."
+        ),
+    ),
+) -> None:
+    """Resolve global CLI options for all commands.
+
+    Args:
+        ctx: Typer context used to share resolved option values with commands.
+        api_key: Optional Congress.gov API key. If omitted, API commands fall
+            back to ``CONGRESS_API_KEY`` and then ``~/.congress/config.toml``.
+
+    """
+    ctx.obj = {"api_key": api_key}
+
+
+@app.command()
+def configure(
+    api_key: str = typer.Option(
+        ...,
+        "--api-key",
+        prompt=True,
+        hide_input=True,
+        help="Congress.gov API key to save locally.",
+    ),
+) -> None:
+    """Save a Congress.gov API key for future CLI commands.
+
+    Args:
+        api_key: Congress.gov API key to write to ``~/.congress/config.toml``.
+
+    """
+    CONFIG_DIR.mkdir(mode=0o700, parents=True, exist_ok=True)
+    content = f'[auth]\napi_key = "{_toml_string(api_key)}"\n'
+
+    fd = os.open(CONFIG_FILE, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as config:
+        config.write(content)
+
+    try:
+        CONFIG_FILE.chmod(0o600)
+    except OSError:
+        pass
+
+    typer.echo("Configuration saved.")
+
+
+@congress_app.command("current")
+def congress_current(ctx: typer.Context) -> None:
+    """Return the current congressional session."""
+    client = _get_client(ctx)
+    _print_json(client.get_current_session())
+
+
+@congress_app.command("list")
+def congress_list(ctx: typer.Context) -> None:
+    """Return available congressional sessions."""
+    client = _get_client(ctx)
+    _print_json(client.get_congresses())
+
+
+@bills_app.command("list")
+def bills_list(
+    ctx: typer.Context,
+    session: Optional[int] = typer.Option(
+        None,
+        "--session",
+        help="Congress session number to pass to the existing SDK method.",
+    ),
+    limit: int = typer.Option(
+        20,
+        "--limit",
+        min=1,
+        help="Number of bills to request per API call.",
+    ),
+    offset: int = typer.Option(
+        0,
+        "--offset",
+        min=0,
+        help=(
+            "Starting offset for single-page mode. "
+            "Ignored when --pages is provided."
+        ),
+    ),
+    pages: Optional[int] = typer.Option(
+        None,
+        "--pages",
+        min=1,
+        help="Number of pages to fetch using the SDK iterator.",
+    ),
+) -> None:
+    """Return bills, optionally filtered by Congress session.
+
+    Args:
+        ctx: Typer context containing global CLI option values.
+        session: Optional Congress number used to filter bill results.
+        limit: Number of bills to request per API call.
+        offset: Starting offset for single-page results.
+        pages: Optional number of pages to fetch with the SDK iterator. When
+            provided, ``offset`` is ignored.
+
+    """
+    client = _get_client(ctx)
+    if pages is None:
+        bills = client.get_bills(session=session, limit=limit, offset=offset)
+    else:
+        bills = list(client.iter_bills(session=session, limit=limit, max_pages=pages))
+    _print_json(bills)
+
+
+@bills_app.command("get")
+def bills_get(ctx: typer.Context, congress: int, bill_type: str, number: int) -> None:
+    """Return one bill by congress, bill type, and number."""
+    client = _get_client(ctx)
+    _print_json(client.get_bill(congress, bill_type, number))
+
+
+@bills_app.command("actions")
+def bills_actions(
+    ctx: typer.Context, congress: int, bill_type: str, number: int
+) -> None:
+    """Return actions for one bill."""
+    client = _get_client(ctx)
+    _print_json(client.get_bill_actions(congress, bill_type, number))
+
+
+@bills_app.command("summaries")
+def bills_summaries(
+    ctx: typer.Context, congress: int, bill_type: str, number: int
+) -> None:
+    """Return summaries for one bill."""
+    client = _get_client(ctx)
+    _print_json(client.get_bill_summaries(congress, bill_type, number))
+
+
+app.add_typer(congress_app, name="congress")
+app.add_typer(bills_app, name="bills")
+
+
+def run() -> None:
+    """Run the Typer application."""
+    app()