lexeme-type 1.0.0__tar.gz

lexeme_type-1.0.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: lexeme-type
+Version: 1.0.0
+Summary: TODO
+Author: Gwyn Uttmark
+Author-email: biosafetylevel5@gmail.com
+Requires-Python: >=3.11,<3.14
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Provides-Extra: doc
+Provides-Extra: lint
+Provides-Extra: test
+Requires-Dist: commitizen ; extra == "doc"
+Requires-Dist: doc8 ; extra == "doc" or extra == "lint"
+Requires-Dist: mypy ; extra == "lint"
+Requires-Dist: myst-parser ; extra == "doc"
+Requires-Dist: pinkrst ; extra == "doc" or extra == "lint"
+Requires-Dist: prettier ; extra == "lint"
+Requires-Dist: pydantic ; extra == "test"
+Requires-Dist: pytest ; extra == "test"
+Requires-Dist: pytest-cov ; extra == "test"
+Requires-Dist: pytest-xdist ; extra == "test"
+Requires-Dist: ruff ; extra == "lint"
+Requires-Dist: sphinx ; extra == "doc"
+Requires-Dist: sphinx-argparse ; extra == "doc"
+Requires-Dist: sphinx-autodoc-typehints ; extra == "doc"
+Requires-Dist: sphinx-copybutton ; extra == "doc"
+Requires-Dist: sphinx-rtd-theme ; extra == "doc"
+Requires-Dist: sphinxcontrib-mermaid ; extra == "doc"
+Project-URL: Documentation, https://biosafetylvl5.github.io/lexeme-type/
+Project-URL: Homepage, https://github.com/biosafetylvl5/lexeme-type
+Project-URL: Issues, https://github.com/biosafetylvl5/lexeme-type/issues
+Project-URL: Repository, https://github.com/biosafetylvl5/lexeme-type
+Description-Content-Type: text/markdown
+
+# lexeme-type
+
+![Tests](.github/badges/tests-badge.svg)
+![Coverage](.github/badges/coverage-badge.svg)
+![Mypy](.github/badges/mypy-badge.svg)
+![Ruff](.github/badges/ruff-badge.svg)
+![Install](.github/badges/install-badge.svg)
+![CSpell](.github/badges/cspell-badge.svg)
+![Commitizen](.github/badges/commitizen-badge.svg)
+
+[![GitHub stars](https://img.shields.io/github/stars/biosafetylvl5/lexeme-type.svg)](https://github.com/biosafetylvl5/lexeme-type/stargazers)
+
+# Lexeme type
+
+Lightweight no-dependency helper for treating singular and plural spellings as equivalent.
+
+A drop‑in str subclass that normalizes English nouns so that their
+singular and plural forms compare as equal, hash to the same key, and work
+inside Pydantic v2 models. Ignores capitalization.
+
+Examples
+
+```python
+>>> from partial_lexeme.lexeme import Lexeme
+>>> Lexeme("reader") == "readers" == Lexeme("readers")
+True
+>>> {Lexeme("analyses"): 1} == {"analysis": 1}
+True
+
+>>> from pydantic import BaseModel
+>>> class _Plugin(BaseModel):
+>>>     kind: Lexeme
+>>>     interface: Lexeme
+>>> model = _Plugin(kind="reader", interface="readers")
+>>> assert model.kind == model.interface == "reader"
+```
+

lexeme_type-1.0.0/README.md

@@ -0,0 +1,36 @@
+# lexeme-type
+
+![Tests](.github/badges/tests-badge.svg)
+![Coverage](.github/badges/coverage-badge.svg)
+![Mypy](.github/badges/mypy-badge.svg)
+![Ruff](.github/badges/ruff-badge.svg)
+![Install](.github/badges/install-badge.svg)
+![CSpell](.github/badges/cspell-badge.svg)
+![Commitizen](.github/badges/commitizen-badge.svg)
+
+[![GitHub stars](https://img.shields.io/github/stars/biosafetylvl5/lexeme-type.svg)](https://github.com/biosafetylvl5/lexeme-type/stargazers)
+
+# Lexeme type
+
+Lightweight no-dependency helper for treating singular and plural spellings as equivalent.
+
+A drop‑in str subclass that normalizes English nouns so that their
+singular and plural forms compare as equal, hash to the same key, and work
+inside Pydantic v2 models. Ignores capitalization.
+
+Examples
+
+```python
+>>> from partial_lexeme.lexeme import Lexeme
+>>> Lexeme("reader") == "readers" == Lexeme("readers")
+True
+>>> {Lexeme("analyses"): 1} == {"analysis": 1}
+True
+
+>>> from pydantic import BaseModel
+>>> class _Plugin(BaseModel):
+>>>     kind: Lexeme
+>>>     interface: Lexeme
+>>> model = _Plugin(kind="reader", interface="readers")
+>>> assert model.kind == model.interface == "reader"
+```

lexeme_type-1.0.0/pyproject.toml

@@ -0,0 +1,221 @@
+[tool.poetry]
+name = "lexeme-type"
+version = "1.0.0"
+description = "TODO"
+authors = ["Gwyn Uttmark <biosafetylevel5@gmail.com>"]
+license = ""
+repository = "https://github.com/biosafetylvl5/lexeme-type"
+
+packages = [{include="lexeme_type", from="src"}]
+
+readme = "README.md"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Typing :: Typed",
+]
+
+[tool.poetry.dependencies]
+python = ">=3.11,<3.14"
+
+# Optional dependencies for extras
+sphinx = { version = "*", optional = true }
+sphinx-rtd-theme = { version = "*", optional = true }
+sphinx-argparse = { version = "*", optional = true }
+sphinx-copybutton = { version = "*", optional = true }
+sphinx-autodoc-typehints = { version = "*", optional = true }
+sphinxcontrib-mermaid = { version = "*", optional = true }
+myst-parser = { version = "*", optional = true }
+pinkrst = { version = "*", optional = true }
+doc8 = { version = "*", optional = true }
+prettier = { version = "*", optional = true }
+ruff = { version = "*", optional = true }
+mypy = { version = "*", optional = true }
+pytest = { version = "*", optional = true }
+pytest-cov = { version = "*", optional = true }
+pytest-xdist = { version = "*", optional = true }
+commitizen = { version = "*", optional = true }
+pydantic = { version = "*", optional = true }
+
+[tool.poetry.group.dev.dependencies]
+# Development dependencies that are always installed for development
+black = "*"
+pre-commit = "*"
+brassy = "*"
+commitizen = "*"
+
+[tool.poetry.extras]
+doc = [
+    "sphinx",                    # for docs building
+    "myst-parser",
+    "sphinx-rtd-theme",          # for docs building
+    "sphinx-copybutton",         # for docs building
+    "sphinx-autodoc-typehints",  # for docs building
+    "sphinxcontrib-mermaid",     # for docs building
+    "sphinx-argparse",           # for docs building
+    "pinkrst",                   # for rst formatting
+    "doc8",                      # for rst linting
+    "commitizen",                # for better commits
+]
+
+lint = [
+    "pinkrst",                   # for rst auto-formatting
+    "doc8",                      # for rst linting
+    "prettier",                  # YAML, JSON linting
+    "ruff",                      # Python linting
+    "mypy",                      # Type checking
+]
+
+test = [
+    "pytest",                    # for running tests
+    "pytest-cov",                # for test coverage
+    "pytest-xdist",              # for parallel testing
+    "pydantic",                  # for pydantic compat. testing
+]
+
+[tool.poetry.scripts]
+# project_cli = "project.cli:main"
+
+[tool.poetry.urls]
+Homepage = "https://github.com/biosafetylvl5/lexeme-type"
+Issues = "https://github.com/biosafetylvl5/lexeme-type/issues"
+Documentation = "https://biosafetylvl5.github.io/lexeme-type/"
+
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+strict_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+follow_untyped_imports = true
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]
+python_files = "test_*.py"
+norecursedirs = ["xarray_utils"]
+addopts = "-v -rf --ff --cov=src --cov-report=term-missing --cov-report=xml -m \"not limited_test_dataset_availability\""
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "integration: CONCURRENT - marks tests as integration (select with '-m \"integration\"')",
+    "spans_multiple_packages: CONCURRENT - marks integration tests that test functionality that could fail due to errors in multiple repositories. e.g. listing or validating all plugins, etc. Allows calling tests to ensure the same error will not cause tests in multiple repos to fail.",
+    "limited_test_dataset_availability: CONCURRENT - marks integration tests that may have limited test dataset availability so may not be available to all users.",
+    "base: OPTIONAL INDEPENDENT - integration tests that complete very quickly and require only a minimal installation for testing basic functionality within the current repository",
+    "full: REQUIRED INDEPENDENT - integration tests that require a 'full' installation for testing all functionality within the current repository. 'full' marker includes all tests for the current repo except for tests included in the optional 'base' marker.",
+]
+
+[tool.coverage.run]
+source = ["src"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "pass",
+    "raise ImportError",
+]
+
+[tool.bandit]
+exclude_dirs = ["tests", "docs"]
+skips = ["B101"]  # Skip assert warnings
+
+[tool.ruff]
+# Target Python version
+target-version = "py312"
+line-length = 88
+exclude = [
+    "tests",
+    "src/legacy",
+]
+
+[tool.ruff.lint]
+# Enable rules
+select = [
+    "E", "F", "W",  # pycodestyle and Pyflakes
+    "I",            # isort
+    "N",            # PEP8 naming
+    "D",            # pydocstyle
+    "UP",           # pyupgrade
+    "B",            # flake8-bugbear
+    "C4",           # flake8-comprehensions
+    "SIM",          # flake8-simplify
+    "ARG",          # flake8-unused-arguments
+    "ERA",          # eradicate
+    "PL",           # Pylint
+    "RUF",          # Ruff-specific rules
+    "TCH",          # flake8-type-checking
+    "S",            # flake8-bandit (security)
+    "A",            # flake8-builtins
+    "COM",          # flake8-commas
+    "PT",           # flake8-pytest-style
+    "PTH",          # flake8-use-pathlib
+    "TRY",          # tryceratops (exception handling)
+]
+
+ignore = [
+    "D203",  # one-blank-line-before-class (conflicts with D211)
+    "D212",  # multi-line-summary-first-line (conflicts with D213)
+    "E731",  # allow variable assigned lambdas (PLEASE!! I need my lambdas!)
+]
+
+# Allow fix for all enabled rules (when `--fix`) is provided.
+fixable = ["ALL"]
+unfixable = []
+
+# Allow unused variables when underscore-prefixed.
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.ruff.lint.mccabe]
+max-complexity = 5
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+
+[tool.ruff.lint.per-file-ignores]
+# Allow assert statements in tests
+"tests/**/*" = ["S101"]
+# Ignore import violations in __init__.py files
+"__init__.py" = ["F401"]
+
+[tool.ruff.format]
+# Like Black, use double quotes for strings.
+quote-style = "double"
+# Like Black, indent with spaces, rather than tabs.
+indent-style = "space"
+# Like Black, respect magic trailing commas.
+skip-magic-trailing-comma = false
+# Unlike Black, force unix style line endings ("\n")
+line-ending = "lf"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+tag_format = "v$version"
+version_provider = "poetry"

