astroapi-io-client 0.1.0__tar.gz

astroapi_io_client-0.1.0/LICENSE.txt

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 AstroAPI
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

astroapi_io_client-0.1.0/PKG-INFO

@@ -0,0 +1,274 @@
+Metadata-Version: 2.4
+Name: astroapi-io-client
+Version: 0.1.0
+Summary: Synchronous Python client for the AstroAPI.io calculation gateway
+License-Expression: ISC
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Dynamic: license-file
+
+# AstroAPI.io Python client
+
+The source client covers all forty source-candidate calculation routes: thirty-nine standard operations plus the separate Pro Nakshatra Timeline. Production R192 exposes thirty-six standard routes plus the timeline, for thirty-seven total. Minor-body calculations are not part of the contract. This package is not registry-published.
+
+An unpublished, synchronous client for Python 3.10+, with no runtime dependencies.
+The package import is `astroapi_client`; the distribution name is
+`astroapi-io-client`. This source release does not imply publication to PyPI or
+new deployed API capabilities.
+
+Install from a local checkout using `python -m pip install ./clients/python`.
+Building needs setuptools and wheel; the installed client uses only the standard
+library. Keep API credentials in trusted server or command-line environments.
+
+```python
+from astroapi_client import AstroAPIClient, HTTPError, RequestTimeoutError
+
+# Reads ASTROAPI_KEY; alternatively pass api_key=your_key explicitly.
+client = AstroAPIClient()
+birth = {
+    "date": "1990-01-01",
+    "time": "12:00",
+    "timezone": "America/New_York",
+    "lat": 40.7128,
+    "lon": -74.006,
+}
+
+try:
+    result = client.birth_chart(birth)
+    sun = result["chart"]["planets"]["Sun"]
+except HTTPError as error:
+    print(error.status, error.retry_after)  # Sanitized; does not trigger a retry.
+except RequestTimeoutError:
+    print("Deadline exceeded; this request may already have consumed quota.")
+```
+
+An explicit key takes precedence over `ASTROAPI_KEY`. Keys must contain exactly
+64 hexadecimal characters. The SDK never reads another application's settings,
+environment files, browser sessions, or stored keys. Do not place keys in source
+control, browser code, URLs, or logs.
+
+## Methods and current response shapes
+
+Each method takes one dictionary using the gateway's field names. It returns
+the **complete parsed JSON object without changing its envelope**. Exported
+`TypedDict` input types and `py.typed` support editors. Methods without a detailed response type return
+`dict[str, Any]` (`JSONResponse`). `lunar_nodes`, `returns`, `solar_arcs` and
+`vimshottari` provide detailed response type hints; Vimshottari is a union of
+`VimshottariResponseDepth2`, `VimshottariResponseDepth3`, and
+`VimshottariResponseDepth4`. The return's existing
+nested chart remains `JSONResponse`.
+Type hints describe the server contract and do not perform response validation.
+
+| Method | OpenAPI operation ID | Input | Important response path |
+|---|---|---|---|
+| `birth_chart` | `calculateBirthChart` | Birth fields; optional zodiac/ayanamsa | `result["chart"]` |
+| `place_search` **beta** | `searchPlaces` | Query; optional uppercase country codes and limit | Ordered versioned candidates in `result["results"]` |
+| `timezone_resolve` **beta** | `resolvePlaceTimezone` | Versioned place ID plus local date/time | Explicit civil-time status/candidates and unique `resolved_input` |
+| `natal_context` **beta** | `calculateNatalContext` | Birth; optional zodiac/ayanamsa/houses/formats | Stable facts, calculation hash, and selected text artifacts |
+| `aspects` | `calculateAspects` | `{"birth": birth}`; optional zodiac/ayanamsa | `result["aspects"]["aspects"]` is the array |
+| `houses` | `calculateHouses` | `{"birth": birth, "system": "whole_sign"}`; optional zodiac/ayanamsa | Full chart at top level; `result["houses"]["systems"]` |
+| `synastry` | `calculateSynastry` | `{"personA": birth, "personB": other}`; optional zodiac/ayanamsa | `result["charts"]`, `result["aspects"]` |
+| `transits` | `calculateTransits` | Birth plus required `transitDate`; optional `transitTime`, timezone, zodiac/ayanamsa | `result["transits"]["natal_chart"]`, `transit_chart`, `aspects` |
+| `horoscope` **beta** | `calculateHoroscope` | Birth plus optional transit fields, timezone, zodiac/ayanamsa | `result["interpretation"]` |
+| `nakshatra_timeline` | `calculateNakshatraTimeline` | Planet, `start_utc`, `end_utc`, ayanamsa | `result["segments"]` |
+| `natal_svg` **beta** | `calculateNatalSvg` | Birth; optional zodiac, ayanamsa, houses/theme/show_aspects, named aspect profile or custom aspects, `include_png` | `result["svg"]`, optional `result["png"]` |
+| `vargas` **beta** | `calculateVargas` | Birth; optional ayanamsa and one of twenty-four divisions through D150 | `result["bodies"]["moon"]["sign"]`, `result["ascendant"]` |
+| `vimshottari` **beta** | `calculateVimshottari` | Birth; optional ayanamsa and depth 2/3/4 | `result["birth_balance"]`, `result["periods"]` |
+| `ashtakoota` **beta** | `calculateAshtakoota` | Required groom/bride births; optional ayanamsa | `result["kootas"]`, `result["total"]`; no verdict/advice |
+| `ashtakavarga` **beta** | `calculateAshtakavarga` | Required birth; optional ayanamsa and `include_reductions` | BAV, Prastara, SAV, and opt-in reductions/pindas; no interpretation |
+| `numerology` **beta** | `calculateNumerology` | Gregorian `birth_date`; optional ASCII `name`, boolean `master_numbers`/`y_vowel`, integer `year` | `numbers` contains symbolic reduction traces; no interpretations or predictions |
+| `composite` **beta** | `calculateComposite` | personA/personB; optional zodiac/ayanamsa/house_system | `result["planets"]`, synthetic `result["houses"]` |
+| `panchang` **beta** | `calculatePanchang` | at civil snapshot; optional ayanamsa | `result["vara"]`, `result["solar_events"]` |
+| `secondary_progressions` **beta** | `calculateSecondaryProgressions` | birth and target civil time; optional zodiac/ayanamsa/house_system | `result["progressed_planets"]`, separate natal_context |
+| `varga_svg` **beta** | `calculateVargaSvg` | birth; optional ayanamsa/division/layout/theme/`include_png` | `result["svg"]`, `result["chart"]`, optional `result["png"]` |
+| `lunar_nodes` **beta** | `calculateLunarNodes` | at civil instant without coordinates; optional zodiac/ayanamsa | `result["mean"]["north"]`, `result["true"]["north"]` |
+| `returns` **beta** | `calculateReturns` | birth, body sun/moon, after civil time; optional zodiac/ayanamsa/house_system/location | `result["return_utc"]`, `result["chart"]`, `result["search"]` |
+| `solar_arcs` **beta** | `calculateSolarArcs` | birth and target civil time; optional zodiac/ayanamsa/house_system | `result["arc"]`, `result["directed_planets"]`, `result["directed_angles"]`, `result["directed_houses"]` |
+| `moon_phases` **beta** | `calculateMoonPhases` | instant `at` or calendar civil `start`/`end`; optional display timezone and `include_ical` | `result["result"]["phase_sector"]` or `result["result"]["events"]`; optional `result["result"]["ical"]` |
+| `planetary_events` **beta** | `calculatePlanetaryEvents` | whole-second UTC interval, event types/bodies; optional aspects/zodiac/ayanamsa | `result["result"]["events"]` |
+| `house_ingresses` **beta** | `calculateHouseIngresses` | reference birth, whole-second UTC interval, bodies; optional Equal/Whole Sign and zodiac/ayanamsa | `result["result"]["events"]`, fixed cusps |
+| `aspect_windows` **beta** | `calculateAspectWindows` | whole-second UTC interval, bodies; optional aspects/orb/zodiac/ayanamsa/iCalendar | `result["result"]["windows"]` |
+| `event_calendar` **beta** | `calculateEventCalendar` | whole-second UTC interval and selected event families | `result["result"]["events"]`; optional iCalendar, strict opt-in fixed-column CSV, and opt-in deduplicated pass groups |
+| `synastry_svg` **beta** | `calculateSynastrySvg` | two births; optional zodiac/houses/theme/aspects/`include_png` | `result["svg"]`, optional `result["png"]` |
+| `transit_svg` **beta** | `calculateTransitSvg` | birth and transit date; optional display controls/`include_png` | `result["svg"]`, optional `result["png"]` |
+| `natal_report` **beta** | `calculateNatalReport` | birth; optional zodiac/houses/theme/SVG/download | `result["html"]`, source-linked `result["facts"]`, optional `result["download"]` |
+| `birth_time_sensitivity` **beta** | `calculateBirthTimeSensitivity` | civil interval up to six hours, or explicit unknown/approximate time, plus coordinates | `result["result"]["samples"]`, optional workflow classification |
+| `fixed_stars` **beta** | `calculateFixedStars` | civil instant and 1–6 documented stars | `result["objects"]`; no minor bodies |
+| `relocation_chart` **beta** | `calculateRelocationChart` | birth and destination coordinates; optional zodiac/ayanamsa/houses | `result["natal_reference"]`, `result["relocated_chart"]` |
+| `astrocartography` **beta** | `calculateAstrocartography` | civil instant, 1–10 unique Sun-through-Pluto bodies, optional `include_geojson`, `include_geojson_seq`, `include_ndjson`, `include_topojson`, `include_kml`, `include_gpx`, `include_csv`, `include_wkt`, `include_wkb`, `include_gml`, `basemap`, `include_svg`, `include_png`, and `theme` | bounded geometry plus optional deterministic RFC 7946 GeoJSON, RFC 8142 GeoJSON Text Sequences, newline-delimited GeoJSON Features, unquantized TopoJSON, OGC KML 2.2, GPX 1.1, RFC 4180 CSV, WKT, WKB, GML 3.2 artifacts, and 1200×800 SVG/PNG coordinate-grid or bundled Natural Earth coastline map |
+| `eclipse_geometry` **beta** | `calculateEclipseGeometry` | whole-second UTC interval up to 366 days, selected solar/lunar types, optional WGS84 observer | global events and optional sea-level/no-refraction snapshot in each event |
+| `electional_search` **beta** | `calculateElectionalSearch` | location, one or more AND-only filters, and UTC interval up to seven days | hourly matches and sampled windows |
+| `natal_analysis` **beta** | `calculateNatalAnalysis` | birth, aspect controls, and strict sidereal graha-drishti or partial-Shadbala opt-ins | aspects/patterns plus optional `graha_drishti` or `shadbala_foundation` |
+| `planetary_hours` **beta** | `calculatePlanetaryHours` | civil date, IANA timezone, and coordinates | twenty-four unequal day/night temporal hours and rulers |
+| `davison` **beta** | `calculateDavison` | personA/personB; optional zodiac/ayanamsa/house_system | `result["chart"]`, `result["midpoint"]`, `result["metadata"]` |
+
+The never-live extended-sky methods were retired rather than depend on licensed
+minor-body source data. They are not SDK methods or API contracts.
+
+Graha drishti is a separate opt-in on `natal_analysis`. Exact `True` requires
+explicit `zodiac: "sidereal"`; omission/false preserves the existing response.
+Ruleset `parashari_whole_sign_full_aspects_v1` includes Sun, Moon, Mars,
+Mercury, Jupiter, Venus, and Saturn only. It returns full whole-sign targets and
+occupying classical grahas, with no node aspects, partial strengths, or
+interpretation. The request remains one standard quota unit.
+
+Synastry cross-aspects retain `transit` for person B and `natal` for person A.
+The horoscope route is a beta, deterministic structured interpretation; it is
+not a stable prose-report or LLM contract. Birth-chart/aspects compute both
+legacy house systems; the houses method filters to the requested system.
+Its `placidus`, `porphyry`, `meridian`, `campanus`, `regiomontanus`,
+`alcabitius`, `koch`, `morinus`, `topocentric`, `sripati`, `vehlow`, `horizon`, `krusinski`, `sunshine`, `sunshine_alt`, `savard`, `pullen_sd`, `pullen_sr`, `carter`, `apc`, `equal_mc`, and `natural` options are beta, with explicit rejection and no fallback. Gauquelin is Houses-only because its response contains 36 sectors; natal
+SVG accepts the preceding twelve-house systems, while other chart/report routes do not accept
+Porphyry, Meridian, Campanus, Regiomontanus, Alcabitius, Koch, Morinus, Topocentric, Sripati, Vehlow, Horizon/Azimuth, Krusinski-Pisa-Goelzer, Sunshine, Sunshine alternative, Savard-A, Pullen SD, Pullen SR, Carter, APC, Equal MC, or Natural. Meridian cusp 1 is
+the Equatorial Ascendant; Campanus, Regiomontanus, Alcabitius, and Koch cusp 1
+are the physical Ascendant. Morinus cusps are latitude-independent; its cusps 1 and 10 are not the physical Ascendant and Midheaven. Topocentric uses Polich/Page house geometry with the physical Ascendant and Midheaven as cusps 1 and 10; it does not alter planet positions. Sripati shifts each cusp to the midpoint of the preceding Porphyry sector; its cusps 1 and 10 are not the physical angles. Vehlow uses twelve equal 30-degree ecliptic houses with the physical Ascendant at the center of house 1; its cusps 1 and 10 are not the physical angles. Horizon/Azimuth projects twelve equal local-horizon divisions through vertical circles to the ecliptic; cusp 1 is not the physical Ascendant and cusp 10 is the Midheaven. Krusinski-Pisa-Goelzer projects twelve equal Ascendant-zenith great-circle divisions through celestial meridian circles; cusps 1 and 10 are the physical Ascendant and Midheaven. Sunshine uses the Treindl construction from trisected solar diurnal and nocturnal semi-arcs; cusps 1 and 10 are the physical Ascendant and Midheaven. Sunshine alternative uses the separate Makransky prime-vertical projection for the same solar house points. Savard-A projects one-third and two-thirds geographic-latitude circles through the prime vertical; cusps 1 and 10 are the physical Ascendant and Midheaven and opposite cusps are antipodal. Pullen SD redistributes each ecliptic quadrant's deviation from 90 degrees with quarter/half/quarter weighting; cusp 10 is the physical Midheaven and cusp 1 uses the orientation-adjusted Ascendant. Pullen SR proportions complementary quadrant house widths as rx, x, rx and r³x, r⁴x, r³x; cusp 10 is the physical Midheaven and cusp 1 uses the orientation-adjusted Ascendant. Carter divides right ascension into twelve equal arcs from the orientation-adjusted Ascendant and projects them to the ecliptic; cusp 10 is not generally the physical Midheaven. APC divides the Ascendant parallel into six sectors below and six above the horizon; cusps 1 and 10 are the orientation-adjusted angles and intermediate opposite cusps are not generally antipodal. Equal MC fixes the physical Midheaven at cusp 10 and places twelve equal 30-degree ecliptic houses; cusp 1 is generally not the physical Ascendant. Natural fixes cusp 1 at zero degrees Aries in the selected zodiac and places all cusps on sign boundaries; physical angles remain separate. Gauquelin is Houses-only and returns 36 clockwise semiarc sector boundaries under the existing houses map; sector 1 is Ascendant and sector 10 is Midheaven. Regiomontanus, Alcabitius, Koch, Morinus, Topocentric, Sripati, Vehlow, Horizon/Azimuth, Krusinski-Pisa-Goelzer, Sunshine, Sunshine alternative, Savard-A, Pullen SD, Pullen SR, Carter, APC, Equal MC, Natural, and Gauquelin are not admitted by saved
+profiles. Equal/Whole Sign remain the existing chart defaults.
+
+```python
+timeline = client.nakshatra_timeline({
+    "planet": "moon",
+    "start_utc": "2026-01-01T00:00:00Z",
+    "end_utc": "2026-01-03T00:00:00Z",
+    "ayanamsa": "lahiri",
+})
+```
+
+The timeline is Pro-only, always sidereal, supports the nine documented bodies,
+and allows a positive range up to 180 days. It uses a separate quota. It does not
+accept a sampling-step override. Dates across routes remain limited to
+1900–2050. Legacy chart nodes and timeline Rahu/Ketu remain mean-node calculations;
+the separate `lunar_nodes` beta supplies a distinct geometric osculating model.
+Installing the SDK does not change any existing calculation convention or accuracy.
+
+The SVG route accepts birth data, not an uploaded chart, SVG, URL, font or image.
+Defaults are Equal houses, light theme, major aspects shown, tropical zodiac
+and Lahiri when sidereal. The result contains an SVG string inside JSON; it is
+not a browser credential or hosted-widget API.
+
+Natal, synastry, transit and varga SVG plus natal report accept exact `light`,
+`dark`, or `monochrome`. Defaults are unchanged. Monochrome is a fixed
+grayscale palette, not an accessibility certification; optional PNG pixels are
+grayscale while retaining RGB encoding.
+
+Natal report HTML accepts optional `report_branding` with a required 1–64 character bounded ASCII `display_name` and optional exact `amber`, `blue`, or `green` accent. It is escaped, text-only, visibly attributed to AstroAPI, and invalid with non-HTML formats; omission preserves exact predecessor bytes. No logo, URL, markup, template, remote resource, localization, or fact mutation is accepted.
+
+Natal report downloads accept exact `include_download: True`. Omitted
+`download_format` retains HTML; exact `pdf`, `docx`, `xlsx`, `ods`, `epub`, `odt`, `rtf`, `json`, `csv`, `xml`, `ndjson`, `tsv`, `markdown`, `text`, or
+`zip` selects deterministic PDF, editable macro-free OOXML, editable
+macro-free and formula-free OOXML workbook, macro-free ODF 1.3, editable dependency-free RTF, machine-readable JSON, tabular CSV, fixed-order XML, canonical one-record-per-fact NDJSON, escaped fixed-column TSV, UTF-8 calculation facts/plain text, or the unchanged fixed
+HTML/PDF/calculation-JSON bundle.
+
+Vargas and Vimshottari always use sidereal coordinates with Lahiri default.
+Vargas supports D1/D2/D3/D4/D5/D6/D7/D8/D9/D10/D11/D12/D16/D20/D24/D27/D30/D40/D45/D60/D81/D108/D144/D150 (default D9) for nine traditional bodies plus the
+Ascendant, not outer planets. Vimshottari returns nine major periods, each with
+nine subperiods, using a fixed 365.25-day Julian year. Its first period begins
+at the theoretical natal-major start, which can precede birth. Arithmetic
+schedule dates may extend outside the ephemeris input-date window; they are
+not predictions or additional ephemeris calculations. Optional `depth: 3` adds
+one fixed third level; omission or `depth: 2` preserves the original response.
+No arbitrary depth,
+year model, range or specialist signoff is claimed. Each of these beta routes
+costs one standard-call unit under unchanged plan quotas/prices and uses the
+normal request deadline.
+
+## Validation, deadlines and errors
+
+The client checks required fields, supported enums, numeric coordinate bounds,
+date/time formats, timeline ranges and the 128 KiB request limit before sending.
+It accepts JSON numbers for coordinates and documented lowercase enum values;
+unknown fields and explicit null optionals are rejected. Omit unused optional
+fields. Timezone identifiers, DST ambiguity/nonexistence and undefined
+Ascendant geometry remain server validation. Supplying a known UTC instant
+avoids ambiguous local clock changes. No defaults are inserted into payloads.
+
+Normal requests have a 20-second caller deadline; planetary events, eclipse geometry, electional search and aspect windows have 35 seconds; timelines have 70 seconds.
+Configure `timeout=`, `planetary_events_timeout=`, and `timeline_timeout=` with finite positive seconds up to
+300. The deadline covers network establishment, TLS, headers, response body and
+JSON parsing, but starts after local input validation/serialization.
+
+The synchronous call uses a daemon transport worker so a stalled operating-system
+DNS lookup or slowly arriving headers/body cannot keep the caller waiting past
+its deadline. Cancellation shuts down the known socket. A DNS call itself
+cannot be forcibly stopped; its worker retains a slot until it exits and checks
+cancellation before sending credentials. There are at most eight outstanding
+transport workers **across all client instances in a process**. Exhaustion raises
+`ClientBusyError` without starting another request. No context manager or explicit
+close is needed; every completed exchange closes its connection. Successful
+calls do not reuse connections.
+
+`max_response_bytes=` defaults to 4 MiB and may be set from 1 byte through 64 MiB.
+Oversized, truncated, compressed, non-object, duplicate-key or malformed JSON
+responses are rejected. Bodies are read incrementally; compressed responses are
+not decompressed. The standard library also limits HTTP header count and line
+length. Errors omit request payloads, response bodies, credentials, raw headers,
+and underlying transport exceptions. `HTTPError` exposes only numeric `status`
+and sanitized `retry_after` (integer seconds or a normalized HTTP date).
+
+There are **no automatic retries**, including for 429, 503 or timeouts. Once the
+gateway reserves quota, even an invalid payload, dependency failure or timeout
+consumes a unit. A client disconnect does not cancel admitted server work.
+
+## Transport origin
+
+The default is `https://api.astroapi.io`; calls use `POST /api/astro/...` with
+`Authorization: Bearer`. A custom `base_url` must be a trusted HTTPS origin
+without a path, credentials, query or fragment. Selecting another HTTPS origin
+authorizes sending your key to that origin. TLS certificates and hostnames are
+verified. Proxy environment variables, cookies and redirects are not used.
+Every redirect is returned as `HTTPError`; keys are never forwarded to its
+destination.
+
+For local Node gateway testing only:
+
+```python
+client = AstroAPIClient(
+    api_key=your_synthetic_key,
+    base_url="http://127.0.0.1:5100",
+    allow_http_localhost=True,
+)
+```
+
+HTTP requires explicit opt-in and both a loopback/localhost URL and a loopback
+connected peer. Never point the client directly at the internal Python engine.
+
+## Offline checks
+
+From this directory, after local installation:
+
+```sh
+python -m unittest discover -s tests -v
+```
+
+Tests use generated synthetic keys and local HTTP/HTTPS servers. Real TLS tests
+generate temporary certificates with local OpenSSL and explicitly skip if it is
+unavailable; no certificate keys are committed. They do not call the
+production API or Stripe. The example under `examples/` makes a billable API
+request when explicitly run with a real key. Its executable-example test replaces
+the transport with a local mock and uses no real account key.
+
+## Additional bounded beta calculations
+
+- Composite: strict personA/personB birth objects; shortest-arc planetary and angle midpoints. Equal/Whole Sign houses are synthetic from midpoint Ascendant, not physical/Davison houses. Near-antipodal sources reject; no Placidus, nodes or speeds.
+- Panchang: strict at civil snapshot and optional ayanamsa, always sidereal. Latitude is inclusive [-88,88]. Classifications are at the requested instant; solar events use the USNO -50 arcminute horizon at elevation 0, not Hindu-geocentric sunrise. Civil weekday and sunrise-based vara differ. Unavailable bounded sunrise gives explicit null vara. Historical local offsets can include seconds; paired UTC fields are interoperable.
+- Secondary progressions: strict birth plus target date/time/timezone, target>=birth. Planets only, fixed 365.2421904-day year in uniform TT; natal_context angles/houses are not progressed. Derived progressed_utc may contain actual leap second 60; preserve the string rather than passing it blindly to JavaScript Date/Python datetime. No progressed angles/houses/aspects/nodes/speeds or prediction claim.
+- Varga SVG: birth plus optional ayanamsa, any supported D1/D2/D3/D4/D5/D6/D7/D8/D9/D10/D11/D12/D16/D20/D24/D27/D30/D40/D45/D60/D81/D108/D144/D150 division, layout north_indian/south_indian and theme light/dark/monochrome. Defaults D1/north_indian/dark; /vargas instead defaults D9. Original North fixed-house/South fixed-sign SVG, houses counted from divisional Ascendant; not bhava-chalit. Response.chart is the unchanged Vargas result; SVG is bounded to 128 KiB inside JSON.
+  D150 additionally accepts exact `d150_method` values `"deva_keralam_chandra_kala_nadi_non_uniform"`, `"deva_keralam_chandra_kala_nadi_uniform_direct"`, `"parivritti_cyclic"`, `"movable_aries_forward_fixed_taurus_reverse_dual_gemini_forward"`, `"movable_aries_forward_fixed_scorpio_reverse_dual_sagittarius_forward"`, `"movable_aries_forward_fixed_leo_reverse_dual_sagittarius_forward"`, and `"movable_source_sign_forward_fixed_source_sign_reverse_dual_source_sign_forward"`; omission retains the uniform-direct D150 response, and the field is rejected for every other division.
+
+- Lunar nodes: `lunar_nodes` takes an `at` civil instant with no coordinates and optional zodiac/ayanamsa. The response provides north/south pairs for Meeus mean nodes and geometric DE421 osculating nodes, each with its explicit source frame. `LunarNodesInput` and `LunarNodesResponse` are exported types. Chart and timeline node fields keep the existing mean-node contract.
+- Returns: `returns` takes birth, exact body `sun` or `moon`, and an `after` civil instant. Optional zodiac/ayanamsa, Equal/Whole Sign houses and `location:{lat,lon}` are supported; location defaults to birth coordinates. `ReturnsInput` and `ReturnsResponse` type the new request/envelope. Read `return_utc`, `chart` and `search`. The first return lies beyond a one-millisecond start exclusion and the full fixed 370-day Sun/32-day Moon TT window must fit the supported UTC range. `after` may precede birth. Preserve leap-second UTC strings; numerical tolerance does not establish physical accuracy.
+
+- Solar arcs: `solar_arcs` takes strict birth plus target civil time and optional zodiac/ayanamsa/Equal or Whole Sign houses. Omitted `method` and exact `true_solar_arc` preserve the direct true tropical Sun arc. Exact `method: "mean_naibod"` applies the fixed 0.98564733° mean longitude key per elapsed 365.2421904-day TT model year. Both methods direct natal planets and Ascendant/MC uniformly and retain synthetic houses, one-unit accounting, the 1900–2050 dates, and natal-date ayanamsa policy. No relocation, converse/right-ascension arc, MC-derived angle recalculation, arbitrary key, aspects, nodes or speeds.
+- Vimshottari depth: `depth` accepts integer 2, 3, or 4. Omission/2 and the complete depth-3 response remain unchanged. Depth 4 adds 6,561 Sookshma leaves, `birth_balance.sookshma_dasha_lord`, and exact count metadata. Fourth-level leaves omit the redundant display-only `years` field so the complete response stays below 1 MiB. Python rejects floats, strings and booleans. Depth 4 is synchronous-only under the durable-job 256 KiB cap. The arithmetic is bounded and deterministic, not arbitrary recursion or prediction; an admitted synchronous call costs one standard unit.
+- Eclipse geometry: `eclipse_geometry` searches at most 366 UTC days. Optional `observer` coordinates add a fixed sea-level, no-refraction topocentric snapshot at each rounded global maximum. It does not calculate the location's maximum, contacts, visibility at other instants, paths, maps, terrain/weather, safety guidance or interpretation.
+- Electional search: `electional_search` applies one or more documented AND-only filters at fixed hourly samples for at most seven days/168 samples. Results are sampled candidates without continuous guarantees, ranking, recommendations, void-of-course analysis or interpretation.
+- Natal analysis: `natal_analysis` returns configured aspects, optional midpoint axes, and geometric Grand Trine, T-square, Grand Cross, and Yod matches for selected Sun-through-Pluto points. `additional_points` may explicitly select Vertex/Antivertex, Equatorial Ascendant/Descendant, and Lots of Fortune/Spirit; they stay separate from aspects and interpretation.
+- Planetary hours: `planetary_hours` returns twelve daylight and twelve nighttime unequal temporal hours with Chaldean rulers. It requires a complete sunrise-sunset-next-sunrise sequence and supplies no electional advice.
+
+All thirty deployed additive beta routes reserve one standard-call unit, accept only exact documented fields/enums, and retain existing prices, quotas and no automatic retry. Practitioner sign-off and a complete astrology catalogue are not claimed.
+
+### Aspect windows beta
+
+Use `client.aspect_windows(...)` for exact-hit-anchored major-aspect orb intervals, repeat numbering, clipped boundaries and optional RFC 5545 text. Inputs span at most 31 UTC days and use a 35-second default deadline.

