<p align="center">
<img src="https://github.com/rlapine/shapefile2db/blob/624aa335a27f6db7b56f53907ff8aecf3f031ba7/shapefile2db/assets/ShapeFile2DB_logo.png?raw=true" alt="shapefile2db logo" width="400"/>
</p>
---
### ShapeFile2DB V 0.1.1
Exports US Census ZCTA (Zip Code Tabulation Area) shapefiles to a SQLite database via CLI or Python API.
---
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://github.com/rlapine/shapefile2db/stargazers)
[](https://github.com/rlapine/shapefile2db/network/members)
---
## 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
```bash
pip install shapefile2db
```
Or for local development:
```bash
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
```python
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
```text
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](LICENSE).
---
## Author
Created by Ryan LaPine [@rlapine](https://github.com/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:
📧 github.stunt845@passinbox.com
🔗 GitHub: [@rlapine](https://github.com/rlapine)
Raw data
{
"_id": null,
"home_page": null,
"name": "shapefile2db",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Ryan Lapine <github.stunt845@passinbox.com>",
"keywords": "SQLite, ZCTA, census data, data export, geodata, geospatial, shapefile, spatial database, vector data",
"author": null,
"author_email": "Ryan Lapine <github.stunt845@passinbox.com>",
"download_url": "https://files.pythonhosted.org/packages/3f/1e/4ced55fddf254f3847863c5b679f83b8233ba615df61a7e2eac2927b44e5/shapefile2db-0.1.1.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"https://github.com/rlapine/shapefile2db/blob/624aa335a27f6db7b56f53907ff8aecf3f031ba7/shapefile2db/assets/ShapeFile2DB_logo.png?raw=true\" alt=\"shapefile2db logo\" width=\"400\"/>\n</p>\n\n---\n\n### ShapeFile2DB V 0.1.1\n\nExports US Census ZCTA (Zip Code Tabulation Area) shapefiles to a SQLite database via CLI or Python API.\n\n---\n\n[](https://www.python.org/downloads/)\n[](LICENSE)\n[](https://github.com/rlapine/shapefile2db/stargazers)\n[](https://github.com/rlapine/shapefile2db/network/members)\n\n---\n\n## Overview\n\nZipShapeFile2DB 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. \n\nDesigned for developers and data analysts, it offers a clean command-line interface and a modular API that integrates seamlessly into Python workflows.\n\nWhether 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.\n\n---\n\n## Shapefile Requirements\n\nThis module is designed to work with shapefiles derived from the 2020 ZCTA dataset\nprovided by the US Census Bureau.\n\nTo download the official shapefiles, visit:\nhttps://www.census.gov/geographies/mapping-files/time-series/geo/tiger-line-files.2020.html\n\nThis download will provid a zipped file containing all of the shapefile components (several files)\n\nRequired Shapefile Components:\n\n .shp (Shape Format):\n Contains the primary geometry data for each feature (points, lines, polygons).\n\n .shx (Shape Index Format):\n Provides an index for efficient access to geometry records in the .shp file.\n\n .dbf (dBASE Table Format):\n Stores attribute data linked to each geometry, such as ZIP code and classification.\n\nNote:\n All three files (.shp, .shx, .dbf) are required for full shapefile functionality.\n The .shx file significantly improves performance when accessing large geometries.\n\n---\n\n## Features\n\n- **CLI & API support** for ZCTA shapefile export \n- **Modular architecture** for easy extension and testing \n- **Google-style docstrings** for clarity and discoverability \n- **Built-in validation** for input paths and schema integrity \n- **Geospatial stack ready**: works with `geopandas`, `shapely`, and `SQLAlchemy`\n\n---\n\n### Installation\n\n```bash\npip install shapefile2db\n```\n\nOr for local development:\n\n```bash\ngit clone https://github.com/rlapine/shapefile2db.git\ncd shapefile2db\npip install -e .\n```\n\n---\n\n## Dependencies\n\n- Python 3.8+\n- geopandas==1.1.1\",\n- pandas==2.3.2\",\n- printpop==0.2.2\",\n- pyogrio==0.11.0\",\n- setuptools==80.9.0\",\n- Shapely==2.1.1\",\n- SQLAlchemy==2.0.43\"\n\n---\n\n### API Example\n\n```python\nfrom shapefile2db import export_shapefile_to_db\n\nexport_shapefile_to_db(state=\"NY\",\n shape_file_name=\"tl_2020_us_zcta520.shp\", \n database_name=\"ny_address.db\")\n\n```\n\n---\n\n### Example Output\n\n```text\nShape File: tl_2020_us_zcta520.shp\nRead Start: 12:51:49:25\nRead Timer: 03.20\nRead End: 12:51:52:45\nTotal Rows: 33791\n\nFilter 'NY' Start: 12:51:52:47\nFilter End: 12:51:52:48\nTotal 'NY' Rows: 1826\n\nWarning: Database file not found at: 'C:\\Users\\ryan\\Visual Code Projects\\shapefile\\ny_address.db'\nWarning: Database file created at: 'C:\\Users\\ryan\\Visual Code Projects\\shapefile\\ny_address.db'\n\nDatabase File: ny_address.db\nRows to Export: 1826\nExport Start: 12:51:52:48\nRows Exported: 596 Time Remaining: 00:00:46.\n```\n\n---\n\n### \ud83d\udda5\ufe0f CLI Demo\n\n\n\n---\n\n### Project Structure\n\n```\nshapefile2db/\n\u251c\u2500\u2500 shapefile2db/\n\u2502 \u251c\u2500\u2500 cli.py # CLI entry point\n\u2502 \u251c\u2500\u2500 core.py # Main export logic\n\u2502 \u251c\u2500\u2500 shape_file_exporter.py # Exporter class\n\u2502 \u251c\u2500\u2500 state_shape_file_exporter.py# Individual state exporter\n\u2502 \u2514\u2500\u2500 address_db/ # Subpackage for database logic\n\u2502 \u251c\u2500\u2500 __init__.py # Address DB API exposure\n\u2502 \u251c\u2500\u2500 address_constants.py # state constants\n\u2502 \u251c\u2500\u2500 address_database.py # DB connection and export logic\n\u2502 \u2514\u2500\u2500 address_models.py # ORM models\n\u251c\u2500\u2500 cli.py # CLI entry point\n\u251c\u2500\u2500 core.py # Main export wrapper\n\u251c\u2500\u2500 __init__.py # API exposure\n\u251c\u2500\u2500 LICENSE # Project license\n\u251c\u2500\u2500 pyproject.toml # Build system and CLI entry points\n\u251c\u2500\u2500 requirements.txt # Runtime dependencies\n\u2514\u2500\u2500 README.md # Project overview and usage\n```\n\n---\n\n## Contributing\n\nPull 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.\n\nTo contribute:\n\nFork the repo\n\nAdd your changes with Google-style comments\n\nSubmit a pull request with a clear description\n\nFor style consistency, follow the Python Google Style Guide for functions and comments.\n\n---\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n\n---\n\n## Author\n\nCreated by Ryan LaPine [@rlapine](https://github.com/rlapine) \u2014 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.\n\n---\n\n## Contact\n\nFeel free to reach out with questions or collaboration ideas:\n\n\ud83d\udce7 github.stunt845@passinbox.com \n\ud83d\udd17 GitHub: [@rlapine](https://github.com/rlapine)",
"bugtrack_url": null,
"license": "MIT",
"summary": "Exports US Census ZCTA (Zip Code Tabulation Area) shapefiles to a SQLite database via CLI or Python API.",
"version": "0.1.1",
"project_urls": {
"Documentation": "https://github.com/rlapine/shapefile2db/blob/624aa335a27f6db7b56f53907ff8aecf3f031ba7/README.md",
"Homepage": "https://github.com/rlapine/shapefile2db",
"Repository": "https://github.com/rlapine/shapefile2db"
},
"split_keywords": [
"sqlite",
" zcta",
" census data",
" data export",
" geodata",
" geospatial",
" shapefile",
" spatial database",
" vector data"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2956d815872c4eb98ca3aad4bdc80c18d0ba2a0dfd319b2b66570b12b2474c4f",
"md5": "a96f7923177aa94be8e69bbe51cce7a0",
"sha256": "f87faf111c69ea88ff7ebcc78c4b3ab04538dfe774c912340f60b87a3b1d90c1"
},
"downloads": -1,
"filename": "shapefile2db-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a96f7923177aa94be8e69bbe51cce7a0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 2278625,
"upload_time": "2025-08-25T18:27:39",
"upload_time_iso_8601": "2025-08-25T18:27:39.066729Z",
"url": "https://files.pythonhosted.org/packages/29/56/d815872c4eb98ca3aad4bdc80c18d0ba2a0dfd319b2b66570b12b2474c4f/shapefile2db-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3f1e4ced55fddf254f3847863c5b679f83b8233ba615df61a7e2eac2927b44e5",
"md5": "cc1595beb189bbcc93f367d48fef4db6",
"sha256": "aea5f240b002140fe18ccdc174bcc608d987aa2fa71e3da687357329b3334311"
},
"downloads": -1,
"filename": "shapefile2db-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "cc1595beb189bbcc93f367d48fef4db6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 2277207,
"upload_time": "2025-08-25T18:27:41",
"upload_time_iso_8601": "2025-08-25T18:27:41.082378Z",
"url": "https://files.pythonhosted.org/packages/3f/1e/4ced55fddf254f3847863c5b679f83b8233ba615df61a7e2eac2927b44e5/shapefile2db-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-25 18:27:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rlapine",
"github_project": "shapefile2db",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "geopandas",
"specs": [
[
"==",
"1.1.1"
]
]
},
{
"name": "pandas",
"specs": [
[
"==",
"2.3.2"
]
]
},
{
"name": "printpop",
"specs": [
[
"==",
"0.2.2"
]
]
},
{
"name": "pyogrio",
"specs": [
[
"==",
"0.11.0"
]
]
},
{
"name": "setuptools",
"specs": [
[
"==",
"80.9.0"
]
]
},
{
"name": "Shapely",
"specs": [
[
"==",
"2.1.1"
]
]
},
{
"name": "SQLAlchemy",
"specs": [
[
"==",
"2.0.43"
]
]
}
],
"lcname": "shapefile2db"
}
JSON
