zeolite 0.1.0__tar.gz

zeolite-0.1.0/.cursor/rules/library.mdc

@@ -0,0 +1,39 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+You are an expert in data analysis, data engineering pipelines, and Python library development.
+
+Dependencies:
+- polars
+
+
+Key Principles:
+- Write concise, technical responses with accurate Python examples.
+- Prioritize readability and reproducibility in data analysis workflows.
+- Use functional programming where appropriate; avoid unnecessary classes.
+- Use type hints for all function signatures.
+- Where possible, use dataclasses, TypedDicts, or Pydantic models for input validation and structured output/function returns.
+- Use descriptive variable names that reflect the data they contain.
+- Follow PEP 8 style guidelines for Python code.
+
+Data Analysis and Manipulation:
+- Use Polars for data manipulation and analysis.
+- Use polars' lazy evaluation to optimize performance and memory usage.
+- Avoid using pandas unless absolutely necessary.
+- Prefer method chaining for data transformations when possible.
+
+Error Handling and Data Validation:
+- Handle missing data appropriately (imputation, removal, or flagging).
+- Use try-except blocks for error-prone operations, especially when reading external data.
+- Validate data types and ranges to ensure data integrity.
+
+
+Performance Optimization:
+- Use vectorized operations and lazy evaluation in polars for improved performance.
+- Utilize efficient data structures (e.g., categorical data types for low-cardinality string columns).
+- Consider using dask for larger-than-memory datasets.
+- Profile code to identify and optimize bottlenecks.
+
+Refer to the official documentation of polars for best practices and up-to-date APIs.

zeolite-0.1.0/.cursor/rules/uv.mdc

@@ -0,0 +1,103 @@
+---
+description: Working with Python package management, using UV as the package manager, and running Python, pip, or UV-related CLI commands
+globs: 
+alwaysApply: false
+---
+# UV Command Rules
+
+## General Rules
+- Always use `uv` commands instead of `uv pip` commands
+- Use `uv sync` instead of `uv pip install`
+- Use `uv run` instead of direct command execution
+- Use `uv add` instead of `uv pip install` for adding dependencies
+
+## Common Commands
+
+### Project Setup
+```bash
+# Initialize a new project
+uv init
+
+# Install all dependencies
+uv sync
+
+# Install with dev dependencies
+uv sync --dev
+
+# Install with specific extras
+uv sync --extras dev,test
+```
+
+### Dependency Management
+```bash
+# Add a new dependency
+uv add polars
+
+# Add a development dependency
+uv add --dev pytest
+
+# Add a dependency with version constraint
+uv add "polars>=1.24.0"
+
+# Remove a dependency
+uv remove polars
+
+# Update dependencies
+uv sync
+```
+
+### Running Commands
+```bash
+# Run tests
+uv run pytest
+
+# Run with specific Python version
+uv run --python 3.11 pytest
+
+# Run with all extras
+uv run --all-extras pytest
+```
+
+### Building and Publishing
+```bash
+# Build the package
+uv build
+
+# Publish to PyPI
+uv publish
+```
+
+### Environment Management
+```bash
+# Create a virtual environment
+uv venv
+
+# List installed packages
+uv tree
+
+# Export requirements
+uv export requirements.txt
+```
+
+### Cache Management
+```bash
+# Clean the cache
+uv cache clean
+
+# Prune the cache
+uv cache prune
+```
+
+## Best Practices
+1. Always use `uv sync` for installing dependencies
+2. Use `uv run` for running commands to ensure correct environment
+3. Use `uv add` for adding new dependencies
+4. Use `uv tree` to inspect dependencies
+5. Use `uv cache prune` periodically to manage cache size
+
+## Common Replacements
+- `pip install` → `uv add`
+- `pip install -e .` → `uv sync`
+- `pip install -r requirements.txt` → `uv sync`
+- `python -m pytest` → `uv run pytest`
+- `pip freeze` → `uv export requirements.txt`

zeolite-0.1.0/.github/release-template.md

