astro96-api 0.2.0__tar.gz → 0.3.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. {astro96_api-0.2.0 → astro96_api-0.3.1}/PKG-INFO +11 -1
  2. {astro96_api-0.2.0 → astro96_api-0.3.1}/README.md +130 -120
  3. {astro96_api-0.2.0 → astro96_api-0.3.1}/pyproject.toml +1 -1
  4. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_client.py +664 -593
  5. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/client.py +162 -26
  6. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/families/ai.py +5 -5
  7. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/families/bnn.py +17 -17
  8. astro96_api-0.3.1/src/astro96_api/_generated/families/chinese.py +310 -0
  9. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/families/dashas.py +726 -17
  10. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/families/doshas_yogas.py +64 -64
  11. astro96_api-0.3.1/src/astro96_api/_generated/families/festivals_muhurta.py +2094 -0
  12. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/families/jaimini.py +15 -15
  13. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/families/kp.py +199 -13
  14. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/families/lal_kitab.py +14 -14
  15. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/families/matching.py +35 -35
  16. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/families/numerology.py +427 -1
  17. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/families/panchang.py +2750 -74
  18. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/families/predictions.py +624 -20
  19. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/families/remedies.py +48 -2
  20. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/families/reports.py +309 -45
  21. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/families/strengths.py +37 -37
  22. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/families/tajika.py +11 -11
  23. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/families/utilities.py +435 -6
  24. astro96_api-0.3.1/src/astro96_api/_generated/families/vastu.py +1364 -0
  25. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/families/vedic_charts.py +251 -63
  26. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/families/western.py +1097 -104
  27. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/schemas.py +2722 -232
  28. astro96_api-0.3.1/src/astro96_api/_version.py +1 -0
  29. astro96_api-0.2.0/src/astro96_api/_generated/families/chinese.py +0 -149
  30. astro96_api-0.2.0/src/astro96_api/_generated/families/festivals_muhurta.py +0 -657
  31. astro96_api-0.2.0/src/astro96_api/_generated/families/vastu.py +0 -670
  32. astro96_api-0.2.0/src/astro96_api/_version.py +0 -1
  33. {astro96_api-0.2.0 → astro96_api-0.3.1}/.gitignore +0 -0
  34. {astro96_api-0.2.0 → astro96_api-0.3.1}/LICENSE +0 -0
  35. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/__init__.py +0 -0
  36. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_errors.py +0 -0
  37. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/__init__.py +0 -0
  38. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/families/__init__.py +0 -0
  39. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/families/face_reading.py +0 -0
  40. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/families/human_design.py +0 -0
  41. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/families/location_astrology.py +0 -0
  42. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/families/mundane.py +0 -0
  43. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/families/palmistry.py +0 -0
  44. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_generated/families/tarot.py +0 -0
  45. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_types.py +0 -0
  46. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/_webhooks.py +0 -0
  47. {astro96_api-0.2.0 → astro96_api-0.3.1}/src/astro96_api/py.typed +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: astro96-api
3
- Version: 0.2.0
3
+ Version: 0.3.1
4
4
  Summary: Official Python client for the 96Astro API: Vedic and Western astrology, panchang, matching, reports and AI readings.
5
5
  Project-URL: Documentation, https://96astroapi.com/docs/sdks
6
6
  Project-URL: API reference, https://96astroapi.com/docs/reference
@@ -116,6 +116,16 @@ Full guide: https://96astroapi.com/docs/sdks
116
116
 
