namegender-client 0.3.0__tar.gz

namegender_client-0.3.0/LICENSE

@@ -0,0 +1 @@
+MIT License. Copyright (c) 2026 NameGender. Permission is granted to use, copy, modify, merge, publish, distribute, sublicense, and/or sell this Software, provided this notice is included. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

namegender_client-0.3.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: namegender-client
+Version: 0.3.0
+Summary: Official Python client for the NameGender API
+Author-email: NameGender <support@namegender.com>
+License-Expression: MIT
+Project-URL: Homepage, https://namegender.com
+Project-URL: Documentation, https://namegender.com/docs
+Project-URL: Repository, https://github.com/anpekesen/namegender-python
+Project-URL: Issues, https://github.com/anpekesen/namegender-python/issues
+Keywords: gender,name,api,namegender
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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 :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# NameGender Python
+
+```sh
+pip install namegender-client
+```
+
+```python
+from namegender import NameGender
+client = NameGender("YOUR_API_KEY")
+result = client.name("Ayşe", country="TR")
+print(result["gender"], result["probability"], result["sample_size"], result["confidence"])
+```
+
+## Options and response
+
+`name`, `email`, `username` and `bulk` accept `country`, `ai_fallback` and
+`best_guess` as keyword arguments:
+
+```python
+result = client.name("Andrea", country="IT", best_guess=True)
+```
+
+A result carries `query`, `name`, `gender`, `country`, `probability`,
+`sample_size`, `took_ms`, `source`, `confidence` and `matched_as`, alongside
+`credits_charged`, `credits_remaining`, `data_version` and `request_id`.
+Success is the HTTP status: any non-2xx response raises `NameGenderError`
+with `status` and `body` (`{"error", "message", "request_id", "docs"}`).
+Branch on `body["error"]`, not on the message.
+
+## Country distribution
+
+Returns the countries a name is recorded in. This is not a country-of-origin or
+ethnicity inference, and must not be used as one.
+
+```python
+result = client.countries("Mehmet", limit=10)
+print(result["registrations"])  # [{"country": "FR", "count": 3775, "share": 58.97, "gender": "male", "probability": 99, "source": "insee"}, ...]
+print(result["attested_in"])    # ["AL", "AU", "BE", ..., "TR", "US"]
+print(result["basis"]["note"])
+```
+
+The two lists are deliberately kept apart. `registrations` is measured volume and
+is comparable only among the seven countries that publish counted birth
+statistics (US, UK, France, Canada, Spain, Ireland, Norway); `share` is a
+percentage across those counts alone. `attested_in` is presence with no weight
+attached, which is where countries that publish no counts, such as Turkey, Japan
+and India, appear. Show `basis["note"]` next to any percentage you display.
+
+`limit` (1–100, default 25) caps how many counted countries come back in
+`registrations`. One credit per request.

namegender_client-0.3.0/README.md

@@ -0,0 +1,50 @@
+# NameGender Python
+
+```sh
+pip install namegender-client
+```
+
+```python
+from namegender import NameGender
+client = NameGender("YOUR_API_KEY")
+result = client.name("Ayşe", country="TR")
+print(result["gender"], result["probability"], result["sample_size"], result["confidence"])
+```
+
+## Options and response
+
+`name`, `email`, `username` and `bulk` accept `country`, `ai_fallback` and
+`best_guess` as keyword arguments:
+
+```python
+result = client.name("Andrea", country="IT", best_guess=True)
+```
+
+A result carries `query`, `name`, `gender`, `country`, `probability`,
+`sample_size`, `took_ms`, `source`, `confidence` and `matched_as`, alongside
+`credits_charged`, `credits_remaining`, `data_version` and `request_id`.
+Success is the HTTP status: any non-2xx response raises `NameGenderError`
+with `status` and `body` (`{"error", "message", "request_id", "docs"}`).
+Branch on `body["error"]`, not on the message.
+
+## Country distribution
+
+Returns the countries a name is recorded in. This is not a country-of-origin or
+ethnicity inference, and must not be used as one.
+
+```python
+result = client.countries("Mehmet", limit=10)
+print(result["registrations"])  # [{"country": "FR", "count": 3775, "share": 58.97, "gender": "male", "probability": 99, "source": "insee"}, ...]
+print(result["attested_in"])    # ["AL", "AU", "BE", ..., "TR", "US"]
+print(result["basis"]["note"])
+```
+
+The two lists are deliberately kept apart. `registrations` is measured volume and
+is comparable only among the seven countries that publish counted birth
+statistics (US, UK, France, Canada, Spain, Ireland, Norway); `share` is a
+percentage across those counts alone. `attested_in` is presence with no weight
+attached, which is where countries that publish no counts, such as Turkey, Japan
+and India, appear. Show `basis["note"]` next to any percentage you display.
+
+`limit` (1–100, default 25) caps how many counted countries come back in
+`registrations`. One credit per request.

