nominatim-reverse-client 0.1.0__tar.gz

nominatim_reverse_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jordan Harrison
+
+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.

nominatim_reverse_client-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: nominatim-reverse-client
+Version: 0.1.0
+Summary: Async reverse geocoding with a caller-owned session and explicit provider
+License-Expression: MIT
+Project-URL: Source, https://github.com/jouwdan/ha-pleos/tree/main/packages/nominatim-reverse-client
+Project-URL: Issues, https://github.com/jouwdan/ha-pleos/issues
+Project-URL: Changelog, https://github.com/jouwdan/ha-pleos/blob/main/packages/nominatim-reverse-client/CHANGELOG.md
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9.5
+Provides-Extra: dev
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: coverage>=7; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: ruff>=0.11; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Dynamic: license-file
+
+# nominatim-reverse-client
+
+An asynchronous Python client for reverse lookup with an explicitly selected Nominatim-compatible provider. It has no Home Assistant dependency and does not select a public provider, cache results, round coordinates, or start background requests.
+
+Requires Python 3.11 or later and a caller-owned `aiohttp.ClientSession`.
+
+Once the release gate below is complete, install the published distribution with `python -m pip install nominatim-reverse-client`.
+
+## Usage
+
+```python
+import aiohttp
+
+from nominatim_reverse_client import GeocodingError, NominatimClient
+
+
+async def lookup(service_url: str, latitude: float, longitude: float):
+    async with aiohttp.ClientSession() as session:
+        client = NominatimClient(
+            session,
+            service_url,
+            user_agent="MyApplication (https://example.com/contact)",
+        )
+        try:
+            address = await client.reverse(latitude, longitude)
+        except GeocodingError as error:
+            # error.code contains no provider URL, API key or coordinates.
+            return error.code
+        return address
+```
+
+`reverse()` returns `Address(display_name, attribution)`. The display name is stripped of surrounding whitespace but is otherwise unchanged. Attribution is taken from `attribution`, `licence`, or `license` in the provider's response. Display the attribution and follow the provider's usage and caching terms.
+
+Pass a base URL or the provider's `/reverse` endpoint. `reverse_url(value)` returns its normalized endpoint, or an empty string when it is missing or invalid. URLs must use HTTP or HTTPS and cannot contain login credentials, query parameters, or fragments. HTTPS protects coordinates and API keys in transit; HTTP is available for providers operated on a trusted local network.
+
+If the selected provider requires a key, pass `api_key="..."`; it is sent using the `key` query parameter. Every lookup also sends `lat`, `lon`, `format=json`, and `addressdetails=1`. Only valid numeric WGS84 coordinates are accepted. Requests use a ten-second timeout and never follow redirects or retry automatically. The client never closes the caller's session.
+
+The caller is responsible for obtaining consent before sending coordinates, choosing a provider, respecting its request limits, caching or rounding as appropriate, and protecting addresses in local history. This client logs nothing. Exceptions contain a code only; provider responses and underlying request exceptions are not included in their displayed traceback.
+
+## Errors
+
+`GeocodingError.code` is one of:
+
+- `service_url_missing`: no valid explicit endpoint was supplied.
+- `invalid_coordinates`: coordinates are missing, nonnumeric, nonfinite, or outside WGS84 bounds.
+- `http_<status>`: the provider returned a non-200 status, including redirects and rate limits.
+- `timeout` or `connection_error`: the request could not complete.
+- `invalid_json`, `invalid_response`, or `no_display_name`: the provider response could not supply an address.
+
+Cancellation propagates to the caller. Provider errors are not retried; callers decide when another request is appropriate.
+
+## Development
+
+From this package directory:
+
+```sh
+python -m pip install -e '.[dev]'
+python -m ruff check .
+python -m ruff format --check .
+python -m mypy
+python -m coverage run -m unittest discover -s tests -v
+python -m coverage report
+python -m build
+python -m twine check dist/*
+```
+
+Tests use synthetic responses and never contact a provider. The public `publish-geocoder.yml` workflow validates Python 3.11 and 3.14 and builds both a source distribution and wheel.
+
+## Release gate
+
+The distribution is maintained in this public repository independently of the Home Assistant integration and `pleos-client`. A package release must be published before an integration release pins it.
+
+Before the first publication, a maintainer must register or reserve the `nominatim-reverse-client` project on PyPI and configure a trusted publisher for repository `jouwdan/ha-pleos`, workflow `publish-geocoder.yml`, and environment `pypi-nominatim-reverse-client`. Configure that GitHub environment with required maintainer approval. This account setup cannot be provided by repository code.
+
+After checks and review, tag the approved commit `nominatim-reverse-client-v<version>` matching this package's `pyproject.toml`, then push that tag. The workflow checks the tag/version match, builds the distributions in public CI, and uses OIDC to publish those same artifacts after environment approval. Ordinary integration tags, branch pushes, pull requests, and manual workflow runs cannot publish this distribution. No PyPI token is stored in the repository.
+
+Do not create a GitHub Release for the package tag: GitHub Releases in this repository belong to the Home Assistant integration and are consumed by HACS. Package provenance is the namespaced Git tag and its public build/publish workflow run; package changes are recorded in `CHANGELOG.md`.
+
+Verify the published wheel and source distribution can be installed before publishing the dependent integration release. Provider credentials or live addresses are not required for release validation.
+
+Licensed under the MIT license.

