shapefile2db 0.1.0

Exports US Census ZCTA (Zip Code Tabulation Area) shapefiles to a SQLite database via CLI or Python API.

---

ShapeFile2DB V 0.1.0

Exports US Census ZCTA (Zip Code Tabulation Area) shapefiles to a SQLite database via CLI or Python API.

---

---

Overview

ZipShapeFile2DB is a Python package for extracting, filtering, and exporting ZIP Code Tabulation Area (ZCTA) shapefiles into structured formats for geospatial analysis in a SQLite3 database file.

Designed for developers and data analysts, it offers a clean command-line interface and a modular API that integrates seamlessly into Python workflows.

Whether you're automating shapefile exports, building spatial dashboards, or prepping data for SQL-based queries, ZipShapeFile2DB provides a transparent, scriptable pipeline with real-time logging, schema validation, and flexible output options.

---

Shapefile Requirements

This module is designed to work with shapefiles derived from the 2020 ZCTA dataset provided by the US Census Bureau.

To download the official shapefiles, visit: https://www.census.gov/geographies/mapping-files/time-series/geo/tiger-line-files.2020.html

This download will provid a zipped file containing all of the shapefile components (several files)

Required Shapefile Components:

.shp (Shape Format):
    Contains the primary geometry data for each feature (points, lines, polygons).

.shx (Shape Index Format):
    Provides an index for efficient access to geometry records in the .shp file.

.dbf (dBASE Table Format):
    Stores attribute data linked to each geometry, such as ZIP code and classification.

Note: All three files (.shp, .shx, .dbf) are required for full shapefile functionality. The .shx file significantly improves performance when accessing large geometries.

---

Features

• CLI & API support for ZCTA shapefile export
• Modular architecture for easy extension and testing
• Google-style docstrings for clarity and discoverability
• Built-in validation for input paths and schema integrity
• Geospatial stack ready: works with geopandas, shapely, and SQLAlchemy

---

Installation

pip install shapefile2db

Or for local development:

git clone https://github.com/rlapine/shapefile2db.git
cd shapefile2db
pip install -e .

---

Dependencies

• Python 3.8+
• geopandas==1.1.1",
• pandas==2.3.2",
• printpop==0.2.2",
• pyogrio==0.11.0",
• setuptools==80.9.0",
• Shapely==2.1.1",
• SQLAlchemy==2.0.43"

---

API Example

from shapefile2db import export_shapefile_to_db

export_shapefile_to_db(state="NY",
                      shape_file_name="tl_2020_us_zcta520.shp", 
                      database_name="ny_address.db")

---

Example Output

Shape File: tl_2020_us_zcta520.shp
Read Start: 12:51:49:25
Read Timer: 03.20
Read End: 12:51:52:45
Total Rows: 33791

Filter 'NY' Start: 12:51:52:47
Filter End: 12:51:52:48
Total 'NY' Rows: 1826

Warning: Database file not found at: 'C:\Users\ryan\Visual Code Projects\shapefile\ny_address.db'
Warning: Database file created at: 'C:\Users\ryan\Visual Code Projects\shapefile\ny_address.db'

Database File: ny_address.db
Rows to Export: 1826
Export Start: 12:51:52:48
Rows Exported: 596 Time Remaining: 00:00:46.

---

🖥️ CLI Demo

---

Project Structure

shapefile2db/
├── shapefile2db/
│   ├── cli.py                      # CLI entry point
│   ├── core.py                     # Main export logic
│   ├── shape_file_exporter.py      # Exporter class
│   ├── state_shape_file_exporter.py# Individual state exporter
│   └── address_db/                 # Subpackage for database logic
│       ├── __init__.py             # Address DB API exposure
│       ├── address_constants.py    # state constants
│       ├── address_database.py     # DB connection and export logic
│       └── address_models.py       # ORM models
├── cli.py                          # CLI entry point
├── core.py                         # Main export wrapper
├── __init__.py                     # API exposure
├── LICENSE                         # Project license
├── pyproject.toml                  # Build system and CLI entry points
├── requirements.txt                # Runtime dependencies
└── README.md                       # Project overview and usage

---

Contributing

Pull requests welcome! If you spot formatting quirks, want to add new named colors or extend features (like terminal detection or theme presets), feel free to collaborate.

To contribute:

Fork the repo

Add your changes with Google-style comments

Submit a pull request with a clear description

For style consistency, follow the Python Google Style Guide for functions and comments.

---

License

This project is licensed under the MIT License.

---

Author

Created by Ryan LaPine @rlapine — a technically skilled developer focused on clarity, maintainability, and audience-ready documentation. This class is part of a broader effort to build reusable, well-documented tools for data-driven projects.

---

Contact

Feel free to reach out with questions or collaboration ideas:

📧 [e-mail]
🔗 GitHub: @rlapine