csan 0.1.0__tar.gz

csan-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: csan
+Version: 0.1.0
+Summary: CLI tool that generates a Cutter-Sanborn identifier, given a first and a last name.
+Keywords: cutter,sanborn,cutter-sanborn,cutter-number,cutter-notation,catalog,cataloging,cataloguing,library,library-catalog,call-number,three-figure,bibliographic,cli,command-line
+Author: VERA LVX
+Author-email: VERA LVX <veralvx@veralvx.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing
+Classifier: Topic :: Text Processing :: General
+Classifier: Topic :: Text Processing :: Indexing
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Maintainer: VERA LVX
+Maintainer-email: VERA LVX <veralvx@veralvx.com>
+Requires-Python: >=3.10
+Project-URL: Changelog, https://github.com/veralvx/csan/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/veralvx/csan
+Project-URL: Homepage, https://github.com/veralvx/csan
+Project-URL: Issues, https://github.com/veralvx/csan/issues
+Project-URL: Releasenotes, https://github.com/veralvx/csan/releases
+Project-URL: Repository, https://github.com/veralvx/csan
+Description-Content-Type: text/markdown
+
+# CSAN: Cutter-Sanborn Number Generator
+
+`csan` is a CLI tool that generates a Cutter-Sanborn identifier, given a first and a last name.
+
+The Cutter-Sanborn identifier, commonly called "Cutter number", is an alphanumeric code used in library classification systems in order to arrange books alphabetically by author. It consists of the first letter of the author's last name followed by three-digit number derived from a predefined [table](https://github.com/veralvx/cutter-sanborn-table). This system was originally developed by Charles Cutter, and revised by Kate Sanborn.
+
+## Installation
+
+You can install this tool using `pip` or `uv`:
+
+```console
+uv tool install csan
+```
+
+```console
+pip install csan
+```
+
+## Usage  
+
+
+```console
+usage: csan [-h] -f FIRST_NAME -l LAST_NAME [-t TITLE] [-v]
+
+Cutter-Sanborn identifier generator.
+
+options:
+  -h, --help            show this help message and exit
+  -f FIRST_NAME, --first-name FIRST_NAME
+  -l LAST_NAME, --last-name LAST_NAME
+  -t TITLE, --title TITLE
+  -v, --verbose
+```
+
+## Examples  
+
+- `csan -f John -l Doe` -> D649
+- `csan -f John -l Doe -t "My Book"` -> D649m
+- `csan -f First -l Last -v` -> L349, with log output to the console
+- `csan -f Jorge -l "De la Cruz"` -> D332

csan-0.1.0/README.md

@@ -0,0 +1,40 @@
+# CSAN: Cutter-Sanborn Number Generator
+
+`csan` is a CLI tool that generates a Cutter-Sanborn identifier, given a first and a last name.
+
+The Cutter-Sanborn identifier, commonly called "Cutter number", is an alphanumeric code used in library classification systems in order to arrange books alphabetically by author. It consists of the first letter of the author's last name followed by three-digit number derived from a predefined [table](https://github.com/veralvx/cutter-sanborn-table). This system was originally developed by Charles Cutter, and revised by Kate Sanborn.
+
+## Installation
+
+You can install this tool using `pip` or `uv`:
+
+```console
+uv tool install csan
+```
+
+```console
+pip install csan
+```
+
+## Usage  
+
+
+```console
+usage: csan [-h] -f FIRST_NAME -l LAST_NAME [-t TITLE] [-v]
+
+Cutter-Sanborn identifier generator.
+
+options:
+  -h, --help            show this help message and exit
+  -f FIRST_NAME, --first-name FIRST_NAME
+  -l LAST_NAME, --last-name LAST_NAME
+  -t TITLE, --title TITLE
+  -v, --verbose
+```
+
+## Examples  
+
+- `csan -f John -l Doe` -> D649
+- `csan -f John -l Doe -t "My Book"` -> D649m
+- `csan -f First -l Last -v` -> L349, with log output to the console
+- `csan -f Jorge -l "De la Cruz"` -> D332

csan-0.1.0/pyproject.toml