astroapi_io_client-0.1.0/README.md

@@ -0,0 +1,262 @@
+# AstroAPI.io Python client
+
+The source client covers all forty source-candidate calculation routes: thirty-nine standard operations plus the separate Pro Nakshatra Timeline. Production R192 exposes thirty-six standard routes plus the timeline, for thirty-seven total. Minor-body calculations are not part of the contract. This package is not registry-published.
+
+An unpublished, synchronous client for Python 3.10+, with no runtime dependencies.
+The package import is `astroapi_client`; the distribution name is
+`astroapi-io-client`. This source release does not imply publication to PyPI or
+new deployed API capabilities.
+
+Install from a local checkout using `python -m pip install ./clients/python`.
+Building needs setuptools and wheel; the installed client uses only the standard
+library. Keep API credentials in trusted server or command-line environments.
+
+```python
+from astroapi_client import AstroAPIClient, HTTPError, RequestTimeoutError
+
+# Reads ASTROAPI_KEY; alternatively pass api_key=your_key explicitly.
+client = AstroAPIClient()
+birth = {
+    "date": "1990-01-01",
+    "time": "12:00",
+    "timezone": "America/New_York",
+    "lat": 40.7128,
+    "lon": -74.006,
+}
+
+try:
+    result = client.birth_chart(birth)
+    sun = result["chart"]["planets"]["Sun"]
+except HTTPError as error:
+    print(error.status, error.retry_after)  # Sanitized; does not trigger a retry.
+except RequestTimeoutError:
+    print("Deadline exceeded; this request may already have consumed quota.")
+```
+
+An explicit key takes precedence over `ASTROAPI_KEY`. Keys must contain exactly
+64 hexadecimal characters. The SDK never reads another application's settings,
+environment files, browser sessions, or stored keys. Do not place keys in source
+control, browser code, URLs, or logs.
+
+## Methods and current response shapes
+
+Each method takes one dictionary using the gateway's field names. It returns
+the **complete parsed JSON object without changing its envelope**. Exported
+`TypedDict` input types and `py.typed` support editors. Methods without a detailed response type return
+`dict[str, Any]` (`JSONResponse`). `lunar_nodes`, `returns`, `solar_arcs` and
+`vimshottari` provide detailed response type hints; Vimshottari is a union of
+`VimshottariResponseDepth2`, `VimshottariResponseDepth3`, and
+`VimshottariResponseDepth4`. The return's existing
+nested chart remains `JSONResponse`.
+Type hints describe the server contract and do not perform response validation.
+
+| Method | OpenAPI operation ID | Input | Important response path |
+|---|---|---|---|
+| `birth_chart` | `calculateBirthChart` | Birth fields; optional zodiac/ayanamsa | `result["chart"]` |
+| `place_search` **beta** | `searchPlaces` | Query; optional uppercase country codes and limit | Ordered versioned candidates in `result["results"]` |
+| `timezone_resolve` **beta** | `resolvePlaceTimezone` | Versioned place ID plus local date/time | Explicit civil-time status/candidates and unique `resolved_input` |
+| `natal_context` **beta** | `calculateNatalContext` | Birth; optional zodiac/ayanamsa/houses/formats | Stable facts, calculation hash, and selected text artifacts |
+| `aspects` | `calculateAspects` | `{"birth": birth}`; optional zodiac/ayanamsa | `result["aspects"]["aspects"]` is the array |
+| `houses` | `calculateHouses` | `{"birth": birth, "system": "whole_sign"}`; optional zodiac/ayanamsa | Full chart at top level; `result["houses"]["systems"]` |
+| `synastry` | `calculateSynastry` | `{"personA": birth, "personB": other}`; optional zodiac/ayanamsa | `result["charts"]`, `result["aspects"]` |
+| `transits` | `calculateTransits` | Birth plus required `transitDate`; optional `transitTime`, timezone, zodiac/ayanamsa | `result["transits"]["natal_chart"]`, `transit_chart`, `aspects` |
+| `horoscope` **beta** | `calculateHoroscope` | Birth plus optional transit fields, timezone, zodiac/ayanamsa | `result["interpretation"]` |
+| `nakshatra_timeline` | `calculateNakshatraTimeline` | Planet, `start_utc`, `end_utc`, ayanamsa | `result["segments"]` |
+| `natal_svg` **beta** | `calculateNatalSvg` | Birth; optional zodiac, ayanamsa, houses/theme/show_aspects, named aspect profile or custom aspects, `include_png` | `result["svg"]`, optional `result["png"]` |
+| `vargas` **beta** | `calculateVargas` | Birth; optional ayanamsa and one of twenty-four divisions through D150 | `result["bodies"]["moon"]["sign"]`, `result["ascendant"]` |
+| `vimshottari` **beta** | `calculateVimshottari` | Birth; optional ayanamsa and depth 2/3/4 | `result["birth_balance"]`, `result["periods"]` |
+| `ashtakoota` **beta** | `calculateAshtakoota` | Required groom/bride births; optional ayanamsa | `result["kootas"]`, `result["total"]`; no verdict/advice |
+| `ashtakavarga` **beta** | `calculateAshtakavarga` | Required birth; optional ayanamsa and `include_reductions` | BAV, Prastara, SAV, and opt-in reductions/pindas; no interpretation |
+| `numerology` **beta** | `calculateNumerology` | Gregorian `birth_date`; optional ASCII `name`, boolean `master_numbers`/`y_vowel`, integer `year` | `numbers` contains symbolic reduction traces; no interpretations or predictions |
+| `composite` **beta** | `calculateComposite` | personA/personB; optional zodiac/ayanamsa/house_system | `result["planets"]`, synthetic `result["houses"]` |
+| `panchang` **beta** | `calculatePanchang` | at civil snapshot; optional ayanamsa | `result["vara"]`, `result["solar_events"]` |
+| `secondary_progressions` **beta** | `calculateSecondaryProgressions` | birth and target civil time; optional zodiac/ayanamsa/house_system | `result["progressed_planets"]`, separate natal_context |
+| `varga_svg` **beta** | `calculateVargaSvg` | birth; optional ayanamsa/division/layout/theme/`include_png` | `result["svg"]`, `result["chart"]`, optional `result["png"]` |
+| `lunar_nodes` **beta** | `calculateLunarNodes` | at civil instant without coordinates; optional zodiac/ayanamsa | `result["mean"]["north"]`, `result["true"]["north"]` |
+| `returns` **beta** | `calculateReturns` | birth, body sun/moon, after civil time; optional zodiac/ayanamsa/house_system/location | `result["return_utc"]`, `result["chart"]`, `result["search"]` |
+| `solar_arcs` **beta** | `calculateSolarArcs` | birth and target civil time; optional zodiac/ayanamsa/house_system | `result["arc"]`, `result["directed_planets"]`, `result["directed_angles"]`, `result["directed_houses"]` |
+| `moon_phases` **beta** | `calculateMoonPhases` | instant `at` or calendar civil `start`/`end`; optional display timezone and `include_ical` | `result["result"]["phase_sector"]` or `result["result"]["events"]`; optional `result["result"]["ical"]` |
+| `planetary_events` **beta** | `calculatePlanetaryEvents` | whole-second UTC interval, event types/bodies; optional aspects/zodiac/ayanamsa | `result["result"]["events"]` |
+| `house_ingresses` **beta** | `calculateHouseIngresses` | reference birth, whole-second UTC interval, bodies; optional Equal/Whole Sign and zodiac/ayanamsa | `result["result"]["events"]`, fixed cusps |
+| `aspect_windows` **beta** | `calculateAspectWindows` | whole-second UTC interval, bodies; optional aspects/orb/zodiac/ayanamsa/iCalendar | `result["result"]["windows"]` |
+| `event_calendar` **beta** | `calculateEventCalendar` | whole-second UTC interval and selected event families | `result["result"]["events"]`; optional iCalendar, strict opt-in fixed-column CSV, and opt-in deduplicated pass groups |
+| `synastry_svg` **beta** | `calculateSynastrySvg` | two births; optional zodiac/houses/theme/aspects/`include_png` | `result["svg"]`, optional `result["png"]` |
+| `transit_svg` **beta** | `calculateTransitSvg` | birth and transit date; optional display controls/`include_png` | `result["svg"]`, optional `result["png"]` |
+| `natal_report` **beta** | `calculateNatalReport` | birth; optional zodiac/houses/theme/SVG/download | `result["html"]`, source-linked `result["facts"]`, optional `result["download"]` |
+| `birth_time_sensitivity` **beta** | `calculateBirthTimeSensitivity` | civil interval up to six hours, or explicit unknown/approximate time, plus coordinates | `result["result"]["samples"]`, optional workflow classification |
+| `fixed_stars` **beta** | `calculateFixedStars` | civil instant and 1–6 documented stars | `result["objects"]`; no minor bodies |
+| `relocation_chart` **beta** | `calculateRelocationChart` | birth and destination coordinates; optional zodiac/ayanamsa/houses | `result["natal_reference"]`, `result["relocated_chart"]` |
+| `astrocartography` **beta** | `calculateAstrocartography` | civil instant, 1–10 unique Sun-through-Pluto bodies, optional `include_geojson`, `include_geojson_seq`, `include_ndjson`, `include_topojson`, `include_kml`, `include_gpx`, `include_csv`, `include_wkt`, `include_wkb`, `include_gml`, `basemap`, `include_svg`, `include_png`, and `theme` | bounded geometry plus optional deterministic RFC 7946 GeoJSON, RFC 8142 GeoJSON Text Sequences, newline-delimited GeoJSON Features, unquantized TopoJSON, OGC KML 2.2, GPX 1.1, RFC 4180 CSV, WKT, WKB, GML 3.2 artifacts, and 1200×800 SVG/PNG coordinate-grid or bundled Natural Earth coastline map |
+| `eclipse_geometry` **beta** | `calculateEclipseGeometry` | whole-second UTC interval up to 366 days, selected solar/lunar types, optional WGS84 observer | global events and optional sea-level/no-refraction snapshot in each event |
+| `electional_search` **beta** | `calculateElectionalSearch` | location, one or more AND-only filters, and UTC interval up to seven days | hourly matches and sampled windows |
+| `natal_analysis` **beta** | `calculateNatalAnalysis` | birth, aspect controls, and strict sidereal graha-drishti or partial-Shadbala opt-ins | aspects/patterns plus optional `graha_drishti` or `shadbala_foundation` |
+| `planetary_hours` **beta** | `calculatePlanetaryHours` | civil date, IANA timezone, and coordinates | twenty-four unequal day/night temporal hours and rulers |
+| `davison` **beta** | `calculateDavison` | personA/personB; optional zodiac/ayanamsa/house_system | `result["chart"]`, `result["midpoint"]`, `result["metadata"]` |
+
+The never-live extended-sky methods were retired rather than depend on licensed
+minor-body source data. They are not SDK methods or API contracts.
+
+Graha drishti is a separate opt-in on `natal_analysis`. Exact `True` requires
+explicit `zodiac: "sidereal"`; omission/false preserves the existing response.
+Ruleset `parashari_whole_sign_full_aspects_v1` includes Sun, Moon, Mars,
+Mercury, Jupiter, Venus, and Saturn only. It returns full whole-sign targets and
+occupying classical grahas, with no node aspects, partial strengths, or
+interpretation. The request remains one standard quota unit.
+
+Synastry cross-aspects retain `transit` for person B and `natal` for person A.
+The horoscope route is a beta, deterministic structured interpretation; it is
+not a stable prose-report or LLM contract. Birth-chart/aspects compute both
+legacy house systems; the houses method filters to the requested system.
+Its `placidus`, `porphyry`, `meridian`, `campanus`, `regiomontanus`,
+`alcabitius`, `koch`, `morinus`, `topocentric`, `sripati`, `vehlow`, `horizon`, `krusinski`, `sunshine`, `sunshine_alt`, `savard`, `pullen_sd`, `pullen_sr`, `carter`, `apc`, `equal_mc`, and `natural` options are beta, with explicit rejection and no fallback. Gauquelin is Houses-only because its response contains 36 sectors; natal
+SVG accepts the preceding twelve-house systems, while other chart/report routes do not accept
+Porphyry, Meridian, Campanus, Regiomontanus, Alcabitius, Koch, Morinus, Topocentric, Sripati, Vehlow, Horizon/Azimuth, Krusinski-Pisa-Goelzer, Sunshine, Sunshine alternative, Savard-A, Pullen SD, Pullen SR, Carter, APC, Equal MC, or Natural. Meridian cusp 1 is
+the Equatorial Ascendant; Campanus, Regiomontanus, Alcabitius, and Koch cusp 1
+are the physical Ascendant. Morinus cusps are latitude-independent; its cusps 1 and 10 are not the physical Ascendant and Midheaven. Topocentric uses Polich/Page house geometry with the physical Ascendant and Midheaven as cusps 1 and 10; it does not alter planet positions. Sripati shifts each cusp to the midpoint of the preceding Porphyry sector; its cusps 1 and 10 are not the physical angles. Vehlow uses twelve equal 30-degree ecliptic houses with the physical Ascendant at the center of house 1; its cusps 1 and 10 are not the physical angles. Horizon/Azimuth projects twelve equal local-horizon divisions through vertical circles to the ecliptic; cusp 1 is not the physical Ascendant and cusp 10 is the Midheaven. Krusinski-Pisa-Goelzer projects twelve equal Ascendant-zenith great-circle divisions through celestial meridian circles; cusps 1 and 10 are the physical Ascendant and Midheaven. Sunshine uses the Treindl construction from trisected solar diurnal and nocturnal semi-arcs; cusps 1 and 10 are the physical Ascendant and Midheaven. Sunshine alternative uses the separate Makransky prime-vertical projection for the same solar house points. Savard-A projects one-third and two-thirds geographic-latitude circles through the prime vertical; cusps 1 and 10 are the physical Ascendant and Midheaven and opposite cusps are antipodal. Pullen SD redistributes each ecliptic quadrant's deviation from 90 degrees with quarter/half/quarter weighting; cusp 10 is the physical Midheaven and cusp 1 uses the orientation-adjusted Ascendant. Pullen SR proportions complementary quadrant house widths as rx, x, rx and r³x, r⁴x, r³x; cusp 10 is the physical Midheaven and cusp 1 uses the orientation-adjusted Ascendant. Carter divides right ascension into twelve equal arcs from the orientation-adjusted Ascendant and projects them to the ecliptic; cusp 10 is not generally the physical Midheaven. APC divides the Ascendant parallel into six sectors below and six above the horizon; cusps 1 and 10 are the orientation-adjusted angles and intermediate opposite cusps are not generally antipodal. Equal MC fixes the physical Midheaven at cusp 10 and places twelve equal 30-degree ecliptic houses; cusp 1 is generally not the physical Ascendant. Natural fixes cusp 1 at zero degrees Aries in the selected zodiac and places all cusps on sign boundaries; physical angles remain separate. Gauquelin is Houses-only and returns 36 clockwise semiarc sector boundaries under the existing houses map; sector 1 is Ascendant and sector 10 is Midheaven. Regiomontanus, Alcabitius, Koch, Morinus, Topocentric, Sripati, Vehlow, Horizon/Azimuth, Krusinski-Pisa-Goelzer, Sunshine, Sunshine alternative, Savard-A, Pullen SD, Pullen SR, Carter, APC, Equal MC, Natural, and Gauquelin are not admitted by saved
+profiles. Equal/Whole Sign remain the existing chart defaults.
+
+```python
+timeline = client.nakshatra_timeline({
+    "planet": "moon",
+    "start_utc": "2026-01-01T00:00:00Z",
+    "end_utc": "2026-01-03T00:00:00Z",
+    "ayanamsa": "lahiri",
+})
+```
+
+The timeline is Pro-only, always sidereal, supports the nine documented bodies,
+and allows a positive range up to 180 days. It uses a separate quota. It does not
+accept a sampling-step override. Dates across routes remain limited to
+1900–2050. Legacy chart nodes and timeline Rahu/Ketu remain mean-node calculations;
+the separate `lunar_nodes` beta supplies a distinct geometric osculating model.
+Installing the SDK does not change any existing calculation convention or accuracy.
+
+The SVG route accepts birth data, not an uploaded chart, SVG, URL, font or image.
+Defaults are Equal houses, light theme, major aspects shown, tropical zodiac
+and Lahiri when sidereal. The result contains an SVG string inside JSON; it is
+not a browser credential or hosted-widget API.
+
+Natal, synastry, transit and varga SVG plus natal report accept exact `light`,
+`dark`, or `monochrome`. Defaults are unchanged. Monochrome is a fixed
+grayscale palette, not an accessibility certification; optional PNG pixels are
+grayscale while retaining RGB encoding.
+
+Natal report HTML accepts optional `report_branding` with a required 1–64 character bounded ASCII `display_name` and optional exact `amber`, `blue`, or `green` accent. It is escaped, text-only, visibly attributed to AstroAPI, and invalid with non-HTML formats; omission preserves exact predecessor bytes. No logo, URL, markup, template, remote resource, localization, or fact mutation is accepted.
+
+Natal report downloads accept exact `include_download: True`. Omitted
+`download_format` retains HTML; exact `pdf`, `docx`, `xlsx`, `ods`, `epub`, `odt`, `rtf`, `json`, `csv`, `xml`, `ndjson`, `tsv`, `markdown`, `text`, or
+`zip` selects deterministic PDF, editable macro-free OOXML, editable
+macro-free and formula-free OOXML workbook, macro-free ODF 1.3, editable dependency-free RTF, machine-readable JSON, tabular CSV, fixed-order XML, canonical one-record-per-fact NDJSON, escaped fixed-column TSV, UTF-8 calculation facts/plain text, or the unchanged fixed
+HTML/PDF/calculation-JSON bundle.
+
+Vargas and Vimshottari always use sidereal coordinates with Lahiri default.
+Vargas supports D1/D2/D3/D4/D5/D6/D7/D8/D9/D10/D11/D12/D16/D20/D24/D27/D30/D40/D45/D60/D81/D108/D144/D150 (default D9) for nine traditional bodies plus the
+Ascendant, not outer planets. Vimshottari returns nine major periods, each with
+nine subperiods, using a fixed 365.25-day Julian year. Its first period begins
+at the theoretical natal-major start, which can precede birth. Arithmetic
+schedule dates may extend outside the ephemeris input-date window; they are
+not predictions or additional ephemeris calculations. Optional `depth: 3` adds
+one fixed third level; omission or `depth: 2` preserves the original response.
+No arbitrary depth,
+year model, range or specialist signoff is claimed. Each of these beta routes
+costs one standard-call unit under unchanged plan quotas/prices and uses the
+normal request deadline.
+
+## Validation, deadlines and errors
+
+The client checks required fields, supported enums, numeric coordinate bounds,
+date/time formats, timeline ranges and the 128 KiB request limit before sending.
+It accepts JSON numbers for coordinates and documented lowercase enum values;
+unknown fields and explicit null optionals are rejected. Omit unused optional
+fields. Timezone identifiers, DST ambiguity/nonexistence and undefined
+Ascendant geometry remain server validation. Supplying a known UTC instant
+avoids ambiguous local clock changes. No defaults are inserted into payloads.
+
+Normal requests have a 20-second caller deadline; planetary events, eclipse geometry, electional search and aspect windows have 35 seconds; timelines have 70 seconds.
+Configure `timeout=`, `planetary_events_timeout=`, and `timeline_timeout=` with finite positive seconds up to
+300. The deadline covers network establishment, TLS, headers, response body and
+JSON parsing, but starts after local input validation/serialization.
+
+The synchronous call uses a daemon transport worker so a stalled operating-system
+DNS lookup or slowly arriving headers/body cannot keep the caller waiting past
+its deadline. Cancellation shuts down the known socket. A DNS call itself
+cannot be forcibly stopped; its worker retains a slot until it exits and checks
+cancellation before sending credentials. There are at most eight outstanding
+transport workers **across all client instances in a process**. Exhaustion raises
+`ClientBusyError` without starting another request. No context manager or explicit
+close is needed; every completed exchange closes its connection. Successful
+calls do not reuse connections.
+
+`max_response_bytes=` defaults to 4 MiB and may be set from 1 byte through 64 MiB.
+Oversized, truncated, compressed, non-object, duplicate-key or malformed JSON
+responses are rejected. Bodies are read incrementally; compressed responses are
+not decompressed. The standard library also limits HTTP header count and line
+length. Errors omit request payloads, response bodies, credentials, raw headers,
+and underlying transport exceptions. `HTTPError` exposes only numeric `status`
+and sanitized `retry_after` (integer seconds or a normalized HTTP date).
+
+There are **no automatic retries**, including for 429, 503 or timeouts. Once the
+gateway reserves quota, even an invalid payload, dependency failure or timeout
+consumes a unit. A client disconnect does not cancel admitted server work.
+
+## Transport origin
+
+The default is `https://api.astroapi.io`; calls use `POST /api/astro/...` with
+`Authorization: Bearer`. A custom `base_url` must be a trusted HTTPS origin
+without a path, credentials, query or fragment. Selecting another HTTPS origin
+authorizes sending your key to that origin. TLS certificates and hostnames are
+verified. Proxy environment variables, cookies and redirects are not used.
+Every redirect is returned as `HTTPError`; keys are never forwarded to its
+destination.
+
+For local Node gateway testing only:
+
+```python
+client = AstroAPIClient(
+    api_key=your_synthetic_key,
+    base_url="http://127.0.0.1:5100",
+    allow_http_localhost=True,
+)
+```
+
+HTTP requires explicit opt-in and both a loopback/localhost URL and a loopback
+connected peer. Never point the client directly at the internal Python engine.
+
+## Offline checks
+
+From this directory, after local installation:
+
+```sh
+python -m unittest discover -s tests -v
+```
+
+Tests use generated synthetic keys and local HTTP/HTTPS servers. Real TLS tests
+generate temporary certificates with local OpenSSL and explicitly skip if it is
+unavailable; no certificate keys are committed. They do not call the
+production API or Stripe. The example under `examples/` makes a billable API
+request when explicitly run with a real key. Its executable-example test replaces
+the transport with a local mock and uses no real account key.
+
+## Additional bounded beta calculations
+
+- Composite: strict personA/personB birth objects; shortest-arc planetary and angle midpoints. Equal/Whole Sign houses are synthetic from midpoint Ascendant, not physical/Davison houses. Near-antipodal sources reject; no Placidus, nodes or speeds.
+- Panchang: strict at civil snapshot and optional ayanamsa, always sidereal. Latitude is inclusive [-88,88]. Classifications are at the requested instant; solar events use the USNO -50 arcminute horizon at elevation 0, not Hindu-geocentric sunrise. Civil weekday and sunrise-based vara differ. Unavailable bounded sunrise gives explicit null vara. Historical local offsets can include seconds; paired UTC fields are interoperable.
+- Secondary progressions: strict birth plus target date/time/timezone, target>=birth. Planets only, fixed 365.2421904-day year in uniform TT; natal_context angles/houses are not progressed. Derived progressed_utc may contain actual leap second 60; preserve the string rather than passing it blindly to JavaScript Date/Python datetime. No progressed angles/houses/aspects/nodes/speeds or prediction claim.
+- Varga SVG: birth plus optional ayanamsa, any supported D1/D2/D3/D4/D5/D6/D7/D8/D9/D10/D11/D12/D16/D20/D24/D27/D30/D40/D45/D60/D81/D108/D144/D150 division, layout north_indian/south_indian and theme light/dark/monochrome. Defaults D1/north_indian/dark; /vargas instead defaults D9. Original North fixed-house/South fixed-sign SVG, houses counted from divisional Ascendant; not bhava-chalit. Response.chart is the unchanged Vargas result; SVG is bounded to 128 KiB inside JSON.
+  D150 additionally accepts exact `d150_method` values `"deva_keralam_chandra_kala_nadi_non_uniform"`, `"deva_keralam_chandra_kala_nadi_uniform_direct"`, `"parivritti_cyclic"`, `"movable_aries_forward_fixed_taurus_reverse_dual_gemini_forward"`, `"movable_aries_forward_fixed_scorpio_reverse_dual_sagittarius_forward"`, `"movable_aries_forward_fixed_leo_reverse_dual_sagittarius_forward"`, and `"movable_source_sign_forward_fixed_source_sign_reverse_dual_source_sign_forward"`; omission retains the uniform-direct D150 response, and the field is rejected for every other division.
+
+- Lunar nodes: `lunar_nodes` takes an `at` civil instant with no coordinates and optional zodiac/ayanamsa. The response provides north/south pairs for Meeus mean nodes and geometric DE421 osculating nodes, each with its explicit source frame. `LunarNodesInput` and `LunarNodesResponse` are exported types. Chart and timeline node fields keep the existing mean-node contract.
+- Returns: `returns` takes birth, exact body `sun` or `moon`, and an `after` civil instant. Optional zodiac/ayanamsa, Equal/Whole Sign houses and `location:{lat,lon}` are supported; location defaults to birth coordinates. `ReturnsInput` and `ReturnsResponse` type the new request/envelope. Read `return_utc`, `chart` and `search`. The first return lies beyond a one-millisecond start exclusion and the full fixed 370-day Sun/32-day Moon TT window must fit the supported UTC range. `after` may precede birth. Preserve leap-second UTC strings; numerical tolerance does not establish physical accuracy.
+
+- Solar arcs: `solar_arcs` takes strict birth plus target civil time and optional zodiac/ayanamsa/Equal or Whole Sign houses. Omitted `method` and exact `true_solar_arc` preserve the direct true tropical Sun arc. Exact `method: "mean_naibod"` applies the fixed 0.98564733° mean longitude key per elapsed 365.2421904-day TT model year. Both methods direct natal planets and Ascendant/MC uniformly and retain synthetic houses, one-unit accounting, the 1900–2050 dates, and natal-date ayanamsa policy. No relocation, converse/right-ascension arc, MC-derived angle recalculation, arbitrary key, aspects, nodes or speeds.
+- Vimshottari depth: `depth` accepts integer 2, 3, or 4. Omission/2 and the complete depth-3 response remain unchanged. Depth 4 adds 6,561 Sookshma leaves, `birth_balance.sookshma_dasha_lord`, and exact count metadata. Fourth-level leaves omit the redundant display-only `years` field so the complete response stays below 1 MiB. Python rejects floats, strings and booleans. Depth 4 is synchronous-only under the durable-job 256 KiB cap. The arithmetic is bounded and deterministic, not arbitrary recursion or prediction; an admitted synchronous call costs one standard unit.
+- Eclipse geometry: `eclipse_geometry` searches at most 366 UTC days. Optional `observer` coordinates add a fixed sea-level, no-refraction topocentric snapshot at each rounded global maximum. It does not calculate the location's maximum, contacts, visibility at other instants, paths, maps, terrain/weather, safety guidance or interpretation.
+- Electional search: `electional_search` applies one or more documented AND-only filters at fixed hourly samples for at most seven days/168 samples. Results are sampled candidates without continuous guarantees, ranking, recommendations, void-of-course analysis or interpretation.
+- Natal analysis: `natal_analysis` returns configured aspects, optional midpoint axes, and geometric Grand Trine, T-square, Grand Cross, and Yod matches for selected Sun-through-Pluto points. `additional_points` may explicitly select Vertex/Antivertex, Equatorial Ascendant/Descendant, and Lots of Fortune/Spirit; they stay separate from aspects and interpretation.
+- Planetary hours: `planetary_hours` returns twelve daylight and twelve nighttime unequal temporal hours with Chaldean rulers. It requires a complete sunrise-sunset-next-sunrise sequence and supplies no electional advice.
+
+All thirty deployed additive beta routes reserve one standard-call unit, accept only exact documented fields/enums, and retain existing prices, quotas and no automatic retry. Practitioner sign-off and a complete astrology catalogue are not claimed.
+
+### Aspect windows beta
+
+Use `client.aspect_windows(...)` for exact-hit-anchored major-aspect orb intervals, repeat numbering, clipped boundaries and optional RFC 5545 text. Inputs span at most 31 UTC days and use a 35-second default deadline.

astroapi_io_client-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "astroapi-io-client"
+version = "0.1.0"
+description = "Synchronous Python client for the AstroAPI.io calculation gateway"
+readme = "README.md"
+license = "ISC"
+license-files = ["LICENSE.txt"]
+requires-python = ">=3.10"
+dependencies = []
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+astroapi_client = ["py.typed"]

astroapi_io_client-0.1.0/setup.cfg

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