A Python library and CLI tool for creating, managing, and deploying databases for Datasette-based systems.
This repository is organized as a uv workspace containing:
packages/zeeker/- Core Zeeker package (published to PyPI)packages/zeeker-common/- Common utilities for data projects (published to PyPI)packages/zeeker-datasette/- Datasette deployment package with custom templates and pluginsexamples/- Example data projects demonstrating best practices
pip install zeeker
# Optional: Install common utilities
pip install zeeker-common# Create a new database project
zeeker init my-project
cd my-project
# Add a data resource
zeeker add users --description "User data"
# Edit resources/users.py to implement fetch_data()
# Build the database
zeeker build
# Deploy to S3 (optional)
zeeker deployFor full documentation, see:
- Zeeker Package README - Core package documentation
- Zeeker-Common Package README - Utilities documentation
- Zeeker-Datasette Package README - Deployment package documentation
- Migration Guide - Upgrading from v0.5.x
- Examples - Reference implementations
- Install uv: https://docs.astral.sh/uv/
- Clone repository:
git clone https://github.com/houfu/zeeker.git cd zeeker - Install all workspace dependencies:
uv sync
# Run all tests
uv run pytest
# Run specific package tests
uv run pytest packages/zeeker/tests
uv run pytest packages/zeeker-common/tests
uv run pytest packages/zeeker-datasette/tests
# Run formatting and linting
uv run black .
uv run ruff check .
# Test the CLI
uv run zeeker --helpzeeker/
├── packages/
│ ├── zeeker/ # Core package
│ │ ├── zeeker/ # Source code
│ │ ├── tests/ # Tests
│ │ ├── pyproject.toml # Package config
│ │ └── README.md # Package docs
│ │
│ ├── zeeker-common/ # Utilities package
│ │ ├── zeeker_common/ # Source code
│ │ ├── tests/ # Tests
│ │ ├── pyproject.toml # Package config
│ │ └── README.md # Package docs
│ │
│ └── zeeker-datasette/ # Datasette deployment
│ ├── plugins/ # Custom Datasette plugins
│ ├── templates/ # Jinja templates
│ ├── static/ # CSS, JS, images
│ ├── scripts/ # Deployment scripts
│ ├── tests/ # Tests
│ ├── Dockerfile # Container image
│ ├── pyproject.toml # Package config
│ └── README.md # Package docs
│
├── examples/ # Example projects
│ ├── legal-news/ # Advanced example
│ └── datasets/ # Simple example
│
├── .github/workflows/ # CI/CD
│ ├── test.yml # Test all packages
│ ├── publish-zeeker.yml # Publish zeeker
│ └── publish-common.yml # Publish zeeker-common
│
├── pyproject.toml # Workspace config
├── pytest.ini # Test config
└── README.md # This file
See CONTRIBUTING.md for detailed contribution guidelines.
- Complete Database Projects: Create, build, and deploy entire databases with data resources
- Intelligent Metadata Generation: Auto-generate column descriptions from schema analysis
- Document Fragments: Split large documents into searchable chunks
- Schema Management: Automatic versioning and conflict detection
- S3 Deployment: Direct deployment to S3-compatible storage
- Full-Text Search: Built-in FTS5 support
- Async Support: Concurrent data fetching for better performance
- Shared Utilities: Reusable code in zeeker-common package
- 🔧 Workspace Architecture: Refactored into uv workspace with separate packages
- 📦 PyPI Distribution: Core package available on PyPI
- 🛠️ Shared Utilities: New zeeker-common package with reusable utilities
- 📚 Example Projects: Reference implementations for learning best practices
- 🔄 Unified Dependencies: Single lock file for all workspace members
MIT License - see LICENSE file for details