Metadata-Version: 2.4
Name: mailwoman-client
Version: 6.0.0
Summary: Typed Python clients for Mailwoman's Photon / Nominatim / libpostal drop-in geocoding APIs and native /v1/* surface, generated from their OpenAPI specs.
Author-email: Sister Software <contact@sister.software>
License-Expression: AGPL-3.0-only OR LicenseRef-Commercial
Project-URL: Homepage, https://mailwoman.sister.software
Project-URL: Documentation, https://mailwoman.sister.software/docs
Project-URL: Repository, https://github.com/sister-software/mailwoman
Project-URL: Issues, https://github.com/sister-software/mailwoman/issues
Keywords: geocoding,photon,nominatim,libpostal,openapi,mailwoman,address
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
License-File: COMMERCIAL-LICENSE.md
Requires-Dist: httpx<0.29,>=0.23
Requires-Dist: attrs>=22.2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff==0.15.20; extra == "dev"
Dynamic: license-file

# mailwoman-client (Python)

Typed Python clients for [Mailwoman](https://mailwoman.sister.software)'s HTTP surfaces —
**generated from their published OpenAPI specs** and bundled under one distributable:

| Subpackage                   | Surface           | Endpoints                                                            |
| ----------------------------- | ------------------ | --------------------------------------------------------------------------- |
| `mailwoman_client.photon`    | Photon drop-in    | `/api`, `/reverse`                                                   |
| `mailwoman_client.nominatim` | Nominatim drop-in | `/search`, `/reverse`, `/lookup`, `/status`                          |
| `mailwoman_client.libpostal` | libpostal drop-in | `/parse`, `/expand`                                                  |
| `mailwoman_client.mailwoman` | Native surface    | `/v1/parse`, `/v1/geocode`, `/v1/batch`, `/v1/resolve`, `/v1/format` |

The four subpackages are generated verbatim by [`openapi-python-client`](https://github.com/openapi-generators/openapi-python-client)
(it runs its own `ruff` pass) and are **overwritten on regen** — do not hand-edit them. The
only hand-written code is the thin ergonomics layer in `mailwoman_client/__init__.py`:
`PhotonClient` / `NominatimClient` / `LibpostalClient` / `MailwomanClient`, each with a
sensible default `base_url`. Regenerate with `mailwoman clients generate` (see the repo's
`docs/articles/api.mdx` "Client libraries" section) — nothing here is hand-maintained.

**Not yet published.** This package is built and verified on every `mailwoman clients generate`
run; publishing to PyPI happens from the gated CI job once the operator provisions a PyPI
account (see the repo's `RELEASING.md`).

## Install

```bash
pip install mailwoman-client
```

Requires Python 3.10+. The only runtime dependencies are `httpx` and `attrs`.

## Usage

Forward-geocode against the hosted Photon trial endpoint (`https://photon.sister.software`, no
local server needed):

```python
from mailwoman_client import PhotonClient
from mailwoman_client.photon.api.geocoding import search

client = PhotonClient.hosted()  # or PhotonClient(base_url="http://127.0.0.1:2322") to self-host
result = search.sync(client=client, q="berlin", limit=3)

for feature in result.features:
    lon, lat = feature.geometry.coordinates
    props = feature.properties
    print(f"{props.name} ({props.type_}) — {lat:.4f}, {lon:.4f} [{props.country or '?'}]")
```

### Self-hosting

`PhotonClient()`, `NominatimClient()`, `LibpostalClient()`, and `MailwomanClient()` default to
their local `serve` ports (2322 / 8080 / 8081 / 3000), so they work out of the box against a
self-hosted server (`npx @mailwoman/photon serve`, `mailwoman serve`, etc.). Only Photon has a
hosted public trial endpoint. Point anywhere with `base_url=`.

### Async

Every endpoint module also exposes an `asyncio` coroutine alongside `sync`:

```python
result = await search.asyncio(client=client, q="berlin", limit=3)
```

## License

AGPL-3.0-only OR LicenseRef-Commercial (see the [repository](https://github.com/sister-software/mailwoman)).