@@ -0,0 +1,17 @@
+# Release v$VERSION
+
+## Release Notes
+
+$CHANGELOG
+
+## Installation
+
+We recommend [uv package manager](https://github.com/astral-sh/uv)
+
+```bash
+uv add zeolite
+```
+
+## Documentation
+
+For full documentation, visit [documentation site link]. 

zeolite-0.1.0/.github/workflows/prerelease.yml

@@ -0,0 +1,61 @@
+name: Pre-Release
+
+on:
+  push:
+    branches: [ 'release/**' ]
+
+jobs:
+  prerelease:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        enable-cache: true
+        cache-dependency-glob: "uv.lock"
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version-file: "pyproject.toml"
+
+    - name: Get version from branch
+      id: get_version
+      run: |
+        BRANCH_NAME=${GITHUB_REF#refs/heads/}
+        VERSION=${BRANCH_NAME#release/}
+        if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+          echo "Error: Branch name must be in format release/X.Y.Z"
+          exit 1
+        fi
+        echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+    - name: Install the project
+      run: uv sync --all-extras --dev
+
+    - name: Run tests
+      run: uv run pytest
+
+    - name: Build package
+      run: uv build
+
+    - name: Create Pre-Release
+      id: create_release
+      uses: softprops/action-gh-release@v1
+      with:
+        tag_name: v${{ steps.get_version.outputs.version }}-rc
+        name: Release Candidate v${{ steps.get_version.outputs.version }}
+        draft: true
+        prerelease: true
+        files: |
+          dist/*.whl
+          dist/*.tar.gz
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 

zeolite-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,65 @@
+# Publish a release to PyPI.
+#
+# Assumed to run as a subworkflow of .github/workflows/release.yml; specifically, as a publish job
+
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  pypi-publish:
+    name: Upload zeolite to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+    permissions:
+      contents: read
+      id-token: write  # IMPORTANT: this is needed for trusted publishing
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        enable-cache: true
+        cache-dependency-glob: "uv.lock"
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version-file: "pyproject.toml"
+
+    - name: Get version
+      id: get_version
+      run: |
+        # Extract version from tag (remove the 'v' prefix)
+        VERSION=${GITHUB_REF#refs/tags/v}
+        echo "version=$VERSION" >> $GITHUB_OUTPUT
+        
+        # Check if pyproject.toml version matches tag version
+        PYPROJECT_VERSION=$(uvx --from=toml-cli toml get project.version --toml-path=pyproject.toml)
+        if [ "$VERSION" != "$PYPROJECT_VERSION" ]; then
+          echo "Error: Tag version ($VERSION) does not match version in pyproject.toml ($PYPROJECT_VERSION)"
+          exit 1
+        fi
+
+    - name: Install dependencies
+      run: uv sync --all-extras --dev
+
+    - name: Run tests
+      run: uv run pytest
+
+    - name: Build package
+      run: uv build
+
+    - name: Publish package to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        verbose: true
+        # No need to specify password when using trusted publishing 

zeolite-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,99 @@
+name: Release
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        enable-cache: true
+        cache-dependency-glob: "uv.lock"
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version-file: "pyproject.toml"
+
+    - name: Get version
+      id: get_version
+      run: |
+        VERSION=$(uvx --from=toml-cli toml get project.version --toml-path=pyproject.toml)
+        if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+          echo "Error: Version in pyproject.toml must be in format X.Y.Z"
+          exit 1
+        fi
+        echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+    - name: Install the project
+      run: uv sync --all-extras --dev
+
+    - name: Run tests
+      run: uv run pytest
+
+    - name: Build package
+      run: uv build
+
+    - name: Extract changelog
+      id: extract_changelog
+      run: |
+        # Install required tool
+        uv pip install -q python-changelog-generator
+        
+        # Extract changelog for current version
+        if [ -f CHANGELOG.md ]; then
+          CHANGELOG=$(python -m changelog_generator extract --file CHANGELOG.md --version ${{ steps.get_version.outputs.version }})
+          echo "changelog<<EOF" >> $GITHUB_OUTPUT
+          echo "$CHANGELOG" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+        else
+          echo "changelog=No CHANGELOG.md found" >> $GITHUB_OUTPUT
+        fi
+
+    - name: Generate release notes
+      id: release_notes
+      run: |
+        # Read the template
+        TEMPLATE=$(cat .github/release-template.md)
+        
+        # Replace variables
+        NOTES="${TEMPLATE//\$VERSION/${{ steps.get_version.outputs.version }}}"
+        NOTES="${NOTES//\$CHANGELOG/${{ steps.extract_changelog.outputs.changelog }}}"
+        
+        # Output the release notes
+        echo "notes<<EOF" >> $GITHUB_OUTPUT
+        echo "$NOTES" >> $GITHUB_OUTPUT
+        echo "EOF" >> $GITHUB_OUTPUT
+
+    - name: Create Git Tag
+      run: |
+        git config --local user.email "action@github.com"
+        git config --local user.name "GitHub Action"
+        git tag -a v${{ steps.get_version.outputs.version }} -m "Release v${{ steps.get_version.outputs.version }}"
+        git push origin v${{ steps.get_version.outputs.version }}
+
+    - name: Create Release
+      id: create_release
+      uses: softprops/action-gh-release@v1
+      with:
+        tag_name: v${{ steps.get_version.outputs.version }}
+        name: Release v${{ steps.get_version.outputs.version }}
+        body: ${{ steps.release_notes.outputs.notes }}
+        draft: false
+        prerelease: false
+        files: |
+          dist/*.whl
+          dist/*.tar.gz
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 

zeolite-0.1.0/.gitignore

@@ -0,0 +1,166 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+.ruff_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don’t work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.env.shared
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+!packages/env
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDE
+.idea
+
+
+# Data folders
+/app
+.app/*
+!.app/.gitkeep
+!.app/README.md
+
+⚡️data
+data
+
+.data/*
+!.data/.gitkeep
+!.data/README.md
+
+.scratch/*
+!.scratch/.gitkeep
+!.scratch/README.md
+_delta_log
+
+# Exclude CSV and Parquet files
+*.csv
+*.parquet
+
+# Exclude DS_Store files
+*.DS_Store

zeolite-0.1.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### What's Changed
+- Changes in existing functionality
+
+### Deprecated
+- Soon-to-be removed features
+
+### Removed
+- Now removed features
+
+### Fixed
+- Any bug fixes
+
+### Security
+- In case of vulnerabilities
+
+## [0.1.0] - 2025-05-06
+
+### What's Changed
+- Initial release
+- 
+
+[Unreleased]: https://github.com/username/zeolite/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/username/zeolite/releases/tag/v0.1.0 

zeolite-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: zeolite
+Version: 0.1.0
+Summary: A library to process raw data into a structured format
+Requires-Python: >=3.11
+Requires-Dist: polars>=1.29.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.2.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ⚗️ Zeolite
+
+---
+
+Zeolite is a Python library that uses a simple configuration approach to define a table/schema structure. Raw
+data can normalised, cleaned, and validated against the schema in a performant and standardised way. 
+
+The final datasets are guaranteed to be in the correct format and can be easily exported to a variety of formats. 
+In addition, Zeolite captures errors and warnings during the processing of the data, which can be used to improve 
+the quality of the data.
+
+
+
+### Example
+
+```python
+import zeolite as z
+
+individual_schema = z.schema("individual").columns(
+    z.str_col("id")
+    .clean(to="id", prefix="ORG_X::")
+    .validations(
+        z.check_is_value_empty(warning="any", error=0.1, reject=0.01, treat_empty_strings_as_null=True),
+        z.check_is_value_duplicated(check_on_cleaned=True, reject="any"),
+    ),
+    
+    z.str_col("birthdate")
+    .clean(to="date")
+    .validations(z.check_is_value_invalid_date(reject="all")),
+    
+    z.str_col("gender").clean(
+        to="enum",
+        sanitize="lowercase",
+        enum_map={
+            "m": "Male", "male": "Male",
+            "f": "Female", "female": "Female",  
+            "d":"Gender Diverse", "diverse": "Gender Diverse"
+        },
+    ),
+    
+    z.str_col("is_active").clean(
+        to="boolean", 
+        true_values={"yes", "active"}, false_values={"no", "inactive"}
+    ),
+    
+    z.str_col("ethnicity").clean(to="sanitised_string"),
+    z.str_col("ethnicity_2").clean(to="sanitised_string"),
+    z.derived_col(
+        "is_maori",
+        function=(
+            z.ref("ethnicity").clean().col.eq("maori")
+            | z.ref("ethnicity_2").clean().col.eq("maori")
+        ),
+        data_type="boolean",
+    ),
+)
+
+
+```