astroway 0.1.0a1__tar.gz

astroway-0.1.0a1/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+env/
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.DS_Store

astroway-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## 0.1.0a1 — 2026-05-09
+
+Initial alpha release. Public API may shift before `0.1.0` proper based on integrator feedback.
+
+### What's in the box
+
+- **Synchronous (`Astroway`) and asynchronous (`AsyncAstroway`) clients** — identical surface, share constructor, methods, error types.
+- **Built on `httpx`** — modern Python HTTP, supports HTTP/1.1 + HTTP/2, sync + async natively.
+- **Two auth schemes:** `X-Api-Key` (default, matches curl/Postman) or `Authorization: Bearer` (matches Stripe/OpenAI/Anthropic convention) via `auth_scheme="bearer"`.
+- **Stainless-template error hierarchy:** `ApiError` → `BadRequestError` / `AuthenticationError` / `PermissionDeniedError` / `NotFoundError` / `UnprocessableEntityError` / `RateLimitError` / `InternalServerError` / `APIConnectionError` (→ `APITimeoutError`).
+- **Built-in retry** with exponential backoff + full jitter on 408 / 409 / 429 / 5xx and connection errors. Default 2 retries; configurable via `retry={"max_retries": 0}` to disable. Honors `Retry-After` (seconds or HTTP-date) on 429.
+- **Per-request timeout** via `httpx.Timeout`, default 30s.
+- **Identification headers** — `User-Agent: astroway-sdk-python/<version> (Python/<py-version>; <platform>)` and `X-Astroway-Channel: sdk-py`. **No telemetry, no phone-home.**
+- **Auto-unwrap of `{ ok, data, error }` envelope** — methods return the `data` payload directly so user code reads naturally.
+- **Context manager support** — both `with Astroway(...) as aw:` (sync) and `async with AsyncAstroway(...) as aw:` (async) close the underlying httpx client cleanly.
+- **PEP 561 typed package** — `py.typed` marker shipped, full type hints throughout.
+
+### Stack
+
+- Python 3.9+ (CPython tested on 3.9 / 3.10 / 3.11 / 3.12 / 3.13).
+- `httpx >= 0.27` — sync + async HTTP.
+- `pydantic >= 2.0` — model validation surface (used by integrators for typed bodies).
+- 40 unit tests — error classification, retry semantics, header propagation, auth scheme switching, async client parity.
+
+### Internal
+
+- Build with `hatchling`. Tests with `pytest` + `pytest-asyncio` + `respx`.
+- Wheel + sdist published via PyPI Trusted Publishers (OIDC, no long-lived tokens).
+- Provenance attestation on every release (Sigstore via GitHub Actions).

astroway-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AstroWay
+
+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.

astroway-0.1.0a1/PKG-INFO

