crashbytes-result 1.0.0__py3-none-any.whl

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

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

@@ -0,0 +1,7 @@
+crashbytes_result/__init__.py,sha256=eCSZRj2dZIUShSOLrgnPvFj99dclgGEAtZDt6j7QD-I,194
+crashbytes_result/_core.py,sha256=-RESJQCIbsDgQeQCGT15KJV_xNlIKfq2MIi0ubQKP_Y,4485
+crashbytes_result/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+crashbytes_result-1.0.0.dist-info/METADATA,sha256=XyoyFIQXIwZ-zGUhH7o-1-Nsekbq_4XH-Y3ZeAjCDgQ,2442
+crashbytes_result-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+crashbytes_result-1.0.0.dist-info/licenses/LICENSE,sha256=Ic61HOO4EsyXXAGNY-D-1nG62feh_IBbipY1v_QcYcY,1067
+crashbytes_result-1.0.0.dist-info/RECORD,,

crashbytes_result-1.0.0.dist-info/WHEEL

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

crashbytes_result-1.0.0.dist-info/licenses/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.