namegender_client-0.3.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "namegender-client"
+version = "0.3.0"
+description = "Official Python client for the NameGender API"
+requires-python = ">=3.9"
+readme = "README.md"
+license = "MIT"
+authors = [{name = "NameGender", email = "support@namegender.com"}]
+keywords = ["gender", "name", "api", "namegender"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "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"
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://namegender.com"
+Documentation = "https://namegender.com/docs"
+Repository = "https://github.com/anpekesen/namegender-python"
+Issues = "https://github.com/anpekesen/namegender-python/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

namegender_client-0.3.0/setup.cfg

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

namegender_client-0.3.0/src/namegender/__init__.py

@@ -0,0 +1,3 @@
+from .client import NameGender, NameGenderError
+
+__all__ = ["NameGender", "NameGenderError"]

namegender_client-0.3.0/src/namegender/client.py

@@ -0,0 +1,71 @@
+import json
+from urllib.error import HTTPError
+from urllib.request import Request, urlopen
+
+
+class NameGenderError(RuntimeError):
+    def __init__(self, message, status=0, body=None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+class NameGender:
+    def __init__(self, api_key, base_url="https://namegender.com/api/v1", timeout=30):
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    # ``options`` are sent as-is: ``ai_fallback=True`` falls back to a language
+    # model for names not in the database (needs AI consent on the account),
+    # ``best_guess=True`` returns the most likely gender even below the
+    # probability threshold. A successful response is any 2xx status; anything
+    # else raises NameGenderError.
+
+    def name(self, name, country=None, **options):
+        return self._post("/gender", self._payload(name=name, country=country, **options))
+
+    def email(self, email, country=None, **options):
+        return self._post("/gender/email", self._payload(email=email, country=country, **options))
+
+    def username(self, username, country=None, **options):
+        return self._post("/gender/username", self._payload(username=username, country=country, **options))
+
+    def bulk(self, names, country=None, type="name", **options):
+        return self._post("/gender/bulk", self._payload(names=list(names), country=country, type=type, **options))
+
+    def countries(self, name, limit=None):
+        """Country distribution of a name. Not a country-of-origin or ethnicity inference.
+
+        ``registrations`` is counted volume, comparable only among countries that publish
+        counted birth statistics; ``attested_in`` is presence with no weight attached.
+        """
+        return self._post("/gender/countries", self._payload(name=name, limit=limit))
+
+    def account(self):
+        return self._request("GET", "/me")
+
+    @staticmethod
+    def _payload(**values):
+        return {key: value for key, value in values.items() if value is not None}
+
+    def _post(self, path, body):
+        return self._request("POST", path, body)
+
+    def _request(self, method, path, body=None):
+        data = json.dumps(body).encode() if body is not None else None
+        request = Request(self.base_url + path, data=data, method=method, headers={
+            "Accept": "application/json", "Content-Type": "application/json",
+            "Authorization": f"Bearer {self.api_key}",
+        })
+        try:
+            with urlopen(request, timeout=self.timeout) as response:
+                return json.loads(response.read())
+        except HTTPError as error:
+            try:
+                payload = json.loads(error.read())
+            except Exception:
+                payload = None
+            raise NameGenderError((payload or {}).get("message", str(error)), error.code, payload) from error

namegender_client-0.3.0/src/namegender_client.egg-info/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: namegender-client
+Version: 0.3.0
+Summary: Official Python client for the NameGender API
+Author-email: NameGender <support@namegender.com>
+License-Expression: MIT
+Project-URL: Homepage, https://namegender.com
+Project-URL: Documentation, https://namegender.com/docs
+Project-URL: Repository, https://github.com/anpekesen/namegender-python
+Project-URL: Issues, https://github.com/anpekesen/namegender-python/issues
+Keywords: gender,name,api,namegender
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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 :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# NameGender Python
+
+```sh
+pip install namegender-client
+```
+
+```python
+from namegender import NameGender
+client = NameGender("YOUR_API_KEY")
+result = client.name("Ayşe", country="TR")
+print(result["gender"], result["probability"], result["sample_size"], result["confidence"])
+```
+
+## Options and response
+
+`name`, `email`, `username` and `bulk` accept `country`, `ai_fallback` and
+`best_guess` as keyword arguments:
+
+```python
+result = client.name("Andrea", country="IT", best_guess=True)
+```
+
+A result carries `query`, `name`, `gender`, `country`, `probability`,
+`sample_size`, `took_ms`, `source`, `confidence` and `matched_as`, alongside
+`credits_charged`, `credits_remaining`, `data_version` and `request_id`.
+Success is the HTTP status: any non-2xx response raises `NameGenderError`
+with `status` and `body` (`{"error", "message", "request_id", "docs"}`).
+Branch on `body["error"]`, not on the message.
+
+## Country distribution
+
+Returns the countries a name is recorded in. This is not a country-of-origin or
+ethnicity inference, and must not be used as one.
+
+```python
+result = client.countries("Mehmet", limit=10)
+print(result["registrations"])  # [{"country": "FR", "count": 3775, "share": 58.97, "gender": "male", "probability": 99, "source": "insee"}, ...]
+print(result["attested_in"])    # ["AL", "AU", "BE", ..., "TR", "US"]
+print(result["basis"]["note"])
+```
+
+The two lists are deliberately kept apart. `registrations` is measured volume and
+is comparable only among the seven countries that publish counted birth
+statistics (US, UK, France, Canada, Spain, Ireland, Norway); `share` is a
+percentage across those counts alone. `attested_in` is presence with no weight
+attached, which is where countries that publish no counts, such as Turkey, Japan
+and India, appear. Show `basis["note"]` next to any percentage you display.
+
+`limit` (1–100, default 25) caps how many counted countries come back in
+`registrations`. One credit per request.

namegender_client-0.3.0/src/namegender_client.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+src/namegender/__init__.py
+src/namegender/client.py
+src/namegender_client.egg-info/PKG-INFO
+src/namegender_client.egg-info/SOURCES.txt
+src/namegender_client.egg-info/dependency_links.txt
+src/namegender_client.egg-info/top_level.txt
+tests/test_client.py

namegender_client-0.3.0/src/namegender_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

namegender_client-0.3.0/src/namegender_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+namegender

namegender_client-0.3.0/tests/test_client.py

@@ -0,0 +1,48 @@
+import io
+import json
+import unittest
+from urllib.error import HTTPError
+from unittest.mock import patch
+from namegender import NameGender, NameGenderError
+
+
+class ClientTest(unittest.TestCase):
+    @patch("namegender.client.urlopen")
+    def test_name(self, urlopen):
+        response = urlopen.return_value.__enter__.return_value
+        response.read.return_value = b'{"gender":"female"}'
+        result = NameGender("secret").name("Ayse", country="TR")
+        self.assertEqual(result["gender"], "female")
+        request = urlopen.call_args.args[0]
+        self.assertEqual(request.headers["Authorization"], "Bearer secret")
+
+    @patch("namegender.client.urlopen")
+    def test_countries(self, urlopen):
+        response = urlopen.return_value.__enter__.return_value
+        response.read.return_value = b'{"name":"Mehmet","registrations":[{"country":"FR","share":58.97}],"attested_in":["FR","TR"]}'
+        result = NameGender("secret").countries("Mehmet", limit=10)
+        self.assertEqual(result["attested_in"], ["FR", "TR"])
+        request = urlopen.call_args.args[0]
+        self.assertEqual(request.full_url, "https://namegender.com/api/v1/gender/countries")
+        self.assertEqual(request.get_method(), "POST")
+        self.assertEqual(request.headers["Authorization"], "Bearer secret")
+        self.assertEqual(json.loads(request.data), {"name": "Mehmet", "limit": 10})
+
+    @patch("namegender.client.urlopen")
+    def test_options_use_namegender_names(self, urlopen):
+        response = urlopen.return_value.__enter__.return_value
+        response.read.return_value = b'{"query":"Andrea","gender":"male","sample_size":120,"took_ms":3}'
+        result = NameGender("secret").name("Andrea", country="IT", ai_fallback=True, best_guess=True)
+        self.assertEqual(result["sample_size"], 120)
+        request = urlopen.call_args.args[0]
+        self.assertEqual(request.full_url, "https://namegender.com/api/v1/gender")
+        self.assertEqual(json.loads(request.data), {"name": "Andrea", "country": "IT", "ai_fallback": True, "best_guess": True})
+
+    @patch("namegender.client.urlopen")
+    def test_error_status_raises(self, urlopen):
+        body = b'{"error":"no_credits","message":"Out of credits.","request_id":"req_1","docs":"https://namegender.com/docs"}'
+        urlopen.side_effect = HTTPError("https://namegender.com/api/v1/me", 402, "Payment Required", {}, io.BytesIO(body))
+        with self.assertRaises(NameGenderError) as caught:
+            NameGender("secret").account()
+        self.assertEqual(caught.exception.status, 402)
+        self.assertEqual(caught.exception.body["error"], "no_credits")