demografix 0.1.0__tar.gz

demografix-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package with dev extras
+        run: python -m pip install -e .[dev]
+
+      - name: Run tests
+        run: python -m pytest -q
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install build
+          python -m build
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

demografix-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,73 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Verify tag matches manifest version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          manifest="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
+          echo "Tag version:      $tag"
+          echo "Manifest version: $manifest"
+          if [ "$tag" != "$manifest" ]; then
+            echo "::error::Tag version ($tag) does not match pyproject.toml version ($manifest)."
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install build
+          python -m build
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI via Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

demografix-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+build/
+dist/
+*.egg-info/
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/

demografix-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Demografix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

demografix-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: demografix
+Version: 0.1.0
+Summary: Official Python SDK for the Demografix APIs: genderize.io, agify.io, nationalize.io.
+Project-URL: Homepage, https://genderize.io
+Project-URL: Documentation, https://genderize.io/documentation/api
+Project-URL: Repository, https://github.com/DemografixGenderize/demografix-python
+Project-URL: Issues, https://github.com/DemografixGenderize/demografix-python/issues
+Author-email: Demografix <info@genderize.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agify,demografix,demographics,genderize,nationalize
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Demografix Python SDK
+
+Run demographic analysis over names — predicted gender, age, and nationality — from one client. The package
+covers [genderize.io](https://genderize.io), [agify.io](https://agify.io), and
+[nationalize.io](https://nationalize.io).
+
+## Install
+
+```
+pip install demografix
+```
+
+The SDK has zero runtime dependencies. It requires Python 3.10 or newer.
+
+## Quickstart
+
+Construct a client, run a list of names through a batch call, read the predictions, and read the quota.
+
+```python
+from collections import Counter
+from demografix import Demografix
+
+client = Demografix(api_key="YOUR_API_KEY")
+
+names = ["michael", "matthew", "jane", "sofia", "lars"]
+
+batch = client.genderize_batch(names)
+
+split = Counter(r.gender or "unknown" for r in batch.results)
+print(split)                      # Counter({'male': 3, 'female': 2})
+print(batch.quota.remaining)      # 24987
+```
+
+## API keys
+
+An API key is required. Creating one is free and includes 2,500 requests per month. Generate a key in your
+dashboard at [genderize.io](https://genderize.io), [agify.io](https://agify.io), or
+[nationalize.io](https://nationalize.io). One key works across all three services.
+
+## Usage
+
+### Gender
+
+```python
+result = client.genderize("peter")
+result.gender          # "male", "female", or None
+result.probability     # 1.0
+result.count           # 1352696
+
+batch = client.genderize_batch(["michael", "matthew", "jane"])
+gender_mix = Counter(r.gender or "unknown" for r in batch.results)
+```
+
+### Age
+
+```python
+result = client.agify("michael")
+result.age             # 57 or None
+result.count           # 311558
+
+batch = client.agify_batch(["michael", "matthew", "jane"])
+ages = [r.age for r in batch.results if r.age is not None]
+average_age = sum(ages) / len(ages)
+```
+
+### Nationality
+
+```python
+result = client.nationalize("nguyen")
+result.country[0].country_id      # "VN"
+result.country[0].probability     # 0.891132
+
+batch = client.nationalize_batch(["nguyen", "schmidt", "rossi"])
+top_countries = Counter(
+    r.country[0].country_id for r in batch.results if r.country
+)
+```
+
+Each batch accepts at most 10 names. A batch of more than 10 raises `ValidationError` before any request
+goes out.
+
+## country_id
+
+`genderize` and `agify` accept an optional `country_id` (ISO 3166-1 alpha-2) to scope the prediction to one
+country. Input is case-insensitive; the response echoes it uppercase. `nationalize` has no such parameter.
+
+```python
+result = client.genderize("kim", country_id="us")
+result.country_id      # "US"
+
+batch = client.agify_batch(["michael", "matthew"], country_id="us")
+```
+
+## Quota
+
+Every result and every raised error carries a `quota` read from the response headers. Quota is never cached
+on the client; read it from the returned value.
+
+| Field | Meaning |
+|---|---|
+| `limit` | names allowed in the current window |
+| `remaining` | names left in the current window |
+| `reset` | seconds until the window resets |
+
+```python
+batch = client.genderize_batch(["michael", "matthew"])
+batch.quota.remaining
+```
+
+## Errors
+
+Non-2xx responses raise a typed exception. Transport failures raise `TransportError`. Every exception
+subclasses `DemografixError` and carries `status`, `message`, and `quota` (when the response included
+headers).
+
+| Exception | Status | Cause |
+|---|---|---|
+| `AuthError` | 401 | invalid or missing API key |
+| `SubscriptionError` | 402 | expired freebie or inactive subscription |
+| `ValidationError` | 422 | bad parameter, or a batch over 10 names (raised client-side) |
+| `RateLimitError` | 429 | window exhausted; `quota` is always populated |
+| `DemografixError` | other non-2xx | base class for the hierarchy |
+| `TransportError` | none | network error, timeout, or non-JSON body |
+
+A `RateLimitError` carries `quota`, so `reset` tells you how long to wait before retrying.
+
+```python
+import time
+from demografix import Demografix, RateLimitError
+
+client = Demografix(api_key="YOUR_API_KEY")
+names = ["michael", "matthew", "jane"]
+
+while True:
+    try:
+        batch = client.genderize_batch(names)
+        break
+    except RateLimitError as exc:
+        time.sleep(exc.quota.reset)
+```
+
+## Methods
+
+| Method | Returns | country_id |
+|---|---|---|
+| `genderize(name, country_id=None)` | `GenderizeResult` | yes |
+| `genderize_batch(names, country_id=None)` | `Batch` of `GenderizePrediction` | yes |
+| `agify(name, country_id=None)` | `AgifyResult` | yes |
+| `agify_batch(names, country_id=None)` | `Batch` of `AgifyPrediction` | yes |
+| `nationalize(name)` | `NationalizeResult` | no |
+| `nationalize_batch(names)` | `Batch` of `NationalizePrediction` | no |
+
+A `*Result` exposes the prediction fields directly plus a `quota`. A `Batch` exposes `results` plus one
+`quota` for the whole response.
+
+## Reference
+
+Full API reference: [genderize.io/documentation/api](https://genderize.io/documentation/api).

demografix-0.1.0/README.md

@@ -0,0 +1,158 @@
+# Demografix Python SDK
+
+Run demographic analysis over names — predicted gender, age, and nationality — from one client. The package
+covers [genderize.io](https://genderize.io), [agify.io](https://agify.io), and
+[nationalize.io](https://nationalize.io).
+
+## Install
+
+```
+pip install demografix
+```
+
+The SDK has zero runtime dependencies. It requires Python 3.10 or newer.
+
+## Quickstart
+
+Construct a client, run a list of names through a batch call, read the predictions, and read the quota.
+
+```python
+from collections import Counter
+from demografix import Demografix
+
+client = Demografix(api_key="YOUR_API_KEY")
+
+names = ["michael", "matthew", "jane", "sofia", "lars"]
+
+batch = client.genderize_batch(names)
+
+split = Counter(r.gender or "unknown" for r in batch.results)
+print(split)                      # Counter({'male': 3, 'female': 2})
+print(batch.quota.remaining)      # 24987
+```
+
+## API keys
+
+An API key is required. Creating one is free and includes 2,500 requests per month. Generate a key in your
+dashboard at [genderize.io](https://genderize.io), [agify.io](https://agify.io), or
+[nationalize.io](https://nationalize.io). One key works across all three services.
+
+## Usage
+
+### Gender
+
+```python
+result = client.genderize("peter")
+result.gender          # "male", "female", or None
+result.probability     # 1.0
+result.count           # 1352696
+
+batch = client.genderize_batch(["michael", "matthew", "jane"])
+gender_mix = Counter(r.gender or "unknown" for r in batch.results)
+```
+
+### Age
+
+```python
+result = client.agify("michael")
+result.age             # 57 or None
+result.count           # 311558
+
+batch = client.agify_batch(["michael", "matthew", "jane"])
+ages = [r.age for r in batch.results if r.age is not None]
+average_age = sum(ages) / len(ages)
+```
+
+### Nationality
+
+```python
+result = client.nationalize("nguyen")
+result.country[0].country_id      # "VN"
+result.country[0].probability     # 0.891132
+
+batch = client.nationalize_batch(["nguyen", "schmidt", "rossi"])
+top_countries = Counter(
+    r.country[0].country_id for r in batch.results if r.country
+)
+```
+
+Each batch accepts at most 10 names. A batch of more than 10 raises `ValidationError` before any request
+goes out.
+
+## country_id
+
+`genderize` and `agify` accept an optional `country_id` (ISO 3166-1 alpha-2) to scope the prediction to one
+country. Input is case-insensitive; the response echoes it uppercase. `nationalize` has no such parameter.
+
+```python
+result = client.genderize("kim", country_id="us")
+result.country_id      # "US"
+
+batch = client.agify_batch(["michael", "matthew"], country_id="us")
+```
+
+## Quota
+
+Every result and every raised error carries a `quota` read from the response headers. Quota is never cached
+on the client; read it from the returned value.
+
+| Field | Meaning |
+|---|---|
+| `limit` | names allowed in the current window |
+| `remaining` | names left in the current window |
+| `reset` | seconds until the window resets |
+
+```python
+batch = client.genderize_batch(["michael", "matthew"])
+batch.quota.remaining
+```
+
+## Errors
+
+Non-2xx responses raise a typed exception. Transport failures raise `TransportError`. Every exception
+subclasses `DemografixError` and carries `status`, `message`, and `quota` (when the response included
+headers).
+
+| Exception | Status | Cause |
+|---|---|---|
+| `AuthError` | 401 | invalid or missing API key |
+| `SubscriptionError` | 402 | expired freebie or inactive subscription |
+| `ValidationError` | 422 | bad parameter, or a batch over 10 names (raised client-side) |
+| `RateLimitError` | 429 | window exhausted; `quota` is always populated |
+| `DemografixError` | other non-2xx | base class for the hierarchy |
+| `TransportError` | none | network error, timeout, or non-JSON body |
+
+A `RateLimitError` carries `quota`, so `reset` tells you how long to wait before retrying.
+
+```python
+import time
+from demografix import Demografix, RateLimitError
+
+client = Demografix(api_key="YOUR_API_KEY")
+names = ["michael", "matthew", "jane"]
+
+while True:
+    try:
+        batch = client.genderize_batch(names)
+        break
+    except RateLimitError as exc:
+        time.sleep(exc.quota.reset)
+```
+
+## Methods
+
+| Method | Returns | country_id |
+|---|---|---|
+| `genderize(name, country_id=None)` | `GenderizeResult` | yes |
+| `genderize_batch(names, country_id=None)` | `Batch` of `GenderizePrediction` | yes |
+| `agify(name, country_id=None)` | `AgifyResult` | yes |
+| `agify_batch(names, country_id=None)` | `Batch` of `AgifyPrediction` | yes |
+| `nationalize(name)` | `NationalizeResult` | no |
+| `nationalize_batch(names)` | `Batch` of `NationalizePrediction` | no |
+
+A `*Result` exposes the prediction fields directly plus a `quota`. A `Batch` exposes `results` plus one
+`quota` for the whole response.
+
+## Reference
+
+Full API reference: [genderize.io/documentation/api](https://genderize.io/documentation/api).

demografix-0.1.0/RELEASING.md

@@ -0,0 +1,73 @@
+# Releasing
+
+This package publishes to PyPI through GitHub Actions. Publishing uses PyPI
+Trusted Publishing (OIDC), so there is no API token to store or rotate. The
+`release` workflow runs on any pushed tag that matches `v*.*.*`.
+
+## One-time setup
+
+Do this once, before the first release.
+
+### 1. Reserve the project name on PyPI
+
+The project name `demografix` must exist on PyPI, or be claimable by the
+account that registers the Trusted Publisher. Confirm the name is available at
+https://pypi.org/project/demografix/ before going further.
+
+### 2. Register the Trusted Publisher on PyPI
+
+In the PyPI project settings, under "Publishing", add a new GitHub trusted
+publisher with these exact values:
+
+- Owner: `DemografixGenderize`
+- Repository: `demografix-python`
+- Workflow name: `release.yml`
+- Environment: `release`
+
+If the project does not exist on PyPI yet, register the publisher as a
+"pending" publisher instead. PyPI creates the project on the first successful
+upload.
+
+### 3. Create the `release` environment in GitHub
+
+In the repository settings, under "Environments", create an environment named
+`release`. The publish job references this environment. Add required reviewers
+or branch restrictions here if you want a manual gate before any upload.
+
+No secrets are required. Trusted Publishing exchanges a short-lived OIDC token
+for the upload credential at publish time. Do not add a `PYPI_API_TOKEN` or any
+password.
+
+## Cutting a release
+
+1. Bump `version` in `pyproject.toml` to the new `X.Y.Z`.
+2. Commit the bump:
+
+   ```
+   git commit -am "Release vX.Y.Z"
+   ```
+
+3. Tag the commit. The tag must match the manifest version, with a `v` prefix:
+
+   ```
+   git tag vX.Y.Z
+   ```
+
+4. Push the commit and the tag:
+
+   ```
+   git push origin main
+   git push origin vX.Y.Z
+   ```
+
+Pushing the tag starts the `release` workflow. It verifies the tag matches the
+`pyproject.toml` version, builds the sdist and wheel, publishes to PyPI, and
+creates a GitHub Release with the built artifacts attached.
+
+## If a release fails
+
+- Tag/version mismatch: the build job stops before publishing. Delete the tag
+  (`git tag -d vX.Y.Z` and `git push origin :vX.Y.Z`), fix the version, and tag
+  again.
+- PyPI rejects the upload because the version already exists: bump to a new
+  version and tag again. PyPI does not allow re-uploading an existing version.

demografix-0.1.0/examples/demographics_summary.py

@@ -0,0 +1,81 @@
+"""Summarize the demographic mix of a list of names.
+
+Run a roster through all three services in batches of 10 and print an aggregate
+gender split, age distribution, and nationality mix across the whole list.
+
+Usage:
+    DEMOGRAFIX_API_KEY=your_key python examples/demographics_summary.py
+"""
+
+import os
+from collections import Counter
+
+from demografix import Demografix
+
+NAMES = [
+    "michael",
+    "matthew",
+    "jane",
+    "nguyen",
+    "kim",
+    "sofia",
+    "lars",
+    "amara",
+]
+
+
+def chunked(items, size):
+    for start in range(0, len(items), size):
+        yield items[start : start + size]
+
+
+def main():
+    api_key = os.environ.get("DEMOGRAFIX_API_KEY")
+    if not api_key:
+        raise SystemExit("Set DEMOGRAFIX_API_KEY to run this example.")
+    client = Demografix(api_key=api_key)
+
+    genders = Counter()
+    ages = []
+    countries = Counter()
+    remaining = None
+
+    for chunk in chunked(NAMES, 10):
+        g = client.genderize_batch(chunk)
+        a = client.agify_batch(chunk)
+        n = client.nationalize_batch(chunk)
+        remaining = n.quota.remaining
+
+        for prediction in g.results:
+            genders[prediction.gender or "unknown"] += 1
+        for prediction in a.results:
+            if prediction.age is not None:
+                ages.append(prediction.age)
+        for prediction in n.results:
+            if prediction.country:
+                countries[prediction.country[0].country_id] += 1
+
+    total = len(NAMES)
+    print("Names analyzed: %d" % total)
+
+    print("\nGender split:")
+    for gender, count in genders.most_common():
+        print("  %-8s %d (%.0f%%)" % (gender, count, 100 * count / total))
+
+    if ages:
+        print("\nAge distribution:")
+        print("  count   %d" % len(ages))
+        print("  min     %d" % min(ages))
+        print("  median  %d" % sorted(ages)[len(ages) // 2])
+        print("  max     %d" % max(ages))
+
+    print("\nTop nationality mix:")
+    for country_id, count in countries.most_common(5):
+        print("  %-4s %d" % (country_id, count))
+
+    if remaining is not None:
+        print("\nQuota remaining: %d" % remaining)
+
+
+if __name__ == "__main__":
+    main()

demografix-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "demografix"
+version = "0.1.0"
+description = "Official Python SDK for the Demografix APIs: genderize.io, agify.io, nationalize.io."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Demografix", email = "info@genderize.io" }]
+keywords = ["genderize", "agify", "nationalize", "demografix", "demographics"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://genderize.io"
+Documentation = "https://genderize.io/documentation/api"
+Repository = "https://github.com/DemografixGenderize/demografix-python"
+Issues = "https://github.com/DemografixGenderize/demografix-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/demografix"]
+# PEP 561: ship the py.typed marker so type checkers pick up the inline types.
+force-include = { "src/demografix/py.typed" = "demografix/py.typed" }