@@ -0,0 +1,130 @@
+[project]
+name = "csan"
+version = "0.1.0"
+description = "CLI tool that generates a Cutter-Sanborn identifier, given a first and a last name."
+readme = "README.md"
+authors = [{ name = "VERA LVX", email = "veralvx@veralvx.com" }]
+maintainers = [{ name = "VERA LVX", email = "veralvx@veralvx.com" }]
+license = "Apache-2.0"
+keywords = [
+    "cutter",
+    "sanborn",
+    "cutter-sanborn",
+    "cutter-number",
+    "cutter-notation",
+    "catalog",
+    "cataloging",
+    "cataloguing",
+    "library",
+    "library-catalog",
+    "call-number",
+    "three-figure",
+    "bibliographic",
+    "cli",
+    "command-line"
+]
+requires-python = ">=3.10"
+# https://pypi.org/classifiers/
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: Apache Software License",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "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",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Text Processing",
+    "Topic :: Text Processing :: General",
+    "Topic :: Text Processing :: Indexing",
+    "Topic :: Utilities",
+    "Typing :: Typed"
+]
+
+[project.urls]
+Changelog = "https://github.com/veralvx/csan/blob/main/CHANGELOG.md"
+Documentation = "https://github.com/veralvx/csan"
+Homepage = "https://github.com/veralvx/csan"
+Issues = "https://github.com/veralvx/csan/issues"
+Releasenotes = "https://github.com/veralvx/csan/releases"
+Repository = "https://github.com/veralvx/csan"
+
+[project.scripts]
+csan = "csan.main:main"
+
+[build-system]
+requires = ["uv_build>=0.9.7,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.ruff.lint]
+preview = false
+select = ["ALL"]
+ignore = [
+    "ANN001",
+    "ANN002",
+    "ANN201",
+    "ANN202",
+    "ANN204",
+    "ANN206",
+    "ANN401",
+    "COM812",
+    "CPY001",
+    "D100",
+    "D101",
+    "D102",
+    "D103",
+    "D104",
+    "D105",
+    "D107",
+    "D203",
+    "D212",
+    "D413",
+    "E731",
+    "EM101",
+    "EM102",
+    "ERA001",  #commented-out-code (ERA001)
+    "FIX002",
+    "FURB118",
+    "INP001",
+    "PLR2004",
+    "PLR0904", # Too many public methods (>20)
+    "PLR1702", # too-many-nested-blocks (PLR1702)
+    "PT011",
+    "PTH123",  # use pathlib instead of open
+    "PYI056",
+    "S101",
+    "S404",    # suspicious-subprocess-import
+    "S603",    # `subprocess` call: check for execution of untrusted inputRuff
+    "S607",    # start-process-with-partial-path (S607)
+    "SIM105",  # suppressible-exception (SIM105)
+    "SLF001",  # private-member-access
+    "T201",
+    "TC006",   #runtime-cast-value
+    "TD",
+    "TRY003",
+    "UP030"    #format-literals (UP030)
+]
+
+[tool.pyright]
+typeCheckingMode = "standard"
+
+[dependency-groups]
+dev = [
+    "basedpyright>=1.33.0",
+    "mypy>=1.18.2",
+    "pyrefly>=0.40.0",
+    "pytest>=8.4.2",
+    "ruff>=0.14.4",
+    "ty>=0.0.1a25"
+]

csan-0.1.0/src/csan/__init__.py

@@ -0,0 +1,10 @@
+from .cutter import cutter_identifier, cutter_number
+from .naming import ascii_name, compose_name, process_name
+
+__all__ = [
+    "ascii_name",
+    "compose_name",
+    "cutter_identifier",
+    "cutter_number",
+    "process_name",
+]

csan-0.1.0/src/csan/cutter.py

@@ -0,0 +1,141 @@
+import logging
+
+from .data import CUTTER_DATA
+from .naming import compose_name, process_name
+
+logger = logging.getLogger(__name__)
+
+
+def cutter_number(
+    first_name: str,
+    last_name: str,
+    composed_name: str | None = None,
+    composed_name_abbr: str | None = None,
+    *,
+    verbose: bool = False,
+) -> int:
+    """
+    Generate/Retrieve a cutter-sanborn number, given a first and last name.
+
+    Args:
+        first_name (str): a person's first name (e.g. "Jane");
+        last_name (str): a person's last name (e.g. "Doe");
+        composed_name (str|None): a composition in the format "Last, First";
+        composed_name_abbr (str|None): an abbreviated compositon, format "Last, F."
+        verbose (bool): show debug logs.
+
+    Returns:
+        An integer, retrieved from the Cutter-Sanborn table.
+
+    Raises:
+        ValueError: if no Cutter-Sanborn number is found.
+
+    Examples:
+        >>> cutter_number("First", "Last")
+        349
+    """
+    log_level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(level=log_level, format="%(message)s")
+
+    first_name, last_name = process_name(first_name, last_name)
+
+    if (composed_name is None) or (composed_name_abbr is None):
+        composed_name, composed_name_abbr = compose_name(first_name, last_name)
+
+    cutter_s = None
+
+    obvious_attempts = [
+        composed_name,
+        last_name + f", {first_name[:3]}.",
+        composed_name_abbr,
+        last_name,
+    ]
+
+    if attempt := next((a for a in obvious_attempts if a in CUTTER_DATA), None):
+        logger.debug(
+            "Obvious attempts: %s\nReturning match '%s' from obvious attempts",
+            obvious_attempts,
+            attempt,
+        )
+        return CUTTER_DATA[attempt]
+
+    sieved_data = [k for k in CUTTER_DATA if k.startswith(last_name[0:2])]
+
+    composed_name_decrescent = [
+        composed_name[: i + 1]
+        for i in range(len(composed_name), 0, -1)
+        if not composed_name[: i + 1].endswith((",", " "))
+    ]
+
+    logger.debug("\nDecrescent last name list: %s", composed_name_decrescent)
+
+    for pos, name in enumerate(composed_name_decrescent[1:]):
+        sub_sieved = [
+            k
+            for k in sieved_data
+            if (k.startswith(name) and (len(k) <= len(composed_name)))
+        ]
+
+        if not sub_sieved:
+            continue
+
+        miss_lttrs = list(composed_name_decrescent[0][len(name) :])
+
+        logger.debug("Name: %s\nPos: %s\nSieved List: %s", name, pos, sub_sieved)
+
+        for candidate in sub_sieved:
+            logger.debug("Candidate: %s", candidate)
+
+            if candidate == name:
+                cutter_s = candidate
+            else:
+                xtra_lttrs = list(candidate[len(name) :].replace(".", ""))
+                logger.debug("Missing Letters: %s", miss_lttrs)
+                logger.debug("Extra Letters: %s", xtra_lttrs)
+
+                if not (pairs := list(zip(miss_lttrs, xtra_lttrs, strict=False))):
+                    logger.debug("Pairs are empty. Continuing...")
+                    continue
+
+                logger.debug("Pairs: %s\nMatch: %s.", pairs, cutter_s)
+
+                cutter_s = (
+                    candidate
+                    if all(x >= y and (x.isalpha() == y.isalpha()) for x, y in pairs)
+                    else cutter_s
+                )
+
+            logger.debug("Match: %s\n", cutter_s)
+
+        if cutter_s is not None:
+            return CUTTER_DATA[cutter_s]
+
+        logger.debug("\n")
+
+    if cutter_s is None:
+        raise RuntimeError("Unable to retrieve Cutter-Sanborn number.")
+
+    return 0
+
+
+# first_letters = last_name[0] if last_name[1] in "aeiou" else last_name[0:2].upper()
+def cutter_identifier(
+    last_name: str, cutter_number: int, title: str | None = None
+) -> str:
+    """
+    Generate an identifier based on last name, cutter-sanborn number and a title.
+
+    Args:
+        last_name (str): a person's last name;
+        cutter_number (int): the cutter-sanborn number;
+        title (str): a work's title.
+
+    Returns:
+        A string identifier
+
+    Examples:
+        >>> cutter_identifier("Doe", 649, "Title")
+        'D649t'
+    """
+    title = "" if title is None else title[0].lower()
+    return last_name[0] + str(cutter_number) + title