Metadata-Version: 2.4
Name: japanese-address-parser-py
Version: 0.3.2
Classifier: Topic :: Text Processing
Classifier: Programming Language :: Rust
Classifier: Typing :: Typed
Summary: A library for processing addresses of Japan
Keywords: converter,utility,geo,rust
Author: Yuuki Toriyama <github@toriyama.dev>
Author-email: Yuuki Toriyama <github@toriyama.dev>
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Source Code, https://github.com/YuukiToriyama/japanese-address-parser

# japanese-address-parser-py

A Python toolkit for processing Japanese addresses

[![PyPI - Version](https://img.shields.io/pypi/v/japanese-address-parser-py)](https://pypi.org/project/japanese-address-parser-py/)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/japanese-address-parser-py)](https://pypi.org/project/japanese-address-parser-py/#history)
[![Unit test & Integration test](https://github.com/YuukiToriyama/japanese-address-parser/actions/workflows/run-test.yaml/badge.svg?branch=main)](https://github.com/YuukiToriyama/japanese-address-parser/actions/workflows/run-test.yaml)

## What is it?

**japanese-address-parser-py** is a Python package for parsing Japanese addresses.
Any address can be parsed into structured data.

## Installation from PyPI

```bash
pip install japanese-address-parser-py
```

## Usage

### Sequential execution

```python
from japanese_address_parser_py import Parser

addresses = [
    "埼玉県さいたま市浦和区高砂3-15-1",
    "千葉県千葉市中央区市場町1-1",
    "東京都新宿区西新宿2-8-1",
    "神奈川県横浜市中区日本大通1",
]
parser = Parser()
for address in addresses:
    parse_result = parser.parse(address)
    print(parse_result.address)
```

```text
{'prefecture': '埼玉県', 'town': '高砂三丁目', 'rest': '15-1', 'city': 'さいたま市浦和区'}
{'rest': '1-1', 'town': '市場町', 'prefecture': '千葉県', 'city': '千葉市中央区'}
{'prefecture': '東京都', 'rest': '8-1', 'town': '西新宿二丁目', 'city': '新宿区'}
{'town': '日本大通', 'city': '横浜市中区', 'prefecture': '神奈川県', 'rest': '1'}
```

### Parallel execution

```python
from concurrent.futures import ThreadPoolExecutor

from japanese_address_parser_py import Parser

addresses = [
    "徳島県徳島市万代町1-1",
    "香川県高松市番町4-1-10",
    "愛媛県松山市一番町4-4-2",
    "高知県高知市丸ノ内1-2-20",
]

parser = Parser()
with ThreadPoolExecutor(max_workers=4) as executor:
    results = executor.map(parser.parse, addresses)

for result in results:
    print(result.address)
```

```text
{'prefecture': '徳島県', 'rest': '1', 'city': '徳島市', 'town': '万代町一丁目'}
{'prefecture': '香川県', 'city': '高松市', 'town': '番町四丁目', 'rest': '1-10'}
{'city': '松山市', 'rest': '4-2', 'town': '一番町四丁目', 'prefecture': '愛媛県'}
{'city': '高知市', 'town': '丸ノ内一丁目', 'rest': '2-20', 'prefecture': '高知県'}
```

## Development

This library is written in Rust. You need to set up a Rust development environment to build this library.
We recommend `uv` for Python dependency management and development.

```bash
# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Clone repository
git clone https://github.com/YuukiToriyama/japanese-address-parser.git
cd japanese-address-parser/python
# Setup environment and install dependencies
uv sync
# Run tests
uv run pytest tests/test_parser.py
```

If you want to build the wheel manually:
```bash
uv tool run maturin build --release --out dist
```

## Support

This software is maintained by [YuukiToriyama](https://github.com/yuukitoriyama).
If you have any questions, please create a new issue.

## Where to get source code

The source code is hosted on GitHub at:
https://github.com/YuukiToriyama/japanese-address-parser

## Acknowledgements

This software was inspired
by [@geolonia/normalize-japanese-addresses](https://github.com/geolonia/normalize-japanese-addresses).  
In addition, the parsing process uses [Geolonia 住所データ](https://github.com/geolonia/japanese-addresses) which is
provided by [株式会社Geolonia](https://www.geolonia.com/company/).

## License

This library is distributed under the terms of the MIT license.

