readyapis 0.1.0__tar.gz

readyapis-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+# Build artifacts
+dist/
+build/
+*.egg-info/
+
+# Virtualenv
+.venv/
+venv/
+
+# Caches
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

readyapis-0.1.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: readyapis
+Version: 0.1.0
+Summary: Official Python SDK for Ready APIs — curated REST APIs and composite signals.
+Project-URL: Homepage, https://readyapis.com
+Project-URL: Documentation, https://readyapis.com/docs
+Project-URL: Repository, https://github.com/ReadyAPIs-com/readyapis
+Project-URL: Issues, https://github.com/ReadyAPIs-com/readyapis/issues
+Author-email: Ready APIs <support@readyapis.com>
+License-Expression: MIT
+Keywords: api,calendar,email,fx,geo,intel,readyapis,sdk,tax
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1.0,>=0.24
+Description-Content-Type: text/markdown
+
+# readyapis
+
+> Official Python SDK for [Ready APIs](https://readyapis.com) — curated REST APIs and composite signals.
+
+```bash
+pip install readyapis
+```
+
+Six hero APIs (geo, tax, fx, email, calendar, intel) plus identity / catalog metadata, in one tiny typed client. No Pydantic, no codegen — just `httpx` and the standard library.
+
+## Quick start
+
+```python
+from readyapis import Client
+
+# Demo mode — no key needed. Hits /demo/api/v1/* with allowlisted params.
+client = Client()
+
+zip_data = client.geo.zip("30301")
+print(zip_data.city, zip_data.state)          # "Atlanta" "GA"
+
+tax = client.tax.calculate(income=125000, state="NY", year=2026, filing_status="single")
+print(tax.federal["tax"], tax.taxable_income) # 18733.42  108900.0
+
+fx = client.fx.convert(amount=100, from_="USD", to="EUR")
+print(fx.converted)                           # 85.4555
+```
+
+## Authentication
+
+Set an API key as an environment variable (recommended) or pass it explicitly:
+
+```bash
+export READYAPIS_API_KEY=ra_live_...
+```
+
+```python
+from readyapis import Client
+
+client = Client()                          # reads READYAPIS_API_KEY
+client = Client(api_key="ra_live_...")     # explicit override
+```
+
+Get a key at <https://readyapis.com/register>. Free tier: 1,000 credits/month.
+
+## Demo mode
+
+If no API key is configured, the client enters **demo mode** automatically. It hits `/demo/api/v1/*` routes, which require no auth but only accept a small set of allowlisted parameters (ZIP `30301`, email `hello@stripe.com`, etc.) — perfect for tinkering and CI.
+
+```python
+client = Client()
+assert client.is_demo
+
+# Demo allowlist: 10001, 30301, 30303, 60601, 78701, 94105, 98101.
+client.geo.zip("30301")                    # OK
+client.geo.zip("12345")                    # raises ApiError (demo_parameter_not_allowed)
+```
+
+## Namespaces
+
+```python
+client.geo.zip("30301")
+client.geo.city(name="Atlanta", state="GA")
+client.geo.ip("8.8.8.8")
+client.geo.enrich(zip="30301")
+client.geo.nearby(lat=33.7488, lon=-84.3877, radius_miles=10)
+
+client.tax.calculate(income=125000, state="NY", year=2026, filing_status="single")
+client.tax.brackets(year=2026)                    # federal
+client.tax.brackets(year=2026, state="NY")        # state
+client.tax.deductions(year=2026, filing_status="single")
+
+client.fx.rates(base="USD")
+client.fx.rates(base="USD", symbols=["EUR", "GBP", "JPY"])
+client.fx.convert(amount=100, from_="USD", to="EUR")
+
+client.email.validate("hello@stripe.com")
+
+client.calendar.holidays(country="US", year=2026)
+client.calendar.business_days(start="2026-01-01", end="2026-01-31")
+
+client.intel.site_risk(zip="30301", site_profile="insurance_underwriting")
+
+client.meta.whoami()        # requires API key
+client.meta.catalog()       # free
+```
+
+The full list of demo-allowed `site_profile` values: `data_center_site`, `insurance_underwriting`, `remote_office`, `retail_storefront`, `small_office`, `warehouse_distribution`. Production mode accepts more.
+
+## Response shape
+
+Every response is wrapped in a `Response` object that proxies the JSON:API-flavored envelope. You can use ergonomic attribute access, dict-style lookup, or get the raw payload.
+
+```python
+r = client.geo.zip("30301")
+
+r.city            # "Atlanta"           — flattened from data.attributes
+r.state           # "GA"
+r["county"]       # "Fulton"            — dict-style works too
+r.data            # the full data dict
+r.attributes      # just the attributes dict
+r.meta            # {credits_used, source, ...}
+r.raw             # the full underlying JSON
+```
+
+For list responses, iterate or index:
+
+```python
+holidays = client.calendar.holidays(country="US", year=2026)
+assert holidays.is_list
+for h in holidays:
+    print(h.date, h.name)
+```
+
+## Errors
+
+All errors inherit from `ApiError`. Specific subclasses let you branch on common cases:
+
+```python
+from readyapis import Client, ApiError, AuthError, RateLimitError, NotFoundError
+
+try:
+    client.geo.zip("99999")
+except RateLimitError as e:
+    print(f"slow down — retry in {e.retry_after}s")
+except AuthError as e:
+    print(f"bad key: {e.code}")
+except NotFoundError as e:
+    print(f"not found: {e.message}")
+except ApiError as e:
+    print(f"{e.status_code} {e.code}: {e.message}")
+    print(e.body)   # full error envelope
+```
+
+Every `ApiError` exposes `.status_code`, `.code`, `.message`, `.body`, and (for 429s) `.retry_after`.
+
+## Retry behavior
+
+The client automatically retries `429`, `500`, `502`, `503`, and `504` responses with exponential backoff (0.5s, 1s, 2s — three attempts total) plus small jitter. On `429`, it honors `Retry-After` if present. Disable per-client:
+
+```python
+client = Client(retry=False)
+```
+
+## Idempotency
+
+`POST` endpoints accept an `idempotency_key` keyword. The server treats two requests with the same key (within the idempotency window) as the same logical operation — safe to retry from the client.
+
+```python
+client.intel.rank(
+    candidates=[...],
+    objective="enterprise_buyer",
+    idempotency_key="run-2026-05-14-abc",
+)
+```
+
+## Configuration
+
+```python
+Client(
+    api_key=None,                          # str | None — falls back to READYAPIS_API_KEY env
+    base_url="https://readyapis.com",      # override for staging/local
+    timeout=30.0,                          # per-request seconds
+    retry=True,                            # retry 429 + 5xx with backoff
+    user_agent=None,                       # override the UA string
+    http_client=None,                      # bring your own httpx.Client
+)
+```
+
+## Compatibility
+
+Python 3.9 and later. Only runtime dependency is `httpx >= 0.24, < 1.0`.
+
+## License
+
+MIT

readyapis-0.1.0/PUBLISHING.md

@@ -0,0 +1,141 @@
+# Publishing `readyapis` to PyPI
+
+This package is built and tested. The homepage already advertises
+`pip install readyapis`, so **until you publish, that command will return
+"No matching distribution found" from PyPI.** Publish to make it real.
+
+## One-time setup (do once, then never again)
+
+1. **Have a PyPI account.** Sign up at <https://pypi.org/account/register/> if
+   you don't already, using `jmoncrief@gmail.com` or whichever email you
+   want associated with the published package.
+
+2. **Enable 2FA.** PyPI requires it before you can create API tokens. Use
+   <https://pypi.org/manage/account/two-factor/> — TOTP (e.g. 1Password,
+   Authy, Google Authenticator) works fine.
+
+3. **Create a project-scoped API token.** Go to
+   <https://pypi.org/manage/account/token/>, name it `readyapis-publish`,
+   scope it to the `readyapis` project (you may need to upload a first
+   release using an "Entire account" token, then narrow the scope after).
+   Copy the token — it starts with `pypi-AgEIcHl…`. You only see it once.
+
+4. **Store the token** in `~/.pypirc` (mode `0600`):
+
+   ```ini
+   [pypi]
+     username = __token__
+     password = pypi-AgEIcHl…YOUR_TOKEN_HERE
+   ```
+
+   Or set it on the fly via `TWINE_USERNAME=__token__ TWINE_PASSWORD=pypi-… twine upload …`.
+
+No org / scope ceremony needed — the package is unscoped (`readyapis`),
+owned by your personal PyPI account directly. (We tried checking the
+`readyapis` name at <https://pypi.org/pypi/readyapis/json> first — it
+returned `Not Found`, so the slot is available.)
+
+## Build
+
+From the repo root:
+
+```bash
+cd sdk/python
+python -m pip install --upgrade build twine
+python -m build
+```
+
+That produces two artifacts in `dist/`:
+
+- `readyapis-0.1.0-py3-none-any.whl`  ← the wheel
+- `readyapis-0.1.0.tar.gz`            ← the sdist
+
+Sanity-check them before uploading:
+
+```bash
+python -m twine check dist/*
+```
+
+Both files should print `PASSED`.
+
+## Publish
+
+```bash
+cd sdk/python
+python -m twine upload dist/*
+```
+
+That's it. Within ~30 seconds:
+
+- The package shows up at <https://pypi.org/project/readyapis/>
+- `pip install readyapis` works from any machine on the planet
+- The homepage `pip install readyapis` hint (if added) starts functioning
+
+## Verify
+
+After publish, in a scratch dir:
+
+```bash
+mkdir /tmp/rapi-py-test && cd /tmp/rapi-py-test
+python -m venv .venv && source .venv/bin/activate
+pip install readyapis
+python -c "
+from readyapis import Client
+r = Client().geo.zip('30301')
+print(r.city, r.state)        # 'Atlanta' 'GA'
+"
+```
+
+## Subsequent releases
+
+Bump `version` in two places (kept manually in sync):
+
+1. `sdk/python/pyproject.toml`  — the `version = "0.1.0"` line.
+2. `sdk/python/src/readyapis/_version.py` — the `__version__ = "0.1.0"` line.
+
+Then:
+
+```bash
+cd sdk/python
+rm -rf dist/
+python -m build
+python -m twine upload dist/*
+```
+
+Recommended workflow:
+
+```bash
+cd sdk/python
+# ... bump version in both files ...
+git commit -am "readyapis 0.1.1"
+git tag readyapis-py-0.1.1
+git push --follow-tags
+
+rm -rf dist/
+python -m build
+python -m twine upload dist/*
+```
+
+## If you change your mind
+
+PyPI **does not allow re-uploading the same version**, even if you delete it.
+If you publish a broken release, bump the patch version (`0.1.0` → `0.1.1`)
+and publish that. You can `pip install readyapis==0.1.1` but `0.1.0` will
+remain in the index (with a "yanked" tag if you yank it).
+
+For early days this is fine — just don't publish anything secret.
+
+## What `pip` users actually download
+
+The published wheel contains just the `src/readyapis/` tree plus `README.md`
+(per the hatchling include rules in `pyproject.toml`):
+
+- `readyapis/__init__.py`
+- `readyapis/_client.py`
+- `readyapis/_errors.py`
+- `readyapis/_types.py`
+- `readyapis/_version.py`
+- `readyapis/geo.py`, `tax.py`, `fx.py`, `email.py`, `calendar.py`, `intel.py`, `meta.py`
+- `readyapis/py.typed`     ← marks the package as typed for mypy / pyright
+
+Single runtime dependency: `httpx >= 0.24, < 1.0`. Total wheel size: ~10 KB.