nominatim_reverse_client-0.1.0/README.md

@@ -0,0 +1,81 @@
+# nominatim-reverse-client
+
+An asynchronous Python client for reverse lookup with an explicitly selected Nominatim-compatible provider. It has no Home Assistant dependency and does not select a public provider, cache results, round coordinates, or start background requests.
+
+Requires Python 3.11 or later and a caller-owned `aiohttp.ClientSession`.
+
+Once the release gate below is complete, install the published distribution with `python -m pip install nominatim-reverse-client`.
+
+## Usage
+
+```python
+import aiohttp
+
+from nominatim_reverse_client import GeocodingError, NominatimClient
+
+
+async def lookup(service_url: str, latitude: float, longitude: float):
+    async with aiohttp.ClientSession() as session:
+        client = NominatimClient(
+            session,
+            service_url,
+            user_agent="MyApplication (https://example.com/contact)",
+        )
+        try:
+            address = await client.reverse(latitude, longitude)
+        except GeocodingError as error:
+            # error.code contains no provider URL, API key or coordinates.
+            return error.code
+        return address
+```
+
+`reverse()` returns `Address(display_name, attribution)`. The display name is stripped of surrounding whitespace but is otherwise unchanged. Attribution is taken from `attribution`, `licence`, or `license` in the provider's response. Display the attribution and follow the provider's usage and caching terms.
+
+Pass a base URL or the provider's `/reverse` endpoint. `reverse_url(value)` returns its normalized endpoint, or an empty string when it is missing or invalid. URLs must use HTTP or HTTPS and cannot contain login credentials, query parameters, or fragments. HTTPS protects coordinates and API keys in transit; HTTP is available for providers operated on a trusted local network.
+
+If the selected provider requires a key, pass `api_key="..."`; it is sent using the `key` query parameter. Every lookup also sends `lat`, `lon`, `format=json`, and `addressdetails=1`. Only valid numeric WGS84 coordinates are accepted. Requests use a ten-second timeout and never follow redirects or retry automatically. The client never closes the caller's session.
+
+The caller is responsible for obtaining consent before sending coordinates, choosing a provider, respecting its request limits, caching or rounding as appropriate, and protecting addresses in local history. This client logs nothing. Exceptions contain a code only; provider responses and underlying request exceptions are not included in their displayed traceback.
+
+## Errors
+
+`GeocodingError.code` is one of:
+
+- `service_url_missing`: no valid explicit endpoint was supplied.
+- `invalid_coordinates`: coordinates are missing, nonnumeric, nonfinite, or outside WGS84 bounds.
+- `http_<status>`: the provider returned a non-200 status, including redirects and rate limits.
+- `timeout` or `connection_error`: the request could not complete.
+- `invalid_json`, `invalid_response`, or `no_display_name`: the provider response could not supply an address.
+
+Cancellation propagates to the caller. Provider errors are not retried; callers decide when another request is appropriate.
+
+## Development
+
+From this package directory:
+
+```sh
+python -m pip install -e '.[dev]'
+python -m ruff check .
+python -m ruff format --check .
+python -m mypy
+python -m coverage run -m unittest discover -s tests -v
+python -m coverage report
+python -m build
+python -m twine check dist/*
+```
+
+Tests use synthetic responses and never contact a provider. The public `publish-geocoder.yml` workflow validates Python 3.11 and 3.14 and builds both a source distribution and wheel.
+
+## Release gate
+
+The distribution is maintained in this public repository independently of the Home Assistant integration and `pleos-client`. A package release must be published before an integration release pins it.
+
+Before the first publication, a maintainer must register or reserve the `nominatim-reverse-client` project on PyPI and configure a trusted publisher for repository `jouwdan/ha-pleos`, workflow `publish-geocoder.yml`, and environment `pypi-nominatim-reverse-client`. Configure that GitHub environment with required maintainer approval. This account setup cannot be provided by repository code.
+
+After checks and review, tag the approved commit `nominatim-reverse-client-v<version>` matching this package's `pyproject.toml`, then push that tag. The workflow checks the tag/version match, builds the distributions in public CI, and uses OIDC to publish those same artifacts after environment approval. Ordinary integration tags, branch pushes, pull requests, and manual workflow runs cannot publish this distribution. No PyPI token is stored in the repository.
+
+Do not create a GitHub Release for the package tag: GitHub Releases in this repository belong to the Home Assistant integration and are consumed by HACS. Package provenance is the namespaced Git tag and its public build/publish workflow run; package changes are recorded in `CHANGELOG.md`.
+
+Verify the published wheel and source distribution can be installed before publishing the dependent integration release. Provider credentials or live addresses are not required for release validation.
+
+Licensed under the MIT license.

