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.
- hangarbay-0.4.0/LICENSE +22 -0
- hangarbay-0.4.0/PKG-INFO +265 -0
- hangarbay-0.4.0/README.md +237 -0
- hangarbay-0.4.0/hangarbay/__init__.py +48 -0
- hangarbay-0.4.0/hangarbay/address.py +137 -0
- hangarbay-0.4.0/hangarbay/api.py +425 -0
- hangarbay-0.4.0/hangarbay/cli.py +658 -0
- hangarbay-0.4.0/hangarbay/config.py +45 -0
- hangarbay-0.4.0/hangarbay/schemas.py +109 -0
- hangarbay-0.4.0/hangarbay.egg-info/PKG-INFO +265 -0
- hangarbay-0.4.0/hangarbay.egg-info/SOURCES.txt +21 -0
- hangarbay-0.4.0/hangarbay.egg-info/dependency_links.txt +1 -0
- hangarbay-0.4.0/hangarbay.egg-info/entry_points.txt +2 -0
- hangarbay-0.4.0/hangarbay.egg-info/requires.txt +12 -0
- hangarbay-0.4.0/hangarbay.egg-info/top_level.txt +2 -0
- hangarbay-0.4.0/pipelines/__init__.py +2 -0
- hangarbay-0.4.0/pipelines/fetch.py +201 -0
- hangarbay-0.4.0/pipelines/normalize.py +430 -0
- hangarbay-0.4.0/pipelines/publish.py +386 -0
- hangarbay-0.4.0/pyproject.toml +52 -0
- hangarbay-0.4.0/setup.cfg +4 -0
- hangarbay-0.4.0/tests/test_address.py +81 -0
- hangarbay-0.4.0/tests/test_schemas.py +51 -0
hangarbay-0.4.0/LICENSE
ADDED
|
@@ -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
|
+
|
hangarbay-0.4.0/PKG-INFO
ADDED
|
@@ -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
|
+
|