moveq-catalogue 0.1.0__tar.gz

moveq_catalogue-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, moveq contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

moveq_catalogue-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: moveq-catalogue
+Version: 0.1.0
+Summary: Same/replace/omit harmonization registry for cross-country transport-equity section catalogues.
+Author-email: Soura <martisoura@gmail.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/SVamseekar/moveq
+Project-URL: Documentation, https://github.com/SVamseekar/moveq/blob/main/docs/catalogue_guide.md
+Project-URL: Repository, https://github.com/SVamseekar/moveq
+Project-URL: Issues, https://github.com/SVamseekar/moveq/issues
+Project-URL: Changelog, https://github.com/SVamseekar/moveq/blob/main/CHANGELOG.md
+Keywords: transport,equity,harmonization,catalogue,cross-country
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# moveq-catalogue
+
+Registry for the **same / replace / omit** pattern used to extend one country's
+section questionnaire to another country without silent omissions.
+
+[![PyPI](https://img.shields.io/pypi/v/moveq-catalogue.svg)](https://pypi.org/project/moveq-catalogue/)
+[![Python versions](https://img.shields.io/pypi/pyversions/moveq-catalogue.svg)](https://pypi.org/project/moveq-catalogue/)
+[![License](https://img.shields.io/pypi/l/moveq-catalogue.svg)](https://github.com/SVamseekar/moveq/blob/main/LICENSE)
+
+- **same** — the question carries over; only the local data source changes
+- **replace** — the question does not transfer; a locally meaningful replacement is required
+- **omit** — no small-area variable exists; the section is dropped with a note
+
+Most applications should install the umbrella package instead:
+
+```bash
+pip install moveq
+```
+
+## Installation
+
+Requires Python 3.10+.
+
+```bash
+pip install moveq-catalogue
+```
+
+## Usage
+
+```python
+from moveq_catalogue import Catalogue, SectionAction
+
+base_sections = ["coverage_pct", "service_deserts", "policy_scenarios"]
+
+ie = Catalogue(base_sections, country="ireland")
+ie.register("coverage_pct", SectionAction.SAME, note="TFI x CSO Small Area")
+ie.register("service_deserts", SectionAction.SAME)
+ie.register(
+    "policy_scenarios",
+    SectionAction.REPLACE,
+    replacement_title="Connecting Ireland / Local Link / BusConnects",
+)
+
+assert ie.validate() == []  # every base section has been decided
+print(ie.summary())  # {'same': 2, 'replace': 1, 'omit': 0}
+```
+
+`validate()` is the whole point of this package: it fails if a new country
+silently forgets to decide what happens to a base section.
+
+## Documentation
+
+- [Catalogue harmonization guide](https://github.com/SVamseekar/moveq/blob/main/docs/catalogue_guide.md)
+- [API reference](https://github.com/SVamseekar/moveq/blob/main/docs/api_reference.md)
+- [Source repository](https://github.com/SVamseekar/moveq)
+- [Changelog](https://github.com/SVamseekar/moveq/blob/main/CHANGELOG.md)
+
+## License
+
+[BSD 3-Clause](https://github.com/SVamseekar/moveq/blob/main/LICENSE).

moveq_catalogue-0.1.0/README.md

@@ -0,0 +1,60 @@
+# moveq-catalogue
+
+Registry for the **same / replace / omit** pattern used to extend one country's
+section questionnaire to another country without silent omissions.
+
+[![PyPI](https://img.shields.io/pypi/v/moveq-catalogue.svg)](https://pypi.org/project/moveq-catalogue/)
+[![Python versions](https://img.shields.io/pypi/pyversions/moveq-catalogue.svg)](https://pypi.org/project/moveq-catalogue/)
+[![License](https://img.shields.io/pypi/l/moveq-catalogue.svg)](https://github.com/SVamseekar/moveq/blob/main/LICENSE)
+
+- **same** — the question carries over; only the local data source changes
+- **replace** — the question does not transfer; a locally meaningful replacement is required
+- **omit** — no small-area variable exists; the section is dropped with a note
+
+Most applications should install the umbrella package instead:
+
+```bash
+pip install moveq
+```
+
+## Installation
+
+Requires Python 3.10+.
+
+```bash
+pip install moveq-catalogue
+```
+
+## Usage
+
+```python
+from moveq_catalogue import Catalogue, SectionAction
+
+base_sections = ["coverage_pct", "service_deserts", "policy_scenarios"]
+
+ie = Catalogue(base_sections, country="ireland")
+ie.register("coverage_pct", SectionAction.SAME, note="TFI x CSO Small Area")
+ie.register("service_deserts", SectionAction.SAME)
+ie.register(
+    "policy_scenarios",
+    SectionAction.REPLACE,
+    replacement_title="Connecting Ireland / Local Link / BusConnects",
+)
+
+assert ie.validate() == []  # every base section has been decided
+print(ie.summary())  # {'same': 2, 'replace': 1, 'omit': 0}
+```
+
+`validate()` is the whole point of this package: it fails if a new country
+silently forgets to decide what happens to a base section.
+
+## Documentation
+
+- [Catalogue harmonization guide](https://github.com/SVamseekar/moveq/blob/main/docs/catalogue_guide.md)
+- [API reference](https://github.com/SVamseekar/moveq/blob/main/docs/api_reference.md)
+- [Source repository](https://github.com/SVamseekar/moveq)
+- [Changelog](https://github.com/SVamseekar/moveq/blob/main/CHANGELOG.md)
+
+## License
+
+[BSD 3-Clause](https://github.com/SVamseekar/moveq/blob/main/LICENSE).

moveq_catalogue-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "moveq-catalogue"
+version = "0.1.0"
+description = "Same/replace/omit harmonization registry for cross-country transport-equity section catalogues."
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [
+    { name = "Soura", email = "martisoura@gmail.com" },
+]
+keywords = [
+    "transport",
+    "equity",
+    "harmonization",
+    "catalogue",
+    "cross-country",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/SVamseekar/moveq"
+Documentation = "https://github.com/SVamseekar/moveq/blob/main/docs/catalogue_guide.md"
+Repository = "https://github.com/SVamseekar/moveq"
+Issues = "https://github.com/SVamseekar/moveq/issues"
+Changelog = "https://github.com/SVamseekar/moveq/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]

moveq_catalogue-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

moveq_catalogue-0.1.0/src/moveq_catalogue/__init__.py

@@ -0,0 +1,7 @@
+"""moveq-catalogue — same/replace/omit registry for cross-country catalogues."""
+
+from moveq_catalogue.catalogue import Catalogue, SectionAction, SectionMapping
+
+__all__ = ["Catalogue", "SectionAction", "SectionMapping"]
+
+__version__ = "0.1.0"

moveq_catalogue-0.1.0/src/moveq_catalogue/catalogue.py

@@ -0,0 +1,114 @@
+"""Same / replace / omit registry for cross-country section catalogues.
+
+A base country defines a questionnaire (a list of section ids). Every other
+country must explicitly decide, per section, whether to keep the same
+question against local data (``same``), swap in a locally-meaningful
+question (``replace``), or drop the section because no free small-area
+variable exists yet (``omit``). ``Catalogue.validate()`` fails loudly on any
+section left undecided, so a new country can never silently inherit an
+unconsidered section from the base.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+
+class SectionAction(str, Enum):
+    SAME = "same"
+    REPLACE = "replace"
+    OMIT = "omit"
+
+
+@dataclass(frozen=True)
+class SectionMapping:
+    section_id: str
+    action: SectionAction
+    country: str
+    note: str | None = None
+    replacement_title: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.action is SectionAction.REPLACE and not self.replacement_title:
+            raise ValueError(
+                f"section '{self.section_id}': action=replace requires a replacement_title"
+            )
+        if self.action is SectionAction.OMIT and not self.note:
+            raise ValueError(
+                f"section '{self.section_id}': action=omit requires a note explaining why"
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "section_id": self.section_id,
+            "action": self.action.value,
+            "country": self.country,
+            "note": self.note,
+            "replacement_title": self.replacement_title,
+        }
+
+
+class Catalogue:
+    """A country's section-by-section decisions against a base questionnaire."""
+
+    def __init__(self, base_sections: list[str], country: str):
+        if len(base_sections) != len(set(base_sections)):
+            raise ValueError("base_sections must not contain duplicates")
+        self.base_sections = list(base_sections)
+        self.country = country
+        self._mappings: dict[str, SectionMapping] = {}
+
+    def register(
+        self,
+        section_id: str,
+        action: SectionAction,
+        *,
+        note: str | None = None,
+        replacement_title: str | None = None,
+    ) -> "Catalogue":
+        if section_id not in self.base_sections:
+            raise ValueError(
+                f"'{section_id}' is not in the base questionnaire for {self.country}"
+            )
+        self._mappings[section_id] = SectionMapping(
+            section_id=section_id,
+            action=action,
+            country=self.country,
+            note=note,
+            replacement_title=replacement_title,
+        )
+        return self
+
+    def unregistered(self) -> list[str]:
+        """Base sections this country has not yet decided on."""
+        return [s for s in self.base_sections if s not in self._mappings]
+
+    def validate(self) -> list[str]:
+        """Return validation issues; an empty list means fully specified."""
+        issues = []
+        missing = self.unregistered()
+        if missing:
+            issues.append(
+                f"{self.country}: {len(missing)} section(s) not mapped: {', '.join(missing)}"
+            )
+        return issues
+
+    def summary(self) -> dict[str, int]:
+        counts = {action.value: 0 for action in SectionAction}
+        for mapping in self._mappings.values():
+            counts[mapping.action.value] += 1
+        return counts
+
+    def mapping_for(self, section_id: str) -> SectionMapping | None:
+        return self._mappings.get(section_id)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "country": self.country,
+            "base_sections": list(self.base_sections),
+            "mappings": [m.to_dict() for m in self._mappings.values()],
+            "unregistered": self.unregistered(),
+            "summary": self.summary(),
+        }

moveq_catalogue-0.1.0/src/moveq_catalogue.egg-info/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: moveq-catalogue
+Version: 0.1.0
+Summary: Same/replace/omit harmonization registry for cross-country transport-equity section catalogues.
+Author-email: Soura <martisoura@gmail.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/SVamseekar/moveq
+Project-URL: Documentation, https://github.com/SVamseekar/moveq/blob/main/docs/catalogue_guide.md
+Project-URL: Repository, https://github.com/SVamseekar/moveq
+Project-URL: Issues, https://github.com/SVamseekar/moveq/issues
+Project-URL: Changelog, https://github.com/SVamseekar/moveq/blob/main/CHANGELOG.md
+Keywords: transport,equity,harmonization,catalogue,cross-country
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# moveq-catalogue
+
+Registry for the **same / replace / omit** pattern used to extend one country's
+section questionnaire to another country without silent omissions.
+
+[![PyPI](https://img.shields.io/pypi/v/moveq-catalogue.svg)](https://pypi.org/project/moveq-catalogue/)
+[![Python versions](https://img.shields.io/pypi/pyversions/moveq-catalogue.svg)](https://pypi.org/project/moveq-catalogue/)
+[![License](https://img.shields.io/pypi/l/moveq-catalogue.svg)](https://github.com/SVamseekar/moveq/blob/main/LICENSE)
+
+- **same** — the question carries over; only the local data source changes
+- **replace** — the question does not transfer; a locally meaningful replacement is required
+- **omit** — no small-area variable exists; the section is dropped with a note
+
+Most applications should install the umbrella package instead:
+
+```bash
+pip install moveq
+```
+
+## Installation
+
+Requires Python 3.10+.
+
+```bash
+pip install moveq-catalogue
+```
+
+## Usage
+
+```python
+from moveq_catalogue import Catalogue, SectionAction
+
+base_sections = ["coverage_pct", "service_deserts", "policy_scenarios"]
+
+ie = Catalogue(base_sections, country="ireland")
+ie.register("coverage_pct", SectionAction.SAME, note="TFI x CSO Small Area")
+ie.register("service_deserts", SectionAction.SAME)
+ie.register(
+    "policy_scenarios",
+    SectionAction.REPLACE,
+    replacement_title="Connecting Ireland / Local Link / BusConnects",
+)
+
+assert ie.validate() == []  # every base section has been decided
+print(ie.summary())  # {'same': 2, 'replace': 1, 'omit': 0}
+```
+
+`validate()` is the whole point of this package: it fails if a new country
+silently forgets to decide what happens to a base section.
+
+## Documentation
+
+- [Catalogue harmonization guide](https://github.com/SVamseekar/moveq/blob/main/docs/catalogue_guide.md)
+- [API reference](https://github.com/SVamseekar/moveq/blob/main/docs/api_reference.md)
+- [Source repository](https://github.com/SVamseekar/moveq)
+- [Changelog](https://github.com/SVamseekar/moveq/blob/main/CHANGELOG.md)
+
+## License
+
+[BSD 3-Clause](https://github.com/SVamseekar/moveq/blob/main/LICENSE).

moveq_catalogue-0.1.0/src/moveq_catalogue.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/moveq_catalogue/__init__.py
+src/moveq_catalogue/catalogue.py
+src/moveq_catalogue.egg-info/PKG-INFO
+src/moveq_catalogue.egg-info/SOURCES.txt
+src/moveq_catalogue.egg-info/dependency_links.txt
+src/moveq_catalogue.egg-info/requires.txt
+src/moveq_catalogue.egg-info/top_level.txt
+tests/test_catalogue.py

moveq_catalogue-0.1.0/src/moveq_catalogue.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

moveq_catalogue-0.1.0/src/moveq_catalogue.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[test]
+pytest>=7

moveq_catalogue-0.1.0/src/moveq_catalogue.egg-info/top_level.txt

@@ -0,0 +1 @@
+moveq_catalogue

moveq_catalogue-0.1.0/tests/test_catalogue.py

@@ -0,0 +1,61 @@
+import pytest
+
+from moveq_catalogue import Catalogue, SectionAction
+
+BASE = ["coverage_pct", "service_deserts", "policy_scenarios"]
+
+
+def test_same_action_registers_cleanly():
+    cat = Catalogue(BASE, country="ireland")
+    cat.register("coverage_pct", SectionAction.SAME, note="TFI x CSO Small Area")
+    mapping = cat.mapping_for("coverage_pct")
+    assert mapping.action is SectionAction.SAME
+    assert mapping.country == "ireland"
+
+
+def test_replace_without_title_raises():
+    cat = Catalogue(BASE, country="ireland")
+    with pytest.raises(ValueError, match="replacement_title"):
+        cat.register("policy_scenarios", SectionAction.REPLACE)
+
+
+def test_omit_without_note_raises():
+    cat = Catalogue(BASE, country="ireland")
+    with pytest.raises(ValueError, match="note"):
+        cat.register("service_deserts", SectionAction.OMIT)
+
+
+def test_register_unknown_section_raises():
+    cat = Catalogue(BASE, country="ireland")
+    with pytest.raises(ValueError, match="not in the base questionnaire"):
+        cat.register("nonexistent", SectionAction.SAME)
+
+
+def test_validate_flags_unregistered_sections():
+    cat = Catalogue(BASE, country="ireland")
+    cat.register("coverage_pct", SectionAction.SAME)
+    issues = cat.validate()
+    assert len(issues) == 1
+    assert "service_deserts" in issues[0]
+    assert "policy_scenarios" in issues[0]
+
+
+def test_validate_passes_when_fully_mapped():
+    cat = Catalogue(BASE, country="ireland")
+    cat.register("coverage_pct", SectionAction.SAME)
+    cat.register("service_deserts", SectionAction.OMIT, note="no free small-area variable")
+    cat.register("policy_scenarios", SectionAction.REPLACE, replacement_title="Connecting Ireland")
+    assert cat.validate() == []
+
+
+def test_summary_counts_actions():
+    cat = Catalogue(BASE, country="ireland")
+    cat.register("coverage_pct", SectionAction.SAME)
+    cat.register("service_deserts", SectionAction.SAME)
+    cat.register("policy_scenarios", SectionAction.REPLACE, replacement_title="Connecting Ireland")
+    assert cat.summary() == {"same": 2, "replace": 1, "omit": 0}
+
+
+def test_duplicate_base_sections_raise():
+    with pytest.raises(ValueError, match="duplicates"):
+        Catalogue(["a", "a", "b"], country="ireland")