crashbytes-result 1.0.0__tar.gz

crashbytes_result-1.0.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @CrashBytes

crashbytes_result-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["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]"
+      - run: ruff check src/ tests/
+      - run: mypy --strict src/
+      - run: pytest --cov=crashbytes_result --cov-branch --cov-fail-under=90

crashbytes_result-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    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

crashbytes_result-1.0.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.pyo
+dist/
+build/
+*.egg-info/
+.coverage
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+

crashbytes_result-1.0.0/LICENSE

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

crashbytes_result-1.0.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: crashbytes-result
+Version: 1.0.0
+Summary: A practical Result type for Python — Ok, Err, and pattern matching.
+Project-URL: Homepage, https://github.com/CrashBytes/crashbytes-result
+Project-URL: Repository, https://github.com/CrashBytes/crashbytes-result
+Project-URL: Issues, https://github.com/CrashBytes/crashbytes-result/issues
+Author-email: CrashBytes <crashbytes@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: err,error-handling,monad,ok,pattern-matching,result
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# crashbytes-result
+
+A practical Result type for Python — `Ok`, `Err`, and pattern matching.
+
+## Install
+
+```bash
+pip install crashbytes-result
+```
+
+## Usage
+
+```python
+from crashbytes_result import Ok, Err, Result, safe
+
+def divide(a: float, b: float) -> Result[float, str]:
+    if b == 0:
+        return Err("division by zero")
+    return Ok(a / b)
+
+result = divide(10, 3)
+match result:
+    case Ok(value):
+        print(f"Result: {value}")
+    case Err(error):
+        print(f"Error: {error}")
+
+# Or use .match()
+msg = result.match(
+    ok=lambda v: f"Got {v:.2f}",
+    err=lambda e: f"Failed: {e}",
+)
+
+# @safe decorator
+@safe
+def parse_int(s: str) -> int:
+    return int(s)
+
+parse_int("42")   # Ok(42)
+parse_int("abc")  # Err(ValueError(...))
+```
+
+## API
+
+| Method | Ok | Err |
+|--------|-----|------|
+| `.unwrap()` | Returns value | Raises `UnwrapError` |
+| `.unwrap_or(default)` | Returns value | Returns default |
+| `.unwrap_err()` | Raises `UnwrapError` | Returns error |
+| `.map(fn)` | `Ok(fn(value))` | `self` |
+| `.map_err(fn)` | `self` | `Err(fn(error))` |
+| `.bind(fn)` | `fn(value)` | `self` |
+| `.match(ok, err)` | `ok(value)` | `err(error)` |
+| `.is_ok` | `True` | `False` |
+| `.is_err` | `False` | `True` |
+
+## License
+
+MIT

crashbytes_result-1.0.0/README.md

@@ -0,0 +1,59 @@
+# crashbytes-result
+
+A practical Result type for Python — `Ok`, `Err`, and pattern matching.
+
+## Install
+
+```bash
+pip install crashbytes-result
+```
+
+## Usage
+
+```python
+from crashbytes_result import Ok, Err, Result, safe
+
+def divide(a: float, b: float) -> Result[float, str]:
+    if b == 0:
+        return Err("division by zero")
+    return Ok(a / b)
+
+result = divide(10, 3)
+match result:
+    case Ok(value):
+        print(f"Result: {value}")
+    case Err(error):
+        print(f"Error: {error}")
+
+# Or use .match()
+msg = result.match(
+    ok=lambda v: f"Got {v:.2f}",
+    err=lambda e: f"Failed: {e}",
+)
+
+# @safe decorator
+@safe
+def parse_int(s: str) -> int:
+    return int(s)
+
+parse_int("42")   # Ok(42)
+parse_int("abc")  # Err(ValueError(...))
+```
+
+## API
+
+| Method | Ok | Err |
+|--------|-----|------|
+| `.unwrap()` | Returns value | Raises `UnwrapError` |
+| `.unwrap_or(default)` | Returns value | Returns default |
+| `.unwrap_err()` | Raises `UnwrapError` | Returns error |
+| `.map(fn)` | `Ok(fn(value))` | `self` |
+| `.map_err(fn)` | `self` | `Err(fn(error))` |
+| `.bind(fn)` | `fn(value)` | `self` |
+| `.match(ok, err)` | `ok(value)` | `err(error)` |
+| `.is_ok` | `True` | `False` |
+| `.is_err` | `False` | `True` |
+
+## License
+
+MIT

crashbytes_result-1.0.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "crashbytes-result"
+version = "1.0.0"
+description = "A practical Result type for Python — Ok, Err, and pattern matching."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "CrashBytes", email = "crashbytes@users.noreply.github.com" }]
+keywords = ["result", "ok", "err", "monad", "error-handling", "pattern-matching"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-cov", "mypy", "ruff"]
+
+[project.urls]
+Homepage = "https://github.com/CrashBytes/crashbytes-result"
+Repository = "https://github.com/CrashBytes/crashbytes-result"
+Issues = "https://github.com/CrashBytes/crashbytes-result/issues"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "SIM", "TCH"]
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+branch = true
+source = ["crashbytes_result"]
+
+[tool.coverage.report]
+fail_under = 90

