RyanData-Address-Utils/llms.txt at main · Abstract-Data/RyanData-Address-Utils · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
# ryandata-address-utils

> US address parsing library with Pydantic models, validation, and pandas integration

## Quick Facts

- Package: ryandata-address-utils
- Version: 0.7.1
- Python: >=3.12.8, <=3.13
- License: MIT
- Repository: https://github.com/Abstract-Data/RyanData-Address-Utils

## What This Library Does

Parse, validate, and normalize US addresses into structured components. Features include:
- 26+ address components (street number, name, city, state, ZIP, unit, etc.)
- ZIP code and state validation against authoritative datasets
- Pandas DataFrame integration for batch processing
- International address support via libpostal (optional)
- Transformation tracking with ProcessLog audit trails

## Main Entry Points

```python
from ryandata_address_utils import AddressService, parse

# Simple parsing
result = parse("123 Main St, Austin TX 78749")
if result.is_valid:
    print(result.address.ZipCode)  # "78749"

# Service-based parsing
service = AddressService()
result = service.parse("456 Oak Ave, Dallas TX 75201")

# Pandas integration
df = service.parse_dataframe(df, "address_column")
```

## Key Classes

- AddressService: Main facade for parsing operations
- Address: Pydantic model with all address components
- ParseResult: Container for parsed address + validation + logs
- AddressBuilder: Fluent API for programmatic address construction
- ProcessLog: Audit trail for transformations

## Installation

```bash
# Using uv (recommended)
uv add git+https://github.com/Abstract-Data/RyanData-Address-Utils.git

# With pandas support
uv add "ryandata-address-utils[pandas] @ git+https://github.com/Abstract-Data/RyanData-Address-Utils.git"
```

## Documentation Files

- README.md: Installation, quick start, usage examples
- docs/ARCHITECTURE.md: Design patterns, data flow, SOLID principles
- AGENTS.md: AI coding assistant guidance
- CHANGELOG.md: Version history and changes
- .cursor/agents.md: Cursor-specific agent workflows

## Architecture

The library uses:
- Facade pattern (AddressService)
- Protocol-based interfaces for extensibility
- Factory pattern for parsers and data sources
- Composite pattern for validators
- Builder pattern for address construction

## Common Operations

### Parse a single address
```python
result = parse("123 Main St, Austin TX 78749")
```

### Parse with automatic US/international detection
```python
result = service.parse_auto("10 Downing Street, London, UK")
```

### Validate ZIP codes
```python
from ryandata_address_utils import is_valid_zip, get_zip_info
is_valid_zip("78749")  # True
info = get_zip_info("78749")  # ZipInfo with city, state, county
```

### Build addresses programmatically
```python
from ryandata_address_utils import AddressBuilder
address = (
    AddressBuilder()
    .with_street_number("123")
    .with_street_name("Main")
    .with_city("Austin")
    .with_state("TX")
    .with_zip("78749")
    .build()
)
```

## Contact

- Issues: https://github.com/Abstract-Data/RyanData-Address-Utils/issues
- Author: Abstract-Data (dev@abstractdata.io)