Skip to content

Latest commit

 

History

History
75 lines (50 loc) · 3.49 KB

CLAUDE.md

File metadata and controls

75 lines (50 loc) · 3.49 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

Python client library (SDK) for the Astrology API v3. Provides typed wrappers around 150+ endpoints organized into 16 category clients. Built on httpx (sync HTTP) and pydantic v2 (request/response models). Requires Python 3.10+.

Commands

# Install (editable + dev deps)
pip install -e ".[dev]"

# Run all tests (coverage is enforced at 100% branch via addopts)
pytest

# Run a single test file
pytest tests/unit/test_client.py

# Run a single test
pytest tests/unit/test_client.py::TestAstrologyClient::test_client_creation_with_config

# Lint and format
ruff check src/ tests/
ruff format src/ tests/

# Type check (strict mode)
mypy src/astroapi

# Pre-commit hooks
pre-commit install

Architecture

Entry point: AstrologyClient (client.py) — creates an HttpClient and instantiates all 16 category clients. Supports context manager protocol for cleanup.

HTTP layer: HttpClient (utils/http_client.py) wraps httpx.Client with Bearer auth, configurable retry logic (RetryConfig), and response envelope unwrapping (data or result keys). Categories depend on the HttpHelper ABC (utils/http.py), not HttpClient directly.

Categories (categories/): 16 clients inheriting BaseCategoryClient. Each declares an API_PREFIX and builds URLs via _build_url(*segments). InsightsClient is unique — it composes 5 sub-clients (relationship, pet, wellness, financial, business) as instance attributes.

Types (types/):

  • config.py — AstrologyClientConfig, RetryConfig dataclasses, type aliases, validation constants
  • requests.py — Pydantic request models with ConfigDict(extra="forbid"), serialized via model_dump(exclude_none=True)
  • responses.py — Pydantic response models with extra="allow" (tolerant of API additions)

Validation: Every category method validates inputs via functions in utils/validators.py before making HTTP calls. All errors surface as AstrologyError (errors.py).

Config: API key resolved from AstrologyClientConfig.api_key or env var ASTROLOGY_API_KEY. Also reads ASTROLOGY_API_BASE_URL and ASTROLOGY_DEBUG.

Versioning

Version is derived automatically from git tags via hatch-vcs (configured in pyproject.toml). There is no hardcoded version anywhere — src/astroapi/_version.py is generated at build/install time.

  • Tag v1.2.3 → package version 1.2.3
  • Between tags → dev version like 1.2.4.dev3+g<hash>
  • _version.py is in .gitignore — never commit it

Release flow: create and push a tag, release.yml handles the rest:

git tag v1.2.0
git push origin v1.2.0

CI workflows use fetch-depth: 0 in checkout so git tags are always available for version resolution.

Conventions

  • Every source file uses from __future__ import annotations
  • Line length: 100 chars
  • Double quotes, space indent
  • All request models forbid extra fields; all response models allow them
  • Tests mock HTTP via pytest-httpx (httpx_mock fixture). Shared fixtures in tests/conftest.py, mock payloads in tests/mocks/responses.py
  • Coverage excludes __init__.py re-export files and TYPE_CHECKING blocks