crashbytes_result-1.0.0/src/crashbytes_result/__init__.py

@@ -0,0 +1,5 @@
+"""crashbytes-result — A practical Result type for Python."""
+
+from crashbytes_result._core import Err, Ok, Result, UnwrapError, safe
+
+__all__ = ["Err", "Ok", "Result", "UnwrapError", "safe"]

crashbytes_result-1.0.0/src/crashbytes_result/_core.py

@@ -0,0 +1,182 @@
+"""Result type for explicit error handling — Ok[T] | Err[E]."""
+
+from __future__ import annotations
+
+import functools
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Generic, NoReturn, TypeVar
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+T = TypeVar("T")
+U = TypeVar("U")
+E = TypeVar("E")
+F = TypeVar("F")
+
+
+@dataclass(frozen=True, slots=True)
+class Ok(Generic[T]):
+    """Represents a successful result containing a value."""
+
+    _value: T
+
+    @property
+    def value(self) -> T:
+        return self._value
+
+    @property
+    def is_ok(self) -> bool:
+        return True
+
+    @property
+    def is_err(self) -> bool:
+        return False
+
+    def unwrap(self) -> T:
+        """Return the contained value."""
+        return self._value
+
+    def unwrap_or(self, default: object) -> T:
+        """Return the contained value (ignores default)."""
+        return self._value
+
+    def unwrap_err(self) -> NoReturn:
+        """Raise because this is Ok, not Err."""
+        raise UnwrapError(f"Called unwrap_err on Ok({self._value!r})")
+
+    def map(self, fn: Callable[[T], U]) -> Ok[U]:
+        """Apply *fn* to the contained value."""
+        return Ok(fn(self._value))
+
+    def map_err(self, fn: Callable[[Any], Any]) -> Ok[T]:
+        """No-op for Ok — return self."""
+        return self
+
+    def bind(self, fn: Callable[[T], Result[U, Any]]) -> Result[U, Any]:
+        """Apply *fn* that returns a Result."""
+        return fn(self._value)
+
+    def match(
+        self,
+        ok: Callable[[T], U],
+        err: Callable[[Any], U],
+    ) -> U:
+        """Pattern match — calls *ok* branch."""
+        return ok(self._value)
+
+    def __repr__(self) -> str:
+        return f"Ok({self._value!r})"
+
+    # Support Python 3.10+ structural pattern matching
+    __match_args__ = ("_value",)
+
+
+@dataclass(frozen=True, slots=True)
+class Err(Generic[E]):
+    """Represents a failed result containing an error."""
+
+    _error: E
+
+    @property
+    def error(self) -> E:
+        return self._error
+
+    @property
+    def is_ok(self) -> bool:
+        return False
+
+    @property
+    def is_err(self) -> bool:
+        return True
+
+    def unwrap(self) -> NoReturn:
+        """Raise because this is Err."""
+        raise UnwrapError(f"Called unwrap on Err({self._error!r})")
+
+    def unwrap_or(self, default: T) -> T:
+        """Return *default* because this is Err."""
+        return default
+
+    def unwrap_err(self) -> E:
+        """Return the contained error."""
+        return self._error
+
+    def map(self, fn: Callable[[Any], Any]) -> Err[E]:
+        """No-op for Err — return self."""
+        return self
+
+    def map_err(self, fn: Callable[[E], F]) -> Err[F]:
+        """Apply *fn* to the contained error."""
+        return Err(fn(self._error))
+
+    def bind(self, fn: Callable[[Any], Any]) -> Err[E]:
+        """No-op for Err — return self."""
+        return self
+
+    def match(
+        self,
+        ok: Callable[[Any], U],
+        err: Callable[[E], U],
+    ) -> U:
+        """Pattern match — calls *err* branch."""
+        return err(self._error)
+
+    def __repr__(self) -> str:
+        return f"Err({self._error!r})"
+
+    __match_args__ = ("_error",)
+
+
+Result = Ok[T] | Err[E]
+"""Type alias: a value is either ``Ok[T]`` or ``Err[E]``."""
+
+
+class UnwrapError(Exception):
+    """Raised when unwrapping a Result incorrectly."""
+
+
+def safe(
+    *args: Any,
+) -> Any:
+    """Decorator that wraps a function to return ``Ok`` or ``Err``.
+
+    Usage::
+
+        @safe
+        def parse_int(s: str) -> int:
+            return int(s)
+
+        @safe(ValueError, KeyError)
+        def lookup(data: dict, key: str) -> str:
+            return data[key]
+    """
+    if len(args) == 1 and callable(args[0]) and not (
+        isinstance(args[0], type) and issubclass(args[0], BaseException)
+    ):
+        fn = args[0]
+
+        @functools.wraps(fn)
+        def wrapper(*a: Any, **kw: Any) -> Any:
+            try:
+                return Ok(fn(*a, **kw))
+            except Exception as exc:
+                return Err(exc)
+
+        return wrapper
+
+    exceptions = tuple(args)
+    if not exceptions:
+        exceptions = (Exception,)
+
+    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+        @functools.wraps(fn)
+        def wrapper(*a: Any, **kw: Any) -> Any:
+            try:
+                return Ok(fn(*a, **kw))
+            except exceptions as exc:
+                return Err(exc)
+
+        return wrapper
+
+    return decorator

