strcoerce 0.1.0__tar.gz

strcoerce-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]" || pip install -e . pytest pytest-cov
+      - run: pytest

strcoerce-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

strcoerce-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+dist/
+*.egg-info/
+__pycache__/
+*.pyc
+.coverage
+.pytest_cache/
+*.pyo

strcoerce-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+- Initial release
+- `parse_bool`: handles true/false/yes/no/1/0/on/off (case-insensitive)
+- `parse_int`: with optional base parameter for hex/binary
+- `parse_float`: with scientific notation support
+- `parse_list`: delimited string to list with configurable separator and strip
+- `parse_duration`: compact duration strings to `timedelta` (Nw Nd Nh Nm Ns)
+- `ParseError`: subclass of `ValueError` for clean exception handling

strcoerce-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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.

strcoerce-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: strcoerce
+Version: 0.1.0
+Summary: Safe string-to-type coercion — parse_bool, parse_int, parse_float, parse_list, parse_duration
+Project-URL: Homepage, https://github.com/SpinnakerSix/strcoerce
+Project-URL: Issues, https://github.com/SpinnakerSix/strcoerce/issues
+Project-URL: Changelog, https://github.com/SpinnakerSix/strcoerce/blob/main/CHANGELOG.md
+License: MIT
+License-File: LICENSE
+Keywords: bool,coerce,convert,environment,parse,string,type
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# strcoerce
+
+Safe string-to-type coercion for Python. Zero dependencies.
+
+## The problem
+
+```python
+import os
+DEBUG = bool(os.environ.get("DEBUG", "false"))  # Always True — "false" is a non-empty string
+```
+
+`bool("false")` is `True` in Python. This catches experienced developers off guard and is a
+[documented trap](https://docs.python.org/3/library/stdtypes.html#truth-value-testing) with no
+stdlib fix.
+
+## Install
+
+```
+pip install strcoerce
+```
+
+
+## Usage
+
+```python
+from strcoerce import parse_bool, parse_int, parse_float, parse_list, parse_duration
+
+# Environment variables
+DEBUG  = parse_bool(os.environ.get("DEBUG", "false"))   # False
+PORT   = parse_int(os.environ.get("PORT", "8080"))      # 8080
+HOSTS  = parse_list(os.environ.get("ALLOWED_HOSTS", ""))  # []
+
+# With defaults
+parse_bool("maybe", default=False)  # False — no exception
+parse_int("oops",   default=0)      # 0
+
+# Durations
+from datetime import timedelta
+parse_duration("2h30m")   # timedelta(hours=2, minutes=30)
+parse_duration("1w2d")    # timedelta(weeks=1, days=2)
+```
+
+## API
+
+### `parse_bool(s, *, default=<raise>)`
+
+| Input | Result |
+|-------|--------|
+| `"1"`, `"true"`, `"yes"`, `"on"`, `"t"`, `"y"` | `True` |
+| `"0"`, `"false"`, `"no"`, `"off"`, `"f"`, `"n"` | `False` |
+| anything else (no default) | `ParseError` |
+| anything else (default given) | `default` |
+
+Case-insensitive. Strips surrounding whitespace.
+
+### `parse_int(s, *, default=<raise>, base=10)`
+
+```python
+parse_int("42")              # 42
+parse_int("0xff", base=16)   # 255
+parse_int("bad", default=0)  # 0
+```
+
+### `parse_float(s, *, default=<raise>)`
+
+```python
+parse_float("3.14")           # 3.14
+parse_float("1e-3")           # 0.001
+parse_float("bad", default=0) # 0
+```
+
+### `parse_list(s, sep=",", *, strip=True)`
+
+```python
+parse_list("a, b, c")          # ["a", "b", "c"]
+parse_list("a|b|c", sep="|")   # ["a", "b", "c"]
+parse_list("")                 # []
+```
+
+### `parse_duration(s)`
+
+Parses combinations of `Nw Nd Nh Nm Ns` (weeks/days/hours/minutes/seconds).
+
+```python
+parse_duration("30s")        # timedelta(seconds=30)
+parse_duration("5m")         # timedelta(minutes=5)
+parse_duration("2h30m")      # timedelta(hours=2, minutes=30)
+parse_duration("1w2d3h4m5s") # timedelta(weeks=1, days=2, hours=3, minutes=4, seconds=5)
+```
+
+## Error handling
+
+All functions raise `ParseError` (subclass of `ValueError`) when input is invalid and no
+default is given.
+
+```python
+from strcoerce import ParseError
+
+try:
+    val = parse_bool(user_input)
+except ParseError as e:
+    print(f"Invalid boolean: {e}")
+```
+
+## License
+
+MIT

strcoerce-0.1.0/README.md

@@ -0,0 +1,107 @@
+# strcoerce
+
+Safe string-to-type coercion for Python. Zero dependencies.
+
+## The problem
+
+```python
+import os
+DEBUG = bool(os.environ.get("DEBUG", "false"))  # Always True — "false" is a non-empty string
+```
+
+`bool("false")` is `True` in Python. This catches experienced developers off guard and is a
+[documented trap](https://docs.python.org/3/library/stdtypes.html#truth-value-testing) with no
+stdlib fix.
+
+## Install
+
+```
+pip install strcoerce
+```
+
+
+## Usage
+
+```python
+from strcoerce import parse_bool, parse_int, parse_float, parse_list, parse_duration
+
+# Environment variables
+DEBUG  = parse_bool(os.environ.get("DEBUG", "false"))   # False
+PORT   = parse_int(os.environ.get("PORT", "8080"))      # 8080
+HOSTS  = parse_list(os.environ.get("ALLOWED_HOSTS", ""))  # []
+
+# With defaults
+parse_bool("maybe", default=False)  # False — no exception
+parse_int("oops",   default=0)      # 0
+
+# Durations
+from datetime import timedelta
+parse_duration("2h30m")   # timedelta(hours=2, minutes=30)
+parse_duration("1w2d")    # timedelta(weeks=1, days=2)
+```
+
+## API
+
+### `parse_bool(s, *, default=<raise>)`
+
+| Input | Result |
+|-------|--------|
+| `"1"`, `"true"`, `"yes"`, `"on"`, `"t"`, `"y"` | `True` |
+| `"0"`, `"false"`, `"no"`, `"off"`, `"f"`, `"n"` | `False` |
+| anything else (no default) | `ParseError` |
+| anything else (default given) | `default` |
+
+Case-insensitive. Strips surrounding whitespace.
+
+### `parse_int(s, *, default=<raise>, base=10)`
+
+```python
+parse_int("42")              # 42
+parse_int("0xff", base=16)   # 255
+parse_int("bad", default=0)  # 0
+```
+
+### `parse_float(s, *, default=<raise>)`
+
+```python
+parse_float("3.14")           # 3.14
+parse_float("1e-3")           # 0.001
+parse_float("bad", default=0) # 0
+```
+
+### `parse_list(s, sep=",", *, strip=True)`
+
+```python
+parse_list("a, b, c")          # ["a", "b", "c"]
+parse_list("a|b|c", sep="|")   # ["a", "b", "c"]
+parse_list("")                 # []
+```
+
+### `parse_duration(s)`
+
+Parses combinations of `Nw Nd Nh Nm Ns` (weeks/days/hours/minutes/seconds).
+
+```python
+parse_duration("30s")        # timedelta(seconds=30)
+parse_duration("5m")         # timedelta(minutes=5)
+parse_duration("2h30m")      # timedelta(hours=2, minutes=30)
+parse_duration("1w2d3h4m5s") # timedelta(weeks=1, days=2, hours=3, minutes=4, seconds=5)
+```
+
+## Error handling
+
+All functions raise `ParseError` (subclass of `ValueError`) when input is invalid and no
+default is given.
+
+```python
+from strcoerce import ParseError
+
+try:
+    val = parse_bool(user_input)
+except ParseError as e:
+    print(f"Invalid boolean: {e}")
+```
+
+## License
+
+MIT

strcoerce-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "strcoerce"
+version = "0.1.0"
+description = "Safe string-to-type coercion — parse_bool, parse_int, parse_float, parse_list, parse_duration"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+keywords = ["parse", "bool", "coerce", "string", "type", "convert", "environment"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/SpinnakerSix/strcoerce"
+Issues = "https://github.com/SpinnakerSix/strcoerce/issues"
+Changelog = "https://github.com/SpinnakerSix/strcoerce/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/strcoerce"]
+
+[dependency-groups]
+dev = [
+    "pytest>=7",
+    "pytest-cov>=4",
+    "ruff>=0.4",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=strcoerce --cov-report=term-missing -v"
+
+[tool.coverage.run]
+source = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]

strcoerce-0.1.0/src/strcoerce/__init__.py

@@ -0,0 +1,18 @@
+from strcoerce._core import (
+    ParseError,
+    parse_bool,
+    parse_duration,
+    parse_float,
+    parse_int,
+    parse_list,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "ParseError",
+    "parse_bool",
+    "parse_duration",
+    "parse_float",
+    "parse_int",
+    "parse_list",
+]

strcoerce-0.1.0/src/strcoerce/_core.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import re
+from datetime import timedelta
+from typing import Any
+
+_MISSING: Any = object()
+
+_TRUE_VALUES = frozenset({"1", "true", "yes", "on", "t", "y"})
+_FALSE_VALUES = frozenset({"0", "false", "no", "off", "f", "n"})
+
+# Matches combinations of Nw Nd Nh Nm Ns — all groups optional but at least one must be present
+_DURATION_RE = re.compile(
+    r"^(?:(\d+)w)?(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$",
+    re.IGNORECASE,
+)
+
+
+class ParseError(ValueError):
+    """Raised when a string cannot be coerced into the requested type."""
+
+
+def parse_bool(s: str, *, default: bool = _MISSING) -> bool:
+    """Parse a string to bool.
+
+    Accepted truthy:  1, true, yes, on, t, y  (case-insensitive)
+    Accepted falsy:   0, false, no, off, f, n  (case-insensitive)
+
+    Raises ParseError if the value is unrecognized and no default is given.
+    Raises TypeError if s is not a str.
+    """
+    if not isinstance(s, str):
+        raise TypeError(f"Expected str, got {type(s).__name__!r}")
+    normalized = s.strip().lower()
+    if normalized in _TRUE_VALUES:
+        return True
+    if normalized in _FALSE_VALUES:
+        return False
+    if default is not _MISSING:
+        return default
+    raise ParseError(
+        f"Cannot parse {s!r} as bool. "
+        f"Accepted values: {sorted(_TRUE_VALUES | _FALSE_VALUES)}"
+    )
+
+
+def parse_int(s: str, *, default: int = _MISSING, base: int = 10) -> int:
+    """Parse a string to int.
+
+    Raises ParseError on failure unless default is given.
+    Pass base=16 for hex strings (e.g. 'ff' or '0xff').
+    """
+    if not isinstance(s, str):
+        raise TypeError(f"Expected str, got {type(s).__name__!r}")
+    try:
+        return int(s.strip(), base)
+    except ValueError:
+        if default is not _MISSING:
+            return default
+        raise ParseError(f"Cannot parse {s!r} as int") from None
+
+
+def parse_float(s: str, *, default: float = _MISSING) -> float:
+    """Parse a string to float.
+
+    Raises ParseError on failure unless default is given.
+    """
+    if not isinstance(s, str):
+        raise TypeError(f"Expected str, got {type(s).__name__!r}")
+    try:
+        return float(s.strip())
+    except ValueError:
+        if default is not _MISSING:
+            return default
+        raise ParseError(f"Cannot parse {s!r} as float") from None
+
+
+def parse_list(s: str, sep: str = ",", *, strip: bool = True) -> list[str]:
+    """Split a delimited string into a list, filtering empty strings.
+
+    parse_list("a, b, c")          -> ["a", "b", "c"]
+    parse_list("a|b|c", sep="|")   -> ["a", "b", "c"]
+    parse_list("")                 -> []
+    """
+    if not s.strip():
+        return []
+    items = s.split(sep)
+    if strip:
+        items = [item.strip() for item in items]
+    return [item for item in items if item]
+
+
+def parse_duration(s: str) -> timedelta:
+    """Parse a compact duration string to timedelta.
+
+    Format: any combination of Nw Nd Nh Nm Ns (weeks/days/hours/minutes/seconds).
+    Examples: '30s', '5m', '2h30m', '1d12h', '1w2d3h4m5s'
+
+    Raises ParseError on unrecognized format.
+    """
+    s = s.strip()
+    if not s:
+        raise ParseError("Cannot parse empty string as duration")
+    match = _DURATION_RE.match(s)
+    if not match or not any(match.groups()):
+        raise ParseError(
+            f"Cannot parse {s!r} as duration. "
+            "Expected format like '30s', '5m', '2h30m', '1d12h', '1w'"
+        )
+    weeks, days, hours, minutes, seconds = (int(g or 0) for g in match.groups())
+    return timedelta(weeks=weeks, days=days, hours=hours, minutes=minutes, seconds=seconds)

strcoerce-0.1.0/tests/test_core.py

@@ -0,0 +1,184 @@
+from datetime import timedelta
+
+import pytest
+
+from strcoerce import ParseError, parse_bool, parse_duration, parse_float, parse_int, parse_list
+
+
+class TestParseBool:
+    @pytest.mark.parametrize("s", ["1", "true", "True", "TRUE", "yes", "YES", "on", "ON", "t", "y"])
+    def test_true_values(self, s):
+        assert parse_bool(s) is True
+
+    @pytest.mark.parametrize("s", ["0", "false", "False", "FALSE", "no", "NO", "off", "OFF", "f", "n"])
+    def test_false_values(self, s):
+        assert parse_bool(s) is False
+
+    def test_strips_whitespace(self):
+        assert parse_bool("  true  ") is True
+        assert parse_bool("  false  ") is False
+
+    def test_python_bool_trap(self):
+        # The whole reason this library exists
+        assert parse_bool("false") is False  # bool("false") would be True
+        assert parse_bool("0") is False      # bool("0") would be True
+        assert parse_bool("no") is False
+
+    def test_invalid_raises_parse_error(self):
+        with pytest.raises(ParseError):
+            parse_bool("maybe")
+
+    def test_parse_error_is_value_error(self):
+        with pytest.raises(ValueError):
+            parse_bool("maybe")
+
+    def test_default_returned_on_invalid(self):
+        assert parse_bool("maybe", default=False) is False
+        assert parse_bool("maybe", default=True) is True
+
+    def test_wrong_type_raises_type_error(self):
+        with pytest.raises(TypeError):
+            parse_bool(True)
+        with pytest.raises(TypeError):
+            parse_bool(1)
+        with pytest.raises(TypeError):
+            parse_bool(None)
+
+
+class TestParseInt:
+    def test_basic(self):
+        assert parse_int("42") == 42
+        assert parse_int("-1") == -1
+        assert parse_int("0") == 0
+
+    def test_strips_whitespace(self):
+        assert parse_int("  42  ") == 42
+
+    def test_hex(self):
+        assert parse_int("ff", base=16) == 255
+        assert parse_int("0xff", base=16) == 255
+        assert parse_int("FF", base=16) == 255
+
+    def test_binary(self):
+        assert parse_int("1010", base=2) == 10
+
+    def test_invalid_raises(self):
+        with pytest.raises(ParseError):
+            parse_int("abc")
+        with pytest.raises(ParseError):
+            parse_int("3.14")
+
+    def test_default_on_invalid(self):
+        assert parse_int("abc", default=0) == 0
+        assert parse_int("", default=-1) == -1
+
+    def test_wrong_type_raises(self):
+        with pytest.raises(TypeError):
+            parse_int(42)
+
+
+class TestParseFloat:
+    def test_basic(self):
+        assert parse_float("3.14") == pytest.approx(3.14)
+        assert parse_float("-2.5") == pytest.approx(-2.5)
+        assert parse_float("0") == pytest.approx(0.0)
+
+    def test_scientific_notation(self):
+        assert parse_float("1e10") == pytest.approx(1e10)
+        assert parse_float("1.5E-3") == pytest.approx(0.0015)
+
+    def test_integer_string(self):
+        assert parse_float("42") == pytest.approx(42.0)
+
+    def test_strips_whitespace(self):
+        assert parse_float("  3.14  ") == pytest.approx(3.14)
+
+    def test_invalid_raises(self):
+        with pytest.raises(ParseError):
+            parse_float("not_a_float")
+        with pytest.raises(ParseError):
+            parse_float("")
+
+    def test_default_on_invalid(self):
+        assert parse_float("bad", default=0.0) == 0.0
+
+    def test_wrong_type_raises(self):
+        with pytest.raises(TypeError):
+            parse_float(3.14)
+
+
+class TestParseList:
+    def test_basic(self):
+        assert parse_list("a,b,c") == ["a", "b", "c"]
+
+    def test_strips_whitespace_by_default(self):
+        assert parse_list("a, b, c") == ["a", "b", "c"]
+        assert parse_list("  a  ,  b  ") == ["a", "b"]
+
+    def test_no_strip(self):
+        assert parse_list("a, b, c", strip=False) == ["a", " b", " c"]
+
+    def test_custom_separator(self):
+        assert parse_list("a|b|c", sep="|") == ["a", "b", "c"]
+        assert parse_list("a::b::c", sep="::") == ["a", "b", "c"]
+
+    def test_empty_string_returns_empty_list(self):
+        assert parse_list("") == []
+        assert parse_list("   ") == []
+
+    def test_filters_empty_items(self):
+        assert parse_list("a,,b") == ["a", "b"]
+        assert parse_list(",a,") == ["a"]
+
+    def test_single_item(self):
+        assert parse_list("only") == ["only"]
+
+    def test_newline_separator(self):
+        assert parse_list("a\nb\nc", sep="\n") == ["a", "b", "c"]
+
+
+class TestParseDuration:
+    def test_seconds(self):
+        assert parse_duration("30s") == timedelta(seconds=30)
+        assert parse_duration("1s") == timedelta(seconds=1)
+
+    def test_minutes(self):
+        assert parse_duration("5m") == timedelta(minutes=5)
+
+    def test_hours(self):
+        assert parse_duration("2h") == timedelta(hours=2)
+
+    def test_days(self):
+        assert parse_duration("3d") == timedelta(days=3)
+
+    def test_weeks(self):
+        assert parse_duration("1w") == timedelta(weeks=1)
+
+    def test_combined(self):
+        assert parse_duration("2h30m") == timedelta(hours=2, minutes=30)
+        assert parse_duration("1d12h") == timedelta(days=1, hours=12)
+        assert parse_duration("1w2d3h4m5s") == timedelta(
+            weeks=1, days=2, hours=3, minutes=4, seconds=5
+        )
+
+    def test_strips_whitespace(self):
+        assert parse_duration("  5m  ") == timedelta(minutes=5)
+
+    def test_case_insensitive(self):
+        assert parse_duration("5M") == timedelta(minutes=5)
+        assert parse_duration("2H") == timedelta(hours=2)
+        assert parse_duration("1W") == timedelta(weeks=1)
+
+    def test_empty_raises(self):
+        with pytest.raises(ParseError):
+            parse_duration("")
+        with pytest.raises(ParseError):
+            parse_duration("   ")
+
+    def test_invalid_raises(self):
+        with pytest.raises(ParseError):
+            parse_duration("foobar")
+        with pytest.raises(ParseError):
+            parse_duration("5x")
+        with pytest.raises(ParseError):
+            parse_duration("5")  # number with no unit