hangarbay 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Hangarbay Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
@@ -0,0 +1,265 @@
1
+ Metadata-Version: 2.4
2
+ Name: hangarbay
3
+ Version: 0.4.0
4
+ Summary: A reproducible workflow for the FAA aircraft registry
5
+ Author-email: Matt Stiles <stiles@users.noreply.github.com>
6
+ License: MIT
7
+ Classifier: Development Status :: 3 - Alpha
8
+ Classifier: Intended Audience :: Developers
9
+ Classifier: License :: OSI Approved :: MIT License
10
+ Classifier: Programming Language :: Python :: 3.10
11
+ Classifier: Programming Language :: Python :: 3.11
12
+ Classifier: Programming Language :: Python :: 3.12
13
+ Requires-Python: >=3.10
14
+ Description-Content-Type: text/markdown
15
+ License-File: LICENSE
16
+ Requires-Dist: pyarrow>=14.0.0
17
+ Requires-Dist: pandas>=2.0.0
18
+ Requires-Dist: duckdb>=0.9.0
19
+ Requires-Dist: typer>=0.9.0
20
+ Requires-Dist: rich>=13.0.0
21
+ Requires-Dist: requests>=2.31.0
22
+ Requires-Dist: xxhash>=3.4.0
23
+ Provides-Extra: dev
24
+ Requires-Dist: pytest>=7.4.0; extra == "dev"
25
+ Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
26
+ Requires-Dist: ruff>=0.1.0; extra == "dev"
27
+ Dynamic: license-file
28
+
29
+ # Hangarbay
30
+
31
+ **Stop struggling with FAA registration data.** Get clean, queryable aircraft registry tables in seconds.
32
+
33
+ Hangarbay downloads, normalizes and indexes the complete [FAA aircraft registry](https://www.faa.gov/licenses_certificates/aircraft_certification/aircraft_registry/releasable_aircraft_download) so you can skip straight to analysis. No more hunting for files to download, or joining fragmented tables, or trying to decoding cryptic lookup relationships. One command gets you 307,000+ aircraft registrations, owners and specifications ready to query with SQL or pandas.
34
+
35
+ This is a tool built for researchers, data journalists and aviation analysts who need fast, reliable and repeatable workflows.
36
+
37
+ ## Quick start
38
+
39
+ **Requirements:** Python 3.9+
40
+
41
+ ### Python API (notebooks & scripts)
42
+
43
+ ```python
44
+ # Install
45
+ pip install hangarbay
46
+
47
+ # One-time setup
48
+ import hangarbay as hb
49
+ hb.load_data() # Downloads & processes FAA data to ~/.hangarbay/data/
50
+
51
+ # Look up aircraft
52
+ df = hb.search("N221LA")
53
+
54
+ # Find fleets
55
+ fleet = hb.fleet("United Airlines")
56
+ fleet = hb.fleet("LAPD|Los Angeles Police", state="CA")
57
+
58
+ # Custom SQL
59
+ df = hb.query("""
60
+ SELECT maker, COUNT(*) as count
61
+ FROM aircraft_decoded
62
+ WHERE year_mfr > 2020
63
+ GROUP BY maker
64
+ ORDER BY count DESC
65
+ """)
66
+
67
+ # Check data age
68
+ info = hb.status()
69
+ print(f"Data is {info['age_days']} days old")
70
+ ```
71
+
72
+ ### Command-line interface
73
+
74
+ ```bash
75
+ # Clone and install
76
+ git clone https://github.com/stiles/hangarbay.git
77
+ cd hangarbay
78
+
79
+ # Recommended: use a virtual environment (uv, venv, conda, etc.)
80
+ uv venv && source .venv/bin/activate # or: python -m venv .venv && source .venv/bin/activate
81
+
82
+ pip install -e ".[dev]"
83
+
84
+ # Run the full pipeline (~2 minutes)
85
+ hangar update # Download, normalize and publish (all-in-one)
86
+
87
+ # Or run steps individually
88
+ hangar fetch # Download FAA data
89
+ hangar normalize # Parse to typed Parquet tables
90
+ hangar publish # Build DuckDB + SQLite FTS indexes
91
+
92
+ # Check data status and age
93
+ hangar status
94
+
95
+ # Start querying!
96
+ hangar search N757AF
97
+ hangar sql "SELECT COUNT(*) FROM aircraft"
98
+ ```
99
+
100
+ ## What this does
101
+
102
+ Hangarbay downloads FAA aircraft registration data, normalizes it into typed tables and provides fast SQL querying:
103
+
104
+ - **307K+ aircraft registrations** with owner and address information
105
+ - **93K+ make/model references** (Cessna, Piper, Boeing, etc.)
106
+ - **4,700+ engine specifications** (horsepower, type, manufacturer)
107
+ - **DuckDB** for analytical SQL queries (sub-second on 300K+ rows)
108
+ - **SQLite FTS5** for full-text search by owner name or address
109
+ - **Parquet** files for efficient columnar storage
110
+ - **Data lineage tracking** with SHA256 checksums and version metadata
111
+ - **Shared data directory** at `~/.hangarbay/data/` - works from any project or notebook
112
+
113
+ ## Features
114
+
115
+ ### N-Number lookup
116
+ Look up any aircraft registration with decoded status codes and human-readable output:
117
+
118
+ ```bash
119
+ hangar search N221LA
120
+ ```
121
+
122
+ ### Fleet search
123
+ Find all aircraft owned by a person or company:
124
+
125
+ ```bash
126
+ # Search by owner name (case-insensitive)
127
+ hangar fleet "United Airlines"
128
+ hangar fleet "LAPD"
129
+ hangar fleet "NetJets"
130
+
131
+ # OR logic with pipe separator (great for finding multiple airlines)
132
+ hangar fleet "LAPD|Los Angeles Police" # Either pattern matches
133
+ hangar fleet "Delta|American|United" # Any of the three
134
+
135
+ # Filter by state
136
+ hangar fleet "Delta" --state GA
137
+
138
+ # Export to CSV
139
+ hangar fleet "Boeing" --export boeing_fleet.csv
140
+
141
+ # Limit results
142
+ hangar fleet "Cessna" --limit 20
143
+ ```
144
+
145
+ ```
146
+ Aircraft Registration: N221LA
147
+
148
+ Owner: LAPD AIR SUPPORT DIVISION
149
+ Location: LOS ANGELES, CA
150
+
151
+ Make & Model: AIRBUS HELICOPTERS INC AS350B3
152
+ Year Manufactured: 2014
153
+ Serial Number: 7900
154
+ Registration Status: Valid
155
+ Certificate Type: Standard Airworthiness - Normal
156
+ Status Date: May 19, 2023
157
+ Expiration: Jun 30, 2028
158
+ ```
159
+
160
+ ### SQL queries
161
+ Execute analytical queries with pretty output:
162
+
163
+ ```bash
164
+ # Total aircraft
165
+ hangar sql "SELECT COUNT(*) FROM aircraft"
166
+
167
+ # Use decoded views for readable output
168
+ hangar sql "SELECT * FROM aircraft_decoded WHERE year_mfr > 2020 LIMIT 10"
169
+ hangar sql "SELECT * FROM owners_clean WHERE owner_name LIKE '%boeing%'" -i
170
+
171
+ # Top manufacturers
172
+ hangar sql "SELECT maker, COUNT(*) as count FROM aircraft
173
+ JOIN aircraft_make_model USING(mfr_mdl_code)
174
+ WHERE maker != '' GROUP BY 1 ORDER BY 2 DESC LIMIT 10"
175
+
176
+ # Lookup status codes
177
+ hangar sql "SELECT * FROM status_codes"
178
+
179
+ # Top states by registrations
180
+ hangar sql "SELECT state_std, COUNT(*) as count FROM owners
181
+ WHERE state_std != '' GROUP BY 1 ORDER BY 2 DESC LIMIT 10"
182
+ ```
183
+
184
+ **Output Formats:**
185
+
186
+ ```bash
187
+ # Pretty table (default)
188
+ hangar sql "SELECT * FROM status_codes LIMIT 3"
189
+
190
+ # JSON output (for APIs/scripts)
191
+ hangar sql "SELECT * FROM status_codes LIMIT 3" --output-format json
192
+
193
+ # CSV output (for Excel/spreadsheets)
194
+ hangar sql "SELECT * FROM status_codes LIMIT 3" --output-format csv
195
+ ```
196
+
197
+ ### Available tables
198
+
199
+ **Core Tables:**
200
+ - **aircraft** - Current registration facts (N-number, serial, make/model, year, status)
201
+ - **registrations** - Canonical registration state (type, status, dates)
202
+ - **owners** - Owner records with raw and standardized addresses
203
+ - **owners_summary** - Aggregated ownership (co-owners, counts)
204
+ - **aircraft_make_model** - Make/model reference (Cessna 172, Boeing 737, etc.)
205
+ - **engines** - Engine specifications (manufacturer, horsepower, type)
206
+
207
+ **Decoded Views (Recommended):**
208
+ - **aircraft_decoded** - Aircraft with decoded status codes and joined make/model
209
+ - **owners_clean** - Simplified owner table (standardized fields only, decoded owner type)
210
+
211
+ **Reference Tables:**
212
+ - **status_codes** - Registration status code lookups
213
+ - **airworthiness_classes** - Airworthiness certificate class lookups
214
+ - **owner_types** - Owner type code lookups
215
+
216
+ ## Data quality
217
+
218
+ - **Type safety**: PyArrow schemas enforce correct data types (dates, integers, strings)
219
+ - **Address standardization**: Uppercase, state/ZIP normalization, whitespace cleanup
220
+ - **Deterministic IDs**: xxhash64 ensures consistent owner IDs across pipeline runs
221
+ - **File verification**: SHA256 checksums validate all downloads
222
+ - **Version tracking**: Manifest records schema versions and row counts for each snapshot
223
+
224
+ ## Architecture
225
+
226
+ ```
227
+ FAA Data (MASTER, ACFTREF, ENGINE)
228
+ ↓ fetch (with SHA256 verification)
229
+ Raw Text Files (275 MB)
230
+ ↓ normalize (PyArrow type casting)
231
+ Typed Parquet Tables (36 MB)
232
+ ↓ publish (indexing)
233
+ DuckDB (106 MB) + SQLite FTS (55 MB)
234
+ ↓ query
235
+ CLI / Python API
236
+ ```
237
+
238
+ ## Development
239
+
240
+ ```bash
241
+ # Run tests
242
+ make test
243
+
244
+ # Update data
245
+ make update # or: hangar update
246
+
247
+ # Check data status
248
+ make status # or: hangar status
249
+
250
+ # Full pipeline (individual steps)
251
+ make all # fetch, normalize, publish, verify
252
+
253
+ # Individual steps
254
+ make fetch
255
+ make normalize
256
+ make publish
257
+
258
+ # Clean intermediate files
259
+ make clean
260
+ ```
261
+
262
+ ## License
263
+
264
+ MIT
265
+
@@ -0,0 +1,237 @@
1
+ # Hangarbay
2
+
3
+ **Stop struggling with FAA registration data.** Get clean, queryable aircraft registry tables in seconds.
4
+
5
+ Hangarbay downloads, normalizes and indexes the complete [FAA aircraft registry](https://www.faa.gov/licenses_certificates/aircraft_certification/aircraft_registry/releasable_aircraft_download) so you can skip straight to analysis. No more hunting for files to download, or joining fragmented tables, or trying to decoding cryptic lookup relationships. One command gets you 307,000+ aircraft registrations, owners and specifications ready to query with SQL or pandas.
6
+
7
+ This is a tool built for researchers, data journalists and aviation analysts who need fast, reliable and repeatable workflows.
8
+
9
+ ## Quick start
10
+
11
+ **Requirements:** Python 3.9+
12
+
13
+ ### Python API (notebooks & scripts)
14
+
15
+ ```python
16
+ # Install
17
+ pip install hangarbay
18
+
19
+ # One-time setup
20
+ import hangarbay as hb
21
+ hb.load_data() # Downloads & processes FAA data to ~/.hangarbay/data/
22
+
23
+ # Look up aircraft
24
+ df = hb.search("N221LA")
25
+
26
+ # Find fleets
27
+ fleet = hb.fleet("United Airlines")
28
+ fleet = hb.fleet("LAPD|Los Angeles Police", state="CA")
29
+
30
+ # Custom SQL
31
+ df = hb.query("""
32
+ SELECT maker, COUNT(*) as count
33
+ FROM aircraft_decoded
34
+ WHERE year_mfr > 2020
35
+ GROUP BY maker
36
+ ORDER BY count DESC
37
+ """)
38
+
39
+ # Check data age
40
+ info = hb.status()
41
+ print(f"Data is {info['age_days']} days old")
42
+ ```
43
+
44
+ ### Command-line interface
45
+
46
+ ```bash
47
+ # Clone and install
48
+ git clone https://github.com/stiles/hangarbay.git
49
+ cd hangarbay
50
+
51
+ # Recommended: use a virtual environment (uv, venv, conda, etc.)
52
+ uv venv && source .venv/bin/activate # or: python -m venv .venv && source .venv/bin/activate
53
+
54
+ pip install -e ".[dev]"
55
+
56
+ # Run the full pipeline (~2 minutes)
57
+ hangar update # Download, normalize and publish (all-in-one)
58
+
59
+ # Or run steps individually
60
+ hangar fetch # Download FAA data
61
+ hangar normalize # Parse to typed Parquet tables
62
+ hangar publish # Build DuckDB + SQLite FTS indexes
63
+
64
+ # Check data status and age
65
+ hangar status
66
+
67
+ # Start querying!
68
+ hangar search N757AF
69
+ hangar sql "SELECT COUNT(*) FROM aircraft"
70
+ ```
71
+
72
+ ## What this does
73
+
74
+ Hangarbay downloads FAA aircraft registration data, normalizes it into typed tables and provides fast SQL querying:
75
+
76
+ - **307K+ aircraft registrations** with owner and address information
77
+ - **93K+ make/model references** (Cessna, Piper, Boeing, etc.)
78
+ - **4,700+ engine specifications** (horsepower, type, manufacturer)
79
+ - **DuckDB** for analytical SQL queries (sub-second on 300K+ rows)
80
+ - **SQLite FTS5** for full-text search by owner name or address
81
+ - **Parquet** files for efficient columnar storage
82
+ - **Data lineage tracking** with SHA256 checksums and version metadata
83
+ - **Shared data directory** at `~/.hangarbay/data/` - works from any project or notebook
84
+
85
+ ## Features
86
+
87
+ ### N-Number lookup
88
+ Look up any aircraft registration with decoded status codes and human-readable output:
89
+
90
+ ```bash
91
+ hangar search N221LA
92
+ ```
93
+
94
+ ### Fleet search
95
+ Find all aircraft owned by a person or company:
96
+
97
+ ```bash
98
+ # Search by owner name (case-insensitive)
99
+ hangar fleet "United Airlines"
100
+ hangar fleet "LAPD"
101
+ hangar fleet "NetJets"
102
+
103
+ # OR logic with pipe separator (great for finding multiple airlines)
104
+ hangar fleet "LAPD|Los Angeles Police" # Either pattern matches
105
+ hangar fleet "Delta|American|United" # Any of the three
106
+
107
+ # Filter by state
108
+ hangar fleet "Delta" --state GA
109
+
110
+ # Export to CSV
111
+ hangar fleet "Boeing" --export boeing_fleet.csv
112
+
113
+ # Limit results
114
+ hangar fleet "Cessna" --limit 20
115
+ ```
116
+
117
+ ```
118
+ Aircraft Registration: N221LA
119
+
120
+ Owner: LAPD AIR SUPPORT DIVISION
121
+ Location: LOS ANGELES, CA
122
+
123
+ Make & Model: AIRBUS HELICOPTERS INC AS350B3
124
+ Year Manufactured: 2014
125
+ Serial Number: 7900
126
+ Registration Status: Valid
127
+ Certificate Type: Standard Airworthiness - Normal
128
+ Status Date: May 19, 2023
129
+ Expiration: Jun 30, 2028
130
+ ```
131
+
132
+ ### SQL queries
133
+ Execute analytical queries with pretty output:
134
+
135
+ ```bash
136
+ # Total aircraft
137
+ hangar sql "SELECT COUNT(*) FROM aircraft"
138
+
139
+ # Use decoded views for readable output
140
+ hangar sql "SELECT * FROM aircraft_decoded WHERE year_mfr > 2020 LIMIT 10"
141
+ hangar sql "SELECT * FROM owners_clean WHERE owner_name LIKE '%boeing%'" -i
142
+
143
+ # Top manufacturers
144
+ hangar sql "SELECT maker, COUNT(*) as count FROM aircraft
145
+ JOIN aircraft_make_model USING(mfr_mdl_code)
146
+ WHERE maker != '' GROUP BY 1 ORDER BY 2 DESC LIMIT 10"
147
+
148
+ # Lookup status codes
149
+ hangar sql "SELECT * FROM status_codes"
150
+
151
+ # Top states by registrations
152
+ hangar sql "SELECT state_std, COUNT(*) as count FROM owners
153
+ WHERE state_std != '' GROUP BY 1 ORDER BY 2 DESC LIMIT 10"
154
+ ```
155
+
156
+ **Output Formats:**
157
+
158
+ ```bash
159
+ # Pretty table (default)
160
+ hangar sql "SELECT * FROM status_codes LIMIT 3"
161
+
162
+ # JSON output (for APIs/scripts)
163
+ hangar sql "SELECT * FROM status_codes LIMIT 3" --output-format json
164
+
165
+ # CSV output (for Excel/spreadsheets)
166
+ hangar sql "SELECT * FROM status_codes LIMIT 3" --output-format csv
167
+ ```
168
+
169
+ ### Available tables
170
+
171
+ **Core Tables:**
172
+ - **aircraft** - Current registration facts (N-number, serial, make/model, year, status)
173
+ - **registrations** - Canonical registration state (type, status, dates)
174
+ - **owners** - Owner records with raw and standardized addresses
175
+ - **owners_summary** - Aggregated ownership (co-owners, counts)
176
+ - **aircraft_make_model** - Make/model reference (Cessna 172, Boeing 737, etc.)
177
+ - **engines** - Engine specifications (manufacturer, horsepower, type)
178
+
179
+ **Decoded Views (Recommended):**
180
+ - **aircraft_decoded** - Aircraft with decoded status codes and joined make/model
181
+ - **owners_clean** - Simplified owner table (standardized fields only, decoded owner type)
182
+
183
+ **Reference Tables:**
184
+ - **status_codes** - Registration status code lookups
185
+ - **airworthiness_classes** - Airworthiness certificate class lookups
186
+ - **owner_types** - Owner type code lookups
187
+
188
+ ## Data quality
189
+
190
+ - **Type safety**: PyArrow schemas enforce correct data types (dates, integers, strings)
191
+ - **Address standardization**: Uppercase, state/ZIP normalization, whitespace cleanup
192
+ - **Deterministic IDs**: xxhash64 ensures consistent owner IDs across pipeline runs
193
+ - **File verification**: SHA256 checksums validate all downloads
194
+ - **Version tracking**: Manifest records schema versions and row counts for each snapshot
195
+
196
+ ## Architecture
197
+
198
+ ```
199
+ FAA Data (MASTER, ACFTREF, ENGINE)
200
+ ↓ fetch (with SHA256 verification)
201
+ Raw Text Files (275 MB)
202
+ ↓ normalize (PyArrow type casting)
203
+ Typed Parquet Tables (36 MB)
204
+ ↓ publish (indexing)
205
+ DuckDB (106 MB) + SQLite FTS (55 MB)
206
+ ↓ query
207
+ CLI / Python API
208
+ ```
209
+
210
+ ## Development
211
+
212
+ ```bash
213
+ # Run tests
214
+ make test
215
+
216
+ # Update data
217
+ make update # or: hangar update
218
+
219
+ # Check data status
220
+ make status # or: hangar status
221
+
222
+ # Full pipeline (individual steps)
223
+ make all # fetch, normalize, publish, verify
224
+
225
+ # Individual steps
226
+ make fetch
227
+ make normalize
228
+ make publish
229
+
230
+ # Clean intermediate files
231
+ make clean
232
+ ```
233
+
234
+ ## License
235
+
236
+ MIT
237
+
@@ -0,0 +1,48 @@
1
+ """hangarbay - FAA aircraft registry data pipeline.
2
+
3
+ Public API for Python notebooks and scripts.
4
+
5
+ Example usage:
6
+ >>> import hangarbay as hb
7
+ >>> hb.load_data() # One-time setup
8
+ >>> df = hb.search("N221LA") # Look up aircraft
9
+ >>> fleet = hb.fleet("United Airlines") # Find fleet
10
+ >>> df = hb.query("SELECT * FROM aircraft WHERE state='CA'") # Custom SQL
11
+ """
12
+
13
+ __version__ = "0.4.0"
14
+
15
+ # Import public API
16
+ from hangarbay.api import (
17
+ fleet,
18
+ get_connection,
19
+ list_tables,
20
+ load_data,
21
+ query,
22
+ schema,
23
+ search,
24
+ status,
25
+ sync_data,
26
+ update,
27
+ )
28
+ from hangarbay.config import get_data_dir, set_data_dir
29
+
30
+ __all__ = [
31
+ # Data management
32
+ "load_data",
33
+ "sync_data",
34
+ "update",
35
+ "status",
36
+ # Query functions
37
+ "search",
38
+ "fleet",
39
+ "query",
40
+ # Advanced
41
+ "get_connection",
42
+ "list_tables",
43
+ "schema",
44
+ # Config
45
+ "get_data_dir",
46
+ "set_data_dir",
47
+ ]
48
+
@@ -0,0 +1,137 @@
1
+ """Lite address standardization utilities."""
2
+
3
+ import re
4
+ from typing import Optional
5
+
6
+
7
+ # USPS state abbreviations mapping (common variants)
8
+ STATE_ABBREVIATIONS = {
9
+ "ALABAMA": "AL", "ALASKA": "AK", "ARIZONA": "AZ", "ARKANSAS": "AR",
10
+ "CALIFORNIA": "CA", "COLORADO": "CO", "CONNECTICUT": "CT", "DELAWARE": "DE",
11
+ "FLORIDA": "FL", "GEORGIA": "GA", "HAWAII": "HI", "IDAHO": "ID",
12
+ "ILLINOIS": "IL", "INDIANA": "IN", "IOWA": "IA", "KANSAS": "KS",
13
+ "KENTUCKY": "KY", "LOUISIANA": "LA", "MAINE": "ME", "MARYLAND": "MD",
14
+ "MASSACHUSETTS": "MA", "MICHIGAN": "MI", "MINNESOTA": "MN", "MISSISSIPPI": "MS",
15
+ "MISSOURI": "MO", "MONTANA": "MT", "NEBRASKA": "NE", "NEVADA": "NV",
16
+ "NEW HAMPSHIRE": "NH", "NEW JERSEY": "NJ", "NEW MEXICO": "NM", "NEW YORK": "NY",
17
+ "NORTH CAROLINA": "NC", "NORTH DAKOTA": "ND", "OHIO": "OH", "OKLAHOMA": "OK",
18
+ "OREGON": "OR", "PENNSYLVANIA": "PA", "RHODE ISLAND": "RI", "SOUTH CAROLINA": "SC",
19
+ "SOUTH DAKOTA": "SD", "TENNESSEE": "TN", "TEXAS": "TX", "UTAH": "UT",
20
+ "VERMONT": "VT", "VIRGINIA": "VA", "WASHINGTON": "WA", "WEST VIRGINIA": "WV",
21
+ "WISCONSIN": "WI", "WYOMING": "WY",
22
+ "DISTRICT OF COLUMBIA": "DC", "PUERTO RICO": "PR", "GUAM": "GU",
23
+ "VIRGIN ISLANDS": "VI", "AMERICAN SAMOA": "AS", "NORTHERN MARIANA ISLANDS": "MP",
24
+ }
25
+
26
+
27
+ def clean_text(text: Optional[str]) -> str:
28
+ """
29
+ Clean and normalize text: uppercase, trim, collapse whitespace.
30
+
31
+ Args:
32
+ text: Input text (can be None or empty)
33
+
34
+ Returns:
35
+ Cleaned text (empty string if input is None/empty)
36
+ """
37
+ if not text or not isinstance(text, str):
38
+ return ""
39
+
40
+ # Strip leading/trailing whitespace
41
+ text = text.strip()
42
+
43
+ # Collapse multiple spaces to single space
44
+ text = re.sub(r'\s+', ' ', text)
45
+
46
+ # Uppercase
47
+ text = text.upper()
48
+
49
+ return text
50
+
51
+
52
+ def standardize_state(state: Optional[str]) -> str:
53
+ """
54
+ Normalize state to 2-letter USPS abbreviation.
55
+
56
+ Args:
57
+ state: State name or abbreviation
58
+
59
+ Returns:
60
+ 2-letter state code (empty if invalid/unknown)
61
+ """
62
+ if not state or not isinstance(state, str):
63
+ return ""
64
+
65
+ state_clean = state.strip().upper()
66
+
67
+ # Already a 2-letter code?
68
+ if len(state_clean) == 2 and state_clean.isalpha():
69
+ return state_clean
70
+
71
+ # Look up full state name
72
+ return STATE_ABBREVIATIONS.get(state_clean, state_clean[:2] if len(state_clean) >= 2 else "")
73
+
74
+
75
+ def standardize_zip(zip_code: Optional[str]) -> str:
76
+ """
77
+ Normalize ZIP code to 5 digits (US only).
78
+
79
+ Args:
80
+ zip_code: ZIP code (may include ZIP+4, hyphens, spaces)
81
+
82
+ Returns:
83
+ 5-digit ZIP code (empty if invalid)
84
+ """
85
+ if not zip_code or not isinstance(zip_code, str):
86
+ return ""
87
+
88
+ # Extract only digits
89
+ digits = re.sub(r'\D', '', zip_code)
90
+
91
+ # Left-pad to 5 digits with zeros
92
+ if len(digits) > 0:
93
+ return digits[:5].zfill(5)
94
+
95
+ return ""
96
+
97
+
98
+ def combine_address(address1: Optional[str], address2: Optional[str]) -> str:
99
+ """
100
+ Combine address1 and address2 into a single standardized field.
101
+
102
+ Args:
103
+ address1: Primary address line
104
+ address2: Secondary address line
105
+
106
+ Returns:
107
+ Combined address (space-separated if both present)
108
+ """
109
+ addr1 = clean_text(address1)
110
+ addr2 = clean_text(address2)
111
+
112
+ if addr1 and addr2:
113
+ return f"{addr1} {addr2}"
114
+ elif addr1:
115
+ return addr1
116
+ elif addr2:
117
+ return addr2
118
+ else:
119
+ return ""
120
+
121
+
122
+ def standardize_owner_name(name: Optional[str]) -> str:
123
+ """
124
+ Standardize owner name with basic cleanup.
125
+
126
+ Args:
127
+ name: Owner name
128
+
129
+ Returns:
130
+ Cleaned owner name
131
+ """
132
+ cleaned = clean_text(name)
133
+
134
+ # Remove common prefixes that clutter searches (optional enhancement)
135
+ # For MVP, just return cleaned
136
+ return cleaned
137
+