astro96-api 0.1.0__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 (43) hide show
  1. astro96_api-0.1.0/.gitignore +5 -0
  2. astro96_api-0.1.0/LICENSE +24 -0
  3. astro96_api-0.1.0/PKG-INFO +147 -0
  4. astro96_api-0.1.0/README.md +120 -0
  5. astro96_api-0.1.0/pyproject.toml +51 -0
  6. astro96_api-0.1.0/src/astro96_api/__init__.py +40 -0
  7. astro96_api-0.1.0/src/astro96_api/_client.py +577 -0
  8. astro96_api-0.1.0/src/astro96_api/_errors.py +62 -0
  9. astro96_api-0.1.0/src/astro96_api/_generated/__init__.py +1 -0
  10. astro96_api-0.1.0/src/astro96_api/_generated/client.py +901 -0
  11. astro96_api-0.1.0/src/astro96_api/_generated/families/__init__.py +1 -0
  12. astro96_api-0.1.0/src/astro96_api/_generated/families/ai.py +780 -0
  13. astro96_api-0.1.0/src/astro96_api/_generated/families/bnn.py +1087 -0
  14. astro96_api-0.1.0/src/astro96_api/_generated/families/chinese.py +155 -0
  15. astro96_api-0.1.0/src/astro96_api/_generated/families/dashas.py +1138 -0
  16. astro96_api-0.1.0/src/astro96_api/_generated/families/doshas_yogas.py +4180 -0
  17. astro96_api-0.1.0/src/astro96_api/_generated/families/face_reading.py +1281 -0
  18. astro96_api-0.1.0/src/astro96_api/_generated/families/festivals_muhurta.py +657 -0
  19. astro96_api-0.1.0/src/astro96_api/_generated/families/human_design.py +390 -0
  20. astro96_api-0.1.0/src/astro96_api/_generated/families/jaimini.py +985 -0
  21. astro96_api-0.1.0/src/astro96_api/_generated/families/kp.py +678 -0
  22. astro96_api-0.1.0/src/astro96_api/_generated/families/lal_kitab.py +893 -0
  23. astro96_api-0.1.0/src/astro96_api/_generated/families/location_astrology.py +1098 -0
  24. astro96_api-0.1.0/src/astro96_api/_generated/families/matching.py +1307 -0
  25. astro96_api-0.1.0/src/astro96_api/_generated/families/mundane.py +1037 -0
  26. astro96_api-0.1.0/src/astro96_api/_generated/families/numerology.py +1073 -0
  27. astro96_api-0.1.0/src/astro96_api/_generated/families/palmistry.py +978 -0
  28. astro96_api-0.1.0/src/astro96_api/_generated/families/panchang.py +4652 -0
  29. astro96_api-0.1.0/src/astro96_api/_generated/families/predictions.py +1995 -0
  30. astro96_api-0.1.0/src/astro96_api/_generated/families/remedies.py +497 -0
  31. astro96_api-0.1.0/src/astro96_api/_generated/families/reports.py +2033 -0
  32. astro96_api-0.1.0/src/astro96_api/_generated/families/strengths.py +2273 -0
  33. astro96_api-0.1.0/src/astro96_api/_generated/families/tajika.py +748 -0
  34. astro96_api-0.1.0/src/astro96_api/_generated/families/tarot.py +743 -0
  35. astro96_api-0.1.0/src/astro96_api/_generated/families/utilities.py +523 -0
  36. astro96_api-0.1.0/src/astro96_api/_generated/families/vastu.py +670 -0
  37. astro96_api-0.1.0/src/astro96_api/_generated/families/vedic_charts.py +3951 -0
  38. astro96_api-0.1.0/src/astro96_api/_generated/families/western.py +3245 -0
  39. astro96_api-0.1.0/src/astro96_api/_generated/schemas.py +5688 -0
  40. astro96_api-0.1.0/src/astro96_api/_types.py +44 -0
  41. astro96_api-0.1.0/src/astro96_api/_version.py +1 -0
  42. astro96_api-0.1.0/src/astro96_api/_webhooks.py +58 -0
  43. astro96_api-0.1.0/src/astro96_api/py.typed +0 -0