readyapis-0.1.0/README.md

@@ -0,0 +1,176 @@
+# readyapis
+
+> Official Python SDK for [Ready APIs](https://readyapis.com) — curated REST APIs and composite signals.
+
+```bash
+pip install readyapis
+```
+
+Six hero APIs (geo, tax, fx, email, calendar, intel) plus identity / catalog metadata, in one tiny typed client. No Pydantic, no codegen — just `httpx` and the standard library.
+
+## Quick start
+
+```python
+from readyapis import Client
+
+# Demo mode — no key needed. Hits /demo/api/v1/* with allowlisted params.
+client = Client()
+
+zip_data = client.geo.zip("30301")
+print(zip_data.city, zip_data.state)          # "Atlanta" "GA"
+
+tax = client.tax.calculate(income=125000, state="NY", year=2026, filing_status="single")
+print(tax.federal["tax"], tax.taxable_income) # 18733.42  108900.0
+
+fx = client.fx.convert(amount=100, from_="USD", to="EUR")
+print(fx.converted)                           # 85.4555
+```
+
+## Authentication
+
+Set an API key as an environment variable (recommended) or pass it explicitly:
+
+```bash
+export READYAPIS_API_KEY=ra_live_...
+```
+
+```python
+from readyapis import Client
+
+client = Client()                          # reads READYAPIS_API_KEY
+client = Client(api_key="ra_live_...")     # explicit override
+```
+
+Get a key at <https://readyapis.com/register>. Free tier: 1,000 credits/month.
+
+## Demo mode
+
+If no API key is configured, the client enters **demo mode** automatically. It hits `/demo/api/v1/*` routes, which require no auth but only accept a small set of allowlisted parameters (ZIP `30301`, email `hello@stripe.com`, etc.) — perfect for tinkering and CI.
+
+```python
+client = Client()
+assert client.is_demo
+
+# Demo allowlist: 10001, 30301, 30303, 60601, 78701, 94105, 98101.
+client.geo.zip("30301")                    # OK
+client.geo.zip("12345")                    # raises ApiError (demo_parameter_not_allowed)
+```
+
+## Namespaces
+
+```python
+client.geo.zip("30301")
+client.geo.city(name="Atlanta", state="GA")
+client.geo.ip("8.8.8.8")
+client.geo.enrich(zip="30301")
+client.geo.nearby(lat=33.7488, lon=-84.3877, radius_miles=10)
+
+client.tax.calculate(income=125000, state="NY", year=2026, filing_status="single")
+client.tax.brackets(year=2026)                    # federal
+client.tax.brackets(year=2026, state="NY")        # state
+client.tax.deductions(year=2026, filing_status="single")
+
+client.fx.rates(base="USD")
+client.fx.rates(base="USD", symbols=["EUR", "GBP", "JPY"])
+client.fx.convert(amount=100, from_="USD", to="EUR")
+
+client.email.validate("hello@stripe.com")
+
+client.calendar.holidays(country="US", year=2026)
+client.calendar.business_days(start="2026-01-01", end="2026-01-31")
+
+client.intel.site_risk(zip="30301", site_profile="insurance_underwriting")
+
+client.meta.whoami()        # requires API key
+client.meta.catalog()       # free
+```
+
+The full list of demo-allowed `site_profile` values: `data_center_site`, `insurance_underwriting`, `remote_office`, `retail_storefront`, `small_office`, `warehouse_distribution`. Production mode accepts more.
+
+## Response shape
+
+Every response is wrapped in a `Response` object that proxies the JSON:API-flavored envelope. You can use ergonomic attribute access, dict-style lookup, or get the raw payload.
+
+```python
+r = client.geo.zip("30301")
+
+r.city            # "Atlanta"           — flattened from data.attributes
+r.state           # "GA"
+r["county"]       # "Fulton"            — dict-style works too
+r.data            # the full data dict
+r.attributes      # just the attributes dict
+r.meta            # {credits_used, source, ...}
+r.raw             # the full underlying JSON
+```
+
+For list responses, iterate or index:
+
+```python
+holidays = client.calendar.holidays(country="US", year=2026)
+assert holidays.is_list
+for h in holidays:
+    print(h.date, h.name)
+```
+
+## Errors
+
+All errors inherit from `ApiError`. Specific subclasses let you branch on common cases:
+
+```python
+from readyapis import Client, ApiError, AuthError, RateLimitError, NotFoundError
+
+try:
+    client.geo.zip("99999")
+except RateLimitError as e:
+    print(f"slow down — retry in {e.retry_after}s")
+except AuthError as e:
+    print(f"bad key: {e.code}")
+except NotFoundError as e:
+    print(f"not found: {e.message}")
+except ApiError as e:
+    print(f"{e.status_code} {e.code}: {e.message}")
+    print(e.body)   # full error envelope
+```
+
+Every `ApiError` exposes `.status_code`, `.code`, `.message`, `.body`, and (for 429s) `.retry_after`.
+
+## Retry behavior
+
+The client automatically retries `429`, `500`, `502`, `503`, and `504` responses with exponential backoff (0.5s, 1s, 2s — three attempts total) plus small jitter. On `429`, it honors `Retry-After` if present. Disable per-client:
+
+```python
+client = Client(retry=False)
+```
+
+## Idempotency
+
+`POST` endpoints accept an `idempotency_key` keyword. The server treats two requests with the same key (within the idempotency window) as the same logical operation — safe to retry from the client.
+
+```python
+client.intel.rank(
+    candidates=[...],
+    objective="enterprise_buyer",
+    idempotency_key="run-2026-05-14-abc",
+)
+```
+
+## Configuration
+
+```python
+Client(
+    api_key=None,                          # str | None — falls back to READYAPIS_API_KEY env
+    base_url="https://readyapis.com",      # override for staging/local
+    timeout=30.0,                          # per-request seconds
+    retry=True,                            # retry 429 + 5xx with backoff
+    user_agent=None,                       # override the UA string
+    http_client=None,                      # bring your own httpx.Client
+)
+```
+
+## Compatibility
+
+Python 3.9 and later. Only runtime dependency is `httpx >= 0.24, < 1.0`.
+
+## License
+
+MIT

readyapis-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "readyapis"
+version = "0.1.0"
+description = "Official Python SDK for Ready APIs — curated REST APIs and composite signals."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "Ready APIs", email = "support@readyapis.com" }]
+keywords = ["readyapis", "api", "sdk", "geo", "tax", "fx", "email", "calendar", "intel"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Internet :: WWW/HTTP",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.24,<1.0"]
+
+[project.urls]
+Homepage = "https://readyapis.com"
+Documentation = "https://readyapis.com/docs"
+Repository = "https://github.com/ReadyAPIs-com/readyapis"
+Issues = "https://github.com/ReadyAPIs-com/readyapis/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/readyapis"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/readyapis",
+    "README.md",
+    "PUBLISHING.md",
+    "pyproject.toml",
+]

readyapis-0.1.0/src/readyapis/__init__.py

@@ -0,0 +1,35 @@
+"""Official Python SDK for Ready APIs.
+
+Quick start:
+
+    from readyapis import Client
+
+    client = Client()  # demo mode, no key needed
+    zip_data = client.geo.zip("30301")
+    print(zip_data.city, zip_data.state)  # "Atlanta", "GA"
+
+Set ``READYAPIS_API_KEY`` in your environment, or pass ``api_key="ra_live_..."``
+explicitly, to hit the production API.
+"""
+
+from ._client import Client
+from ._errors import (
+    ApiError,
+    AuthError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+)
+from ._types import Response
+from ._version import __version__
+
+__all__ = [
+    "Client",
+    "Response",
+    "ApiError",
+    "AuthError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+    "__version__",
+]