locio 0.1.0__tar.gz

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

@@ -0,0 +1,21 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      # No install step: the library has no dependencies and the suite runs
+      # on stdlib unittest, so this is the real "does it work from scratch".
+      - run: PYTHONPATH=src python -m unittest discover -s tests -v

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

@@ -0,0 +1,25 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+# Trusted publishing: PyPI verifies this workflow's identity, so there is no
+# long lived API token in the repository to leak. Configure the publisher at
+# pypi.org/manage/project/locio/settings/publishing/ before the first tag.
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: PYTHONPATH=src python -m unittest discover -s tests
+      - run: pip install build && python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

locio-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+.venv/

locio-0.1.0/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0
+
+First release. Search, get, resolve and similar against the Locio address API,
+with no dependencies.

locio-0.1.0/LICENSE

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

locio-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.5
+Name: locio
+Version: 0.1.0
+Summary: Australian address autocomplete, validation and geocoding from G-NAF
+Project-URL: Homepage, https://locio.com.au
+Project-URL: Documentation, https://locio.com.au/docs/
+Project-URL: Source, https://github.com/locio-au/locio-python
+Project-URL: Changelog, https://github.com/locio-au/locio-python/blob/main/CHANGELOG.md
+Author: Locio
+License: MIT License
+        
+        Copyright (c) 2026 Locio
+        
+        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.
+License-File: LICENSE
+Keywords: address autocomplete,address geocoding,address validation,address validation service,australia,australian address api,g-naf,geocoding,gnaf,postcode
+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.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 :: Scientific/Engineering :: GIS
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# locio
+
+**Australian address validation, address autocomplete and address geocoding**
+in Python, from G-NAF, the national address register.
+
+One call gives you a stable G-NAF id, a coordinate, an ABS mesh block and the
+address split into fields. Comparable services bill validate, geocode and
+meshblock separately; here they are fields of one response.
+
+No dependencies. Python 3.9+.
+
+```sh
+pip install locio
+```
+
+## Address validation
+
+`resolve` takes an address however you hold it and tells you whether it is
+real, where it is, and what it is made of.
+
+```python
+from locio import Locio
+
+locio = Locio("lc_live_...")
+
+result = locio.resolve("1 george st sydenham nsw 2044")
+
+if result.matched:
+    a = result.address
+    print(a.formatted)               # 1 George Street, Sydenham NSW 2044
+    print(a.address_detail_pid)      # store this, not the text
+    print(a.lat, a.lng)              # geocoded
+    print(a.mesh_block)              # ABS mesh block
+    print(a.components.postcode)     # parsed
+```
+
+`matched` is `False` for an address that is not in G-NAF. That is an ordinary
+answer, not an error, and it is what a validation call is asking. `Resolution`
+is falsy when nothing matched, so this reads the way you want:
+
+```python
+if not locio.resolve(typed):
+    ...  # ask the customer to check it
+```
+
+## Cleaning a spreadsheet
+
+The commonest thing this library gets asked to do. `to_dict()` flattens a
+record to one level so it goes straight into a `DictWriter`.
+
+```python
+import csv
+from locio import Locio
+
+locio = Locio("lc_live_...")
+
+with open("customers.csv") as f, open("clean.csv", "w", newline="") as out:
+    rows = list(csv.DictReader(f))
+    writer = None
+
+    for row in rows:
+        result = locio.resolve(row["address"])
+        clean = result.address.to_dict() if result.matched else {}
+        record = {**row, **clean, "matched": result.matched}
+
+        if writer is None:
+            writer = csv.DictWriter(out, fieldnames=list(record))
+            writer.writeheader()
+        writer.writerow(record)
+```
+
+`resolve_many` does the same sequentially, which is deliberate: the quota is
+per key, and firing a thousand requests at once is how a free tier is spent in
+a second.
+
+## Address autocomplete
+
+```python
+for a in locio.search("104/119 turner", limit=8):
+    print(a.formatted, a.address_detail_pid)
+```
+
+For a browser autocomplete use [`@locio-au/react`](https://www.npmjs.com/package/@locio-au/react)
+or [`@locio-au/vue`](https://www.npmjs.com/package/@locio-au/vue) with a **public**
+key. This library takes a secret key, and a secret key must never reach a page.
+
+## Correcting a typo
+
+```python
+if not (result := locio.resolve(typed)):
+    for near in locio.similar(typed, limit=5):
+        print(near.formatted)
+```
+
+Three units, because it scores rows by similarity rather than seeking an
+index. Call it once on an address that failed to resolve, never per keystroke.
+
+## Reading an id back
+
+```python
+from locio import NotFound
+
+try:
+    a = locio.get("GAVIC425624910")
+except NotFound:
+    ...  # G-NAF retires ids between releases; search for it again
+```
+
+## Two ids, and which to store
+
+A record can carry two pids and they mean different things:
+
+| Attribute | Means |
+|---|---|
+| `address_detail_pid` | **This address.** The one to store. |
+| `gnaf.primary_pid` | The **parcel** it sits on, when this row is a unit. |
+
+`address.is_unit` reports which you have. Storing the primary pid stores the
+building rather than the door, and nothing about the value itself says so.
+
+## Errors
+
+```python
+from locio import LocioError, NotFound, AuthError
+
+try:
+    locio.search("90 bay road")
+except AuthError as err:
+    print(err.status, err.title, err.detail)
+```
+
+The API writes refusals for a person to read and they are carried through,
+because the detail is the part that says what to do.
+
+## Keys and safety
+
+Secret keys (`lc_live_...`) belong on a server. Get one at
+[locio.com.au/account/api](https://locio.com.au/account/api).
+
+The client refuses a plaintext `http://` base URL to any host but loopback: a
+bearer key sent in the clear is a key given away.
+
+## What it costs
+
+`search`, `resolve` and `get` are one unit each, `similar` is three. See
+[locio.com.au/pricing](https://locio.com.au/pricing/).
+
+## Licence
+
+MIT. Address data is G-NAF, published by Geoscape Australia under CC BY 4.0;
+attribution belongs wherever you show it.

locio-0.1.0/README.md

@@ -0,0 +1,151 @@
+# locio
+
+**Australian address validation, address autocomplete and address geocoding**
+in Python, from G-NAF, the national address register.
+
+One call gives you a stable G-NAF id, a coordinate, an ABS mesh block and the
+address split into fields. Comparable services bill validate, geocode and
+meshblock separately; here they are fields of one response.
+
+No dependencies. Python 3.9+.
+
+```sh
+pip install locio
+```
+
+## Address validation
+
+`resolve` takes an address however you hold it and tells you whether it is
+real, where it is, and what it is made of.
+
+```python
+from locio import Locio
+
+locio = Locio("lc_live_...")
+
+result = locio.resolve("1 george st sydenham nsw 2044")
+
+if result.matched:
+    a = result.address
+    print(a.formatted)               # 1 George Street, Sydenham NSW 2044
+    print(a.address_detail_pid)      # store this, not the text
+    print(a.lat, a.lng)              # geocoded
+    print(a.mesh_block)              # ABS mesh block
+    print(a.components.postcode)     # parsed
+```
+
+`matched` is `False` for an address that is not in G-NAF. That is an ordinary
+answer, not an error, and it is what a validation call is asking. `Resolution`
+is falsy when nothing matched, so this reads the way you want:
+
+```python
+if not locio.resolve(typed):
+    ...  # ask the customer to check it
+```
+
+## Cleaning a spreadsheet
+
+The commonest thing this library gets asked to do. `to_dict()` flattens a
+record to one level so it goes straight into a `DictWriter`.
+
+```python
+import csv
+from locio import Locio
+
+locio = Locio("lc_live_...")
+
+with open("customers.csv") as f, open("clean.csv", "w", newline="") as out:
+    rows = list(csv.DictReader(f))
+    writer = None
+
+    for row in rows:
+        result = locio.resolve(row["address"])
+        clean = result.address.to_dict() if result.matched else {}
+        record = {**row, **clean, "matched": result.matched}
+
+        if writer is None:
+            writer = csv.DictWriter(out, fieldnames=list(record))
+            writer.writeheader()
+        writer.writerow(record)
+```
+
+`resolve_many` does the same sequentially, which is deliberate: the quota is
+per key, and firing a thousand requests at once is how a free tier is spent in
+a second.
+
+## Address autocomplete
+
+```python
+for a in locio.search("104/119 turner", limit=8):
+    print(a.formatted, a.address_detail_pid)
+```
+
+For a browser autocomplete use [`@locio-au/react`](https://www.npmjs.com/package/@locio-au/react)
+or [`@locio-au/vue`](https://www.npmjs.com/package/@locio-au/vue) with a **public**
+key. This library takes a secret key, and a secret key must never reach a page.
+
+## Correcting a typo
+
+```python
+if not (result := locio.resolve(typed)):
+    for near in locio.similar(typed, limit=5):
+        print(near.formatted)
+```
+
+Three units, because it scores rows by similarity rather than seeking an
+index. Call it once on an address that failed to resolve, never per keystroke.
+
+## Reading an id back
+
+```python
+from locio import NotFound
+
+try:
+    a = locio.get("GAVIC425624910")
+except NotFound:
+    ...  # G-NAF retires ids between releases; search for it again
+```
+
+## Two ids, and which to store
+
+A record can carry two pids and they mean different things:
+
+| Attribute | Means |
+|---|---|
+| `address_detail_pid` | **This address.** The one to store. |
+| `gnaf.primary_pid` | The **parcel** it sits on, when this row is a unit. |
+
+`address.is_unit` reports which you have. Storing the primary pid stores the
+building rather than the door, and nothing about the value itself says so.
+
+## Errors
+
+```python
+from locio import LocioError, NotFound, AuthError
+
+try:
+    locio.search("90 bay road")
+except AuthError as err:
+    print(err.status, err.title, err.detail)
+```
+
+The API writes refusals for a person to read and they are carried through,
+because the detail is the part that says what to do.
+
+## Keys and safety
+
+Secret keys (`lc_live_...`) belong on a server. Get one at
+[locio.com.au/account/api](https://locio.com.au/account/api).
+
+The client refuses a plaintext `http://` base URL to any host but loopback: a
+bearer key sent in the clear is a key given away.
+
+## What it costs
+
+`search`, `resolve` and `get` are one unit each, `similar` is three. See
+[locio.com.au/pricing](https://locio.com.au/pricing/).
+
+## Licence
+
+MIT. Address data is G-NAF, published by Geoscape Australia under CC BY 4.0;
+attribution belongs wherever you show it.

locio-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "locio"
+version = "0.1.0"
+description = "Australian address autocomplete, validation and geocoding from G-NAF"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [{ name = "Locio" }]
+keywords = [
+  "address validation",
+  "address autocomplete",
+  "address geocoding",
+  "address validation service",
+  "australian address api",
+  "gnaf",
+  "g-naf",
+  "geocoding",
+  "australia",
+  "postcode",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "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 :: Scientific/Engineering :: GIS",
+  "Typing :: Typed",
+]
+# No dependencies, on purpose. The whole client is one urllib call and a
+# dataclass; asking for requests would make this the heaviest thing in
+# somebody's lambda for no gain.
+dependencies = []
+
+[project.urls]
+Homepage = "https://locio.com.au"
+Documentation = "https://locio.com.au/docs/"
+Source = "https://github.com/locio-au/locio-python"
+Changelog = "https://github.com/locio-au/locio-python/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/locio"]

locio-0.1.0/src/locio/__init__.py

@@ -0,0 +1,36 @@
+"""Locio: Australian address autocomplete, validation and geocoding.
+
+Resolve an Australian address to a stable G-NAF id, a coordinate, an ABS mesh
+block and structured components, from the national address register.
+
+    from locio import Locio
+
+    locio = Locio("lc_live_...")
+
+    result = locio.resolve("1 george st sydenham nsw 2044")
+    if result.matched:
+        print(result.address.formatted)
+        print(result.address.address_detail_pid)  # store this, not the text
+        print(result.address.lat, result.address.lng)
+
+Keys: this library takes a **secret** key and belongs on a server. For browser
+code use a public key with an origin allow list, through ``@locio-au/react`` or
+``@locio-au/vue``.
+"""
+
+from ._client import DEFAULT_BASE_URL, Locio, __version__
+from ._errors import AuthError, LocioError, NotFound
+from ._models import Address, Components, Record, Resolution
+
+__all__ = [
+    "Locio",
+    "Address",
+    "Components",
+    "Record",
+    "Resolution",
+    "LocioError",
+    "NotFound",
+    "AuthError",
+    "DEFAULT_BASE_URL",
+    "__version__",
+]

locio-0.1.0/src/locio/_client.py

@@ -0,0 +1,207 @@
+"""The client itself."""
+
+from __future__ import annotations
+
+import ipaddress
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Iterable, Sequence
+
+from ._errors import LocioError, error_for
+from ._models import Address, Resolution
+
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://api.locio.com.au"
+
+#: (method, url, headers, timeout) -> (status, body bytes)
+Transport = Callable[[str, str, dict, float], "tuple[int, bytes]"]
+
+
+def _urllib_transport(method: str, url: str, headers: dict, timeout: float):
+    req = urllib.request.Request(url, method=method, headers=headers)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as res:
+            # Bounded: a client should not be talked into reading an unbounded
+            # body by whatever is on the other end of the socket.
+            return res.status, res.read(8 << 20)
+    except urllib.error.HTTPError as err:
+        return err.code, err.read(8 << 20)
+
+
+def _check_base_url(raw: str) -> str:
+    """Refuse anything that would send the key somewhere it should not go.
+
+    The key is a bearer credential: whoever receives it can spend it. The base
+    URL is the one part of this client a caller supplies, so it is the one
+    place a mistake or an injected value could redirect the credential. https
+    always, and plaintext http only to loopback, which is what a local proxy
+    and a test server need.
+    """
+    if not raw:
+        raise ValueError("locio: no base URL")
+
+    parsed = urllib.parse.urlparse(raw)
+    if not parsed.scheme or not parsed.hostname:
+        raise ValueError(f"locio: base URL {raw!r} is not absolute")
+
+    if parsed.scheme == "https":
+        return raw.rstrip("/")
+
+    if parsed.scheme == "http" and _is_loopback(parsed.hostname):
+        return raw.rstrip("/")
+
+    if parsed.scheme == "http":
+        raise ValueError(
+            f"locio: base URL {raw!r} is plaintext http to a public host, "
+            "which would send the key in the clear"
+        )
+    raise ValueError(f"locio: base URL {raw!r} has scheme {parsed.scheme!r}, want https")
+
+
+def _is_loopback(host: str) -> bool:
+    if host == "localhost":
+        return True
+    try:
+        return ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        return False
+
+
+class Locio:
+    """A client for the Locio Australian address API.
+
+    Address autocomplete, address validation and address geocoding against
+    G-NAF, the national address register.
+
+        >>> from locio import Locio
+        >>> locio = Locio("lc_live_...")
+        >>> result = locio.resolve("1 george st sydenham nsw 2044")
+        >>> result.matched
+        True
+        >>> result.address.address_detail_pid
+        'GANSW...'
+
+    Takes a **secret** key (``lc_live_...``), which belongs on a server. A
+    secret key must never reach a browser: anyone who can read the page can
+    read the key and spend the quota. For browser code use a public key
+    (``lc_pub_...``) with an origin allow list, through ``@locio-au/react`` or
+    ``@locio-au/vue``.
+
+    Thread safe. Make one and keep it.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 15.0,
+        transport: Transport | None = None,
+    ):
+        if not api_key:
+            raise ValueError(
+                "locio: no API key. Get one at https://locio.com.au/account/api"
+            )
+        self._key = api_key
+        self._base_url = _check_base_url(base_url)
+        self._timeout = timeout
+        self._transport = transport or _urllib_transport
+
+    # -- the four calls -------------------------------------------------
+
+    def search(self, term: str, limit: int | None = None) -> list[Address]:
+        """Candidate addresses for what somebody has typed so far.
+
+        The **address autocomplete** call: a prefix match down the street
+        line, number first then the street, narrowed by a suburb or postcode
+        when the term carries one. One unit.
+
+        Building a browser autocomplete? Use ``@locio-au/react`` or ``@locio-au/vue``
+        with a public key rather than putting this key in a page.
+        """
+        body = self._get("/v1/addresses", {"q": term, "limit": limit})
+        return [Address.from_json(a) for a in body.get("data") or []]
+
+    def get(self, pid: str) -> Address:
+        """Read one address back by its G-NAF Address Detail PID.
+
+        Raises :class:`NotFound` when the pid is not in the current release.
+        That is worth catching rather than treating as a failure: G-NAF
+        retires ids between quarterly releases.
+        """
+        body = self._get(f"/v1/addresses/{urllib.parse.quote(pid)}", None)
+        return Address.from_json(body.get("data") or {})
+
+    def resolve(self, address: str) -> Resolution:
+        """Turn a whole address string into one record.
+
+        The **address validation** call, and it geocodes and parses in the
+        same answer rather than charging for three. Write the address however
+        you hold it: abbreviations, missing commas and a missing state are all
+        fine.
+
+        ``matched`` false is an ordinary answer, not an error. Try
+        :meth:`similar` when a typo is likely.
+        """
+        body = self._get("/v1/addresses/resolve", {"q": address})
+        data = body.get("data") or {}
+        found = data.get("address")
+        return Resolution(
+            matched=bool(data.get("matched")),
+            address=Address.from_json(found) if found else None,
+        )
+
+    def similar(self, address: str, limit: int | None = None) -> list[Address]:
+        """Match an address that is not quite right.
+
+        For when :meth:`resolve` said no and a misspelling is likely: "1 gorge
+        rd sydenhum" is one address, and this says which.
+
+        Three units, because it scores rows by similarity rather than seeking
+        an index. Call it once on an address that failed to resolve, never on
+        a keystroke.
+        """
+        body = self._get("/v1/addresses/similar", {"q": address, "limit": limit})
+        return [Address.from_json(a) for a in body.get("data") or []]
+
+    # -- convenience -----------------------------------------------------
+
+    def resolve_many(self, addresses: Iterable[str]) -> "list[Resolution]":
+        """Resolve a column of addresses, in order.
+
+        Sequential on purpose: the quota is per key, and firing a thousand
+        requests at once is how a free tier is spent in a second and a shared
+        key starves everybody else on it.
+        """
+        return [self.resolve(a) for a in addresses]
+
+    # -- plumbing --------------------------------------------------------
+
+    def _get(self, path: str, params: dict | None) -> dict:
+        url = self._base_url + path
+        query = {k: v for k, v in (params or {}).items() if v not in (None, "", 0)}
+        if query:
+            url += "?" + urllib.parse.urlencode(query)
+
+        status, raw = self._transport(
+            "GET",
+            url,
+            {
+                "Authorization": f"Bearer {self._key}",
+                "Accept": "application/json",
+                "User-Agent": f"locio-python/{__version__}",
+            },
+            self._timeout,
+        )
+
+        try:
+            body = json.loads(raw or b"{}")
+        except ValueError:
+            body = {}
+
+        if not 200 <= status < 300:
+            raise error_for(status, body.get("title", ""), body.get("detail", ""))
+        return body

locio-0.1.0/src/locio/_errors.py

@@ -0,0 +1,44 @@
+"""What the API said when it refused."""
+
+from __future__ import annotations
+
+
+class LocioError(Exception):
+    """The API refused, and said why.
+
+    The service writes a title and a detail meant for a person to read and act
+    on: which key is wrong, what a public key may call, how to narrow a search
+    that timed out. Collapsing that into "HTTP 403" throws away the only part
+    of the answer that says what to do about it.
+    """
+
+    def __init__(self, status: int, title: str = "", detail: str = ""):
+        self.status = status
+        self.title = title
+        self.detail = detail
+        message = title or f"HTTP {status}"
+        if detail:
+            message = f"{message}: {detail}"
+        super().__init__(f"{status} {message}")
+
+
+class NotFound(LocioError):
+    """No address with that id in the current G-NAF release.
+
+    Its own class because it is an ordinary thing to hit rather than a
+    failure: G-NAF retires ids between quarterly releases, so a caller storing
+    pids will meet this eventually and needs to tell it apart from a key
+    problem or an outage.
+    """
+
+
+class AuthError(LocioError):
+    """The key was refused: missing, wrong, or not allowed from this origin."""
+
+
+def error_for(status: int, title: str = "", detail: str = "") -> LocioError:
+    if status == 404:
+        return NotFound(status, title, detail)
+    if status in (401, 403):
+        return AuthError(status, title, detail)
+    return LocioError(status, title, detail)

locio-0.1.0/src/locio/_models.py

@@ -0,0 +1,195 @@
+"""The shapes the API returns."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field, fields
+from datetime import date, datetime
+from typing import Any, Mapping
+
+
+def _only_known(cls, raw: Mapping[str, Any]) -> dict:
+    """Keep the fields this class knows about.
+
+    The API may add a field before this library knows the name, and a client
+    that raises on an unrecognised key turns a compatible change at the
+    service into an outage in somebody's nightly job.
+    """
+    known = {f.name for f in fields(cls)}
+    return {k: v for k, v in (raw or {}).items() if k in known}
+
+
+@dataclass(frozen=True)
+class Components:
+    """A G-NAF address split into its published fields, which is what a form
+    has boxes for."""
+
+    building_name: str | None = None
+
+    flat_type: str | None = None
+    flat_number: str | None = None
+    level_type: str | None = None
+    level_number: str | None = None
+
+    #: The only number an address on a new subdivision has, before street
+    #: numbers are assigned.
+    lot_number: str | None = None
+
+    number_first: str | None = None
+    number_first_suffix: str | None = None
+    number_last: str | None = None
+    number_last_suffix: str | None = None
+
+    street_name: str | None = None
+    street_type: str | None = None
+    street_suffix: str | None = None
+
+    locality_name: str | None = None
+    state: str | None = None
+    postcode: str | None = None
+
+    @classmethod
+    def from_json(cls, raw: Mapping[str, Any] | None) -> "Components":
+        return cls(**_only_known(cls, raw))
+
+
+@dataclass(frozen=True)
+class Record:
+    """The part of a G-NAF row that is not the address itself.
+
+    Values are carried as G-NAF publishes them, upper case included:
+    ``PRINCIPAL``, ``SECONDARY``, ``PROPERTY ACCESS POINT SETBACK``. They are
+    codes to match on rather than prose to print.
+    """
+
+    #: When G-NAF first published this address.
+    date_created: date | None = None
+
+    #: G-NAF's name for the site, where the address is part of a named one:
+    #: a school, a hospital, a caravan park.
+    address_site_name: str | None = None
+
+    #: The title reference for the parcel, and the join to a land registry.
+    legal_parcel_id: str | None = None
+
+    #: PRINCIPAL or ALIAS.
+    alias_principal: str | None = None
+
+    #: PRIMARY or SECONDARY.
+    primary_secondary: str | None = None
+
+    #: The parcel this address sits on, when this row is a unit under one.
+    #:
+    #: Emphatically not the address id. Storing this instead of
+    #: ``address_detail_pid`` stores the building rather than the door.
+    primary_pid: str | None = None
+
+    #: How the coordinate was derived: the difference between a pin on the
+    #: door and a pin in the middle of a paddock.
+    geocode_type: str | None = None
+
+    @classmethod
+    def from_json(cls, raw: Mapping[str, Any] | None) -> "Record":
+        data = _only_known(cls, raw)
+        created = data.get("date_created")
+        if isinstance(created, str) and created:
+            # A date that will not parse is one field of one row. Dropping it
+            # is better than refusing an address that is otherwise complete.
+            try:
+                data["date_created"] = datetime.fromisoformat(
+                    created.replace("Z", "+00:00")
+                ).date()
+            except ValueError:
+                data["date_created"] = None
+        return cls(**data)
+
+
+@dataclass(frozen=True)
+class Address:
+    """One resolved G-NAF record."""
+
+    #: The G-NAF Address Detail PID: **this** address, and the id to store
+    #: against your own record. Stable across G-NAF releases for an address
+    #: that has not changed.
+    #:
+    #: Not to be confused with ``gnaf.primary_pid``, which identifies the
+    #: parcel this address sits on.
+    address_detail_pid: str = ""
+
+    #: The address on one line, as an envelope would write it.
+    formatted: str = ""
+
+    lat: float | None = None
+    lng: float | None = None
+
+    #: The ABS mesh block: the smallest unit the census publishes, and the
+    #: join key to every ABS statistic about the area.
+    mesh_block: str | None = None
+
+    components: Components = field(default_factory=Components)
+    gnaf: Record = field(default_factory=Record)
+
+    #: Where it sits, as names. Empty for an address outside the areas seeded
+    #: so far, which is an ordinary thing for a good address to be.
+    country: str | None = None
+    region: str | None = None
+    locality: str | None = None
+
+    #: Deprecated former name for :attr:`address_detail_pid`, same value,
+    #: carried while the API emits both.
+    gnaf_pid: str | None = None
+
+    @classmethod
+    def from_json(cls, raw: Mapping[str, Any]) -> "Address":
+        data = _only_known(cls, raw)
+        data["components"] = Components.from_json(raw.get("components"))
+        data["gnaf"] = Record.from_json(raw.get("gnaf"))
+        return cls(**data)
+
+    @property
+    def is_unit(self) -> bool:
+        """Whether this address is a unit under a parcel, in which case
+        ``gnaf.primary_pid`` names the parcel."""
+        return (self.gnaf.primary_secondary or "").upper() == "SECONDARY"
+
+    def to_dict(self) -> dict:
+        """Flatten to one level, for writing straight into a csv.DictWriter.
+
+        Cleaning a spreadsheet of addresses is the commonest thing this
+        library is asked to do, and a nested record means every caller writes
+        the same unpacking loop.
+        """
+        out = {
+            "address_detail_pid": self.address_detail_pid,
+            "formatted": self.formatted,
+            "lat": self.lat,
+            "lng": self.lng,
+            "mesh_block": self.mesh_block,
+            "country": self.country,
+            "region": self.region,
+            "locality": self.locality,
+        }
+        out.update({k: v for k, v in asdict(self.components).items() if v is not None})
+        out.update(
+            {
+                f"gnaf_{k}": (v.isoformat() if isinstance(v, date) else v)
+                for k, v in asdict(self.gnaf).items()
+                if v is not None
+            }
+        )
+        return out
+
+
+@dataclass(frozen=True)
+class Resolution:
+    """The answer to a validation call: whether the address is real, and what
+    it resolves to when it is.
+
+    Falsy when nothing matched, so ``if not client.resolve(...)`` reads the
+    way it should.
+    """
+
+    matched: bool = False
+    address: Address | None = None
+
+    def __bool__(self) -> bool:
+        return self.matched

locio-0.1.0/tests/test_client.py

@@ -0,0 +1,205 @@
+"""The Locio client, tested against the shape the API actually sends.
+
+Written on unittest rather than pytest so the suite runs with nothing
+installed: the library itself has no dependencies, and a test suite that needs
+one is a worse first impression than no test suite. pytest runs these too.
+"""
+
+from __future__ import annotations
+
+import json
+import unittest
+from datetime import date
+
+from locio import Address, Locio, LocioError, NotFound
+
+# A real answer, copied rather than invented.
+UNIT = {
+    "data": [
+        {
+            "address_detail_pid": "GAVIC425624910",
+            "gnaf_pid": "GAVIC425624910",
+            "formatted": "Unit 104, 119 Turner Street, Abbotsford VIC 3067",
+            "lat": -37.79928725,
+            "lng": 145.0004257,
+            "mesh_block": "21301420000",
+            "country": "Australia",
+            "region": "Victoria",
+            "locality": "Abbotsford",
+            "components": {
+                "flat_type": "Unit",
+                "flat_number": "104",
+                "number_first": "119",
+                "street_name": "Turner",
+                "street_type": "Street",
+                "locality_name": "Abbotsford",
+                "state": "VIC",
+                "postcode": "3067",
+            },
+            "gnaf": {
+                "date_created": "2018-07-20T00:00:00Z",
+                "legal_parcel_id": "T104\\PS638763",
+                "alias_principal": "PRINCIPAL",
+                "primary_secondary": "SECONDARY",
+                "primary_pid": "GAVIC425580914",
+                "geocode_type": "PROPERTY ACCESS POINT SETBACK",
+            },
+        }
+    ],
+    "generated_at": "2026-09-17T06:35:33Z",
+}
+
+
+class Recorder:
+    """A transport that records the request and returns a canned answer."""
+
+    def __init__(self, status=200, body=None):
+        self.status = status
+        self.body = body if body is not None else UNIT
+        self.calls = []
+
+    def __call__(self, method, url, headers, timeout):
+        self.calls.append({"method": method, "url": url, "headers": headers})
+        return self.status, json.dumps(self.body).encode()
+
+    @property
+    def last_url(self):
+        return self.calls[-1]["url"]
+
+
+def client(recorder, key="lc_live_secret", **kw):
+    return Locio(key, transport=recorder, **kw)
+
+
+class TestSearch(unittest.TestCase):
+    def test_decodes_the_whole_record(self):
+        rec = Recorder()
+        found = client(rec).search("104/119 turner", limit=5)
+
+        self.assertEqual(len(found), 1)
+        a = found[0]
+        self.assertIsInstance(a, Address)
+        self.assertEqual(a.address_detail_pid, "GAVIC425624910")
+        self.assertEqual(a.components.flat_number, "104")
+        self.assertEqual(a.components.street_name, "Turner")
+        # The parcel is a different address from the door.
+        self.assertEqual(a.gnaf.primary_pid, "GAVIC425580914")
+        self.assertTrue(a.is_unit)
+        self.assertEqual(a.gnaf.date_created, date(2018, 7, 20))
+        self.assertEqual(a.mesh_block, "21301420000")
+
+        self.assertIn("/v1/addresses?", rec.last_url)
+        self.assertIn("q=104%2F119+turner", rec.last_url)
+        self.assertIn("limit=5", rec.last_url)
+        self.assertEqual(rec.calls[-1]["headers"]["Authorization"], "Bearer lc_live_secret")
+        self.assertTrue(rec.calls[-1]["headers"]["User-Agent"].startswith("locio-python/"))
+
+    def test_a_zero_limit_is_omitted(self):
+        """The service's own default is the right one; do not invent a zero."""
+        rec = Recorder()
+        client(rec).search("90 bay road")
+        self.assertNotIn("limit=", rec.last_url)
+
+
+class TestResolve(unittest.TestCase):
+    def test_reports_whether_it_matched(self):
+        rec = Recorder(body={"data": {"matched": False, "address": None}})
+        res = client(rec).resolve("1 nowhere st")
+
+        self.assertFalse(res.matched)
+        self.assertIsNone(res.address)
+        # Falsy, so `if not client.resolve(...)` reads correctly.
+        self.assertFalse(res)
+
+    def test_returns_the_address_when_it_matched(self):
+        rec = Recorder(body={"data": {"matched": True, "address": UNIT["data"][0]}})
+        res = client(rec).resolve("104/119 turner st abbotsford")
+
+        self.assertTrue(res.matched)
+        self.assertEqual(res.address.address_detail_pid, "GAVIC425624910")
+        self.assertTrue(res)
+
+
+class TestErrors(unittest.TestCase):
+    def test_a_retired_pid_raises_not_found(self):
+        """G-NAF retires ids between releases. Worth catching by itself."""
+        rec = Recorder(status=404, body={"title": "no address with that id"})
+        with self.assertRaises(NotFound):
+            client(rec).get("GAVIC000000000")
+
+    def test_an_api_error_keeps_what_the_api_said(self):
+        rec = Recorder(
+            status=403,
+            body={
+                "title": "this key is not allowed from here",
+                "detail": "A public key only works from the sites listed on it.",
+            },
+        )
+        with self.assertRaises(LocioError) as caught:
+            client(rec).search("90 bay road")
+
+        err = caught.exception
+        self.assertEqual(err.status, 403)
+        self.assertIn("not allowed from here", str(err))
+        self.assertIn("sites listed on it", str(err))
+
+
+class TestBaseURLIsACredentialBoundary(unittest.TestCase):
+    """A bearer key sent in the clear is a key given away.
+
+    The base URL is the one part of this client a caller supplies, so it is
+    the one place a mistake could redirect the credential somewhere else.
+    """
+
+    def test_must_be_https(self):
+        for bad in ["", "not a url", "ftp://example.com", "//evil.example",
+                    "http://example.com"]:
+            with self.subTest(bad=bad), self.assertRaises(ValueError):
+                Locio("lc_live_x", base_url=bad, transport=Recorder())
+
+    def test_loopback_http_is_allowed_for_local_development(self):
+        Locio("lc_live_x", base_url="http://127.0.0.1:8080", transport=Recorder())
+        Locio("lc_live_x", base_url="http://localhost:8080", transport=Recorder())
+
+
+class TestSimilar(unittest.TestCase):
+    def test_sends_the_limit(self):
+        rec = Recorder()
+        client(rec).similar("1 gorge rd sydenhum", limit=3)
+        self.assertIn("/v1/addresses/similar?", rec.last_url)
+        self.assertIn("limit=3", rec.last_url)
+
+
+class TestTolerance(unittest.TestCase):
+    def test_a_missing_gnaf_record_does_not_break_decoding(self):
+        """An older record carries no gnaf object. That is not a failure."""
+        bare = {k: v for k, v in UNIT["data"][0].items() if k != "gnaf"}
+        rec = Recorder(body={"data": [bare]})
+        a = client(rec).search("104/119 turner")[0]
+
+        self.assertIsNone(a.gnaf.primary_pid)
+        self.assertFalse(a.is_unit)
+
+    def test_an_unknown_field_is_ignored_rather_than_fatal(self):
+        """The API may add a field before this library knows about it."""
+        extra = dict(UNIT["data"][0], something_new="x")
+        rec = Recorder(body={"data": [extra]})
+        a = client(rec).search("104/119 turner")[0]
+        self.assertEqual(a.address_detail_pid, "GAVIC425624910")
+
+
+class TestSpreadsheetUse(unittest.TestCase):
+    def test_address_flattens_for_csv_writing(self):
+        """Cleaning a spreadsheet is the commonest server side use, so the
+        record has to reach csv.DictWriter without hand unpacking."""
+        rec = Recorder()
+        a = client(rec).search("104/119 turner")[0]
+        row = a.to_dict()
+
+        self.assertEqual(row["address_detail_pid"], "GAVIC425624910")
+        self.assertEqual(row["postcode"], "3067")
+        self.assertEqual(row["lat"], -37.79928725)
+
+
+if __name__ == "__main__":
+    unittest.main()