strcoerce 0.1.0__py3-none-any.whl

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/_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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,6 @@
+strcoerce/__init__.py,sha256=qIF24CXaZk1-qEedC2oSFHhaSGdLzjaT4x4T9ahc1OY,281
+strcoerce/_core.py,sha256=F9dFzm-P1kvcPNChftNs3vq8dk_-nc14YOgIpJCGjDA,3615
+strcoerce-0.1.0.dist-info/METADATA,sha256=QE5cO17gCVbWVGMIaQSnmDYcWa-F6Fcg56pv8FCiLD4,3637
+strcoerce-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+strcoerce-0.1.0.dist-info/licenses/LICENSE,sha256=ESYyLizI0WWtxMeS7rGVcX3ivMezm-HOd5WdeOh-9oU,1056
+strcoerce-0.1.0.dist-info/RECORD,,

strcoerce-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

strcoerce-0.1.0.dist-info/licenses/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.