nominatim_reverse_client-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nominatim-reverse-client"
+version = "0.1.0"
+description = "Async reverse geocoding with a caller-owned session and explicit provider"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["aiohttp>=3.9.5"]
+classifiers = [
+  "Framework :: AsyncIO",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Source = "https://github.com/jouwdan/ha-pleos/tree/main/packages/nominatim-reverse-client"
+Issues = "https://github.com/jouwdan/ha-pleos/issues"
+Changelog = "https://github.com/jouwdan/ha-pleos/blob/main/packages/nominatim-reverse-client/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = ["build>=1", "coverage>=7", "mypy>=1.10", "ruff>=0.11", "twine>=6"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+nominatim_reverse_client = ["py.typed"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src"]
+
+[tool.coverage.run]
+branch = true
+source = ["nominatim_reverse_client"]
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 100
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]

nominatim_reverse_client-0.1.0/setup.cfg

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

nominatim_reverse_client-0.1.0/src/nominatim_reverse_client/__init__.py

@@ -0,0 +1,110 @@
+"""Nominatim-compatible reverse lookup without logging private request data."""
+
+from dataclasses import dataclass
+from math import isfinite
+from urllib.parse import urlparse
+
+from aiohttp import ClientError, ClientSession, ClientTimeout, ContentTypeError
+
+
+class GeocodingError(Exception):
+    """A provider failure with a public code and no request or response details."""
+
+    def __init__(self, code: str) -> None:
+        super().__init__(code)
+        self.code = code
+
+
+@dataclass(frozen=True)
+class Address:
+    """The provider's address and attribution, without Home Assistant state limits."""
+
+    display_name: str
+    attribution: str | None = None
+
+
+def reverse_url(value: str) -> str:
+    """Normalize an explicit provider URL, rejecting credentials and query data."""
+    if not isinstance(value, str) or not value.strip():
+        return ""
+    value = value.strip().rstrip("/")
+    try:
+        parsed = urlparse(value)
+        if (
+            parsed.scheme not in ("http", "https")
+            or not parsed.hostname
+            or parsed.username is not None
+            or parsed.password is not None
+            or "?" in value
+            or "#" in value
+        ):
+            return ""
+        parsed.port
+    except ValueError:
+        return ""
+    return value if parsed.path.endswith("/reverse") else value + "/reverse"
+
+
+class NominatimClient:
+    """Read an explicitly selected provider, never following redirects.
+
+    The caller owns the HTTP session, coordinate rounding, caching and polling.
+    No default provider is selected and no requests or private values are logged.
+    """
+
+    def __init__(
+        self, session: ClientSession, service_url: str, *, user_agent: str, api_key: str = ""
+    ) -> None:
+        self.session = session
+        self.service_url = reverse_url(service_url)
+        self.user_agent = user_agent
+        self.api_key = api_key.strip()
+
+    async def reverse(self, latitude: float, longitude: float) -> Address:
+        """Return the address or raise a sanitized provider error."""
+        if not self.service_url:
+            raise GeocodingError("service_url_missing")
+        if any(
+            isinstance(value, bool)
+            or not isinstance(value, (float, int))
+            or not -limit <= value <= limit
+            or not isfinite(value)
+            for value, limit in ((latitude, 90), (longitude, 180))
+        ):
+            raise GeocodingError("invalid_coordinates")
+        params: dict[str, str | float | int] = {
+            "lat": latitude,
+            "lon": longitude,
+            "format": "json",
+            "addressdetails": 1,
+        }
+        if self.api_key:
+            params["key"] = self.api_key
+        try:
+            async with self.session.get(
+                self.service_url,
+                params=params,
+                headers={"User-Agent": self.user_agent, "Accept": "application/json"},
+                timeout=ClientTimeout(total=10),
+                allow_redirects=False,
+            ) as response:
+                if response.status != 200:
+                    raise GeocodingError(f"http_{response.status}")
+                try:
+                    data = await response.json()
+                except (ContentTypeError, ValueError):
+                    raise GeocodingError("invalid_json") from None
+        except TimeoutError:
+            raise GeocodingError("timeout") from None
+        except ClientError:
+            raise GeocodingError("connection_error") from None
+        if not isinstance(data, dict):
+            raise GeocodingError("invalid_response")
+        display_name = data.get("display_name")
+        if not isinstance(display_name, str) or not display_name.strip():
+            raise GeocodingError("no_display_name")
+        attribution = data.get("attribution") or data.get("licence") or data.get("license")
+        return Address(
+            display_name.strip(),
+            attribution.strip() if isinstance(attribution, str) and attribution.strip() else None,
+        )