@@ -0,0 +1,5 @@
1
+ dist/
2
+ build/
3
+ *.egg-info/
4
+ __pycache__/
5
+ .pytest_cache/
@@ -0,0 +1,24 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kuber Astro (96Astro)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
23
+ This licence covers the client library only. Use of the 96Astro API itself is
24
+ governed by the terms at https://96astroapi.com/legal/terms.
@@ -0,0 +1,147 @@
1
+ Metadata-Version: 2.5
2
+ Name: astro96-api
3
+ Version: 0.1.0
4
+ Summary: Official Python client for the 96Astro API: Vedic and Western astrology, panchang, matching, reports and AI readings.
5
+ Project-URL: Documentation, https://96astroapi.com/docs/sdks
6
+ Project-URL: API reference, https://96astroapi.com/docs/reference
7
+ Author-email: "Kuber Astro (96Astro)" <support@96astroapi.com>
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Keywords: 96astro,api,astrology,horoscope,jyotish,kundli,panchang,sdk,vedic
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3 :: Only
15
+ Classifier: Programming Language :: Python :: 3.9
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Typing :: Typed
21
+ Requires-Python: >=3.9
22
+ Requires-Dist: httpx<1,>=0.23
23
+ Requires-Dist: typing-extensions>=4.7
24
+ Provides-Extra: test
25
+ Requires-Dist: pytest>=7; extra == 'test'
26
+ Description-Content-Type: text/markdown
27
+
28
+ # astro96-api
29
+
30
+ 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.
31
+
32
+ - Sync (`Astro96Client`) and asyncio (`AsyncAstro96Client`) clients on `httpx`, Python 3.9+
33
+ - A typed method for every capability, generated from the OpenAPI document (`TypedDict` request bodies)
34
+ - Retries with backoff on `429` / `503` (honouring `Retry-After`), automatic idempotency keys so a retry is never charged twice
35
+ - `ApiError` with `code`, `field`, `retryable` and `request_id`; rate-limit headers on every response
36
+ - PDF job helpers (`create_pdf_job`, `wait_for_job`, `download_file`, `render_pdf`) and webhook signature verification
37
+
38
+ > **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).
39
+
40
+ ## Install
41
+
42
+ ```bash
43
+ pip install astro96-api
44
+ ```
45
+
46
+ ## Quickstart
47
+
48
+ ```python
49
+ from astro96_api import Astro96Client
50
+
51
+ astro = Astro96Client() # reads ASTRO_API_KEY (sk_test_... or sk_live_...)
52
+
53
+ res = astro.vedic_charts.planet_positions(
54
+ {"datetime": "1990-10-18T14:30:00", "timezone": "Asia/Kolkata", "latitude": 28.6139, "longitude": 77.209}
55
+ )
56
+ print(res.data["ascendant"]["sign"], res.meta["credits_used"], res.rate_limit)
57
+ ```
58
+
59
+ ```python
60
+ import asyncio
61
+ from astro96_api import AsyncAstro96Client
62
+
63
+ async def main() -> None:
64
+ async with AsyncAstro96Client() as astro:
65
+ res = await astro.panchang.daily_panchang(
66
+ {"date": "2026-10-15", "timezone": "Asia/Kolkata", "latitude": 28.6139, "longitude": 77.209}
67
+ )
68
+ print(res.data)
69
+
70
+ asyncio.run(main())
71
+ ```
72
+
73
+ `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`.
74
+
75
+ 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.
76
+
77
+ ### Errors
78
+
79
+ ```python
80
+ from astro96_api import ApiConnectionError, ApiError
81
+
82
+ try:
83
+ astro.vedic_charts.planet_positions(birth)
84
+ except ApiError as e:
85
+ print(e.status, e.code, e.field, e.retryable, e.request_id)
86
+ except ApiConnectionError as e:
87
+ print("network", e.timed_out)
88
+ ```
89
+
90
+ ### Retries and idempotency
91
+
92
+ `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:
93
+
94
+ ```python
95
+ from astro96_api import idempotency_key
96
+ astro.reports.report_career(birth, idempotency_key=stored_key or idempotency_key())
97
+ ```
98
+
99
+ 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=`.
100
+
101
+ ### PDF reports
102
+
103
+ ```python
104
+ pdf = astro.render_pdf("report-career", birth, branding={"brand_name": "Shree Jyotish Kendra"})
105
+ # or step by step: create_pdf_job -> wait_for_job -> download_file
106
+ ```
107
+
108
+ ### Webhooks
109
+
110
+ ```python
111
+ from astro96_api import verify_webhook
112
+ event = verify_webhook(raw_body, headers, os.environ["ASTRO_WEBHOOK_SECRET"])
113
+ ```
114
+
115
+ Full guide: https://96astroapi.com/docs/sdks
116
+
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
+
119
+ ## Development
120
+
121
+ 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.
122
+
123
+ ```bash
124
+ python ../../tools/sdk/generate_python.py # regenerate after the OpenAPI document changes
125
+ python -m pytest # unit tests (httpx.MockTransport) + drift test
126
+ ```
127
+
128
+ ### Publishing
129
+
130
+ 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.
131
+ 2. `python ../../tools/sdk/generate_python.py --check && python -m pytest`
132
+ 3. `python -m build` then `python -m twine upload dist/*` with a PyPI token for the project.
133
+
134
+ ## Audio reports
135
+
136
+ 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).
137
+
138
+ ```python
139
+ job = client.create_audio_job(
140
+ "report-career",
141
+ {"datetime": "1990-10-18T14:30:00", "timezone": "Asia/Kolkata", "latitude": 28.6139, "longitude": 77.209},
142
+ language="hi",
143
+ minutes=5,
144
+ )
145
+ ```
146
+
147
+ Palm and face readings are ordinary calls that take a photo as base64: see [Palm and face readings](https://96astroapi.com/docs/photo-readings).
@@ -0,0 +1,120 @@
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).
@@ -0,0 +1,51 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.27"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ # The distribution name on PyPI; the import name is astro96_api either way.
7
+ name = "astro96-api"
8
+ version = "0.1.0"
9
+ description = "Official Python client for the 96Astro API: Vedic and Western astrology, panchang, matching, reports and AI readings."
10
+ readme = "README.md"
11
+ requires-python = ">=3.9"
12
+ license = "MIT"
13
+ license-files = ["LICENSE"]
14
+ authors = [{ name = "Kuber Astro (96Astro)", email = "support@96astroapi.com" }]
15
+ keywords = ["astrology", "vedic", "jyotish", "panchang", "kundli", "horoscope", "96astro", "api", "sdk"]
16
+ classifiers = [
17
+ "Development Status :: 4 - Beta",
18
+ "Intended Audience :: Developers",
19
+ "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3 :: Only",
21
+ "Programming Language :: Python :: 3.9",
22
+ "Programming Language :: Python :: 3.10",
23
+ "Programming Language :: Python :: 3.11",
24
+ "Programming Language :: Python :: 3.12",
25
+ "Programming Language :: Python :: 3.13",
26
+ "Typing :: Typed",
27
+ ]
28
+ dependencies = ["httpx>=0.23,<1", "typing_extensions>=4.7"]
29
+
30
+ [project.optional-dependencies]
31
+ test = ["pytest>=7"]
32
+
33
+ [project.urls]
34
+ Documentation = "https://96astroapi.com/docs/sdks"
35
+ "API reference" = "https://96astroapi.com/docs/reference"
36
+
37
+ [tool.hatch.build.targets.wheel]
38
+ packages = ["src/astro96_api"]
39
+
40
+ [tool.hatch.build.targets.sdist]
41
+ include = ["src/astro96_api", "README.md", "LICENSE", "pyproject.toml"]
42
+
43
+ [tool.pytest.ini_options]
44
+ testpaths = ["tests"]
45
+ pythonpath = ["src"]
46
+
47
+ [tool.ruff]
48
+ line-length = 140
49
+
50
+ [tool.ruff.format]
51
+ exclude = ["**/_generated/**"]
@@ -0,0 +1,40 @@
1
+ """Official Python client for the 96Astro API.
2
+
3
+ >>> from astro96_api import Astro96Client
4
+ >>> astro = Astro96Client() # reads ASTRO_API_KEY
5
+ >>> res = astro.vedic_charts.planet_positions(
6
+ ... {"datetime": "1990-10-18T14:30:00", "timezone": "Asia/Kolkata", "latitude": 28.6139, "longitude": 77.209}
7
+ ... )
8
+ """
9
+
10
+ from ._client import AsyncAstro96Client, Astro96Client, idempotency_key, parse_rate_limit, parse_retry_after, should_retry
11
+ from ._errors import ApiConnectionError, ApiError, Astro96Error, JobError
12
+ from ._generated import schemas
13
+ from ._generated.client import API_VERSION, CAPABILITY_FAMILIES, DEFAULT_BASE_URL, PdfCapability
14
+ from ._types import ApiResponse, RateLimitInfo, RequestOptions
15
+ from ._version import __version__
16
+ from ._webhooks import WebhookSignatureError, verify_webhook
17
+
18
+ __all__ = [
19
+ "API_VERSION",
20
+ "CAPABILITY_FAMILIES",
21
+ "DEFAULT_BASE_URL",
22
+ "ApiConnectionError",
23
+ "ApiError",
24
+ "ApiResponse",
25
+ "Astro96Client",
26
+ "Astro96Error",
27
+ "AsyncAstro96Client",
28
+ "JobError",
29
+ "PdfCapability",
30
+ "RateLimitInfo",
31
+ "RequestOptions",
32
+ "WebhookSignatureError",
33
+ "__version__",
34
+ "idempotency_key",
35
+ "parse_rate_limit",
36
+ "parse_retry_after",
37
+ "schemas",
38
+ "should_retry",
39
+ "verify_webhook",
40
+ ]