zipcodes 2.0.1__tar.gz → 3.0.1__tar.gz

{zipcodes-2.0.1 → zipcodes-3.0.1}/Cargo.lock

@@ -216,7 +216,7 @@ checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
 
 [[package]]
 name = "zipcodes"
-version = "2.0.1"
+version = "3.0.1"
 dependencies = [
  "bzip2",
  "serde",
@@ -226,7 +226,7 @@ dependencies = [
 
 [[package]]
 name = "zipcodes-py"
-version = "2.0.1"
+version = "3.0.1"
 dependencies = [
  "pyo3",
  "serde_json",

{zipcodes-2.0.1 → zipcodes-3.0.1}/Cargo.toml

@@ -3,7 +3,7 @@ members = ["crates/zipcodes", "crates/zipcodes-py"]
 resolver = "2"
 
 [workspace.package]
-version = "2.0.1"
+version = "3.0.1"
 edition = "2021"
 rust-version = "1.82"
 authors = ["Sean Pianka <pianka@eml.cc>"]

{zipcodes-2.0.1 → zipcodes-3.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zipcodes
-Version: 2.0.1
+Version: 3.0.1
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3.9
@@ -23,14 +23,12 @@ Project-URL: Issues, https://github.com/seanpianka/zipcodes/issues
 
 # Zipcodes
 
-![PyPI - Python Version](https://img.shields.io/pypi/pyversions/zipcodes)
-[![PyPI](https://img.shields.io/pypi/v/zipcodes)](https://pypi.org/project/zipcodes/)
-[![crates.io](https://img.shields.io/crates/v/zipcodes)](https://crates.io/crates/zipcodes)
-[![Downloads](https://static.pepy.tech/badge/zipcodes/month)](https://pepy.tech/project/zipcodes)
-[![Contributors](https://img.shields.io/github/contributors/seanpianka/zipcodes.svg)](https://github.com/seanpianka/zipcodes/graphs/contributors)
+Python: ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/zipcodes) [![PyPI](https://img.shields.io/pypi/v/zipcodes)](https://pypi.org/project/zipcodes/) [![Python downloads (all time)](https://static.pepy.tech/badge/zipcodes)](https://pepy.tech/project/zipcodes) [![Python downloads (monthly)](https://static.pepy.tech/badge/zipcodes/month)](https://pepy.tech/project/zipcodes)
+
+Rust: [![Minimum Rust version](https://img.shields.io/crates/msrv/zipcodes)](https://crates.io/crates/zipcodes) [![crates.io](https://img.shields.io/crates/v/zipcodes)](https://crates.io/crates/zipcodes) [![Rust downloads (all time)](https://img.shields.io/crates/d/zipcodes?label=downloads%20(all%20time))](https://crates.io/crates/zipcodes) [![Rust downloads (recent)](https://img.shields.io/crates/dr/zipcodes?label=downloads%20(recent))](https://crates.io/crates/zipcodes)
 
 Zipcodes is a simple library for querying U.S. zipcodes. No SQLite, no
-network, no runtime data files — the full dataset is embedded in the package.
+network, no runtime data files — the full dataset is embedded in the package. [![Contributors](https://img.shields.io/github/contributors/seanpianka/zipcodes.svg)](https://github.com/seanpianka/zipcodes/graphs/contributors)
 
 Since 2.0, the library is implemented in Rust and published from a single
 codebase as both the [`zipcodes` Python package](https://pypi.org/project/zipcodes/)
@@ -106,6 +104,17 @@ $ cargo add zipcodes
 - Behavioral notes for upgraders: query results are fresh dicts (mutating a
   result no longer mutates the shared database list), and
   `filter_by(active=1)` no longer matches `active=True` (pass a bool).
+- **Unified validation.** Input validation now lives once, in the Rust core,
+  instead of a separate Python validator. This changes a few edge cases:
+  - **Breaking:** `is_real`/`matching` now raise `ValueError` for input shorter
+    than five characters (after trimming), instead of returning `False`/`[]`.
+  - **Relaxations:** surrounding whitespace (`"  06903  "`) and space-separated
+    Zip+4 (`"12345 6789"`) are now accepted; any input of five or more
+    characters is normalized to its first five digits, generalizing the
+    existing `#####-####` handling.
+  - **Private API removal:** the undocumented helpers `zipcodes._clean` and
+    `zipcodes._contains_nondigits` (and the `_digits`/`_valid_zipcode_length`
+    module attributes) no longer exist.
 
 ## Zipcode Data
 
@@ -135,20 +144,26 @@ automatically.
 To rebuild the dataset manually:
 
 ```shell script
-$ pip install xlrd
+$ pip install -r scripts/requirements.txt
 $ curl -fsSL https://download.geonames.org/export/zip/US.zip -o /tmp/geonames_us.zip
-$ # download the .xls linked from https://postalpro.usps.com/ZIP_Locale_Detail
+$ # download the .xlsx linked from https://postalpro.usps.com/ZIP_Locale_Detail
 $ python scripts/update_zipcode_dataset.py \
     --base scripts/data/zip_code_database.csv \
     --gps scripts/data/zip-codes-database-FREE.csv \
     --geonames-zip /tmp/geonames_us.zip \
-    --usps-xls /tmp/usps_zip_locale.xls \
+    --usps-file /tmp/usps_zip_locale.xlsx \
     --output-bz2 crates/zipcodes/src/zips.json.bz2 \
     --summary-output /tmp/change_summary.json
 ```
 
 ## Tests
 
+[CI](https://github.com/seanpianka/Zipcodes/actions/workflows/ci.yml) runs Rust
+checks and Python tests on pushes to `master` and pull requests. Rust API docs
+are built automatically on [docs.rs](https://docs.rs/zipcodes) after each crate
+release; this README is published to [PyPI](https://pypi.org/project/zipcodes/)
+with each Python release.
+
 The tests are defined in a declarative, table-based format that generates test
 cases.
 
@@ -208,7 +223,7 @@ Traceback (most recent call last):
   ...
 ValueError: Invalid characters, zipcode may only contain digits and "-".
 
->>> zipcodes.matching('064690')
+>>> zipcodes.matching('0646')
 Traceback (most recent call last):
   ...
 ValueError: Invalid format, zipcode must be of the format: "#####" or "#####-####"

{zipcodes-2.0.1 → zipcodes-3.0.1}/README.md

@@ -1,13 +1,11 @@
 # Zipcodes
 
-![PyPI - Python Version](https://img.shields.io/pypi/pyversions/zipcodes)
-[![PyPI](https://img.shields.io/pypi/v/zipcodes)](https://pypi.org/project/zipcodes/)
-[![crates.io](https://img.shields.io/crates/v/zipcodes)](https://crates.io/crates/zipcodes)
-[![Downloads](https://static.pepy.tech/badge/zipcodes/month)](https://pepy.tech/project/zipcodes)
-[![Contributors](https://img.shields.io/github/contributors/seanpianka/zipcodes.svg)](https://github.com/seanpianka/zipcodes/graphs/contributors)
+Python: ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/zipcodes) [![PyPI](https://img.shields.io/pypi/v/zipcodes)](https://pypi.org/project/zipcodes/) [![Python downloads (all time)](https://static.pepy.tech/badge/zipcodes)](https://pepy.tech/project/zipcodes) [![Python downloads (monthly)](https://static.pepy.tech/badge/zipcodes/month)](https://pepy.tech/project/zipcodes)
+
+Rust: [![Minimum Rust version](https://img.shields.io/crates/msrv/zipcodes)](https://crates.io/crates/zipcodes) [![crates.io](https://img.shields.io/crates/v/zipcodes)](https://crates.io/crates/zipcodes) [![Rust downloads (all time)](https://img.shields.io/crates/d/zipcodes?label=downloads%20(all%20time))](https://crates.io/crates/zipcodes) [![Rust downloads (recent)](https://img.shields.io/crates/dr/zipcodes?label=downloads%20(recent))](https://crates.io/crates/zipcodes)
 
 Zipcodes is a simple library for querying U.S. zipcodes. No SQLite, no
-network, no runtime data files — the full dataset is embedded in the package.
+network, no runtime data files — the full dataset is embedded in the package. [![Contributors](https://img.shields.io/github/contributors/seanpianka/zipcodes.svg)](https://github.com/seanpianka/zipcodes/graphs/contributors)
 
 Since 2.0, the library is implemented in Rust and published from a single
 codebase as both the [`zipcodes` Python package](https://pypi.org/project/zipcodes/)
@@ -83,6 +81,17 @@ $ cargo add zipcodes
 - Behavioral notes for upgraders: query results are fresh dicts (mutating a
   result no longer mutates the shared database list), and
   `filter_by(active=1)` no longer matches `active=True` (pass a bool).
+- **Unified validation.** Input validation now lives once, in the Rust core,
+  instead of a separate Python validator. This changes a few edge cases:
+  - **Breaking:** `is_real`/`matching` now raise `ValueError` for input shorter
+    than five characters (after trimming), instead of returning `False`/`[]`.
+  - **Relaxations:** surrounding whitespace (`"  06903  "`) and space-separated
+    Zip+4 (`"12345 6789"`) are now accepted; any input of five or more
+    characters is normalized to its first five digits, generalizing the
+    existing `#####-####` handling.
+  - **Private API removal:** the undocumented helpers `zipcodes._clean` and
+    `zipcodes._contains_nondigits` (and the `_digits`/`_valid_zipcode_length`
+    module attributes) no longer exist.
 
 ## Zipcode Data
 
@@ -112,20 +121,26 @@ automatically.
 To rebuild the dataset manually:
 
 ```shell script
-$ pip install xlrd
+$ pip install -r scripts/requirements.txt
 $ curl -fsSL https://download.geonames.org/export/zip/US.zip -o /tmp/geonames_us.zip
-$ # download the .xls linked from https://postalpro.usps.com/ZIP_Locale_Detail
+$ # download the .xlsx linked from https://postalpro.usps.com/ZIP_Locale_Detail
 $ python scripts/update_zipcode_dataset.py \
     --base scripts/data/zip_code_database.csv \
     --gps scripts/data/zip-codes-database-FREE.csv \
     --geonames-zip /tmp/geonames_us.zip \
-    --usps-xls /tmp/usps_zip_locale.xls \
+    --usps-file /tmp/usps_zip_locale.xlsx \
     --output-bz2 crates/zipcodes/src/zips.json.bz2 \
     --summary-output /tmp/change_summary.json
 ```
 
 ## Tests
 
+[CI](https://github.com/seanpianka/Zipcodes/actions/workflows/ci.yml) runs Rust
+checks and Python tests on pushes to `master` and pull requests. Rust API docs
+are built automatically on [docs.rs](https://docs.rs/zipcodes) after each crate
+release; this README is published to [PyPI](https://pypi.org/project/zipcodes/)
+with each Python release.
+
 The tests are defined in a declarative, table-based format that generates test
 cases.
 
@@ -185,7 +200,7 @@ Traceback (most recent call last):
   ...
 ValueError: Invalid characters, zipcode may only contain digits and "-".
 
->>> zipcodes.matching('064690')
+>>> zipcodes.matching('0646')
 Traceback (most recent call last):
   ...
 ValueError: Invalid format, zipcode must be of the format: "#####" or "#####-####"

zipcodes-3.0.1/crates/zipcodes/examples/gen_schema.rs

@@ -0,0 +1,12 @@
+//! Emit the canonical record schema as JSON for the data pipeline to consume.
+//!
+//! `scripts/update_zipcode_dataset.py` loads `field_order` from the generated
+//! file instead of hard-coding it, and CI diffs the committed copy against fresh
+//! output so a struct/`FIELD_ORDER` change can't ship without refreshing it.
+//!
+//! Regenerate with:
+//!   cargo run -p zipcodes --example gen_schema > scripts/data/schema.json
+fn main() {
+    let schema = serde_json::json!({ "field_order": zipcodes::FIELD_ORDER });
+    println!("{}", serde_json::to_string_pretty(&schema).unwrap());
+}

{zipcodes-2.0.1 → zipcodes-3.0.1}/crates/zipcodes/src/lib.rs

@@ -56,6 +56,31 @@ pub struct Zipcode {
     pub zip_code_type: String,
 }
 
+/// Canonical field order of records in `zips.json` and of the dicts returned by
+/// the Python package. This is the base CSV's historical column order — **not**
+/// alphabetical (the struct above is declared alphabetically; serde matches by
+/// name, so the two need only agree on the field *set*, not its order).
+///
+/// `lat`/`long` are `String` here and round-trip losslessly through serde; if
+/// they ever become `f64`, the serde-based `to_dict` in the Python binding and
+/// the JSON build pipeline must be revisited together.
+pub const FIELD_ORDER: [&str; 14] = [
+    "zip_code",
+    "zip_code_type",
+    "active",
+    "city",
+    "acceptable_cities",
+    "unacceptable_cities",
+    "state",
+    "county",
+    "timezone",
+    "area_codes",
+    "world_region",
+    "country",
+    "lat",
+    "long",
+];
+
 impl Zipcode {
     /// Compare a named field against a JSON value, mirroring the Python
     /// package's `filter_by(**kwargs)` semantics: an unknown field name or a
@@ -211,7 +236,10 @@ pub fn database() -> &'static [Zipcode] {
     &ZIPCODES
 }
 
-fn clean_zipcode(zipcode: &str) -> Result<&str> {
+/// Validate and normalize a full zipcode (`"#####"`, `"#####-####"`, or
+/// `"##### ####"`): trim surrounding whitespace, require at least five
+/// characters, then take the first five and require them to be ASCII digits.
+pub fn clean_zipcode(zipcode: &str) -> Result<&str> {
     let zipcode = zipcode.trim();
     if zipcode.len() < ZIPCODE_LENGTH {
         return Err(Error::InvalidFormat);
@@ -223,11 +251,46 @@ fn clean_zipcode(zipcode: &str) -> Result<&str> {
     Ok(prefix)
 }
 
+/// Validate a partial zipcode (prefix or fragment): after trimming, require
+/// 1–5 ASCII digits. Longer input is [`Error::InvalidFormat`]; non-digits are
+/// [`Error::InvalidCharacters`]. Empty input is also rejected as
+/// [`Error::InvalidFormat`] (the Python shim guards it earlier with a
+/// `TypeError`), so this never returns `Ok("")`.
+pub fn clean_prefix(partial: &str) -> Result<&str> {
+    let partial = partial.trim();
+    if partial.is_empty() || partial.len() > ZIPCODE_LENGTH {
+        return Err(Error::InvalidFormat);
+    }
+    if !partial.chars().all(|c| c.is_ascii_digit()) {
+        return Err(Error::InvalidCharacters);
+    }
+    Ok(partial)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
     use serde_json::json;
 
+    #[test]
+    fn field_order_matches_struct() {
+        // FIELD_ORDER must list exactly the struct's serialized fields. A field
+        // added to one but not the other fails here rather than silently
+        // dropping from the dicts the binding builds.
+        let record = &matching("06903", None).unwrap()[0];
+        let value = serde_json::to_value(record).unwrap();
+        let mut keys: Vec<&str> = value
+            .as_object()
+            .unwrap()
+            .keys()
+            .map(String::as_str)
+            .collect();
+        keys.sort_unstable();
+        let mut expected = FIELD_ORDER.to_vec();
+        expected.sort_unstable();
+        assert_eq!(keys, expected);
+    }
+
     #[test]
     fn should_find_real_zipcodes() {
         assert!(is_real("06903").unwrap());
@@ -295,6 +358,40 @@ mod tests {
         ));
     }
 
+    #[test]
+    fn clean_zipcode_normalizes_valid_input() {
+        assert_eq!(clean_zipcode("12345").unwrap(), "12345");
+        assert_eq!(clean_zipcode("12345-6789").unwrap(), "12345");
+        assert_eq!(clean_zipcode("12345 6789").unwrap(), "12345");
+        assert_eq!(clean_zipcode("  06903  ").unwrap(), "06903");
+    }
+
+    #[test]
+    fn clean_zipcode_rejects_invalid_input() {
+        assert!(matches!(clean_zipcode("123"), Err(Error::InvalidFormat)));
+        assert!(matches!(clean_zipcode("   "), Err(Error::InvalidFormat)));
+        assert!(matches!(
+            clean_zipcode("1234a"),
+            Err(Error::InvalidCharacters)
+        ));
+    }
+
+    #[test]
+    fn clean_prefix_accepts_one_to_five_digits() {
+        for p in ["1", "12", "123", "1234", "12345"] {
+            assert_eq!(clean_prefix(p).unwrap(), p);
+        }
+        assert_eq!(clean_prefix("  10  ").unwrap(), "10");
+    }
+
+    #[test]
+    fn clean_prefix_rejects_invalid_input() {
+        assert!(matches!(clean_prefix("123456"), Err(Error::InvalidFormat)));
+        assert!(matches!(clean_prefix(""), Err(Error::InvalidFormat)));
+        assert!(matches!(clean_prefix("   "), Err(Error::InvalidFormat)));
+        assert!(matches!(clean_prefix("10a"), Err(Error::InvalidCharacters)));
+    }
+
     #[test]
     fn should_include_county_field() {
         let zips = matching("06475", None).unwrap();

zipcodes-3.0.1/crates/zipcodes-py/src/lib.rs

@@ -0,0 +1,264 @@
+//! Native module `zipcodes._zipcodes`.
+//!
+//! Database scans delegate to the `zipcodes` crate's query functions, and the
+//! `zips=` override path (chaining filters over previously returned dicts) is
+//! filtered here in Rust, so the crate is the single implementation of scan
+//! semantics. The Python-facing compat layer (argument validation, exact 1.x
+//! exception messages) lives in `python/zipcodes/__init__.py`.
+
+use pyo3::exceptions::PyValueError;
+use pyo3::prelude::*;
+use pyo3::types::{PyBool, PyDict, PyList};
+use serde_json::Value;
+use zipcodes::Zipcode;
+
+/// Map a core validation error to the 1.x `ValueError`, preserving its message
+/// verbatim. A free helper rather than `impl From<zipcodes::Error> for PyErr`
+/// because both types are foreign to this crate (orphan rule).
+fn to_py_err(e: zipcodes::Error) -> PyErr {
+    PyValueError::new_err(e.to_string())
+}
+
+/// Build a dict in `zipcodes::FIELD_ORDER` order (the 1.x pure-Python key order).
+///
+/// This is hand-written rather than derived from `serde_json::to_value` on
+/// purpose: a serde-based builder iterating `FIELD_ORDER` cannot drift from the
+/// struct, but it allocates a `Map<String, Value>` per record and measured ~60%
+/// slower on `list_all()` (which materializes ~42k dicts) — past our tolerance.
+/// Drift is instead caught by tests, not by construction: `FIELD_ORDER` is
+/// pinned to the struct by `field_order_matches_struct` in the core crate, and
+/// this builder's output is pinned to `FIELD_ORDER` by `tests/test_schema.py`.
+/// Keep the `set_item` order identical to `FIELD_ORDER`.
+fn to_dict<'py>(py: Python<'py>, z: &Zipcode) -> PyResult<Bound<'py, PyDict>> {
+    let dict = PyDict::new(py);
+    dict.set_item("zip_code", &z.zip_code)?;
+    dict.set_item("zip_code_type", &z.zip_code_type)?;
+    dict.set_item("active", z.active)?;
+    dict.set_item("city", &z.city)?;
+    dict.set_item("acceptable_cities", &z.acceptable_cities)?;
+    dict.set_item("unacceptable_cities", &z.unacceptable_cities)?;
+    dict.set_item("state", &z.state)?;
+    dict.set_item("county", &z.county)?;
+    dict.set_item("timezone", &z.timezone)?;
+    dict.set_item("area_codes", &z.area_codes)?;
+    dict.set_item("world_region", &z.world_region)?;
+    dict.set_item("country", &z.country)?;
+    dict.set_item("lat", &z.lat)?;
+    dict.set_item("long", &z.long)?;
+    Ok(dict)
+}
+
+/// Convert crate query results to a list of dicts (1.x field order).
+fn to_pylist<'py>(py: Python<'py>, zips: &[Zipcode]) -> PyResult<Bound<'py, PyList>> {
+    let dicts = zips
+        .iter()
+        .map(|z| to_dict(py, z))
+        .collect::<PyResult<Vec<_>>>()?;
+    PyList::new(py, dicts)
+}
+
+/// Filter a caller-supplied list of dicts, returning the matching items as-is
+/// (no deserialization round-trip, no re-ordering of caller keys). The
+/// predicate treats any per-item failure (missing key, non-dict item,
+/// inconvertible value) as "not a match".
+fn filter_pylist<'py, F>(
+    py: Python<'py>,
+    zips: &Bound<'py, PyList>,
+    pred: F,
+) -> PyResult<Bound<'py, PyList>>
+where
+    F: Fn(&Bound<'py, PyAny>) -> bool,
+{
+    let matches: Vec<_> = zips.iter().filter(|item| pred(item)).collect();
+    PyList::new(py, matches)
+}
+
+/// Extract `item[key]` as a string; `None` on a missing key or non-string value.
+fn get_str(item: &Bound<'_, PyAny>, key: &str) -> Option<String> {
+    item.get_item(key).ok()?.extract::<String>().ok()
+}
+
+/// Extract `item[key]` as a coordinate, accepting str or float values as the
+/// 1.x `float(z["lat"])` did.
+fn get_coordinate(item: &Bound<'_, PyAny>, key: &str) -> Option<f64> {
+    let value = item.get_item(key).ok()?;
+    if let Ok(f) = value.extract::<f64>() {
+        return Some(f);
+    }
+    value.extract::<String>().ok()?.parse::<f64>().ok()
+}
+
+/// Convert a Python filter value to JSON for comparison against record fields.
+/// Returns None for values no record field could ever equal (e.g. sets,
+/// arbitrary objects), which the caller treats as "matches nothing".
+fn py_to_json(value: &Bound<'_, PyAny>) -> Option<Value> {
+    if value.is_none() {
+        return Some(Value::Null);
+    }
+    if let Ok(b) = value.cast::<PyBool>() {
+        return Some(Value::Bool(b.is_true()));
+    }
+    if let Ok(i) = value.extract::<i64>() {
+        return Some(Value::from(i));
+    }
+    if let Ok(f) = value.extract::<f64>() {
+        return Some(Value::from(f));
+    }
+    if let Ok(s) = value.extract::<String>() {
+        return Some(Value::String(s));
+    }
+    if let Ok(list) = value.cast::<PyList>() {
+        let mut arr = Vec::with_capacity(list.len());
+        for item in list.iter() {
+            arr.push(py_to_json(&item)?);
+        }
+        return Some(Value::Array(arr));
+    }
+    None
+}
+
+#[pyfunction]
+#[pyo3(signature = (zipcode, zips=None))]
+fn matching<'py>(
+    py: Python<'py>,
+    zipcode: &str,
+    zips: Option<Bound<'py, PyList>>,
+) -> PyResult<Bound<'py, PyList>> {
+    match zips {
+        None => {
+            let found = zipcodes::matching(zipcode, None).map_err(to_py_err)?;
+            to_pylist(py, &found)
+        }
+        Some(zips) => {
+            let zipcode = zipcodes::clean_zipcode(zipcode).map_err(to_py_err)?;
+            filter_pylist(py, &zips, |item| {
+                get_str(item, "zip_code").as_deref() == Some(zipcode)
+            })
+        }
+    }
+}
+
+#[pyfunction]
+fn is_real(zipcode: &str) -> PyResult<bool> {
+    zipcodes::is_real(zipcode).map_err(to_py_err)
+}
+
+#[pyfunction]
+#[pyo3(signature = (prefix, zips=None))]
+fn similar_to<'py>(
+    py: Python<'py>,
+    prefix: &str,
+    zips: Option<Bound<'py, PyList>>,
+) -> PyResult<Bound<'py, PyList>> {
+    let prefix = zipcodes::clean_prefix(prefix).map_err(to_py_err)?;
+    match zips {
+        None => to_pylist(py, &zipcodes::similar_to(prefix, None)),
+        Some(zips) => filter_pylist(py, &zips, |item| {
+            get_str(item, "zip_code").is_some_and(|zc| zc.starts_with(prefix))
+        }),
+    }
+}
+
+#[pyfunction]
+#[pyo3(signature = (fragment, zips=None))]
+fn contains<'py>(
+    py: Python<'py>,
+    fragment: &str,
+    zips: Option<Bound<'py, PyList>>,
+) -> PyResult<Bound<'py, PyList>> {
+    let fragment = zipcodes::clean_prefix(fragment).map_err(to_py_err)?;
+    match zips {
+        None => to_pylist(py, &zipcodes::contains(fragment, None)),
+        Some(zips) => filter_pylist(py, &zips, |item| {
+            get_str(item, "zip_code").is_some_and(|zc| zc.contains(fragment))
+        }),
+    }
+}
+
+/// Use `kwargs` to select for desired attributes from list of zipcode dicts
+#[pyfunction]
+#[pyo3(signature = (zips=None, **kwargs))]
+fn filter_by<'py>(
+    py: Python<'py>,
+    zips: Option<Bound<'py, PyList>>,
+    kwargs: Option<&Bound<'py, PyDict>>,
+) -> PyResult<Bound<'py, PyList>> {
+    let mut filters = Vec::new();
+    if let Some(kwargs) = kwargs {
+        for (key, value) in kwargs.iter() {
+            let key: String = key.extract()?;
+            match py_to_json(&value) {
+                Some(value) => filters.push((key, value)),
+                // A value of an inconvertible type can never equal a record
+                // field, and all filters must match.
+                None => return Ok(PyList::empty(py)),
+            }
+        }
+    }
+    match zips {
+        None => to_pylist(py, &zipcodes::filter_by_fields(&filters, None)),
+        // Both sides of the comparison go through `py_to_json`, never Python
+        // rich comparison, so e.g. `active=1` does not match a True field.
+        Some(zips) => filter_pylist(py, &zips, |item| {
+            filters.iter().all(|(key, value)| {
+                item.get_item(key.as_str())
+                    .ok()
+                    .and_then(|v| py_to_json(&v))
+                    .as_ref()
+                    == Some(value)
+            })
+        }),
+    }
+}
+
+#[pyfunction]
+#[pyo3(signature = (lat, long, radius_in_miles, zips=None))]
+fn filter_by_coordinates<'py>(
+    py: Python<'py>,
+    lat: f64,
+    long: f64,
+    radius_in_miles: f64,
+    zips: Option<Bound<'py, PyList>>,
+) -> PyResult<Bound<'py, PyList>> {
+    match zips {
+        None => to_pylist(
+            py,
+            &zipcodes::filter_by_coordinates(lat, long, radius_in_miles, None),
+        ),
+        Some(zips) => filter_pylist(py, &zips, |item| {
+            match (get_coordinate(item, "lat"), get_coordinate(item, "long")) {
+                (Some(z_lat), Some(z_long)) => {
+                    zipcodes::haversine(z_long, z_lat, long, lat) <= radius_in_miles
+                }
+                _ => false,
+            }
+        }),
+    }
+}
+
+/// Calculate the great circle distance in miles between two points on the
+/// earth (specified in decimal degrees).
+#[pyfunction]
+fn haversine(lon1: f64, lat1: f64, lon2: f64, lat2: f64) -> f64 {
+    zipcodes::haversine(lon1, lat1, lon2, lat2)
+}
+
+#[pyfunction]
+fn list_all<'py>(py: Python<'py>) -> PyResult<Bound<'py, PyList>> {
+    to_pylist(py, zipcodes::database())
+}
+
+#[pymodule]
+fn _zipcodes(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    m.add("__version__", env!("CARGO_PKG_VERSION"))?;
+    m.add("FIELD_ORDER", zipcodes::FIELD_ORDER.to_vec())?;
+    m.add_function(wrap_pyfunction!(matching, m)?)?;
+    m.add_function(wrap_pyfunction!(is_real, m)?)?;
+    m.add_function(wrap_pyfunction!(similar_to, m)?)?;
+    m.add_function(wrap_pyfunction!(contains, m)?)?;
+    m.add_function(wrap_pyfunction!(filter_by, m)?)?;
+    m.add_function(wrap_pyfunction!(filter_by_coordinates, m)?)?;
+    m.add_function(wrap_pyfunction!(haversine, m)?)?;
+    m.add_function(wrap_pyfunction!(list_all, m)?)?;
+    Ok(())
+}

zipcodes-3.0.1/python/zipcodes/__init__.py

@@ -0,0 +1,116 @@
+"""
+zipcodes
+~~~~~~~~
+
+No-SQLite U.S. zipcode validation Python package, ready for use in AWS Lambda
+
+:author: Sean Pianka
+:github: @seanpianka
+
+All queries — full-database scans and ``zips=`` chaining lists alike — run in
+the compiled Rust extension (``zipcodes._zipcodes``); this module preserves
+the exact 1.x behavior for argument validation and exceptions.
+"""
+import warnings
+
+from zipcodes import _zipcodes
+
+__author__ = "Sean Pianka"
+__email__ = "pianka@eml.cc"
+__license__ = "MIT"
+__version__ = _zipcodes.__version__
+
+_zips_cache = None
+
+
+def _load_zips():
+    global _zips_cache
+    if _zips_cache is None:
+        _zips_cache = _zipcodes.list_all()
+    return _zips_cache
+
+
+def __getattr__(name):
+    # `_zips` was a module-level list in 1.x; keep it importable, but
+    # materialize the 42k dicts lazily instead of at import time.
+    if name == "_zips":
+        return _load_zips()
+    raise AttributeError("module {!r} has no attribute {!r}".format(__name__, name))
+
+
+def _require_str(zipcode):
+    # The only validation that must stay in Python: PyO3's auto-generated
+    # TypeError for a non-str argument has a different message than 1.x. All
+    # format/character validation lives in the Rust core.
+    if not zipcode or not isinstance(zipcode, str):
+        raise TypeError("Invalid type, zipcode must be a string.")
+
+
+def matching(zipcode, zips=None):
+    """Retrieve zipcode dict for provided zipcode"""
+    _require_str(zipcode)
+    return _zipcodes.matching(zipcode, zips=zips)
+
+
+def is_valid(zipcode):
+    _require_str(zipcode)
+    warnings.warn("is_valid is deprecated; use is_real", DeprecationWarning, stacklevel=2)
+    return is_real(zipcode)
+
+
+def is_real(zipcode):
+    """Determine whether a given zip or zip+4 zipcode is real."""
+    _require_str(zipcode)
+    return _zipcodes.is_real(zipcode)
+
+
+def similar_to(partial_zipcode, zips=None):
+    """List of zipcode dicts where zipcode prefix matches `partial_zipcode`"""
+    _require_str(partial_zipcode)
+    return _zipcodes.similar_to(partial_zipcode, zips=zips)
+
+
+def contains(partial_zipcode, zips=None):
+    """List of zipcode dicts where zipcode contains `partial_zipcode` fragment"""
+    _require_str(partial_zipcode)
+    return _zipcodes.contains(partial_zipcode, zips=zips)
+
+
+def filter_by_state(state, zips=None):
+    return filter_by(zips, state=state)
+
+
+def filter_by_city(city, zips=None):
+    return filter_by(zips, city=city)
+
+
+def filter_by_county(county, zips=None):
+    return filter_by(zips, county=county)
+
+
+def filter_by_timezone(timezone, zips=None):
+    return filter_by(zips, timezone=timezone)
+
+
+def filter_by_zip_code_type(zip_code_type, zips=None):
+    return filter_by(zips, zip_code_type=zip_code_type)
+
+
+def filter_by_coordinates(lat, long, radius_in_miles=10, zips=None):
+    """List of zipcode dicts within `radius_in_miles` of (`lat`, `long`)."""
+    return _zipcodes.filter_by_coordinates(lat, long, radius_in_miles, zips=zips)
+
+
+# Pure passthroughs: the native functions already have the desired signature
+# and docstring, so re-export them verbatim rather than wrapping. (The wrappers
+# above add Python-only behavior — a type guard, a default arg, or caching —
+# and so are kept.)
+filter_by = _zipcodes.filter_by
+haversine = _zipcodes.haversine
+
+
+def list_all(zips=None):
+    """Return a list containing all zip-code objects."""
+    if zips is None:
+        return _load_zips()
+    return zips

zipcodes-3.0.1/python/zipcodes/_zipcodes.pyi

@@ -0,0 +1,26 @@
+from typing import Any, Dict, List, Optional
+
+__version__: str
+FIELD_ORDER: List[str]
+
+def matching(
+    zipcode: str, zips: Optional[List[Dict[str, Any]]] = None
+) -> List[Dict[str, Any]]: ...
+def is_real(zipcode: str) -> bool: ...
+def similar_to(
+    prefix: str, zips: Optional[List[Dict[str, Any]]] = None
+) -> List[Dict[str, Any]]: ...
+def contains(
+    fragment: str, zips: Optional[List[Dict[str, Any]]] = None
+) -> List[Dict[str, Any]]: ...
+def filter_by(
+    zips: Optional[List[Dict[str, Any]]] = None, **filters: Any
+) -> List[Dict[str, Any]]: ...
+def filter_by_coordinates(
+    lat: float,
+    long: float,
+    radius_in_miles: float,
+    zips: Optional[List[Dict[str, Any]]] = None,
+) -> List[Dict[str, Any]]: ...
+def haversine(lon1: float, lat1: float, lon2: float, lat2: float) -> float: ...
+def list_all() -> List[Dict[str, Any]]: ...

zipcodes-2.0.1/crates/zipcodes-py/src/lib.rs

@@ -1,156 +0,0 @@
-//! Native module `zipcodes._zipcodes`.
-//!
-//! The Python-facing compat layer (validation, exact 1.x exception messages,
-//! `zips=` chaining over caller-supplied dicts) lives in
-//! `python/zipcodes/__init__.py`; this module only handles scans over the
-//! embedded database, materializing matching records as Python dicts.
-
-use pyo3::prelude::*;
-use pyo3::types::{PyBool, PyDict, PyList};
-use serde_json::Value;
-use zipcodes::Zipcode;
-
-/// Build a dict with the same field order the 1.x pure-Python package produced.
-fn to_dict<'py>(py: Python<'py>, z: &Zipcode) -> PyResult<Bound<'py, PyDict>> {
-    let dict = PyDict::new(py);
-    dict.set_item("zip_code", &z.zip_code)?;
-    dict.set_item("zip_code_type", &z.zip_code_type)?;
-    dict.set_item("active", z.active)?;
-    dict.set_item("city", &z.city)?;
-    dict.set_item("acceptable_cities", &z.acceptable_cities)?;
-    dict.set_item("unacceptable_cities", &z.unacceptable_cities)?;
-    dict.set_item("state", &z.state)?;
-    dict.set_item("county", &z.county)?;
-    dict.set_item("timezone", &z.timezone)?;
-    dict.set_item("area_codes", &z.area_codes)?;
-    dict.set_item("world_region", &z.world_region)?;
-    dict.set_item("country", &z.country)?;
-    dict.set_item("lat", &z.lat)?;
-    dict.set_item("long", &z.long)?;
-    Ok(dict)
-}
-
-fn collect<'py, F>(py: Python<'py>, predicate: F) -> PyResult<Bound<'py, PyList>>
-where
-    F: Fn(&Zipcode) -> bool,
-{
-    let dicts = zipcodes::database()
-        .iter()
-        .filter(|z| predicate(z))
-        .map(|z| to_dict(py, z))
-        .collect::<PyResult<Vec<_>>>()?;
-    PyList::new(py, dicts)
-}
-
-/// Convert a Python filter value to JSON for comparison against record fields.
-/// Returns None for values no record field could ever equal (e.g. sets,
-/// arbitrary objects), which the caller treats as "matches nothing".
-fn py_to_json(value: &Bound<'_, PyAny>) -> Option<Value> {
-    if value.is_none() {
-        return Some(Value::Null);
-    }
-    if let Ok(b) = value.cast::<PyBool>() {
-        return Some(Value::Bool(b.is_true()));
-    }
-    if let Ok(i) = value.extract::<i64>() {
-        return Some(Value::from(i));
-    }
-    if let Ok(f) = value.extract::<f64>() {
-        return Some(Value::from(f));
-    }
-    if let Ok(s) = value.extract::<String>() {
-        return Some(Value::String(s));
-    }
-    if let Ok(list) = value.cast::<PyList>() {
-        let mut arr = Vec::with_capacity(list.len());
-        for item in list.iter() {
-            arr.push(py_to_json(&item)?);
-        }
-        return Some(Value::Array(arr));
-    }
-    None
-}
-
-/// `zipcode` arrives pre-validated by the Python shim (digits only, length <= 5).
-#[pyfunction]
-fn matching<'py>(py: Python<'py>, zipcode: &str) -> PyResult<Bound<'py, PyList>> {
-    collect(py, |z| z.zip_code == zipcode)
-}
-
-#[pyfunction]
-fn is_real(zipcode: &str) -> bool {
-    zipcodes::database().iter().any(|z| z.zip_code == zipcode)
-}
-
-#[pyfunction]
-fn similar_to<'py>(py: Python<'py>, prefix: &str) -> PyResult<Bound<'py, PyList>> {
-    collect(py, |z| z.zip_code.starts_with(prefix))
-}
-
-#[pyfunction]
-fn contains<'py>(py: Python<'py>, fragment: &str) -> PyResult<Bound<'py, PyList>> {
-    collect(py, |z| z.zip_code.contains(fragment))
-}
-
-#[pyfunction]
-#[pyo3(signature = (**kwargs))]
-fn filter_by<'py>(
-    py: Python<'py>,
-    kwargs: Option<&Bound<'py, PyDict>>,
-) -> PyResult<Bound<'py, PyList>> {
-    let mut filters = Vec::new();
-    if let Some(kwargs) = kwargs {
-        for (key, value) in kwargs.iter() {
-            let key: String = key.extract()?;
-            match py_to_json(&value) {
-                Some(value) => filters.push((key, value)),
-                // A value of an inconvertible type can never equal a record
-                // field, and all filters must match.
-                None => return Ok(PyList::empty(py)),
-            }
-        }
-    }
-    let filters = filters; // freeze for the closure
-    collect(py, |z| filters.iter().all(|(k, v)| z.field_matches(k, v)))
-}
-
-#[pyfunction]
-fn filter_by_coordinates<'py>(
-    py: Python<'py>,
-    lat: f64,
-    long: f64,
-    radius_in_miles: f64,
-) -> PyResult<Bound<'py, PyList>> {
-    collect(py, |z| {
-        match (z.lat.parse::<f64>(), z.long.parse::<f64>()) {
-            (Ok(z_lat), Ok(z_long)) => {
-                zipcodes::haversine(z_long, z_lat, long, lat) <= radius_in_miles
-            }
-            _ => false,
-        }
-    })
-}
-
-#[pyfunction]
-fn haversine(lon1: f64, lat1: f64, lon2: f64, lat2: f64) -> f64 {
-    zipcodes::haversine(lon1, lat1, lon2, lat2)
-}
-
-#[pyfunction]
-fn list_all<'py>(py: Python<'py>) -> PyResult<Bound<'py, PyList>> {
-    collect(py, |_| true)
-}
-
-#[pymodule]
-fn _zipcodes(m: &Bound<'_, PyModule>) -> PyResult<()> {
-    m.add("__version__", env!("CARGO_PKG_VERSION"))?;
-    m.add_function(wrap_pyfunction!(matching, m)?)?;
-    m.add_function(wrap_pyfunction!(is_real, m)?)?;
-    m.add_function(wrap_pyfunction!(similar_to, m)?)?;
-    m.add_function(wrap_pyfunction!(contains, m)?)?;
-    m.add_function(wrap_pyfunction!(filter_by, m)?)?;
-    m.add_function(wrap_pyfunction!(filter_by_coordinates, m)?)?;
-    m.add_function(wrap_pyfunction!(haversine, m)?)?;
-    m.add_function(wrap_pyfunction!(list_all, m)?)?;
-    Ok(())
-}

zipcodes-2.0.1/python/zipcodes/__init__.py

@@ -1,174 +0,0 @@
-"""
-zipcodes
-~~~~~~~~
-
-No-SQLite U.S. zipcode validation Python package, ready for use in AWS Lambda
-
-:author: Sean Pianka
-:github: @seanpianka
-
-The full-database scans run in the compiled Rust extension
-(``zipcodes._zipcodes``); this module preserves the exact 1.x behavior for
-argument validation, exceptions, and the ``zips=`` chaining lists.
-"""
-import re
-import warnings
-from math import asin, cos, radians, sin, sqrt
-
-from zipcodes import _zipcodes
-
-__author__ = "Sean Pianka"
-__email__ = "pianka@eml.cc"
-__license__ = "MIT"
-__version__ = _zipcodes.__version__
-
-_digits = re.compile(r"[^\d\-]")
-_valid_zipcode_length = 5
-
-_zips_cache = None
-
-
-def _load_zips():
-    global _zips_cache
-    if _zips_cache is None:
-        _zips_cache = _zipcodes.list_all()
-    return _zips_cache
-
-
-def __getattr__(name):
-    # `_zips` was a module-level list in 1.x; keep it importable, but
-    # materialize the 42k dicts lazily instead of at import time.
-    if name == "_zips":
-        return _load_zips()
-    raise AttributeError("module {!r} has no attribute {!r}".format(__name__, name))
-
-
-def _clean_zipcode(fn):
-    def decorator(zipcode, *args, **kwargs):
-        if not zipcode or not isinstance(zipcode, str):
-            raise TypeError("Invalid type, zipcode must be a string.")
-
-        return fn(
-            _clean(zipcode, min(len(zipcode), _valid_zipcode_length)), *args, **kwargs
-        )
-
-    return decorator
-
-
-@_clean_zipcode
-def matching(zipcode, zips=None):
-    """Retrieve zipcode dict for provided zipcode"""
-    if zips is None:
-        return _zipcodes.matching(zipcode)
-    return [z for z in zips if z["zip_code"] == zipcode]
-
-
-@_clean_zipcode
-def is_valid(zipcode):
-    warnings.warn("is_valid is deprecated; use is_real", DeprecationWarning, stacklevel=2)
-    return is_real(zipcode)
-
-
-@_clean_zipcode
-def is_real(zipcode):
-    """Determine whether a given zip or zip+4 zipcode is real."""
-    return _zipcodes.is_real(zipcode)
-
-
-@_clean_zipcode
-def similar_to(partial_zipcode, zips=None):
-    """List of zipcode dicts where zipcode prefix matches `partial_zipcode`"""
-    if zips is None:
-        return _zipcodes.similar_to(partial_zipcode)
-    return [z for z in zips if z["zip_code"].startswith(partial_zipcode)]
-
-
-@_clean_zipcode
-def contains(partial_zipcode, zips=None):
-    """List of zipcode dicts where zipcode contains `partial_zipcode` fragment"""
-    if zips is None:
-        return _zipcodes.contains(partial_zipcode)
-    return [z for z in zips if partial_zipcode in z["zip_code"]]
-
-
-def filter_by_state(state, zips=None):
-    return filter_by(zips, state=state)
-
-
-def filter_by_city(city, zips=None):
-    return filter_by(zips, city=city)
-
-
-def filter_by_county(county, zips=None):
-    return filter_by(zips, county=county)
-
-
-def filter_by_timezone(timezone, zips=None):
-    return filter_by(zips, timezone=timezone)
-
-
-def filter_by_zip_code_type(zip_code_type, zips=None):
-    return filter_by(zips, zip_code_type=zip_code_type)
-
-
-def haversine(lon1, lat1, lon2, lat2):
-    """
-    Calculate the great circle distance in miles between two points
-    on the earth (specified in decimal degrees)
-    """
-    lon1, lat1, lon2, lat2 = map(radians, [lon1, lat1, lon2, lat2])
-
-    dlon = lon2 - lon1
-    dlat = lat2 - lat1
-    a = sin(dlat / 2) ** 2 + cos(lat1) * cos(lat2) * sin(dlon / 2) ** 2
-    c = 2 * asin(sqrt(a))
-    r = 3956  # Radius of earth in miles. Use 6371 for kilometers.
-    return c * r
-
-
-def filter_by_coordinates(lat, long, radius_in_miles=10, zips=None):
-    """List of zipcode dicts within `radius_in_miles` of (`lat`, `long`)."""
-    if zips is None:
-        return _zipcodes.filter_by_coordinates(lat, long, radius_in_miles)
-    return [
-        z
-        for z in zips
-        if haversine(float(z["long"]), float(z["lat"]), long, lat) <= radius_in_miles
-    ]
-
-
-def filter_by(zips=None, **filters):
-    """Use `kwargs` to select for desired attributes from list of zipcode dicts"""
-    if zips is None:
-        return _zipcodes.filter_by(**filters)
-    return [
-        z
-        for z in zips
-        if all(key in z and z[key] == value for key, value in filters.items())
-    ]
-
-
-def list_all(zips=None):
-    """Return a list containing all zip-code objects."""
-    if zips is None:
-        return _load_zips()
-    return zips
-
-
-def _contains_nondigits(s):
-    return bool(_digits.search(s))
-
-
-def _clean(zipcode, valid_length=_valid_zipcode_length):
-    """Assumes zipcode is of type `str`"""
-    zipcode = zipcode.split("-")[0]  # Convert #####-#### to #####
-
-    if len(zipcode) != valid_length:
-        raise ValueError(
-            'Invalid format, zipcode must be of the format: "#####" or "#####-####"'
-        )
-
-    if _contains_nondigits(zipcode):
-        raise ValueError('Invalid characters, zipcode may only contain digits and "-".')
-
-    return zipcode

zipcodes-2.0.1/python/zipcodes/_zipcodes.pyi

@@ -1,14 +0,0 @@
-from typing import Any, Dict, List
-
-__version__: str
-
-def matching(zipcode: str) -> List[Dict[str, Any]]: ...
-def is_real(zipcode: str) -> bool: ...
-def similar_to(prefix: str) -> List[Dict[str, Any]]: ...
-def contains(fragment: str) -> List[Dict[str, Any]]: ...
-def filter_by(**filters: Any) -> List[Dict[str, Any]]: ...
-def filter_by_coordinates(
-    lat: float, long: float, radius_in_miles: float
-) -> List[Dict[str, Any]]: ...
-def haversine(lon1: float, lat1: float, lon2: float, lat2: float) -> float: ...
-def list_all() -> List[Dict[str, Any]]: ...