nominatim_reverse_client-0.1.0/src/nominatim_reverse_client.egg-info/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: nominatim-reverse-client
+Version: 0.1.0
+Summary: Async reverse geocoding with a caller-owned session and explicit provider
+License-Expression: MIT
+Project-URL: Source, https://github.com/jouwdan/ha-pleos/tree/main/packages/nominatim-reverse-client
+Project-URL: Issues, https://github.com/jouwdan/ha-pleos/issues
+Project-URL: Changelog, https://github.com/jouwdan/ha-pleos/blob/main/packages/nominatim-reverse-client/CHANGELOG.md
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9.5
+Provides-Extra: dev
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: coverage>=7; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: ruff>=0.11; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Dynamic: license-file
+
+# nominatim-reverse-client
+
+An asynchronous Python client for reverse lookup with an explicitly selected Nominatim-compatible provider. It has no Home Assistant dependency and does not select a public provider, cache results, round coordinates, or start background requests.
+
+Requires Python 3.11 or later and a caller-owned `aiohttp.ClientSession`.
+
+Once the release gate below is complete, install the published distribution with `python -m pip install nominatim-reverse-client`.
+
+## Usage
+
+```python
+import aiohttp
+
+from nominatim_reverse_client import GeocodingError, NominatimClient
+
+
+async def lookup(service_url: str, latitude: float, longitude: float):
+    async with aiohttp.ClientSession() as session:
+        client = NominatimClient(
+            session,
+            service_url,
+            user_agent="MyApplication (https://example.com/contact)",
+        )
+        try:
+            address = await client.reverse(latitude, longitude)
+        except GeocodingError as error:
+            # error.code contains no provider URL, API key or coordinates.
+            return error.code
+        return address
+```
+
+`reverse()` returns `Address(display_name, attribution)`. The display name is stripped of surrounding whitespace but is otherwise unchanged. Attribution is taken from `attribution`, `licence`, or `license` in the provider's response. Display the attribution and follow the provider's usage and caching terms.
+
+Pass a base URL or the provider's `/reverse` endpoint. `reverse_url(value)` returns its normalized endpoint, or an empty string when it is missing or invalid. URLs must use HTTP or HTTPS and cannot contain login credentials, query parameters, or fragments. HTTPS protects coordinates and API keys in transit; HTTP is available for providers operated on a trusted local network.
+
+If the selected provider requires a key, pass `api_key="..."`; it is sent using the `key` query parameter. Every lookup also sends `lat`, `lon`, `format=json`, and `addressdetails=1`. Only valid numeric WGS84 coordinates are accepted. Requests use a ten-second timeout and never follow redirects or retry automatically. The client never closes the caller's session.
+
+The caller is responsible for obtaining consent before sending coordinates, choosing a provider, respecting its request limits, caching or rounding as appropriate, and protecting addresses in local history. This client logs nothing. Exceptions contain a code only; provider responses and underlying request exceptions are not included in their displayed traceback.
+
+## Errors
+
+`GeocodingError.code` is one of:
+
+- `service_url_missing`: no valid explicit endpoint was supplied.
+- `invalid_coordinates`: coordinates are missing, nonnumeric, nonfinite, or outside WGS84 bounds.
+- `http_<status>`: the provider returned a non-200 status, including redirects and rate limits.
+- `timeout` or `connection_error`: the request could not complete.
+- `invalid_json`, `invalid_response`, or `no_display_name`: the provider response could not supply an address.
+
+Cancellation propagates to the caller. Provider errors are not retried; callers decide when another request is appropriate.
+
+## Development
+
+From this package directory:
+
+```sh
+python -m pip install -e '.[dev]'
+python -m ruff check .
+python -m ruff format --check .
+python -m mypy
+python -m coverage run -m unittest discover -s tests -v
+python -m coverage report
+python -m build
+python -m twine check dist/*
+```
+
+Tests use synthetic responses and never contact a provider. The public `publish-geocoder.yml` workflow validates Python 3.11 and 3.14 and builds both a source distribution and wheel.
+
+## Release gate
+
+The distribution is maintained in this public repository independently of the Home Assistant integration and `pleos-client`. A package release must be published before an integration release pins it.
+
+Before the first publication, a maintainer must register or reserve the `nominatim-reverse-client` project on PyPI and configure a trusted publisher for repository `jouwdan/ha-pleos`, workflow `publish-geocoder.yml`, and environment `pypi-nominatim-reverse-client`. Configure that GitHub environment with required maintainer approval. This account setup cannot be provided by repository code.
+
+After checks and review, tag the approved commit `nominatim-reverse-client-v<version>` matching this package's `pyproject.toml`, then push that tag. The workflow checks the tag/version match, builds the distributions in public CI, and uses OIDC to publish those same artifacts after environment approval. Ordinary integration tags, branch pushes, pull requests, and manual workflow runs cannot publish this distribution. No PyPI token is stored in the repository.
+
+Do not create a GitHub Release for the package tag: GitHub Releases in this repository belong to the Home Assistant integration and are consumed by HACS. Package provenance is the namespaced Git tag and its public build/publish workflow run; package changes are recorded in `CHANGELOG.md`.
+
+Verify the published wheel and source distribution can be installed before publishing the dependent integration release. Provider credentials or live addresses are not required for release validation.
+
+Licensed under the MIT license.