@@ -0,0 +1,264 @@
+Metadata-Version: 2.4
+Name: astroway
+Version: 0.1.0a1
+Summary: Official Python SDK for the AstroWay API — natal, synastry, transits, Vedic, Human Design, Tarot, Numerology, AI horoscopes. Type-safe, retry-aware, OpenAPI 3.1 generated.
+Project-URL: Homepage, https://api.astroway.info/docs/
+Project-URL: Repository, https://github.com/astroway/astroway-python
+Project-URL: Issues, https://github.com/astroway/astroway-python/issues
+Project-URL: Changelog, https://github.com/astroway/astroway-python/blob/main/CHANGELOG.md
+Author-email: AstroWay <astroway.info@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,astrology,human-design,natal-chart,numerology,openapi,sdk,swiss-ephemeris,synastry,tarot,transits,vedic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic<3.0,>=2.0
+Provides-Extra: dev
+Requires-Dist: datamodel-code-generator[http]>=0.26; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# astroway
+
+> Official Python SDK for the [AstroWay API](https://api.astroway.info) — natal charts, synastry, transits, Vedic dashas, Tarot, Numerology, Human Design, AI horoscopes. Sync + async, type-hinted, retry-aware.
+
+[![PyPI version](https://img.shields.io/pypi/v/astroway.svg?style=flat&color=blue)](https://pypi.org/project/astroway/)
+[![Python versions](https://img.shields.io/pypi/pyversions/astroway.svg)](https://pypi.org/project/astroway/)
+[![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+700+ endpoints. Synchronous and asynchronous clients with the same surface. Built-in retry on 408/409/429/5xx with exponential backoff. Stainless-style error hierarchy (`AuthenticationError` / `RateLimitError` / `BadRequestError` / …). Just `httpx` + `pydantic` under the hood.
+
+---
+
+## Install
+
+```bash
+pip install astroway
+# or with uv
+uv add astroway
+# or with poetry
+poetry add astroway
+```
+
+Get an API key at <https://api.astroway.info/dashboard/sign-up> — **10 000 credits/month free**, no card required. Each endpoint costs 5–500 credits depending on what it computes ([pricing](https://api.astroway.info/pricing/)).
+
+Requires Python 3.9+.
+
+---
+
+## Quick start
+
+### Synchronous
+
+```python
+from astroway import Astroway
+
+aw = Astroway(api_key="aw_live_...")
+
+chart = aw.post("/chart", body={
+    "date": "1990-07-14",
+    "time": "14:30:00",
+    "timezoneOffset": 3,
+    "latitude": 50.45,
+    "longitude": 30.52,
+    "houseSystem": "P",
+})
+
+asc = chart["angles"]["asc"]
+print(f"ASC: {asc['sign']} {asc['degree']:.2f}°")
+```
+
+### Asynchronous
+
+```python
+import asyncio
+from astroway import AsyncAstroway
+
+async def main() -> None:
+    async with AsyncAstroway(api_key="aw_live_...") as aw:
+        chart = await aw.post("/chart", body={
+            "date": "1990-07-14",
+            "time": "14:30:00",
+            "timezoneOffset": 3,
+            "latitude": 50.45,
+            "longitude": 30.52,
+        })
+        print(chart["angles"]["asc"])
+
+asyncio.run(main())
+```
+
+The two clients share an identical surface — same constructor params, same methods (`get`, `post`, `put`, `delete`, low-level `request`), same error types.
+
+---
+
+## Common workflows
+
+### Synastry
+
+```python
+result = aw.post("/synastry", body={
+    "chart1": {"date": "1990-07-14", "time": "14:30:00", "timezoneOffset": 3, "latitude": 50.45, "longitude": 30.52},
+    "chart2": {"date": "1992-03-22", "time": "09:15:00", "timezoneOffset": 2, "latitude": 48.85, "longitude": 2.35},
+})
+print(f"Score: {result['compatibility']['score']}/100 ({result['compatibility']['label']})")
+```
+
+### Transits to natal
+
+```python
+transits = aw.post("/transits", body={
+    "date": "1990-07-14", "time": "14:30:00", "timezoneOffset": 3, "latitude": 50.45, "longitude": 30.52,
+    "targetDate": "2027-01-01",
+})
+```
+
+### Vedic Vimshottari Mahadasha
+
+```python
+dasha = aw.post("/vedic/dashas/vimshottari/maha", body={
+    "date": "1985-07-22", "time": "06:45:00", "timezoneOffset": 5.5,
+    "latitude": 19.07, "longitude": 72.87,
+})
+```
+
+### Tarot reading
+
+```python
+spread = aw.post("/tarot/rider-waite/spread", body={"spreadType": "three-card", "seed": 42})
+```
+
+### Human Design
+
+```python
+hd = aw.post("/human-design", body={
+    "date": "1990-07-14", "time": "14:30:00", "timezoneOffset": 3, "latitude": 50.45, "longitude": 30.52,
+})
+print(f"{hd['type']} — {hd['strategy']} — {hd['authority']}")
+```
+
+---
+
+## Error handling
+
+The SDK raises typed subclasses of `ApiError`. Catch order matters — most specific first:
+
+```python
+from astroway import (
+    Astroway, ApiError,
+    AuthenticationError, RateLimitError, BadRequestError,
+)
+
+try:
+    aw.post("/chart", body=body)
+except RateLimitError as e:
+    time.sleep(e.retry_after_seconds or 60)
+    # retry once...
+except AuthenticationError:
+    raise RuntimeError("Rotate your AstroWay API key")
+except BadRequestError as e:
+    print("Validation failed:", e.body)
+except ApiError as e:
+    print(f"API error {e.status} ({e.code}): {e!s} [request_id={e.request_id}]")
+```
+
+Full hierarchy:
+
+- `ApiError` (base)
+  - `APIConnectionError`
+    - `APITimeoutError`
+  - `BadRequestError` (400)
+  - `AuthenticationError` (401)
+  - `PermissionDeniedError` (403)
+  - `NotFoundError` (404)
+  - `UnprocessableEntityError` (422)
+  - `RateLimitError` (429) — carries `retry_after_seconds`
+  - `InternalServerError` (5xx)
+
+---
+
+## Configuration
+
+```python
+aw = Astroway(
+    api_key="aw_live_...",                  # required
+    base_url="https://api.astroway.info/v1", # override for staging / self-hosted
+    auth_scheme="header",                    # "header" (X-Api-Key, default) or "bearer" (Authorization: Bearer)
+    timeout=30.0,                            # per-request timeout in seconds
+    retry={
+        "max_retries": 2,                    # total attempts = 1 + max_retries
+        "base_delay_ms": 250,
+        "max_delay_ms": 30_000,
+        "retryable_statuses": frozenset({408, 409, 429, 500, 502, 503, 504}),
+    },
+    default_headers={"X-Trace-Id": "..."},
+)
+```
+
+The default retry honors `Retry-After` (seconds or HTTP-date) on 429 responses.
+
+Set `retry={"max_retries": 0}` to disable retries entirely.
+
+---
+
+## Authentication
+
+Two equivalent auth schemes — pick whichever your stack prefers:
+
+- **Header (default):** `X-Api-Key: aw_live_...` — same convention as `curl`/Postman examples.
+- **Bearer:** `Authorization: Bearer aw_live_...` — same convention as Stripe/OpenAI/Anthropic SDKs.
+
+Set via `auth_scheme="bearer"` in the constructor.
+
+---
+
+## Privacy
+
+The SDK does **not** phone home. There is no telemetry, no analytics, no usage reporting. The only network traffic the SDK originates is the AstroWay API calls you ask it to make.
+
+Outgoing requests carry two identifying headers so the AstroWay backend can distinguish SDK traffic from raw HTTP traffic in its own logs:
+
+- `User-Agent: astroway-sdk-python/<version> (Python/<py-version>; <platform>)`
+- `X-Astroway-Channel: sdk-py`
+
+Neither carries a session ID, machine fingerprint, or anything personal.
+
+---
+
+## Stability
+
+- **Public API stable inside a major version.** Methods/classes shipped under `1.x` won't be renamed or removed without a deprecation note in `CHANGELOG.md` and a one-minor parallel-availability window.
+- **Body shape stable inside a minor version.** Tightening (constraints, enum) ships in patches; new required keys require a minor bump.
+- **API version vs SDK version are independent.** SDK `0.x` follows its own semver; the API itself sits at `/v1/`.
+
+---
+
+## Links
+
+- 📦 PyPI: <https://pypi.org/project/astroway/>
+- 📘 API docs: <https://api.astroway.info/docs/api/>
+- 🔑 Sign up & dashboard: <https://api.astroway.info/dashboard/>
+- 💰 Pricing: <https://api.astroway.info/pricing/>
+- 🟦 TypeScript SDK: [`@astroway/sdk`](https://www.npmjs.com/package/@astroway/sdk)
+- 🤖 MCP server: [`@astroway/mcp`](https://www.npmjs.com/package/@astroway/mcp)
+- 🌐 Website: <https://astroway.info>
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

astroway-0.1.0a1/README.md

@@ -0,0 +1,230 @@
+# astroway
+
+> Official Python SDK for the [AstroWay API](https://api.astroway.info) — natal charts, synastry, transits, Vedic dashas, Tarot, Numerology, Human Design, AI horoscopes. Sync + async, type-hinted, retry-aware.
+
+[![PyPI version](https://img.shields.io/pypi/v/astroway.svg?style=flat&color=blue)](https://pypi.org/project/astroway/)
+[![Python versions](https://img.shields.io/pypi/pyversions/astroway.svg)](https://pypi.org/project/astroway/)
+[![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+700+ endpoints. Synchronous and asynchronous clients with the same surface. Built-in retry on 408/409/429/5xx with exponential backoff. Stainless-style error hierarchy (`AuthenticationError` / `RateLimitError` / `BadRequestError` / …). Just `httpx` + `pydantic` under the hood.
+
+---
+
+## Install
+
+```bash
+pip install astroway
+# or with uv
+uv add astroway
+# or with poetry
+poetry add astroway
+```
+
+Get an API key at <https://api.astroway.info/dashboard/sign-up> — **10 000 credits/month free**, no card required. Each endpoint costs 5–500 credits depending on what it computes ([pricing](https://api.astroway.info/pricing/)).
+
+Requires Python 3.9+.
+
+---
+
+## Quick start
+
+### Synchronous
+
+```python
+from astroway import Astroway
+
+aw = Astroway(api_key="aw_live_...")
+
+chart = aw.post("/chart", body={
+    "date": "1990-07-14",
+    "time": "14:30:00",
+    "timezoneOffset": 3,
+    "latitude": 50.45,
+    "longitude": 30.52,
+    "houseSystem": "P",
+})
+
+asc = chart["angles"]["asc"]
+print(f"ASC: {asc['sign']} {asc['degree']:.2f}°")
+```
+
+### Asynchronous
+
+```python
+import asyncio
+from astroway import AsyncAstroway
+
+async def main() -> None:
+    async with AsyncAstroway(api_key="aw_live_...") as aw:
+        chart = await aw.post("/chart", body={
+            "date": "1990-07-14",
+            "time": "14:30:00",
+            "timezoneOffset": 3,
+            "latitude": 50.45,
+            "longitude": 30.52,
+        })
+        print(chart["angles"]["asc"])
+
+asyncio.run(main())
+```
+
+The two clients share an identical surface — same constructor params, same methods (`get`, `post`, `put`, `delete`, low-level `request`), same error types.
+
+---
+
+## Common workflows
+
+### Synastry
+
+```python
+result = aw.post("/synastry", body={
+    "chart1": {"date": "1990-07-14", "time": "14:30:00", "timezoneOffset": 3, "latitude": 50.45, "longitude": 30.52},
+    "chart2": {"date": "1992-03-22", "time": "09:15:00", "timezoneOffset": 2, "latitude": 48.85, "longitude": 2.35},
+})
+print(f"Score: {result['compatibility']['score']}/100 ({result['compatibility']['label']})")
+```
+
+### Transits to natal
+
+```python
+transits = aw.post("/transits", body={
+    "date": "1990-07-14", "time": "14:30:00", "timezoneOffset": 3, "latitude": 50.45, "longitude": 30.52,
+    "targetDate": "2027-01-01",
+})
+```
+
+### Vedic Vimshottari Mahadasha
+
+```python
+dasha = aw.post("/vedic/dashas/vimshottari/maha", body={
+    "date": "1985-07-22", "time": "06:45:00", "timezoneOffset": 5.5,
+    "latitude": 19.07, "longitude": 72.87,
+})
+```
+
+### Tarot reading
+
+```python
+spread = aw.post("/tarot/rider-waite/spread", body={"spreadType": "three-card", "seed": 42})
+```
+
+### Human Design
+
+```python
+hd = aw.post("/human-design", body={
+    "date": "1990-07-14", "time": "14:30:00", "timezoneOffset": 3, "latitude": 50.45, "longitude": 30.52,
+})
+print(f"{hd['type']} — {hd['strategy']} — {hd['authority']}")
+```
+
+---
+
+## Error handling
+
+The SDK raises typed subclasses of `ApiError`. Catch order matters — most specific first:
+
+```python
+from astroway import (
+    Astroway, ApiError,
+    AuthenticationError, RateLimitError, BadRequestError,
+)
+
+try:
+    aw.post("/chart", body=body)
+except RateLimitError as e:
+    time.sleep(e.retry_after_seconds or 60)
+    # retry once...
+except AuthenticationError:
+    raise RuntimeError("Rotate your AstroWay API key")
+except BadRequestError as e:
+    print("Validation failed:", e.body)
+except ApiError as e:
+    print(f"API error {e.status} ({e.code}): {e!s} [request_id={e.request_id}]")
+```
+
+Full hierarchy:
+
+- `ApiError` (base)
+  - `APIConnectionError`
+    - `APITimeoutError`
+  - `BadRequestError` (400)
+  - `AuthenticationError` (401)
+  - `PermissionDeniedError` (403)
+  - `NotFoundError` (404)
+  - `UnprocessableEntityError` (422)
+  - `RateLimitError` (429) — carries `retry_after_seconds`
+  - `InternalServerError` (5xx)
+
+---
+
+## Configuration
+
+```python
+aw = Astroway(
+    api_key="aw_live_...",                  # required
+    base_url="https://api.astroway.info/v1", # override for staging / self-hosted
+    auth_scheme="header",                    # "header" (X-Api-Key, default) or "bearer" (Authorization: Bearer)
+    timeout=30.0,                            # per-request timeout in seconds
+    retry={
+        "max_retries": 2,                    # total attempts = 1 + max_retries
+        "base_delay_ms": 250,
+        "max_delay_ms": 30_000,
+        "retryable_statuses": frozenset({408, 409, 429, 500, 502, 503, 504}),
+    },
+    default_headers={"X-Trace-Id": "..."},
+)
+```
+
+The default retry honors `Retry-After` (seconds or HTTP-date) on 429 responses.
+
+Set `retry={"max_retries": 0}` to disable retries entirely.
+
+---
+
+## Authentication
+
+Two equivalent auth schemes — pick whichever your stack prefers:
+
+- **Header (default):** `X-Api-Key: aw_live_...` — same convention as `curl`/Postman examples.
+- **Bearer:** `Authorization: Bearer aw_live_...` — same convention as Stripe/OpenAI/Anthropic SDKs.
+
+Set via `auth_scheme="bearer"` in the constructor.
+
+---
+
+## Privacy
+
+The SDK does **not** phone home. There is no telemetry, no analytics, no usage reporting. The only network traffic the SDK originates is the AstroWay API calls you ask it to make.
+
+Outgoing requests carry two identifying headers so the AstroWay backend can distinguish SDK traffic from raw HTTP traffic in its own logs:
+
+- `User-Agent: astroway-sdk-python/<version> (Python/<py-version>; <platform>)`
+- `X-Astroway-Channel: sdk-py`
+
+Neither carries a session ID, machine fingerprint, or anything personal.
+
+---
+
+## Stability
+
+- **Public API stable inside a major version.** Methods/classes shipped under `1.x` won't be renamed or removed without a deprecation note in `CHANGELOG.md` and a one-minor parallel-availability window.
+- **Body shape stable inside a minor version.** Tightening (constraints, enum) ships in patches; new required keys require a minor bump.
+- **API version vs SDK version are independent.** SDK `0.x` follows its own semver; the API itself sits at `/v1/`.
+
+---
+
+## Links
+
+- 📦 PyPI: <https://pypi.org/project/astroway/>
+- 📘 API docs: <https://api.astroway.info/docs/api/>
+- 🔑 Sign up & dashboard: <https://api.astroway.info/dashboard/>
+- 💰 Pricing: <https://api.astroway.info/pricing/>
+- 🟦 TypeScript SDK: [`@astroway/sdk`](https://www.npmjs.com/package/@astroway/sdk)
+- 🤖 MCP server: [`@astroway/mcp`](https://www.npmjs.com/package/@astroway/mcp)
+- 🌐 Website: <https://astroway.info>
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

astroway-0.1.0a1/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "astroway"
+version = "0.1.0a1"
+description = "Official Python SDK for the AstroWay API — natal, synastry, transits, Vedic, Human Design, Tarot, Numerology, AI horoscopes. Type-safe, retry-aware, OpenAPI 3.1 generated."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "AstroWay", email = "astroway.info@gmail.com" }]
+keywords = [
+  "astrology", "api", "sdk",
+  "natal-chart", "synastry", "transits",
+  "vedic", "human-design", "tarot", "numerology",
+  "swiss-ephemeris", "openapi",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27,<1.0",
+  "pydantic>=2.0,<3.0",
+]
+
+[project.urls]
+Homepage = "https://api.astroway.info/docs/"
+Repository = "https://github.com/astroway/astroway-python"
+Issues = "https://github.com/astroway/astroway-python/issues"
+Changelog = "https://github.com/astroway/astroway-python/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "respx>=0.21",
+  "ruff>=0.6",
+  "datamodel-code-generator[http]>=0.26",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/astroway"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/astroway",
+  "openapi.json",
+  "README.md",
+  "CHANGELOG.md",
+  "LICENSE",
+  "pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "RUF"]
+ignore = ["E501"]

astroway-0.1.0a1/src/astroway/__init__.py

@@ -0,0 +1,56 @@
+"""astroway — Official Python SDK for the AstroWay API.
+
+Quick start::
+
+    from astroway import Astroway
+
+    aw = Astroway(api_key="aw_live_...")
+    chart = aw.post("/chart", body={
+        "date": "1990-07-14", "time": "14:30:00", "timezoneOffset": 3,
+        "latitude": 50.45, "longitude": 30.52,
+    })
+    print(chart["angles"]["asc"])
+
+For async workloads use :class:`AsyncAstroway` with the same surface.
+
+Errors thrown by the SDK live in :mod:`astroway.errors` — catch
+``RateLimitError`` / ``AuthenticationError`` / ``BadRequestError`` /
+``ApiError`` for the common cases.
+"""
+
+from __future__ import annotations
+
+from ._client import AsyncAstroway, Astroway
+from ._retry import RetryConfig
+from ._version import SDK_VERSION
+from .errors import (
+    APIConnectionError,
+    APITimeoutError,
+    ApiError,
+    AuthenticationError,
+    BadRequestError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    UnprocessableEntityError,
+)
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    "APIConnectionError",
+    "APITimeoutError",
+    "ApiError",
+    "AsyncAstroway",
+    "Astroway",
+    "AuthenticationError",
+    "BadRequestError",
+    "InternalServerError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "RetryConfig",
+    "SDK_VERSION",
+    "UnprocessableEntityError",
+]

astroway-0.1.0a1/src/astroway/_client.py

@@ -0,0 +1,327 @@
+"""Astroway / AsyncAstroway — sync + async clients wrapping httpx with auth,
+retry, error mapping, and identification headers.
+"""
+
+from __future__ import annotations
+
+import platform
+import sys
+from collections.abc import Mapping
+from typing import Any, Literal
+
+import httpx
+
+from ._retry import AsyncRetryTransport, RetryConfig, SyncRetryTransport
+from ._version import SDK_VERSION
+from .errors import (
+    APIConnectionError,
+    APITimeoutError,
+    ApiError,
+    classify_http_error,
+)
+
+DEFAULT_BASE_URL = "https://api.astroway.info/v1"
+AuthScheme = Literal["header", "bearer"]
+
+
+def _user_agent() -> str:
+    py = f"Python/{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+    plat = f"{platform.system().lower()}-{platform.machine().lower()}"
+    return f"astroway-sdk-python/{SDK_VERSION} ({py}; {plat})"
+
+
+def _default_headers(api_key: str, auth_scheme: AuthScheme) -> dict[str, str]:
+    headers: dict[str, str] = {
+        "User-Agent": _user_agent(),
+        "X-Astroway-Channel": "sdk-py",
+        "Content-Type": "application/json",
+    }
+    if auth_scheme == "bearer":
+        headers["Authorization"] = f"Bearer {api_key}"
+    else:
+        headers["X-Api-Key"] = api_key
+    return headers
+
+
+def _raise_on_error(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+    request_id = response.headers.get("x-request-id")
+    retry_after_raw = response.headers.get("retry-after")
+    retry_after_seconds: int | None = None
+    if retry_after_raw is not None:
+        try:
+            retry_after_seconds = int(float(retry_after_raw))
+        except ValueError:
+            retry_after_seconds = None
+
+    body: Any = None
+    code: str | None = None
+    message = f"{response.status_code} {response.reason_phrase}"
+    try:
+        body = response.json()
+        err = body.get("error") if isinstance(body, dict) else None
+        if isinstance(err, dict):
+            if err.get("code"):
+                code = str(err["code"])
+            if err.get("message"):
+                message = str(err["message"])
+    except Exception:  # noqa: BLE001 — body wasn't JSON, fine
+        pass
+
+    raise classify_http_error(
+        status=response.status_code,
+        message=message,
+        code=code,
+        body=body,
+        request_id=request_id,
+        retry_after_seconds=retry_after_seconds,
+    )
+
+
+class _BaseAstroway:
+    """Shared constructor logic + property accessors for sync and async clients."""
+
+    base_url: str
+    api_key: str
+    auth_scheme: AuthScheme
+    timeout: float
+    retry: RetryConfig
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str | None = None,
+        auth_scheme: AuthScheme = "header",
+        timeout: float = 30.0,
+        retry: dict | RetryConfig | None = None,
+        default_headers: Mapping[str, str] | None = None,
+    ) -> None:
+        if not api_key:
+            raise ApiError(
+                "Astroway: api_key is required. Get one at "
+                "https://api.astroway.info/dashboard/sign-up — 10,000 credits/month free."
+            )
+        self.api_key = api_key
+        self.base_url = base_url or DEFAULT_BASE_URL
+        self.auth_scheme = auth_scheme
+        self.timeout = timeout
+        self.retry = (
+            retry if isinstance(retry, RetryConfig) else RetryConfig.from_dict(retry)
+        )
+        self._headers: dict[str, str] = {
+            **_default_headers(api_key, auth_scheme),
+            **(dict(default_headers) if default_headers else {}),
+        }
+
+
+class Astroway(_BaseAstroway):
+    """Synchronous Astroway client.
+
+    Example::
+
+        from astroway import Astroway
+        aw = Astroway(api_key="aw_live_...")
+        chart = aw.post("/chart", body={
+            "date": "1990-07-14", "time": "14:30:00", "timezoneOffset": 3,
+            "latitude": 50.45, "longitude": 30.52,
+        })
+        print(chart["angles"]["asc"])
+    """
+
+    _http: httpx.Client
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str | None = None,
+        auth_scheme: AuthScheme = "header",
+        timeout: float = 30.0,
+        retry: dict | RetryConfig | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            auth_scheme=auth_scheme,
+            timeout=timeout,
+            retry=retry,
+            default_headers=default_headers,
+        )
+        inner = transport if transport is not None else httpx.HTTPTransport()
+        wrapped = SyncRetryTransport(inner, self.retry)
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            headers=self._headers,
+            timeout=self.timeout,
+            transport=wrapped,
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any | None = None,
+        params: Mapping[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Any:
+        try:
+            response = self._http.request(
+                method,
+                path,
+                json=body,
+                params=params,
+                headers=dict(headers) if headers else None,
+            )
+        except httpx.TimeoutException as exc:
+            raise APITimeoutError(
+                f"Request to {path} timed out after {self.timeout}s"
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise APIConnectionError(
+                f"Network error calling {path}: {exc!s}. Check connection or base_url."
+            ) from exc
+
+        _raise_on_error(response)
+        try:
+            payload = response.json()
+        except Exception:  # noqa: BLE001
+            return response.text
+        # Endpoints wrap responses as { ok, data, error } — unwrap data when present.
+        if isinstance(payload, dict) and "data" in payload:
+            return payload["data"]
+        return payload
+
+    def get(self, path: str, *, params: Mapping[str, Any] | None = None) -> Any:
+        return self.request("GET", path, params=params)
+
+    def post(
+        self,
+        path: str,
+        *,
+        body: Any | None = None,
+        params: Mapping[str, Any] | None = None,
+    ) -> Any:
+        return self.request("POST", path, body=body, params=params)
+
+    def put(self, path: str, *, body: Any | None = None) -> Any:
+        return self.request("PUT", path, body=body)
+
+    def delete(self, path: str) -> Any:
+        return self.request("DELETE", path)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Astroway:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+class AsyncAstroway(_BaseAstroway):
+    """Async counterpart of :class:`Astroway`. Same surface, awaitable methods.
+
+    Example::
+
+        from astroway import AsyncAstroway
+        async with AsyncAstroway(api_key="aw_live_...") as aw:
+            chart = await aw.post("/chart", body={...})
+    """
+
+    _http: httpx.AsyncClient
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str | None = None,
+        auth_scheme: AuthScheme = "header",
+        timeout: float = 30.0,
+        retry: dict | RetryConfig | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            auth_scheme=auth_scheme,
+            timeout=timeout,
+            retry=retry,
+            default_headers=default_headers,
+        )
+        inner = transport if transport is not None else httpx.AsyncHTTPTransport()
+        wrapped = AsyncRetryTransport(inner, self.retry)
+        self._http = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers=self._headers,
+            timeout=self.timeout,
+            transport=wrapped,
+        )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any | None = None,
+        params: Mapping[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Any:
+        try:
+            response = await self._http.request(
+                method,
+                path,
+                json=body,
+                params=params,
+                headers=dict(headers) if headers else None,
+            )
+        except httpx.TimeoutException as exc:
+            raise APITimeoutError(
+                f"Request to {path} timed out after {self.timeout}s"
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise APIConnectionError(
+                f"Network error calling {path}: {exc!s}. Check connection or base_url."
+            ) from exc
+
+        _raise_on_error(response)
+        try:
+            payload = response.json()
+        except Exception:  # noqa: BLE001
+            return response.text
+        if isinstance(payload, dict) and "data" in payload:
+            return payload["data"]
+        return payload
+
+    async def get(self, path: str, *, params: Mapping[str, Any] | None = None) -> Any:
+        return await self.request("GET", path, params=params)
+
+    async def post(
+        self,
+        path: str,
+        *,
+        body: Any | None = None,
+        params: Mapping[str, Any] | None = None,
+    ) -> Any:
+        return await self.request("POST", path, body=body, params=params)
+
+    async def put(self, path: str, *, body: Any | None = None) -> Any:
+        return await self.request("PUT", path, body=body)
+
+    async def delete(self, path: str) -> Any:
+        return await self.request("DELETE", path)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncAstroway:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()

astroway-0.1.0a1/src/astroway/_retry.py

@@ -0,0 +1,157 @@
+"""httpx retry transports — sync + async. Default: 2 retries, exponential
+backoff with full jitter, on connection errors / 408 / 409 / 429 / 5xx.
+Honors ``Retry-After`` (seconds or HTTP-date) when present on 429.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import email.utils
+import random
+import time
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+import httpx
+
+DEFAULT_RETRYABLE: frozenset[int] = frozenset({408, 409, 429, 500, 502, 503, 504})
+
+
+@dataclass(frozen=True)
+class RetryConfig:
+    """Retry knobs for the SDK transport. ``max_retries=0`` disables retries entirely."""
+
+    max_retries: int = 2
+    base_delay_ms: int = 250
+    max_delay_ms: int = 30_000
+    retryable_statuses: frozenset[int] = DEFAULT_RETRYABLE
+
+    @classmethod
+    def from_dict(cls, value: dict | None) -> RetryConfig:
+        if value is None:
+            return cls()
+        kwargs: dict = {}
+        if "max_retries" in value:
+            kwargs["max_retries"] = int(value["max_retries"])
+        if "base_delay_ms" in value:
+            kwargs["base_delay_ms"] = int(value["base_delay_ms"])
+        if "max_delay_ms" in value:
+            kwargs["max_delay_ms"] = int(value["max_delay_ms"])
+        if "retryable_statuses" in value:
+            kwargs["retryable_statuses"] = frozenset(value["retryable_statuses"])
+        return cls(**kwargs)
+
+
+def _parse_retry_after(value: str | None) -> float | None:
+    """Returns delay in milliseconds, or None when header absent / unparseable."""
+    if not value:
+        return None
+    try:
+        seconds = float(value)
+        if seconds >= 0:
+            return seconds * 1000
+    except ValueError:
+        pass
+    try:
+        when = email.utils.parsedate_to_datetime(value)
+        delta = (when.timestamp() - time.time()) * 1000
+        return max(0.0, delta)
+    except (TypeError, ValueError):
+        return None
+
+
+def _jitter_delay_ms(attempt: int, base: int, cap: int) -> float:
+    upper = min(cap, base * (2**attempt))
+    return random.random() * upper
+
+
+_RetryableExceptions: tuple[type[BaseException], ...] = (
+    httpx.ConnectError,
+    httpx.ConnectTimeout,
+    httpx.ReadError,
+    httpx.WriteError,
+    httpx.PoolTimeout,
+    httpx.ReadTimeout,
+)
+
+
+class SyncRetryTransport(httpx.BaseTransport):
+    """Wraps a sync transport with retry semantics."""
+
+    def __init__(self, inner: httpx.BaseTransport, config: RetryConfig) -> None:
+        self._inner = inner
+        self._config = config
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        last_exc: BaseException | None = None
+        for attempt in range(self._config.max_retries + 1):
+            try:
+                response = self._inner.handle_request(request)
+                if (
+                    response.status_code not in self._config.retryable_statuses
+                    or attempt == self._config.max_retries
+                ):
+                    return response
+                # Drain response body before retry — httpx requires this so
+                # the connection can be returned to the pool cleanly.
+                response.read()
+                response.close()
+                retry_after_ms = _parse_retry_after(response.headers.get("retry-after"))
+                delay = retry_after_ms or _jitter_delay_ms(
+                    attempt, self._config.base_delay_ms, self._config.max_delay_ms
+                )
+                time.sleep(delay / 1000)
+            except _RetryableExceptions as exc:
+                last_exc = exc
+                if attempt == self._config.max_retries:
+                    raise
+                delay = _jitter_delay_ms(
+                    attempt, self._config.base_delay_ms, self._config.max_delay_ms
+                )
+                time.sleep(delay / 1000)
+        if last_exc is not None:
+            raise last_exc
+        raise RuntimeError("retry loop exhausted without response or exception")
+
+    def close(self) -> None:
+        self._inner.close()
+
+
+class AsyncRetryTransport(httpx.AsyncBaseTransport):
+    """Async counterpart of :class:`SyncRetryTransport`."""
+
+    def __init__(self, inner: httpx.AsyncBaseTransport, config: RetryConfig) -> None:
+        self._inner = inner
+        self._config = config
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        last_exc: BaseException | None = None
+        for attempt in range(self._config.max_retries + 1):
+            try:
+                response = await self._inner.handle_async_request(request)
+                if (
+                    response.status_code not in self._config.retryable_statuses
+                    or attempt == self._config.max_retries
+                ):
+                    return response
+                await response.aread()
+                await response.aclose()
+                retry_after_ms = _parse_retry_after(response.headers.get("retry-after"))
+                delay = retry_after_ms or _jitter_delay_ms(
+                    attempt, self._config.base_delay_ms, self._config.max_delay_ms
+                )
+                await asyncio.sleep(delay / 1000)
+            except _RetryableExceptions as exc:
+                last_exc = exc
+                if attempt == self._config.max_retries:
+                    raise
+                delay = _jitter_delay_ms(
+                    attempt, self._config.base_delay_ms, self._config.max_delay_ms
+                )
+                await asyncio.sleep(delay / 1000)
+        if last_exc is not None:
+            raise last_exc
+        raise RuntimeError("retry loop exhausted without response or exception")
+
+    async def aclose(self) -> None:
+        await self._inner.aclose()

astroway-0.1.0a1/src/astroway/_version.py

@@ -0,0 +1,3 @@
+"""SDK version. Mirror of pyproject.toml `version`. Bumped together."""
+
+SDK_VERSION = "0.1.0a1"

astroway-0.1.0a1/src/astroway/errors.py

@@ -0,0 +1,137 @@
+"""Error hierarchy mirroring the Stainless template (OpenAI / Anthropic / Cloudflare SDKs).
+
+Catch order recommendation in user code::
+
+    try:
+        ...
+    except RateLimitError as e:
+        # respect e.retry_after_seconds
+    except AuthenticationError:
+        # rotate the API key
+    except ApiError as e:
+        # generic 4xx/5xx, inspect e.status / e.code / e.body / e.request_id
+    except Exception:
+        raise
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class ApiError(Exception):
+    """Base class for every error raised by the SDK on top of Python's built-ins."""
+
+    status: int | None
+    code: str | None
+    body: Any | None
+    request_id: str | None
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        code: str | None = None,
+        body: Any | None = None,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.body = body
+        self.request_id = request_id
+
+
+class APIConnectionError(ApiError):
+    """Network-level failure — DNS, connection refused, TLS, timeouts before bytes received."""
+
+
+class APITimeoutError(APIConnectionError):
+    """Request exceeded the configured timeout."""
+
+
+class BadRequestError(ApiError):
+    """HTTP 400 — request did not parse or violated a basic constraint."""
+
+
+class AuthenticationError(ApiError):
+    """HTTP 401 — API key missing, invalid, or revoked."""
+
+
+class PermissionDeniedError(ApiError):
+    """HTTP 403 — authenticated but not allowed to call this endpoint."""
+
+
+class NotFoundError(ApiError):
+    """HTTP 404 — resource (or endpoint) does not exist."""
+
+
+class UnprocessableEntityError(ApiError):
+    """HTTP 422 — payload parsed but failed schema validation."""
+
+
+class RateLimitError(ApiError):
+    """HTTP 429 — rate limit exceeded. ``retry_after_seconds`` from ``Retry-After`` if present."""
+
+    retry_after_seconds: int | None
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        code: str | None = None,
+        body: Any | None = None,
+        request_id: str | None = None,
+        retry_after_seconds: int | None = None,
+    ) -> None:
+        super().__init__(message, status=status, code=code, body=body, request_id=request_id)
+        self.retry_after_seconds = retry_after_seconds
+
+
+class InternalServerError(ApiError):
+    """HTTP 5xx — server-side failure. Retried by default unless ``retry={"max_retries": 0}``."""
+
+
+def classify_http_error(
+    *,
+    status: int,
+    message: str,
+    code: str | None = None,
+    body: Any | None = None,
+    request_id: str | None = None,
+    retry_after_seconds: int | None = None,
+) -> ApiError:
+    """Maps an HTTP status to the most specific subclass."""
+    init: dict[str, Any] = {"status": status, "code": code, "body": body, "request_id": request_id}
+    if status == 400:
+        return BadRequestError(message, **init)
+    if status == 401:
+        return AuthenticationError(message, **init)
+    if status == 403:
+        return PermissionDeniedError(message, **init)
+    if status == 404:
+        return NotFoundError(message, **init)
+    if status == 422:
+        return UnprocessableEntityError(message, **init)
+    if status == 429:
+        return RateLimitError(message, **init, retry_after_seconds=retry_after_seconds)
+    if status >= 500:
+        return InternalServerError(message, **init)
+    return ApiError(message, **init)
+
+
+__all__ = [
+    "APIConnectionError",
+    "APITimeoutError",
+    "ApiError",
+    "AuthenticationError",
+    "BadRequestError",
+    "InternalServerError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "UnprocessableEntityError",
+    "classify_http_error",
+]