crashbytes_result-1.0.0/tests/test_result.py

@@ -0,0 +1,186 @@
+"""Tests for crashbytes-result."""
+
+from __future__ import annotations
+
+import pytest
+
+from crashbytes_result import Err, Ok, UnwrapError, safe
+
+
+class TestOk:
+    def test_value(self) -> None:
+        assert Ok(42).value == 42
+
+    def test_is_ok(self) -> None:
+        assert Ok(1).is_ok is True
+
+    def test_is_err(self) -> None:
+        assert Ok(1).is_err is False
+
+    def test_unwrap(self) -> None:
+        assert Ok("hello").unwrap() == "hello"
+
+    def test_unwrap_or(self) -> None:
+        assert Ok(10).unwrap_or(0) == 10
+
+    def test_unwrap_err_raises(self) -> None:
+        with pytest.raises(UnwrapError, match="Called unwrap_err on Ok"):
+            Ok(1).unwrap_err()
+
+    def test_map(self) -> None:
+        result = Ok(5).map(lambda x: x * 2)
+        assert result == Ok(10)
+
+    def test_map_err_is_noop(self) -> None:
+        result = Ok(5).map_err(lambda e: str(e))
+        assert result == Ok(5)
+
+    def test_bind_ok(self) -> None:
+        result = Ok(5).bind(lambda x: Ok(x + 1))
+        assert result == Ok(6)
+
+    def test_bind_err(self) -> None:
+        result = Ok(5).bind(lambda x: Err("fail"))
+        assert result == Err("fail")
+
+    def test_match_ok(self) -> None:
+        value = Ok(42).match(ok=lambda v: f"got {v}", err=lambda e: f"err {e}")
+        assert value == "got 42"
+
+    def test_repr(self) -> None:
+        assert repr(Ok(42)) == "Ok(42)"
+        assert repr(Ok("hi")) == "Ok('hi')"
+
+    def test_equality(self) -> None:
+        assert Ok(1) == Ok(1)
+        assert Ok(1) != Ok(2)
+        assert Ok(1) != Err(1)
+
+    def test_frozen(self) -> None:
+        with pytest.raises(AttributeError):
+            Ok(1)._value = 2  # type: ignore[misc]
+
+
+class TestErr:
+    def test_error(self) -> None:
+        assert Err("fail").error == "fail"
+
+    def test_is_ok(self) -> None:
+        assert Err("x").is_ok is False
+
+    def test_is_err(self) -> None:
+        assert Err("x").is_err is True
+
+    def test_unwrap_raises(self) -> None:
+        with pytest.raises(UnwrapError, match="Called unwrap on Err"):
+            Err("oops").unwrap()
+
+    def test_unwrap_or(self) -> None:
+        assert Err("fail").unwrap_or(42) == 42
+
+    def test_unwrap_err(self) -> None:
+        assert Err("fail").unwrap_err() == "fail"
+
+    def test_map_is_noop(self) -> None:
+        result = Err("fail").map(lambda x: x * 2)
+        assert result == Err("fail")
+
+    def test_map_err(self) -> None:
+        result = Err("fail").map_err(lambda e: e.upper())
+        assert result == Err("FAIL")
+
+    def test_bind_is_noop(self) -> None:
+        result = Err("fail").bind(lambda x: Ok(x + 1))
+        assert result == Err("fail")
+
+    def test_match_err(self) -> None:
+        value = Err("bad").match(ok=lambda v: f"got {v}", err=lambda e: f"err {e}")
+        assert value == "err bad"
+
+    def test_repr(self) -> None:
+        assert repr(Err("fail")) == "Err('fail')"
+
+    def test_equality(self) -> None:
+        assert Err("a") == Err("a")
+        assert Err("a") != Err("b")
+        assert Err(1) != Ok(1)
+
+    def test_frozen(self) -> None:
+        with pytest.raises(AttributeError):
+            Err("x")._error = "y"  # type: ignore[misc]
+
+
+class TestPatternMatching:
+    def test_match_ok(self) -> None:
+        result: Ok[int] | Err[str] = Ok(42)
+        match result:
+            case Ok(value):
+                assert value == 42
+            case Err(error):
+                pytest.fail(f"Unexpected Err: {error}")
+
+    def test_match_err(self) -> None:
+        result: Ok[int] | Err[str] = Err("fail")
+        match result:
+            case Ok(value):
+                pytest.fail(f"Unexpected Ok: {value}")
+            case Err(error):
+                assert error == "fail"
+
+
+class TestSafeDecorator:
+    def test_safe_returns_ok(self) -> None:
+        @safe
+        def parse(s: str) -> int:
+            return int(s)
+
+        result = parse("42")
+        assert result == Ok(42)
+
+    def test_safe_returns_err(self) -> None:
+        @safe
+        def parse(s: str) -> int:
+            return int(s)
+
+        result = parse("abc")
+        assert isinstance(result, Err)
+        assert isinstance(result.error, ValueError)
+
+    def test_safe_with_specific_exceptions(self) -> None:
+        @safe(ValueError)
+        def parse(s: str) -> int:
+            return int(s)
+
+        result = parse("abc")
+        assert isinstance(result, Err)
+
+    def test_safe_with_specific_exceptions_unhandled(self) -> None:
+        @safe(ValueError)
+        def parse(s: str) -> int:
+            raise TypeError("wrong type")
+
+        with pytest.raises(TypeError, match="wrong type"):
+            parse("abc")
+
+    def test_safe_preserves_name(self) -> None:
+        @safe
+        def my_func() -> int:
+            return 1
+
+        assert my_func.__name__ == "my_func"
+
+    def test_safe_with_kwargs(self) -> None:
+        @safe
+        def add(a: int, b: int = 0) -> int:
+            return a + b
+
+        assert add(1, b=2) == Ok(3)
+
+    def test_safe_no_args_catches_all(self) -> None:
+        @safe()
+        def boom() -> int:
+            raise RuntimeError("boom")
+
+        result = boom()
+        assert isinstance(result, Err)
+        assert isinstance(result.error, RuntimeError)