{"id":29883501,"url":"https://github.com/jamesbrink/pypostal-flake","last_synced_at":"2026-04-16T15:33:27.588Z","repository":{"id":306211559,"uuid":"1025379915","full_name":"jamesbrink/pypostal-flake","owner":"jamesbrink","description":"Nix flake providing pypostal (Python bindings for libpostal) - Fast international address parsing/normalization","archived":false,"fork":false,"pushed_at":"2025-08-13T01:06:11.000Z","size":37,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-26T23:12:07.833Z","etag":null,"topics":["address-parsing","geocoding","libpostal","nix","nix-flake","python","python-bindings"],"latest_commit_sha":null,"homepage":null,"language":"Nix","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jamesbrink.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-24T07:03:52.000Z","updated_at":"2025-08-13T01:06:14.000Z","dependencies_parsed_at":"2025-07-24T11:19:06.960Z","dependency_job_id":"90daad6f-6d5d-45f2-8173-fbf5b925d8a6","html_url":"https://github.com/jamesbrink/pypostal-flake","commit_stats":null,"previous_names":["jamesbrink/pypostal-flake"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/jamesbrink/pypostal-flake","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesbrink%2Fpypostal-flake","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesbrink%2Fpypostal-flake/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesbrink%2Fpypostal-flake/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesbrink%2Fpypostal-flake/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jamesbrink","download_url":"https://codeload.github.com/jamesbrink/pypostal-flake/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesbrink%2Fpypostal-flake/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31892377,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T11:36:10.202Z","status":"ssl_error","status_checked_at":"2026-04-16T11:36:09.652Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["address-parsing","geocoding","libpostal","nix","nix-flake","python","python-bindings"],"created_at":"2025-07-31T14:00:29.967Z","updated_at":"2026-04-16T15:33:27.550Z","avatar_url":"https://github.com/jamesbrink.png","language":"Nix","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pypostal-flake\n\nA Nix flake providing [pypostal](https://github.com/openvenues/pypostal) - Python bindings for [libpostal](https://github.com/openvenues/libpostal), a fast statistical parser/normalizer for international street addresses.\n\n[![CI/CD](https://github.com/jamesbrink/pypostal-flake/actions/workflows/ci.yml/badge.svg)](https://github.com/jamesbrink/pypostal-flake/actions/workflows/ci.yml)\n[![Built with Nix](https://img.shields.io/badge/Built_With-Nix-5277C3.svg?logo=nixos\u0026labelColor=73C3D5)](https://nixos.org)\n[![Python Versions](https://img.shields.io/badge/Python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/)\n\n## Table of Contents\n\n- [Features](#features)\n- [Quick Start](#quick-start)\n- [Installation](#installation)\n  - [Install to User Profile](#install-to-user-profile)\n  - [NixOS Configuration](#nixos-configuration)\n  - [Home Manager](#home-manager)\n- [Usage in Your Project](#usage-in-your-project)\n- [Development](#development)\n- [Package Outputs](#package-outputs)\n- [Troubleshooting](#troubleshooting)\n- [License](#license)\n\n## Features\n\n- Pre-built packages for Python 3.10, 3.11, 3.12, and 3.13\n- Automatic handling of libpostal data files via `libpostalWithData`\n- Development shells with all dependencies\n- Overlay support for integration into other flakes\n- Comprehensive test suite\n\n## About libpostal Data\n\nThis flake uses the `libpostalWithData` package from nixpkgs, which includes the large pre-trained statistical models needed for address parsing. The data directory (approximately 2GB) is automatically configured via the `LIBPOSTAL_DATA_DIR` environment variable in all shells and scripts.\n\n## Quick Start\n\n### Try it out instantly\n\n```bash\n# Run the interactive demo\nnix run github:jamesbrink/pypostal-flake\n\n# Parse a specific address\nnix run github:jamesbrink/pypostal-flake -- \"123 Main St, San Francisco, CA 94102\"\n```\n\n### Use in a Nix shell\n\n```bash\n# Python 3.12 (default)\nnix develop github:jamesbrink/pypostal-flake\n\n# Python 3.10\nnix develop github:jamesbrink/pypostal-flake#py310\n\n# Python 3.11\nnix develop github:jamesbrink/pypostal-flake#py311\n\n# Python 3.13\nnix develop github:jamesbrink/pypostal-flake#py313\n```\n\n## Installation\n\n### Install to User Profile\n\n```bash\n# Install default (Python 3.12)\nnix profile add github:jamesbrink/pypostal-flake#pypostal\n\n# Install specific Python version\nnix profile add github:jamesbrink/pypostal-flake#pypostal-py311\n\n# Note: You'll need to set LIBPOSTAL_DATA_DIR environment variable\nexport LIBPOSTAL_DATA_DIR=$(nix eval --raw nixpkgs#libpostalWithData)/share/libpostal\n```\n\n### NixOS Configuration\n\nAdd to your `configuration.nix`:\n\n```nix\n{\n  inputs.pypostal.url = \"github:jamesbrink/pypostal-flake\";\n  \n  # In your system configuration\n  environment.systemPackages = with pkgs; [\n    inputs.pypostal.packages.${system}.pypostal\n    # Or for a specific Python version\n    # inputs.pypostal.packages.${system}.pypostal-py311\n  ];\n  \n  # Set the environment variable system-wide\n  environment.variables = {\n    LIBPOSTAL_DATA_DIR = \"${pkgs.libpostalWithData}/share/libpostal\";\n  };\n}\n```\n\n### Home Manager\n\nAdd to your Home Manager configuration:\n\n```nix\n{ inputs, pkgs, ... }:\n{\n  home.packages = [\n    inputs.pypostal.packages.${pkgs.system}.pypostal\n  ];\n  \n  home.sessionVariables = {\n    LIBPOSTAL_DATA_DIR = \"${pkgs.libpostalWithData}/share/libpostal\";\n  };\n}\n```\n\n## Usage in Your Project\n\nThere are two main ways to use pypostal in your Nix project:\n\n### Method 1: Direct Package Reference (Recommended)\n\nThis method gives you direct control and works reliably for all use cases including development shells:\n\n```nix\n{\n  inputs = {\n    nixpkgs.url = \"github:NixOS/nixpkgs/nixos-unstable\";\n    pypostal-flake.url = \"github:jamesbrink/pypostal-flake\";\n  };\n\n  outputs = { self, nixpkgs, pypostal-flake }:\n    let\n      system = \"x86_64-linux\"; # or your system\n      pkgs = import nixpkgs { inherit system; };\n      \n      # Get the specific pypostal package for your Python version\n      pypostal = pypostal-flake.packages.${system}.pypostal-py312;\n      \n      pythonEnv = pkgs.python312.withPackages (ps: [\n        # Add pypostal directly (not from ps)\n        pypostal\n        # your other Python packages from ps\n        ps.requests\n        ps.numpy\n      ]);\n    in\n    {\n      devShells.${system}.default = pkgs.mkShell {\n        buildInputs = [\n          pythonEnv\n          pkgs.libpostalWithData\n        ];\n        \n        shellHook = ''\n          export LIBPOSTAL_DATA_DIR=\"${pkgs.libpostalWithData}/share/libpostal\"\n        '';\n      };\n    };\n}\n```\n\n### Method 2: Using the Overlay\n\n**Note:** The overlay method has limitations with devShells when used from external flakes. It works best for building packages.\n\nThe overlay adds `pypostal` to all Python package sets:\n\n```nix\n{\n  inputs = {\n    nixpkgs.url = \"github:NixOS/nixpkgs/nixos-unstable\";\n    pypostal-flake.url = \"github:jamesbrink/pypostal-flake\";\n  };\n\n  outputs = { self, nixpkgs, pypostal-flake }:\n    let\n      system = \"x86_64-linux\"; # or your system\n      pkgs = import nixpkgs {\n        inherit system;\n        overlays = [ pypostal-flake.overlays.default ];\n      };\n    in\n    {\n      # Works for packages but not reliably for devShells\n      packages.${system} = {\n        my-app = pkgs.writeScriptBin \"my-app\" ''\n          #!${pkgs.python312.withPackages (ps: [ ps.pypostal ])}/bin/python\n          from postal.parser import parse_address\n          # your application code here\n        '';\n        \n        # Python environment package\n        python-env = pkgs.python312.withPackages (ps: [ ps.pypostal ]);\n      };\n    };\n}\n```\n\n### Package Naming\n\nThe flake provides the following package outputs:\n\n- `pypostal` or `default` - Default package (Python 3.12)\n- `pypostal-py310` - Python 3.10 version\n- `pypostal-py311` - Python 3.11 version  \n- `pypostal-py312` - Python 3.12 version\n- `pypostal-py313` - Python 3.13 version\n\n### Using Multiple Python Versions\n\nWith direct package references:\n\n```nix\npackages = {\n  myapp-py310 = pkgs.python310.withPackages (ps: [\n    pypostal-flake.packages.${system}.pypostal-py310\n  ]);\n  myapp-py311 = pkgs.python311.withPackages (ps: [\n    pypostal-flake.packages.${system}.pypostal-py311\n  ]);\n  myapp-py312 = pkgs.python312.withPackages (ps: [\n    pypostal-flake.packages.${system}.pypostal-py312\n  ]);\n  myapp-py313 = pkgs.python313.withPackages (ps: [\n    pypostal-flake.packages.${system}.pypostal-py313\n  ]);\n};\n```\n\nWith the overlay (for packages only, not devShells):\n\n```nix\n# After applying the overlay to pkgs\npackages = {\n  myapp-py310 = pkgs.python310.withPackages (ps: [ ps.pypostal ]);\n  myapp-py311 = pkgs.python311.withPackages (ps: [ ps.pypostal ]);\n  myapp-py312 = pkgs.python312.withPackages (ps: [ ps.pypostal ]);\n  myapp-py313 = pkgs.python313.withPackages (ps: [ ps.pypostal ]);\n};\n```\n\n## Environment Variables\n\nThe `LIBPOSTAL_DATA_DIR` environment variable must be set to the libpostal data directory. This is automatically configured in the development shells and demo script.\n\n```bash\nexport LIBPOSTAL_DATA_DIR=\"${pkgs.libpostalWithData}/share/libpostal\"\n```\n\n## Example Usage\n\n```python\nfrom postal.parser import parse_address\n\n# Parse an address\nparsed = parse_address(\"The White House, 1600 Pennsylvania Avenue NW, Washington, DC 20500\")\nprint(parsed)\n# Output: [('the white house', 'house'), ('1600', 'house_number'), \n#          ('pennsylvania avenue nw', 'road'), ('washington', 'city'),\n#          ('dc', 'state'), ('20500', 'postcode')]\n\n# Expand an address (normalize abbreviations)\nfrom postal.expand import expand_address\nexpansions = expand_address(\"123 Main St Apt 4\")\nprint(expansions)\n# Output: ['123 main street apartment 4', '123 main st apartment 4', ...]\n```\n\n## Development\n\n### Building locally\n\n```bash\n# Clone the repository\ngit clone https://github.com/jamesbrink/pypostal-flake\ncd pypostal-flake\n\n# Enter development shell\nnix develop\n\n# Run tests\nnix flake check\n\n# Build packages\nnix build .#pypostal-py310\nnix build .#pypostal-py311\nnix build .#pypostal-py312\nnix build .#pypostal-py313\n```\n\n### Running tests\n\n```bash\n# Run all checks\nnix flake check\n\n# Run specific tests\nnix build .#checks.x86_64-linux.pypostal-py312-import\nnix build .#checks.x86_64-linux.pypostal-py312-functionality\n```\n\n## Package Outputs\n\n- `packages.default` - Default pypostal package (Python 3.12)\n- `packages.pypostal` - Same as default\n- `packages.pypostal-py310` - Python 3.10 version\n- `packages.pypostal-py311` - Python 3.11 version\n- `packages.pypostal-py312` - Python 3.12 version\n- `packages.pypostal-py313` - Python 3.13 version\n- `packages.demo` - Demo script\n\n## Overlay\n\nThe overlay adds `pypostal` to all Python package sets:\n\n```nix\noverlays = [ pypostal.overlays.default ];\n\n# Then use with any Python version\npython310.withPackages (ps: [ ps.pypostal ])\npython311.withPackages (ps: [ ps.pypostal ])\npython312.withPackages (ps: [ ps.pypostal ])\npython313.withPackages (ps: [ ps.pypostal ])\n```\n\n## Troubleshooting\n\n### \"No module named 'postal'\" when using the overlay\n\nThe overlay method has limitations when used from external flakes for devShells. If you encounter this error:\n\n1. **Use the direct package reference method instead** (Method 1) for development shells\n2. The overlay works for building packages but not reliably for devShells in external flakes\n3. This is a known Nix limitation with how overlays compose across flake boundaries\n\n### Import Error: \"Could not find libpostal\"\n\nThis error means the libpostal data directory is not set. Ensure `LIBPOSTAL_DATA_DIR` is set correctly:\n\n```bash\nexport LIBPOSTAL_DATA_DIR=\"${pkgs.libpostalWithData}/share/libpostal\"\n```\n\nAlso make sure `libpostalWithData` is included in your `buildInputs`.\n\n### Finding available package versions\n\nTo see all available pypostal packages:\n\n```bash\nnix flake show github:jamesbrink/pypostal-flake\n```\n\n### Building from source fails\n\nMake sure you have the required build dependencies:\n\n```nix\nbuildInputs = [ pkg-config libpostalWithData ];\n```\n\n### Overlay not working in your flake\n\nIf the overlay doesn't work for devShells, use the direct package reference method (Method 1). The overlay method is best suited for building packages, not development shells.\n\n## License\n\nThis flake is released under the MIT License. See [LICENSE](LICENSE) for details.\n\npypostal itself is also MIT licensed.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Acknowledgments\n\n- [libpostal](https://github.com/openvenues/libpostal) - The underlying address parsing library\n- [pypostal](https://github.com/openvenues/pypostal) - Python bindings for libpostal","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamesbrink%2Fpypostal-flake","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjamesbrink%2Fpypostal-flake","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamesbrink%2Fpypostal-flake/lists"}