lexeme_type-1.0.0/src/lexeme_type/__init__.py

@@ -0,0 +1,16 @@
+import logging
+
+try:
+    import importlib.metadata
+
+    __version__ = importlib.metadata.version(__package__ or __name__)
+except ModuleNotFoundError:
+    try:
+        import importlib_metadata
+
+        __version__ = importlib_metadata.version(__package__ or __name__)
+    except ModuleNotFoundError:
+        logging.debug(
+            "Could not set __version__ because importlib.metadata is not available."
+            + "If running python 3.7, installing importlib-metadata will fix this issue"
+        )

lexeme_type-1.0.0/src/lexeme_type/lexeme.py

@@ -0,0 +1,261 @@
+# # # This source code is subject to the license referenced at
+# # # https://github.com/NRLMMD-GEOIPS.
+
+"""Lightweight helper for treating singular and plural spellings as equivalent.
+
+A drop‑in str subclass that normalizes English nouns so that their
+singular and plural forms compare as equal, hash to the same key, and work
+inside Pydantic v2 models. Ignores capitalization.
+
+Examples
+--------
+>>> from partial_lexeme import Lexeme
+>>> Lexeme("reader") == "readers" == Lexeme("readers")
+True
+>>> {Lexeme("analyses"): 1} == {"analysis": 1}
+True
+
+>>> from pydantic import BaseModel
+>>> class _Plugin(BaseModel):
+>>>     kind: Lexeme
+>>>     interface: Lexeme
+>>> model = _Plugin(kind="reader", interface="readers")
+>>> assert model.kind == model.interface == "reader"
+"""
+
+from __future__ import annotations
+from typing import Any, Dict
+
+__all__ = ["Lexeme"]
+
+# Irregular nouns – plural ↔ singular
+#   - Each plural maps to its singular
+#   - Singulars map to themselves so that a single lookup works
+_IRREGULAR: Dict[str, str] = {
+    "analyses": "analysis",
+    "analysis": "analysis",
+    "indices": "index",
+    "index": "index",
+    "children": "child",
+    "data": "datum",
+    "criteria": "criterion",
+}
+
+# Reverse map – singular → plural
+_S_TO_P: Dict[str, str] = {
+    singular: plural for plural, singular in _IRREGULAR.items() if plural != singular
+}
+
+
+def _normalize(word: str) -> str:
+    """Convert nouns to their singular form.
+
+    When provided with a noun, whether singular or plural, returns its singular form.
+     This is done using:
+
+        1. An irregular lookup table, `_IRREGULAR` for known exceptions.
+        2. Heuristic suffix rules for regular pluralization:
+
+        - Words ending in "ies" - replace "ies" with "y" if preceded by a consonant
+        - Words in double "zzes" - removes "zes"
+        - Words ending in "sses", "xes", or "zes" - remove "es"
+        - Words ending in "ses" - remove "s"
+        - Words ending in "es" and containing "sh" or "ch" in their singular form -
+            remove "es"
+        - Words ending in singular "s" and more than three characters long - remove "s"
+
+    Parameters
+    ----------
+    word : str
+        The noun in its singular or plural form.
+
+    Returns
+    -------
+    str
+        A plausible singular form of the given word.
+
+    Notes
+    -----
+    - It does not handle all English irregulars such as mice -> mouse unless present
+       in `_IRREGULAR`.
+    - Words that do not match any rule are returned unchanged in lowercase.
+    """
+    w = word.strip().lower()
+    if not w:
+        return ""
+
+    if w in _IRREGULAR:
+        return _IRREGULAR[w]
+
+    # heuristics
+
+    # parties -> party (replace "ies" with "y" if the preceding letter is a consonant)
+    if w.endswith("ies") and len(w) > 3 and w[-4] not in "aeiou":
+        return w[:-3] + "y"
+
+    # quizzes -> quiz (remove "zes")
+    if w.endswith("zzes"):
+        return w[:-3]
+
+    # processes -> process (remove "es")
+    # boxes -> box, buzzes -> buzz (remove "es")
+    if w.endswith(("sses", "xes", "zes")):
+        return w[:-2]
+
+    # processes -> process (remove "s")
+    if w.endswith("ses"):
+        return w[:-1]
+
+    # dishes -> dish, churches -> church (remove "es")
+    if w.endswith("es") and w[-4:-2] in {"sh", "ch"}:
+        return w[:-2]
+
+    # readers -> reader (remove "s")
+    if w.endswith("s") and not w.endswith("ss") and len(w) > 3:
+        return w[:-1]
+
+    return w
+
+
+def _to_plural(word: str) -> str:
+    r"""Return a plausible plural spelling for *word*.
+
+    In this function’s documentation, consider * a regular Linux wildcard character.
+    This function attempts tp pluralize a singular English noun using:
+
+    1. An irregular lookup table, `_S_TO_P` for known exceptions.
+    2. Heuristic spelling rules for regular pluralization:
+
+      - \\*consonant + y --> \\*+ies such as party -> parties
+      - \\*(x, ch, sh, ss, zz) --> \\*+es such as box -> boxes, buzz -> buzzes
+      - \\*z -> \\*+zes --> such as quiz -> quizzes
+      - near-default with min length of two characters -> default+s
+
+    Parameters
+    ----------
+    word : str
+        The singular form of noun.
+
+    Returns
+    -------
+    str
+        A plausible plural form of the given word.
+
+    Raises
+    ------
+    ValueError
+        If the `word` is empty or no pluralization rule can be applied.
+
+    Notes
+    -----
+    -  This is best‑effort but the lexeme type does not depend on it because equality
+       and hashing always normalizes back to singular.
+    -  It does not handle all English irregulars such as mouse -> mice unless present
+       in `_S_TO_P`.
+    - Consider ``*`` a regular Linux wildcard character for reference.
+
+    """
+    w = word.strip().lower()
+
+    # check for irregular words first
+    if w in _S_TO_P:
+        return _S_TO_P[w]
+
+    # heuristics
+
+    # party -> parties (replace "y" with "ies" if preceding by a consonant)
+    if w.endswith("y") and w[-2] not in "aeiou":
+        return w[:-1] + "ies"
+
+    # box -> boxes (ends with "x" -> append "es")
+    # church -> churches (ends with "ch" -> append "es")
+    # dish -> dishes (ends with "sh" -> append "es")
+    # process -> processes  (ends with "ss" -> append "es")
+    # buzz -> buzzes (ends with double "z" -> append "es")
+    if w.endswith(("x", "ch", "sh", "ss", "zz")):
+        return w + "es"
+
+    # quiz -> quizzes (ends with single "z" -> append zes)
+    if w.endswith("z"):
+        return w + "zes"
+
+    # reader -> readers (near default scenario, append "s")
+    if len(w) >= 2:
+        return w + "s"
+
+    raise ValueError(
+        f"No pluralization rule for word: {w}. Check if it's a valid noun!!"
+    )
+
+
+class Lexeme(str):
+    """A string that treats singular and plural spellings as equal.
+
+    It behaves exactly like a built‑in ``str`` but overrides equality and
+    hashing to use the canonical singular form.  This makes singular and
+    plural spellings interchangeable as dict keys, set members, CLI options,
+    etc.
+    """
+
+    def __new__(cls, value: Any) -> "Lexeme":
+        """Create new Lexeme."""
+        if isinstance(value, str):
+            return super().__new__(cls, value)
+        raise TypeError(
+            f"{cls.__name__} must be built from str, got {type(value).__name__}"
+        )
+
+    @property
+    def singular(self) -> "Lexeme":
+        """Return the singular spelling."""
+        return _normalize(self)
+
+    @property
+    def plural(self) -> "Lexeme":
+        """Return a plural spelling."""
+        return _to_plural(self.singular)
+
+    def _key(self) -> str:
+        """Normalize key for comparisons and hashing."""
+        return _normalize(self)
+
+    def __eq__(self, other: object) -> bool:
+        """Plural or singular equality check."""
+        if isinstance(other, str):
+            return self._key() == _normalize(other)
+        if isinstance(other, Lexeme):
+            return self._key() == other._key()
+        return False
+
+    def __hash__(self) -> int:
+        """Hash lexeme."""
+        return hash(self._key())
+
+    def __repr__(self) -> str:
+        """Print out un-serialized self."""
+        return f"{self.__class__.__name__}({super().__str__()!r})"
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, _source_type, _handler):
+        """Return a core_schema that allows ``Lexeme`` for use as a field in pydantic.
+
+        Accepts ``str`` or ``Lexeme``; coerces to ``Lexeme``.
+        Always serializes output as plain string.
+        """
+        # lazy import so only imported if using pydantic
+        from pydantic_core import core_schema
+
+        def _to_lexeme(value: object, _info=None):
+            if isinstance(value, cls):
+                return value
+            if isinstance(value, str):
+                return cls(value)
+            raise TypeError("String or Lexeme required")
+
+        return core_schema.no_info_after_validator_function(
+            _to_lexeme,
+            core_schema.str_schema(),
+            serialization=core_schema.plain_serializer_function_ser_schema(
+                lambda v: str(v)
+            ),
+        )