nominatim_reverse_client-0.1.0/src/nominatim_reverse_client.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/nominatim_reverse_client/__init__.py
+src/nominatim_reverse_client/py.typed
+src/nominatim_reverse_client.egg-info/PKG-INFO
+src/nominatim_reverse_client.egg-info/SOURCES.txt
+src/nominatim_reverse_client.egg-info/dependency_links.txt
+src/nominatim_reverse_client.egg-info/requires.txt
+src/nominatim_reverse_client.egg-info/top_level.txt
+tests/test_client.py

nominatim_reverse_client-0.1.0/src/nominatim_reverse_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nominatim_reverse_client-0.1.0/src/nominatim_reverse_client.egg-info/requires.txt

@@ -0,0 +1,8 @@
+aiohttp>=3.9.5
+
+[dev]
+build>=1
+coverage>=7
+mypy>=1.10
+ruff>=0.11
+twine>=6

nominatim_reverse_client-0.1.0/src/nominatim_reverse_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+nominatim_reverse_client

nominatim_reverse_client-0.1.0/tests/test_client.py

@@ -0,0 +1,205 @@
+"""Provider boundaries use synthetic responses and never contact a service."""
+
+import asyncio
+import traceback
+import unittest
+from unittest.mock import AsyncMock, MagicMock
+
+from aiohttp import ClientError, ContentTypeError
+
+from nominatim_reverse_client import Address, GeocodingError, NominatimClient, reverse_url
+
+
+class ReverseClientTests(unittest.IsolatedAsyncioTestCase):
+    def setUp(self):
+        self.session = MagicMock()
+        self.client = NominatimClient(
+            self.session, "https://geo.example/api", user_agent="SyntheticClient/1.0"
+        )
+
+    def response(self, payload, status=200):
+        response = MagicMock(status=status)
+        response.json = AsyncMock(return_value=payload)
+        self.session.get.return_value.__aenter__.return_value = response
+        return response
+
+    def test_valid_provider_urls_are_normalized(self):
+        for value, expected in (
+            ("  https://geo.example///  ", "https://geo.example/reverse"),
+            ("https://geo.example/api", "https://geo.example/api/reverse"),
+            ("https://geo.example/api/reverse/", "https://geo.example/api/reverse"),
+            ("http://127.0.0.1:8080", "http://127.0.0.1:8080/reverse"),
+            ("http://[::1]:8080", "http://[::1]:8080/reverse"),
+        ):
+            with self.subTest(value=value):
+                self.assertEqual(reverse_url(value), expected)
+
+    def test_unsafe_or_missing_urls_are_rejected(self):
+        for value in (
+            None,
+            12,
+            "",
+            "  ",
+            "ftp://geo.example",
+            "https://",
+            "https://[invalid",
+            "https://geo.example:invalid",
+            "https://geo.example:65536",
+            "https://user@geo.example",
+            "https://user:secret@geo.example",
+            "https://:secret@geo.example",
+            "https://geo.example?key=secret",
+            "https://geo.example/#secret",
+            "https://geo.example?",
+            "https://geo.example#",
+        ):
+            with self.subTest(value=value):
+                self.assertEqual(reverse_url(value), "")
+
+    async def test_no_provider_means_no_request(self):
+        self.client = NominatimClient(self.session, "", user_agent="SyntheticClient/1.0")
+        with self.assertRaises(GeocodingError) as caught:
+            await self.client.reverse(55.1, 10.1)
+        self.assertEqual(caught.exception.code, "service_url_missing")
+        self.session.get.assert_not_called()
+
+    async def test_lookup_preserves_address_and_caller_session(self):
+        address = "Synthetic Street, " * 30
+        self.response({"display_name": "  " + address + "  ", "licence": " Fixture licence "})
+        result = await self.client.reverse(55.1234, 10.4321)
+        self.assertEqual(result, Address(address.strip(), "Fixture licence"))
+        request = self.session.get.call_args
+        self.assertEqual(request.args, ("https://geo.example/api/reverse",))
+        self.assertEqual(
+            request.kwargs["params"],
+            {
+                "lat": 55.1234,
+                "lon": 10.4321,
+                "format": "json",
+                "addressdetails": 1,
+            },
+        )
+        self.assertEqual(
+            request.kwargs["headers"],
+            {
+                "User-Agent": "SyntheticClient/1.0",
+                "Accept": "application/json",
+            },
+        )
+        self.assertEqual(request.kwargs["timeout"].total, 10)
+        self.assertIs(request.kwargs["allow_redirects"], False)
+        self.session.close.assert_not_called()
+
+    async def test_explicit_api_key_is_trimmed_and_passed_only_in_query(self):
+        self.client = NominatimClient(
+            self.session, "https://geo.example", user_agent="Fixture", api_key=" fixture-key "
+        )
+        self.response({"display_name": "Fixture address"})
+        await self.client.reverse(0, 0)
+        request = self.session.get.call_args
+        self.assertEqual(request.kwargs["params"]["key"], "fixture-key")
+        self.assertNotIn("fixture-key", repr(request.args))
+        self.assertNotIn("fixture-key", repr(request.kwargs["headers"]))
+
+    async def test_attribution_keys_and_optional_values(self):
+        for attributes, expected in (
+            ({"attribution": " Provider ", "licence": "Other"}, "Provider"),
+            ({"licence": " Provider licence "}, "Provider licence"),
+            ({"license": " Provider license "}, "Provider license"),
+            ({"attribution": "", "licence": "Fallback"}, "Fallback"),
+            ({"attribution": " "}, None),
+            ({"attribution": 123}, None),
+            ({}, None),
+        ):
+            with self.subTest(attributes=attributes):
+                self.response({"display_name": "Fixture", **attributes})
+                self.assertEqual((await self.client.reverse(0, 0)).attribution, expected)
+
+    async def test_coordinate_boundaries_are_valid(self):
+        self.response({"display_name": "Fixture"})
+        for coordinates in ((-90, -180), (90, 180), (0, 0)):
+            with self.subTest(coordinates=coordinates):
+                self.assertEqual(await self.client.reverse(*coordinates), Address("Fixture"))
+
+    async def test_invalid_coordinates_never_leave_the_process(self):
+        for coordinates in (
+            (None, 0),
+            ("55.1", 0),
+            (False, 0),
+            (0, True),
+            ([], 0),
+            (float("nan"), 0),
+            (0, float("inf")),
+            (float("-inf"), 0),
+            (-90.1, 0),
+            (90.1, 0),
+            (0, -180.1),
+            (0, 180.1),
+            (10**1000, 0),
+        ):
+            with self.subTest(coordinates=coordinates):
+                with self.assertRaises(GeocodingError) as caught:
+                    await self.client.reverse(*coordinates)
+                self.assertEqual(caught.exception.code, "invalid_coordinates")
+        self.session.get.assert_not_called()
+
+    async def test_non_200_responses_never_parse_body_or_retry(self):
+        for status in (301, 302, 401, 403, 429, 500):
+            with self.subTest(status=status):
+                self.session.get.reset_mock()
+                response = self.response({"private": "fixture-secret"}, status)
+                with self.assertRaises(GeocodingError) as caught:
+                    await self.client.reverse(55.1, 10.1)
+                self.assertEqual(str(caught.exception), f"http_{status}")
+                self.session.get.assert_called_once()
+                response.json.assert_not_awaited()
+
+    async def test_request_errors_are_sanitized_and_not_logged(self):
+        secret = "https://geo.example?key=fixture-secret&lat=55.123"
+        for error, code in (
+            (TimeoutError(secret), "timeout"),
+            (ClientError(secret), "connection_error"),
+        ):
+            with self.subTest(code=code):
+                self.session.get.side_effect = error
+                with self.assertNoLogs("nominatim_reverse_client", level="DEBUG"):
+                    with self.assertRaises(GeocodingError) as caught:
+                        await self.client.reverse(55.123, 10.1)
+                self.assertEqual(caught.exception.code, code)
+                rendered = "".join(traceback.format_exception(caught.exception))
+                self.assertNotIn(secret, rendered)
+                self.assertNotIn("fixture-secret", rendered)
+                self.assertTrue(caught.exception.__suppress_context__)
+
+    async def test_invalid_json_and_content_type_are_sanitized(self):
+        for error in (
+            ValueError("fixture-private-body"),
+            ContentTypeError(request_info=MagicMock(), history=(), message="fixture-private-body"),
+        ):
+            with self.subTest(error=type(error).__name__):
+                self.response({}).json.side_effect = error
+                with self.assertRaises(GeocodingError) as caught:
+                    await self.client.reverse(55.1, 10.1)
+                self.assertEqual(str(caught.exception), "invalid_json")
+                self.assertTrue(caught.exception.__suppress_context__)
+
+    async def test_missing_or_malformed_address_is_not_returned(self):
+        for payload, code in (
+            (None, "invalid_response"),
+            ([], "invalid_response"),
+            ({}, "no_display_name"),
+            ({"display_name": 123}, "no_display_name"),
+            ({"display_name": "  "}, "no_display_name"),
+            ({"error": "fixture-private-error"}, "no_display_name"),
+        ):
+            with self.subTest(payload=payload):
+                self.response(payload)
+                with self.assertRaises(GeocodingError) as caught:
+                    await self.client.reverse(55.1, 10.1)
+                self.assertEqual(str(caught.exception), code)
+
+    async def test_cancellation_propagates(self):
+        self.session.get.side_effect = asyncio.CancelledError()
+        with self.assertRaises(asyncio.CancelledError):
+            await self.client.reverse(55.1, 10.1)
+        self.session.get.assert_called_once()