hardguard25 1.3.0__tar.gz

hardguard25-1.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Snap Synapse LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hardguard25-1.3.0/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: hardguard25
+Version: 1.3.0
+Summary: HardGuard25: A human-friendly unique ID alphabet. 25 unambiguous characters.
+Author-email: Snap Synapse <info@snapsynapse.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/snapsynapse/hardguard25
+Project-URL: Documentation, https://github.com/snapsynapse/hardguard25/blob/main/SPEC.md
+Project-URL: Repository, https://github.com/snapsynapse/hardguard25
+Keywords: id,uid,unique-id,identifier,human-readable,unambiguous
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# hardguard25
+
+A human-friendly unique ID alphabet. 25 unambiguous characters, zero confusion.
+
+```
+0 1 2 3 4 5 6 7 8 9 A C D F G H J K M N P R U W Y
+```
+
+See the full specification and documentation at [github.com/snapsynapse/hardguard25](https://github.com/snapsynapse/hardguard25).

hardguard25-1.3.0/README.md

@@ -0,0 +1,9 @@
+# hardguard25
+
+A human-friendly unique ID alphabet. 25 unambiguous characters, zero confusion.
+
+```
+0 1 2 3 4 5 6 7 8 9 A C D F G H J K M N P R U W Y
+```
+
+See the full specification and documentation at [github.com/snapsynapse/hardguard25](https://github.com/snapsynapse/hardguard25).

hardguard25-1.3.0/hardguard25/__init__.py

@@ -0,0 +1,196 @@
+"""
+HardGuard25: A 25-character alphabet for human-friendly unique IDs.
+
+This module provides functions for generating, validating, and managing
+HardGuard25 identifiers. The alphabet excludes visually ambiguous characters
+(B, E, I, L, O, Q, S, T, V, X, Z) to prevent confusion.
+
+Character set: 0 1 2 3 4 5 6 7 8 9 A C D F G H J K M N P R U W Y
+"""
+
+import re
+import secrets
+from typing import Dict
+
+__version__ = "1.3.0"
+
+# The 25-character HardGuard25 alphabet
+ALPHABET = "0123456789ACDFGHJKMNPRUWY"
+
+# Frozenset for O(1) membership testing
+ALPHABET_SET = frozenset(ALPHABET)
+
+# Dictionary mapping each character to its 0-24 index
+_CHAR_TO_INDEX: Dict[str, int] = {char: idx for idx, char in enumerate(ALPHABET)}
+
+# Compiled regex pattern for validation
+_REGEX = re.compile(r"^[0-9ACDFGHJKMNPRUWY]+$")
+
+
+def generate(length: int, *, check_digit: bool = False) -> str:
+    """
+    Generate a random HardGuard25 identifier.
+
+    Uses cryptographically secure random number generation with rejection sampling
+    to ensure uniform distribution across the 25-character alphabet.
+
+    Args:
+        length: The desired length of the identifier (must be > 0).
+        check_digit: If True, append a check digit (result will be length+1 chars).
+
+    Returns:
+        A random HardGuard25 string of the specified length (plus 1 if check_digit=True).
+
+    Raises:
+        ValueError: If length <= 0.
+    """
+    if length <= 0:
+        raise ValueError("length must be greater than 0")
+
+    result = []
+    alphabet_len = 25
+
+    # Rejection sampling: only accept byte values < 225 (25*9)
+    # This ensures uniform distribution
+    while len(result) < length:
+        random_bytes = secrets.token_bytes(1)
+        byte_val = random_bytes[0]
+
+        # Reject values >= 225 to ensure uniform distribution
+        if byte_val < 225:
+            index = byte_val % alphabet_len
+            result.append(ALPHABET[index])
+
+    code = "".join(result)
+
+    if check_digit:
+        code += check_digit_func(code)
+
+    return code
+
+
+def validate(input_str: str) -> bool:
+    """
+    Validate a HardGuard25 identifier.
+
+    Normalizes the input and checks if it matches the HardGuard25 pattern.
+    Never raises an exception; returns False for invalid input.
+
+    Args:
+        input_str: The string to validate.
+
+    Returns:
+        True if the input is a valid HardGuard25 identifier, False otherwise.
+    """
+    try:
+        normalized = normalize(input_str)
+        return bool(_REGEX.match(normalized))
+    except ValueError:
+        return False
+
+
+def normalize(input_str: str) -> str:
+    """
+    Normalize a HardGuard25 identifier.
+
+    Trims whitespace, collapses separators (hyphens, spaces, underscores, dots),
+    converts to uppercase, and validates the result.
+
+    Args:
+        input_str: The string to normalize.
+
+    Returns:
+        The normalized HardGuard25 string.
+
+    Raises:
+        ValueError: If the input contains invalid characters (after separator removal).
+    """
+    if not isinstance(input_str, str):
+        raise ValueError("input must be a string")
+
+    # Trim whitespace
+    normalized = input_str.strip()
+
+    # Remove common separators
+    normalized = normalized.replace("-", "").replace(" ", "").replace("_", "").replace(".", "")
+
+    # Convert to uppercase
+    normalized = normalized.upper()
+
+    # Check for invalid characters
+    if not _REGEX.match(normalized):
+        raise ValueError(f"invalid characters in input: {input_str}")
+
+    return normalized
+
+
+def check_digit(code: str) -> str:
+    """
+    Compute the check digit for a HardGuard25 code.
+
+    Uses a mod-25 weighted checksum where each character is weighted by its
+    position (1-indexed).
+
+    Args:
+        code: The code to compute the check digit for.
+
+    Returns:
+        A single character representing the check digit.
+
+    Raises:
+        ValueError: If the code contains invalid characters.
+    """
+    if not code:
+        raise ValueError("code must not be empty")
+
+    upper_code = code.upper()
+    try:
+        weighted_sum = sum(
+            _CHAR_TO_INDEX[char] * (i + 1)
+            for i, char in enumerate(upper_code)
+        )
+    except KeyError as e:
+        raise ValueError(f"invalid character in code: {e}")
+
+    return ALPHABET[weighted_sum % 25]
+
+
+def verify_check_digit(code_with_check: str) -> bool:
+    """
+    Verify the check digit of a HardGuard25 code.
+
+    Strips the last character, recomputes the check digit, and compares.
+
+    Args:
+        code_with_check: The code including the check digit.
+
+    Returns:
+        True if the check digit is valid, False otherwise.
+    """
+    if not isinstance(code_with_check, str) or len(code_with_check) < 2:
+        return False
+
+    try:
+        upper = code_with_check.upper()
+        code = upper[:-1]
+        provided_check = upper[-1]
+        computed_check = check_digit(code)
+        return provided_check == computed_check
+    except (ValueError, AttributeError):
+        return False
+
+
+# Backward-compatible alias for earlier pre-release naming.
+check_digit_func = check_digit
+
+
+__all__ = [
+    "ALPHABET",
+    "ALPHABET_SET",
+    "generate",
+    "validate",
+    "normalize",
+    "check_digit",
+    "check_digit_func",
+    "verify_check_digit",
+]

hardguard25-1.3.0/hardguard25.egg-info/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: hardguard25
+Version: 1.3.0
+Summary: HardGuard25: A human-friendly unique ID alphabet. 25 unambiguous characters.
+Author-email: Snap Synapse <info@snapsynapse.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/snapsynapse/hardguard25
+Project-URL: Documentation, https://github.com/snapsynapse/hardguard25/blob/main/SPEC.md
+Project-URL: Repository, https://github.com/snapsynapse/hardguard25
+Keywords: id,uid,unique-id,identifier,human-readable,unambiguous
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# hardguard25
+
+A human-friendly unique ID alphabet. 25 unambiguous characters, zero confusion.
+
+```
+0 1 2 3 4 5 6 7 8 9 A C D F G H J K M N P R U W Y
+```
+
+See the full specification and documentation at [github.com/snapsynapse/hardguard25](https://github.com/snapsynapse/hardguard25).

hardguard25-1.3.0/hardguard25.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+hardguard25/__init__.py
+hardguard25/py.typed
+hardguard25.egg-info/PKG-INFO
+hardguard25.egg-info/SOURCES.txt
+hardguard25.egg-info/dependency_links.txt
+hardguard25.egg-info/top_level.txt
+tests/test_hardguard25.py

hardguard25-1.3.0/hardguard25.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hardguard25-1.3.0/hardguard25.egg-info/top_level.txt

@@ -0,0 +1 @@
+hardguard25

hardguard25-1.3.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hardguard25"
+version = "1.3.0"
+description = "HardGuard25: A human-friendly unique ID alphabet. 25 unambiguous characters."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [
+    {name = "Snap Synapse", email = "info@snapsynapse.com"}
+]
+keywords = ["id", "uid", "unique-id", "identifier", "human-readable", "unambiguous"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries",
+]
+
+[tool.setuptools.packages.find]
+include = ["hardguard25*"]
+exclude = ["tests*"]
+
+[project.urls]
+Homepage = "https://github.com/snapsynapse/hardguard25"
+Documentation = "https://github.com/snapsynapse/hardguard25/blob/main/SPEC.md"
+Repository = "https://github.com/snapsynapse/hardguard25"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

hardguard25-1.3.0/setup.cfg

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

hardguard25-1.3.0/tests/test_hardguard25.py

@@ -0,0 +1,238 @@
+"""
+Comprehensive test suite for HardGuard25.
+
+Tests cover alphabet validation, ID generation, validation, normalization,
+check digits, and distribution characteristics.
+"""
+
+import pytest
+from collections import Counter
+
+import hardguard25
+
+
+class TestAlphabet:
+
+    def test_alphabet_length(self):
+        assert len(hardguard25.ALPHABET) == 25
+
+    def test_alphabet_set_matches_alphabet(self):
+        assert hardguard25.ALPHABET_SET == frozenset(hardguard25.ALPHABET)
+
+    def test_no_duplicates_in_alphabet(self):
+        assert len(set(hardguard25.ALPHABET)) == 25
+
+    def test_no_excluded_chars(self):
+        excluded = set("BEILOQSTVXZ")
+        alphabet_set = set(hardguard25.ALPHABET)
+        assert alphabet_set.isdisjoint(excluded)
+
+    def test_only_base10_and_uppercase_letters(self):
+        for char in hardguard25.ALPHABET:
+            assert char.isdigit() or char.isupper()
+
+    def test_char_to_index_mapping(self):
+        for idx, char in enumerate(hardguard25.ALPHABET):
+            assert hardguard25._CHAR_TO_INDEX[char] == idx
+
+
+class TestGeneration:
+
+    def test_generate_correct_length(self):
+        for length in [1, 5, 10, 32, 64, 128]:
+            result = hardguard25.generate(length)
+            assert len(result) == length
+
+    def test_generate_invalid_length(self):
+        with pytest.raises(ValueError):
+            hardguard25.generate(0)
+        with pytest.raises(ValueError):
+            hardguard25.generate(-1)
+
+    def test_generate_only_valid_chars(self):
+        for _ in range(1000):
+            result = hardguard25.generate(20)
+            for char in result:
+                assert char in hardguard25.ALPHABET_SET
+
+    def test_generate_with_check_digit(self):
+        for length in [5, 10, 32]:
+            result = hardguard25.generate(length, check_digit=True)
+            assert len(result) == length + 1
+
+    def test_generate_randomness(self):
+        results = [hardguard25.generate(20) for _ in range(10)]
+        assert len(set(results)) == 10
+
+    def test_generate_distribution(self):
+        chars = []
+        for _ in range(400):
+            chars.extend(hardguard25.generate(25))
+        counter = Counter(chars)
+        assert len(counter) == 25
+        for char in hardguard25.ALPHABET:
+            assert counter.get(char, 0) > 0
+
+
+class TestValidation:
+
+    def test_validate_valid_ids(self):
+        valid_ids = [
+            "ACD123",
+            "0123456789",
+            "ACDFGHJKMNPRUWY",
+            "acd123",
+            "A-C-D-1-2-3",
+            "A C D 1 2 3",
+            "A_C_D_1_2_3",
+            "A.C.D.1.2.3",
+        ]
+        for test_id in valid_ids:
+            assert hardguard25.validate(test_id), f"Failed to validate: {test_id}"
+
+    def test_validate_invalid_ids(self):
+        invalid_ids = [
+            "BEILOQSTVXZ",
+            "!@#$%^&*()",
+            "ACD123XBZ",
+            "",
+        ]
+        for test_id in invalid_ids:
+            assert not hardguard25.validate(test_id), f"Should not validate: {test_id}"
+
+    def test_validate_never_raises(self):
+        test_inputs = [None, 123, [], {}, "ACD\x00123"]
+        for test_input in test_inputs:
+            try:
+                result = hardguard25.validate(test_input)
+                assert isinstance(result, bool)
+            except Exception as e:
+                pytest.fail(f"validate() raised {type(e).__name__}: {e}")
+
+
+class TestNormalization:
+
+    def test_normalize_uppercase(self):
+        assert hardguard25.normalize("acd") == "ACD"
+        assert hardguard25.normalize("aCd") == "ACD"
+
+    def test_normalize_trim_whitespace(self):
+        assert hardguard25.normalize("  ACD123  ") == "ACD123"
+
+    def test_normalize_remove_separators(self):
+        assert hardguard25.normalize("A-C-D-1-2-3") == "ACD123"
+        assert hardguard25.normalize("A C D 1 2 3") == "ACD123"
+        assert hardguard25.normalize("A_C_D_1_2_3") == "ACD123"
+        assert hardguard25.normalize("A.C.D.1.2.3") == "ACD123"
+        assert hardguard25.normalize("A-C D_1.2 3") == "ACD123"
+
+    def test_normalize_idempotent(self):
+        test_ids = ["acd-123", "A C D 1 2 3", "A_C_D_1_2_3", "A.C.D.1.2.3"]
+        for test_id in test_ids:
+            once = hardguard25.normalize(test_id)
+            twice = hardguard25.normalize(once)
+            assert once == twice
+
+    def test_normalize_invalid_input_raises(self):
+        invalid_inputs = ["BEILOQSTVXZ", "ACD!@#"]
+        for test_input in invalid_inputs:
+            with pytest.raises(ValueError):
+                hardguard25.normalize(test_input)
+
+    def test_normalize_non_string_input_raises(self):
+        with pytest.raises(ValueError):
+            hardguard25.normalize(123)
+        with pytest.raises(ValueError):
+            hardguard25.normalize(None)
+
+
+class TestCheckDigit:
+
+    def test_check_digit_returns_single_char(self):
+        for length in [1, 5, 10, 32]:
+            code = hardguard25.generate(length)
+            digit = hardguard25.check_digit(code)
+            assert len(digit) == 1
+            assert digit in hardguard25.ALPHABET_SET
+
+    def test_check_digit_deterministic(self):
+        code = "ACD123"
+        digit1 = hardguard25.check_digit(code)
+        digit2 = hardguard25.check_digit(code)
+        assert digit1 == digit2
+
+    def test_check_digit_different_for_different_codes(self):
+        digits = set()
+        for length in [1, 2, 3, 4, 5]:
+            code = hardguard25.generate(length)
+            digit = hardguard25.check_digit(code)
+            digits.add(digit)
+        assert len(digits) > 1
+
+    def test_check_digit_invalid_input_raises(self):
+        with pytest.raises(ValueError):
+            hardguard25.check_digit("")
+        with pytest.raises(ValueError):
+            hardguard25.check_digit("ACD!@#")
+
+    def test_check_digit_backward_compatible_alias(self):
+        code = "ACD123"
+        assert hardguard25.check_digit(code) == hardguard25.check_digit_func(code)
+
+    def test_verify_check_digit_valid(self):
+        code = hardguard25.generate(10)
+        digit = hardguard25.check_digit(code)
+        full_code = code + digit
+        assert hardguard25.verify_check_digit(full_code)
+
+    def test_verify_check_digit_invalid(self):
+        code = hardguard25.generate(10)
+        digit = hardguard25.check_digit(code)
+        wrong_chars = [c for c in hardguard25.ALPHABET if c != digit]
+        wrong_code = code + wrong_chars[0]
+        assert not hardguard25.verify_check_digit(wrong_code)
+
+    def test_verify_check_digit_short_input(self):
+        assert not hardguard25.verify_check_digit("")
+        assert not hardguard25.verify_check_digit("A")
+
+    def test_verify_check_digit_never_raises(self):
+        test_inputs = ["ACD!@#", None, 123, []]
+        for test_input in test_inputs:
+            try:
+                result = hardguard25.verify_check_digit(test_input)
+                assert isinstance(result, bool)
+            except Exception as e:
+                pytest.fail(f"verify_check_digit() raised {type(e).__name__}: {e}")
+
+    def test_check_digit_workflow(self):
+        for _ in range(100):
+            code = hardguard25.generate(15)
+            digit = hardguard25.check_digit(code)
+            full = code + digit
+            assert hardguard25.verify_check_digit(full)
+            wrong_chars = [c for c in hardguard25.ALPHABET if c != digit]
+            corrupted = code + wrong_chars[0]
+            assert not hardguard25.verify_check_digit(corrupted)
+
+
+class TestDistribution:
+
+    def test_distribution_all_chars_appear(self):
+        chars = []
+        for _ in range(400):
+            chars.extend(hardguard25.generate(25))
+        counter = Counter(chars)
+        assert len(counter) == 25
+
+    def test_distribution_roughly_uniform(self):
+        chars = []
+        for _ in range(400):
+            chars.extend(hardguard25.generate(25))
+        counter = Counter(chars)
+        total = len(chars)
+        expected_per_char = total / 25
+        for char in hardguard25.ALPHABET:
+            count = counter.get(char, 0)
+            ratio = count / expected_per_char
+            assert 0.5 < ratio < 1.5