117
117
  > **Not wrapped yet:** AI streaming (`stream: true` / `Accept: text/event-stream`), the `/v1/conversations` routes and `.ics` calendar export. These clients always ask for JSON; call those routes over plain HTTP (see https://96astroapi.com/docs/ai-streaming-and-chat). Everything else, including the image options (`image_format`, `image_theme`, `image_delivery`), works through the typed inputs.
118
118
 
119
+ ## Name your app (optional)
120
+
121
+ Optional: tell the API which app is calling, so you can see where your keys are used (the dashboard's *Where your keys are used*) and spot a leaked key.
122
+
123
+ ```python
124
+ astro = Astro96Client(api_key=key, app_info={"name": "Acme Shop", "version": "2.1.0", "url": "https://shop.acme.com"})
125
+ ```
126
+
127
+ The name is required (printable ASCII, at most 60 characters, no `/` or parentheses); the version (at most 40) and the url (`http(s)`, at most 120) are optional. It is sent as the `X-Astro-App` header, never with your key; the API keeps the name, the version and only the **host** of the url. The User-Agent also carries the platform (`plt/node`, `plt/linux`...). An invalid value is refused when the client is created. (`ValueError`)
128
+
119
129
  ## Development
120
130
 
121
131
  The typed methods in `src/astro96_api/_generated/` are written by `tools/sdk/generate_python.py` from `packages/registry/openapi/v1.openapi.json`; never edit them by hand.
@@ -1,120 +1,130 @@
1
- # astro96-api
2
-
3
- The official Python client for the [96Astro API](https://96astroapi.com): Vedic and Western astrology, panchang, matching, reports and AI readings over one JSON API.
4
-
5
- - Sync (`Astro96Client`) and asyncio (`AsyncAstro96Client`) clients on `httpx`, Python 3.9+
6
- - A typed method for every capability, generated from the OpenAPI document (`TypedDict` request bodies)
7
- - Retries with backoff on `429` / `503` (honouring `Retry-After`), automatic idempotency keys so a retry is never charged twice
8
- - `ApiError` with `code`, `field`, `retryable` and `request_id`; rate-limit headers on every response
9
- - PDF job helpers (`create_pdf_job`, `wait_for_job`, `download_file`, `render_pdf`) and webhook signature verification
10
-
11
- > **Not on PyPI yet.** Publishing is in progress; until then `pip install astro96-api` will not find the package. Contact support for a pre-release wheel, or build it from this repository (see Development).
12
-
13
- ## Install
14
-
15
- ```bash
16
- pip install astro96-api
17
- ```
18
-
19
- ## Quickstart
20
-
21
- ```python
22
- from astro96_api import Astro96Client
23
-
24
- astro = Astro96Client() # reads ASTRO_API_KEY (sk_test_... or sk_live_...)
25
-
26
- res = astro.vedic_charts.planet_positions(
27
- {"datetime": "1990-10-18T14:30:00", "timezone": "Asia/Kolkata", "latitude": 28.6139, "longitude": 77.209}
28
- )
29
- print(res.data["ascendant"]["sign"], res.meta["credits_used"], res.rate_limit)
30
- ```
31
-
32
- ```python
33
- import asyncio
34
- from astro96_api import AsyncAstro96Client
35
-
36
- async def main() -> None:
37
- async with AsyncAstro96Client() as astro:
38
- res = await astro.panchang.daily_panchang(
39
- {"date": "2026-10-15", "timezone": "Asia/Kolkata", "latitude": 28.6139, "longitude": 77.209}
40
- )
41
- print(res.data)
42
-
43
- asyncio.run(main())
44
- ```
45
-
46
- `POST /v1/{family}/{capability}` is `client.family.capability()` in snake_case. Each call returns an `ApiResponse` with `data`, `meta`, `status`, `request_id`, `rate_limit`, `replayed`, `idempotency_key` and `headers`.
47
-
48
- Response `data` is typed as a `TypedDict` of its top-level fields, **from each endpoint's published schema**: a hand-written contract for the main endpoints, and for almost all others a schema measured from several real answers (a required field was in every answer). A few have only the schema inferred from one example. An answer to an input none of the samples covered can still differ, so check optional fields. Nested objects are plain dicts.
49
-
50
- ### Errors
51
-
52
- ```python
53
- from astro96_api import ApiConnectionError, ApiError
54
-
55
- try:
56
- astro.vedic_charts.planet_positions(birth)
57
- except ApiError as e:
58
- print(e.status, e.code, e.field, e.retryable, e.request_id)
59
- except ApiConnectionError as e:
60
- print("network", e.timed_out)
61
- ```
62
-
63
- ### Retries and idempotency
64
-
65
- `429 rate_limited` and `503` are retried after `Retry-After` (up to `max_retry_delay`, default 30 s). Other `retryable` errors and network failures are retried only when the call has an idempotency key, which every POST gets automatically (`auto_idempotency=True`) and keeps across retries. `quota_exhausted` is never retried. Pass your own key to retry across processes:
66
-
67
- ```python
68
- from astro96_api import idempotency_key
69
- astro.reports.report_career(birth, idempotency_key=stored_key or idempotency_key())
70
- ```
71
-
72
- Client options: `api_key`, `base_url`, `auth` (`"bearer"` or `"x-api-key"`), `timeout` (60 s), `max_retries` (2), `max_retry_delay`, `auto_idempotency`, `headers`, `http_client`. Per call: `idempotency_key=`, `timeout=`, `max_retries=`, `headers=`.
73
-
74
- ### PDF reports
75
-
76
- ```python
77
- pdf = astro.render_pdf("report-career", birth, branding={"brand_name": "Shree Jyotish Kendra"})
78
- # or step by step: create_pdf_job -> wait_for_job -> download_file
79
- ```
80
-
81
- ### Webhooks
82
-
83
- ```python
84
- from astro96_api import verify_webhook
85
- event = verify_webhook(raw_body, headers, os.environ["ASTRO_WEBHOOK_SECRET"])
86
- ```
87
-
88
- Full guide: https://96astroapi.com/docs/sdks
89
-
90
- > **Not wrapped yet:** AI streaming (`stream: true` / `Accept: text/event-stream`), the `/v1/conversations` routes and `.ics` calendar export. These clients always ask for JSON; call those routes over plain HTTP (see https://96astroapi.com/docs/ai-streaming-and-chat). Everything else, including the image options (`image_format`, `image_theme`, `image_delivery`), works through the typed inputs.
91
-
92
- ## Development
93
-
94
- The typed methods in `src/astro96_api/_generated/` are written by `tools/sdk/generate_python.py` from `packages/registry/openapi/v1.openapi.json`; never edit them by hand.
95
-
96
- ```bash
97
- python ../../tools/sdk/generate_python.py # regenerate after the OpenAPI document changes
98
- python -m pytest # unit tests (httpx.MockTransport) + drift test
99
- ```
100
-
101
- ### Publishing
102
-
103
- 1. Set `name` in `pyproject.toml` if it should differ from `astro96-api`, bump `version` (and `src/astro96_api/_version.py`), and add a `license` and `LICENSE` file.
104
- 2. `python ../../tools/sdk/generate_python.py --check && python -m pytest`
105
- 3. `python -m build` then `python -m twine upload dist/*` with a PyPI token for the project.
106
-
107
- ## Audio reports
108
-
109
- Any report can come back as a spoken MP3 in 26 languages, as a background job. Poll it as you would a PDF job. See [Audio reports](https://96astroapi.com/docs/audio-reports).
110
-
111
- ```python
112
- job = client.create_audio_job(
113
- "report-career",
114
- {"datetime": "1990-10-18T14:30:00", "timezone": "Asia/Kolkata", "latitude": 28.6139, "longitude": 77.209},
115
- language="hi",
116
- minutes=5,
117
- )
118
- ```
119
-
120
- Palm and face readings are ordinary calls that take a photo as base64: see [Palm and face readings](https://96astroapi.com/docs/photo-readings).
1
+ # astro96-api
2
+
3
+ The official Python client for the [96Astro API](https://96astroapi.com): Vedic and Western astrology, panchang, matching, reports and AI readings over one JSON API.
4
+
5
+ - Sync (`Astro96Client`) and asyncio (`AsyncAstro96Client`) clients on `httpx`, Python 3.9+
6
+ - A typed method for every capability, generated from the OpenAPI document (`TypedDict` request bodies)
7
+ - Retries with backoff on `429` / `503` (honouring `Retry-After`), automatic idempotency keys so a retry is never charged twice
8
+ - `ApiError` with `code`, `field`, `retryable` and `request_id`; rate-limit headers on every response
9
+ - PDF job helpers (`create_pdf_job`, `wait_for_job`, `download_file`, `render_pdf`) and webhook signature verification
10
+
11
+ > **Not on PyPI yet.** Publishing is in progress; until then `pip install astro96-api` will not find the package. Contact support for a pre-release wheel, or build it from this repository (see Development).
12
+
13
+ ## Install
14
+
15
+ ```bash
16
+ pip install astro96-api
17
+ ```
18
+
19
+ ## Quickstart
20
+
21
+ ```python
22
+ from astro96_api import Astro96Client
23
+
24
+ astro = Astro96Client() # reads ASTRO_API_KEY (sk_test_... or sk_live_...)
25
+
26
+ res = astro.vedic_charts.planet_positions(
27
+ {"datetime": "1990-10-18T14:30:00", "timezone": "Asia/Kolkata", "latitude": 28.6139, "longitude": 77.209}
28
+ )
29
+ print(res.data["ascendant"]["sign"], res.meta["credits_used"], res.rate_limit)
30
+ ```
31
+
32
+ ```python
33
+ import asyncio
34
+ from astro96_api import AsyncAstro96Client
35
+
36
+ async def main() -> None:
37
+ async with AsyncAstro96Client() as astro:
38
+ res = await astro.panchang.daily_panchang(
39
+ {"date": "2026-10-15", "timezone": "Asia/Kolkata", "latitude": 28.6139, "longitude": 77.209}
40
+ )
41
+ print(res.data)
42
+
43
+ asyncio.run(main())
44
+ ```
45
+
46
+ `POST /v1/{family}/{capability}` is `client.family.capability()` in snake_case. Each call returns an `ApiResponse` with `data`, `meta`, `status`, `request_id`, `rate_limit`, `replayed`, `idempotency_key` and `headers`.
47
+
48
+ Response `data` is typed as a `TypedDict` of its top-level fields, **from each endpoint's published schema**: a hand-written contract for the main endpoints, and for almost all others a schema measured from several real answers (a required field was in every answer). A few have only the schema inferred from one example. An answer to an input none of the samples covered can still differ, so check optional fields. Nested objects are plain dicts.
49
+
50
+ ### Errors
51
+
52
+ ```python
53
+ from astro96_api import ApiConnectionError, ApiError
54
+
55
+ try:
56
+ astro.vedic_charts.planet_positions(birth)
57
+ except ApiError as e:
58
+ print(e.status, e.code, e.field, e.retryable, e.request_id)
59
+ except ApiConnectionError as e:
60
+ print("network", e.timed_out)
61
+ ```
62
+
63
+ ### Retries and idempotency
64
+
65
+ `429 rate_limited` and `503` are retried after `Retry-After` (up to `max_retry_delay`, default 30 s). Other `retryable` errors and network failures are retried only when the call has an idempotency key, which every POST gets automatically (`auto_idempotency=True`) and keeps across retries. `quota_exhausted` is never retried. Pass your own key to retry across processes:
66
+
67
+ ```python
68
+ from astro96_api import idempotency_key
69
+ astro.reports.report_career(birth, idempotency_key=stored_key or idempotency_key())
70
+ ```
71
+
72
+ Client options: `api_key`, `base_url`, `auth` (`"bearer"` or `"x-api-key"`), `timeout` (60 s), `max_retries` (2), `max_retry_delay`, `auto_idempotency`, `headers`, `http_client`. Per call: `idempotency_key=`, `timeout=`, `max_retries=`, `headers=`.
73
+
74
+ ### PDF reports
75
+
76
+ ```python
77
+ pdf = astro.render_pdf("report-career", birth, branding={"brand_name": "Shree Jyotish Kendra"})
78
+ # or step by step: create_pdf_job -> wait_for_job -> download_file
79
+ ```
80
+
81
+ ### Webhooks
82
+
83
+ ```python
84
+ from astro96_api import verify_webhook
85
+ event = verify_webhook(raw_body, headers, os.environ["ASTRO_WEBHOOK_SECRET"])
86
+ ```
87
+
88
+ Full guide: https://96astroapi.com/docs/sdks
89
+
90
+ > **Not wrapped yet:** AI streaming (`stream: true` / `Accept: text/event-stream`), the `/v1/conversations` routes and `.ics` calendar export. These clients always ask for JSON; call those routes over plain HTTP (see https://96astroapi.com/docs/ai-streaming-and-chat). Everything else, including the image options (`image_format`, `image_theme`, `image_delivery`), works through the typed inputs.
91
+
92
+ ## Name your app (optional)
93
+
94
+ Optional: tell the API which app is calling, so you can see where your keys are used (the dashboard's *Where your keys are used*) and spot a leaked key.
95
+
96
+ ```python
97
+ astro = Astro96Client(api_key=key, app_info={"name": "Acme Shop", "version": "2.1.0", "url": "https://shop.acme.com"})
98
+ ```
99
+
100
+ The name is required (printable ASCII, at most 60 characters, no `/` or parentheses); the version (at most 40) and the url (`http(s)`, at most 120) are optional. It is sent as the `X-Astro-App` header, never with your key; the API keeps the name, the version and only the **host** of the url. The User-Agent also carries the platform (`plt/node`, `plt/linux`...). An invalid value is refused when the client is created. (`ValueError`)
101
+
102
+ ## Development
103
+
104
+ The typed methods in `src/astro96_api/_generated/` are written by `tools/sdk/generate_python.py` from `packages/registry/openapi/v1.openapi.json`; never edit them by hand.
105
+
106
+ ```bash
107
+ python ../../tools/sdk/generate_python.py # regenerate after the OpenAPI document changes
108
+ python -m pytest # unit tests (httpx.MockTransport) + drift test
109
+ ```
110
+
111
+ ### Publishing
112
+
113
+ 1. Set `name` in `pyproject.toml` if it should differ from `astro96-api`, bump `version` (and `src/astro96_api/_version.py`), and add a `license` and `LICENSE` file.
114
+ 2. `python ../../tools/sdk/generate_python.py --check && python -m pytest`
115
+ 3. `python -m build` then `python -m twine upload dist/*` with a PyPI token for the project.
116
+
117
+ ## Audio reports
118
+
119
+ Any report can come back as a spoken MP3 in 26 languages, as a background job. Poll it as you would a PDF job. See [Audio reports](https://96astroapi.com/docs/audio-reports).
120
+
121
+ ```python
122
+ job = client.create_audio_job(
123
+ "report-career",
124
+ {"datetime": "1990-10-18T14:30:00", "timezone": "Asia/Kolkata", "latitude": 28.6139, "longitude": 77.209},
125
+ language="hi",
126
+ minutes=5,
127
+ )
128
+ ```
129
+
130
+ Palm and face readings are ordinary calls that take a photo as base64: see [Palm and face readings](https://96astroapi.com/docs/photo-readings).
@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
5
5
  [project]
6
6
  # The distribution name on PyPI; the import name is astro96_api either way.
7
7
  name = "astro96-api"
8
- version = "0.2.0"
8
+ version = "0.3.1"
9
9
  description = "Official Python client for the 96Astro API: Vedic and Western astrology, panchang, matching, reports and AI readings."
10
10
  readme = "README.md"
11
11
  requires-python = ">=3.9"