Metadata-Version: 2.1
Name: dripostal
Version: 0.1.1
Summary: A tiny API client for the Pelias Libpostal REST service.
Home-page: https://dribia.github.io/dripostal
License: MIT
Author: Dribia Data Research
Author-email: opensource@dribia.com
Maintainer: Nabil Kakeh
Maintainer-email: nabil@dribia.com
Requires-Python: >=3.6.2,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Provides-Extra: aiohttp
Requires-Dist: aiohttp (>=3.7.4,<4.0.0); extra == "aiohttp"
Requires-Dist: importlib-metadata (>=1.0,<5.0); python_version < "3.8"
Requires-Dist: pydantic (>=1.8.2,<2.0.0)
Project-URL: Documentation, https://dribia.github.io/dripostal
Project-URL: Repository, https://github.com/dribia/dripostal
Description-Content-Type: text/markdown

<p style="text-align: center; padding-bottom: 1rem;">
    <a href="https://dribia.github.io/dripostal">
        <img 
            src="https://dribia.github.io/dripostal/img/logo_dribia_blau_cropped.png" 
            alt="dripostal" 
            style="display: block; margin-left: auto; margin-right: auto; width: 40%;"
        >
    </a>
</p>

<p style="text-align: center">
    <a href="https://github.com/dribia/dripostal/actions?query=workflow%3ATest" target="_blank">
        <img src="https://github.com/dribia/dripostal/workflows/Test/badge.svg" alt="Test">
    </a>
    <a href="https://github.com/dribia/dripostal/actions?query=workflow%3APublish" target="_blank">
        <img src="https://github.com/dribia/dripostal/workflows/Publish/badge.svg" alt="Publish">
    </a>
    <a href="https://codecov.io/gh/dribia/dripostal" target="_blank">
        <img src="https://img.shields.io/codecov/c/github/dribia/dripostal?color=%2334D058" alt="Coverage">
    </a>
    <a href="https://pypi.org/project/dripostal" target="_blank">
        <img src="https://img.shields.io/pypi/v/dripostal?color=%2334D058&label=pypi%20package" alt="Package version">
    </a>
</p>

<p style="text-align: center;">
    <em>A tiny API client for the Pelias Libpostal REST service.</em>
</p>

---

**Documentation**: <a href="https://dribia.github.io/dripostal" target="_blank">https://dribia.github.io/dripostal</a>

**Source Code**: <a href="https://github.com/dribia/dripostal" target="_blank">
https://github.com/dribia/dripostal</a>

---

[**Libpostal**](https://github.com/openvenues/libpostal) is a widely known C library for 
**parsing and normalizing street addresses** around the world. 

Despite having its own Python bindings, getting to install the library can be quite hard and time-consuming.
A common workaround is then to use a dockerized service exposing Libpostal as a REST API, 
e.g. [**Pelias' Libpostal REST service**](https://github.com/pelias/libpostal-service).

**Dripostal** aims to provide a Python interface with such API, both in the synchronous and the asynchronous ways.

## Key features

* Query Libpostal's [**`parse`**](https://github.com/openvenues/libpostal#examples-of-parsing) and [**`expand`**](https://github.com/openvenues/libpostal#examples-of-normalization) methods.
* Return results as [**Pydantic**](https://pydantic-docs.helpmanual.io/) models.
* Provides a mirror [**async client**](https://docs.python.org/3/library/asyncio.html) enabling asynchronous queries to the Libpostal REST service.

## Example

In order to successfully run the following example, a Libpostal service should be running locally:

```shell
docker run -d -p 4400:4400 pelias/libpostal-service
```

!!!info
    The command above will be pulling the `libpostal-service` Docker image from **Pelias** and 
    running a container that will serve the Libpostal REST service through its port 4400.

    * With option `-p 4400:4400` we are mapping port 
      `4400` in the docker container to port `4400` in the docker host, i.e. your computer. 
      You could map it to another port of the host, e.g. the `8080`, changing `4400:4400` for `8080:4400`.
    * With option `-d` we are running the docker container in _detached mode_, i.e. in the background. 

Now we should be able to run the following code:

```python
from dripostal import DriPostal

dripostal = DriPostal(url="http://0.0.0.0:4400")

dripostal.parse("Planta 3 mòdul 303, Carrer de la Llacuna, 162, 08018 Barcelona")

"""
Address(
    house='mòdul 303', 
    house_number='162', 
    road='carrer de la llacuna', 
    level='planta 3', 
    postcode='08018', 
    city='barcelona', 
    country=None, 
    ...
)
"""
```

