rust-ok 0.1.0__tar.gz

rust_ok-0.1.0/LICENSE.txt

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, pesap
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

rust_ok-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.3
+Name: rust-ok
+Version: 0.1.0
+Summary: Rust-inspired Result/Ok/Err primitives for Python
+Keywords: result,error-handling,rust,functional,typing
+Author: pesap
+Author-email: pesap <pesap@users.noreply.github.com>
+License: BSD 3-Clause License
+         
+         Copyright (c) 2025, pesap
+         
+         Redistribution and use in source and binary forms, with or without
+         modification, are permitted provided that the following conditions are met:
+         
+         1. Redistributions of source code must retain the above copyright notice, this
+            list of conditions and the following disclaimer.
+         
+         2. Redistributions in binary form must reproduce the above copyright notice,
+            this list of conditions and the following disclaimer in the documentation
+            and/or other materials provided with the distribution.
+         
+         3. Neither the name of the copyright holder nor the names of its
+            contributors may be used to endorse or promote products derived from
+            this software without specific prior written permission.
+         
+         THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+         AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+         IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+         DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+         FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+         DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+         SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+         CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+         OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+         OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Natural Language :: English
+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: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11, <3.15
+Description-Content-Type: text/markdown
+
+# rust-ok
+Rust-style `Result`, `Ok`, and `Err` primitives for Python projects.
+
+## Installation
+```bash
+pip install rust-ok
+```
+
+## Usage
+```python
+from rust_ok import Result, Ok, Err
+
+def parse_int(raw: str) -> Result[int, str]:
+    try:
+        return Ok(int(raw))
+    except ValueError as exc:
+        return Err(str(exc))
+
+result = parse_int("42")
+print(result.unwrap_or(0))  # -> 42
+```
+
+### Formatting exception chains
+```python
+from rust_ok import Err, Ok, format_exception_chain
+
+try:
+    Err(ValueError("boom")).unwrap()
+except Exception as exc:
+    print(format_exception_chain(exc))
+```
+
+### Iterating over results
+```python
+from rust_ok import Err, Ok, is_ok
+
+results = [Ok(1), Err("bad"), Ok(3)]
+
+for res in results:
+    if is_ok(res):
+        print("value:", res.unwrap())
+```

rust_ok-0.1.0/README.md

@@ -0,0 +1,42 @@
+# rust-ok
+Rust-style `Result`, `Ok`, and `Err` primitives for Python projects.
+
+## Installation
+```bash
+pip install rust-ok
+```
+
+## Usage
+```python
+from rust_ok import Result, Ok, Err
+
+def parse_int(raw: str) -> Result[int, str]:
+    try:
+        return Ok(int(raw))
+    except ValueError as exc:
+        return Err(str(exc))
+
+result = parse_int("42")
+print(result.unwrap_or(0))  # -> 42
+```
+
+### Formatting exception chains
+```python
+from rust_ok import Err, Ok, format_exception_chain
+
+try:
+    Err(ValueError("boom")).unwrap()
+except Exception as exc:
+    print(format_exception_chain(exc))
+```
+
+### Iterating over results
+```python
+from rust_ok import Err, Ok, is_ok
+
+results = [Ok(1), Err("bad"), Ok(3)]
+
+for res in results:
+    if is_ok(res):
+        print("value:", res.unwrap())
+```

rust_ok-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "rust-ok"
+version = "0.1.0"
+description = "Rust-inspired Result/Ok/Err primitives for Python"
+readme = "README.md"
+authors = [
+    { name = "pesap", email = "pesap@users.noreply.github.com" }
+]
+requires-python = ">=3.11,<3.15"
+license = { file = "LICENSE.txt" }
+keywords = [
+    "result",
+    "error-handling",
+    "rust",
+    "functional",
+    "typing",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: BSD License",
+    "Natural Language :: English",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[dependency-groups]
+dev = [
+    "mypy>=1.18.2",
+    "pre-commit>=4.5.0,<5.0.0",
+    "pytest>=8.3.0,<9.0.0",
+    "pytest-cov>=5.0.0,<6.0.0",
+    "ruff>=0.6.8,<0.7.0",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+addopts = [
+    "--cov=rust_ok",
+    "--cov-report=term-missing",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.10,<0.10.0"]
+build-backend = "uv_build"

rust_ok-0.1.0/src/rust_ok/__init__.py

@@ -0,0 +1,21 @@
+"""Public API for rust-ok."""
+
+from .exceptions import IsNotError, RustOkError, UnwrapError
+from .err import Err
+from .ok import Ok
+from .guards import is_err, is_ok
+from .result import Result
+from .trace import format_exception_chain, iter_causes
+
+__all__ = [
+    "Err",
+    "IsNotError",
+    "Ok",
+    "Result",
+    "RustOkError",
+    "UnwrapError",
+    "format_exception_chain",
+    "iter_causes",
+    "is_err",
+    "is_ok",
+]

rust_ok-0.1.0/src/rust_ok/err.py

@@ -0,0 +1,92 @@
+"""Implementation of the Err variant."""
+
+from __future__ import annotations
+
+from typing import Callable, Optional, TypeVar
+
+from .exceptions import UnwrapError
+from .result import Result
+
+T = TypeVar("T")
+E = TypeVar("E")
+U = TypeVar("U")
+F = TypeVar("F")
+
+
+class Err(Result[T, E]):
+    """Error result containing an error value."""
+
+    __slots__ = ("_error_value",)
+    __match_args__ = ("error",)
+
+    def __init__(self, error: E) -> None:
+        self._error_value = error
+
+    def __repr__(self) -> str:
+        return f"Err({self._error_value!r})"
+
+    def __str__(self) -> str:
+        return f"Err({self._error_value})"
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Err):
+            return bool(self._error_value == other._error_value)
+        return False
+
+    def __hash__(self) -> int:
+        return hash(("Err", self._error_value))
+
+    def __bool__(self) -> bool:
+        return False
+
+    def unwrap(self) -> T:
+        raise UnwrapError(f"Called unwrap on Err: {self._error_value}")
+
+    def unwrap_err(self) -> E:
+        return self._error_value
+
+    def unwrap_or(self, default: T) -> T:
+        return default
+
+    def unwrap_or_else(self, func: Callable[[E], T]) -> T:
+        return func(self._error_value)
+
+    def expect(self, msg: str) -> T:
+        raise UnwrapError(f"{msg}: {self._error_value}")
+
+    def is_ok(self) -> bool:
+        return False
+
+    def is_err(self) -> bool:
+        return True
+
+    def map(self, func: Callable[[T], U]) -> Result[U, E]:
+        return Err(self._error_value)
+
+    def map_err(self, func: Callable[[E], F]) -> Result[T, F]:
+        return Err(func(self._error_value))
+
+    def and_then(self, func: Callable[[T], Result[U, E]]) -> Result[U, E]:
+        return Err(self._error_value)
+
+    def or_else(self, func: Callable[[E], Result[T, F]]) -> Result[T, F]:
+        return func(self._error_value)
+
+    def ok(self) -> T | None:
+        return None
+
+    def err(self) -> E:
+        return self._error_value
+
+    def unwrap_or_raise(
+        self,
+        exc_type: type[BaseException] = Exception,
+        context: Optional[str] = None,
+    ) -> T:
+        payload = self._error_value
+        msg = context if context is not None else str(payload)
+
+        if isinstance(payload, BaseException):
+            raise exc_type(msg) from payload
+
+        raise exc_type(f"{msg}: {payload!r}")

rust_ok-0.1.0/src/rust_ok/exceptions.py

@@ -0,0 +1,13 @@
+"""Custom exceptions for rust-ok."""
+
+
+class RustOkError(Exception):
+    """Base exception for all rust-ok errors."""
+
+
+class UnwrapError(RustOkError):
+    """Raised when accessing an Ok/Err value in an invalid way."""
+
+
+class IsNotError(RustOkError):
+    """Raised when attempting to retrieve an error from an Ok result."""

rust_ok-0.1.0/src/rust_ok/guards.py

@@ -0,0 +1,22 @@
+"""Type-guard helpers for Result values."""
+
+from __future__ import annotations
+
+from typing import TypeGuard, TypeVar
+
+from .err import Err
+from .ok import Ok
+from .result import Result
+
+T = TypeVar("T")
+E = TypeVar("E")
+
+
+def is_ok(result: Result[T, E]) -> TypeGuard[Ok[T, E]]:
+    """Return True if the result is Ok."""
+    return isinstance(result, Ok)
+
+
+def is_err(result: Result[T, E]) -> TypeGuard[Err[T, E]]:
+    """Return True if the result is Err."""
+    return isinstance(result, Err)

rust_ok-0.1.0/src/rust_ok/ok.py

@@ -0,0 +1,94 @@
+"""Implementation of the Ok variant."""
+
+from __future__ import annotations
+
+from typing import Callable, Literal, Optional, TypeVar, cast, overload
+
+from .exceptions import IsNotError, UnwrapError
+from .result import Result
+
+T = TypeVar("T")
+E = TypeVar("E")
+U = TypeVar("U")
+F = TypeVar("F")
+
+
+class Ok(Result[T, E]):
+    """Success result containing a value."""
+
+    __slots__ = ("value",)
+    __match_args__ = ("value",)
+
+    value: T
+
+    @overload
+    def __init__(self: "Ok[None, E]", value: Literal[None] = None) -> None: ...
+
+    @overload
+    def __init__(self: "Ok[T, E]", value: T) -> None: ...
+
+    def __init__(self, value: Optional[T] = None) -> None:
+        self.value = cast(T, value)
+
+    def __repr__(self) -> str:
+        return f"Ok({self.value!r})"
+
+    def __str__(self) -> str:
+        return f"Ok({self.value})"
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Ok):
+            return bool(self.value == other.value)
+        return False
+
+    def __hash__(self) -> int:
+        return hash(("Ok", self.value))
+
+    def __bool__(self) -> bool:
+        return True
+
+    def unwrap(self) -> T:
+        return self.value
+
+    def unwrap_err(self) -> E:
+        raise UnwrapError("Called unwrap_err on Ok")
+
+    def unwrap_or(self, default: T) -> T:
+        return self.value
+
+    def unwrap_or_else(self, func: Callable[[E], T]) -> T:
+        return self.value
+
+    def expect(self, msg: str) -> T:
+        return self.value
+
+    def is_ok(self) -> bool:
+        return True
+
+    def is_err(self) -> bool:
+        return False
+
+    def map(self, func: Callable[[T], U]) -> Result[U, E]:
+        return Ok(func(self.value))
+
+    def map_err(self, func: Callable[[E], F]) -> Result[T, F]:
+        return Ok(self.value)
+
+    def and_then(self, func: Callable[[T], Result[U, E]]) -> Result[U, E]:
+        return func(self.value)
+
+    def or_else(self, func: Callable[[E], Result[T, F]]) -> Result[T, F]:
+        return Ok(self.value)
+
+    def ok(self) -> T:
+        return self.value
+
+    def err(self) -> E:
+        raise IsNotError
+
+    def unwrap_or_raise(
+        self,
+        exc_type: type[BaseException] = Exception,
+        context: str | None = None,
+    ) -> T:
+        return self.value

rust_ok-0.1.0/src/rust_ok/result.py

@@ -0,0 +1,85 @@
+"""Base Result primitives and helpers."""
+
+from __future__ import annotations
+
+from typing import Callable, Generic, Optional, TypeVar
+
+T = TypeVar("T")
+E = TypeVar("E")
+U = TypeVar("U")
+F = TypeVar("F")
+
+
+class Result(Generic[T, E]):
+    """Base type for Ok/Err results."""
+
+    __slots__ = ()
+
+    def unwrap(self) -> T:
+        """Return the contained value if successful, else raise in subclass."""
+        raise NotImplementedError  # pragma: no cover
+
+    def unwrap_err(self) -> E:
+        """Return the contained error if Err, else raise in subclass."""
+        raise NotImplementedError  # pragma: no cover
+
+    def unwrap_or(self, default: T) -> T:
+        """Return the contained value if Ok, otherwise return the default."""
+        raise NotImplementedError  # pragma: no cover
+
+    def unwrap_or_else(self, func: Callable[[E], T]) -> T:
+        """Return the contained value if Ok, otherwise compute a default."""
+        raise NotImplementedError  # pragma: no cover
+
+    def expect(self, msg: str) -> T:
+        """Return the contained value if Ok, otherwise raise with custom message."""
+        raise NotImplementedError  # pragma: no cover
+
+    def is_ok(self) -> bool:  # pragma: no cover
+        """Return True if this is Ok."""
+        from .ok import Ok
+
+        return isinstance(self, Ok)
+
+    def is_err(self) -> bool:  # pragma: no cover
+        """Return True if this is Err."""
+        from .err import Err
+
+        return isinstance(self, Err)
+
+    def map(self, func: Callable[[T], U]) -> Result[U, E]:
+        """Apply func to the contained value if Ok, returning a new Result."""
+        raise NotImplementedError  # pragma: no cover
+
+    def map_err(self, func: Callable[[E], F]) -> Result[T, F]:
+        """Apply func to the error if Err, returning a new Result."""
+        raise NotImplementedError  # pragma: no cover
+
+    def and_then(self, func: Callable[[T], Result[U, E]]) -> Result[U, E]:
+        """Chain another computation on the contained value if Ok."""
+        raise NotImplementedError  # pragma: no cover
+
+    def or_else(self, func: Callable[[E], Result[T, F]]) -> Result[T, F]:
+        """Handle the error by calling func if Err, returning a new Result."""
+        raise NotImplementedError  # pragma: no cover
+
+    def ok(self) -> T | None:
+        """Return the success value if Ok, otherwise None."""
+        raise NotImplementedError  # pragma: no cover
+
+    def err(self) -> E:
+        """Return the error value if Err, otherwise raise in subclass."""
+        raise NotImplementedError  # pragma: no cover
+
+    @property
+    def error(self) -> E | None:
+        """Return the error value if Err, otherwise None."""
+        return self.err()
+
+    def unwrap_or_raise(
+        self,
+        exc_type: type[BaseException] = Exception,
+        context: Optional[str] = None,
+    ) -> T:
+        """Return the Ok value or raise `exc_type`."""
+        raise NotImplementedError  # pragma: no cover

rust_ok-0.1.0/src/rust_ok/trace.py

@@ -0,0 +1,40 @@
+"""Helpers for formatting chained exceptions."""
+
+from __future__ import annotations
+
+from io import StringIO
+from typing import Iterator
+
+
+def iter_causes(exc: BaseException) -> Iterator[BaseException]:
+    """Yield an exception and its chained causes/contexts in order."""
+    current: BaseException | None = exc
+    while current is not None:
+        yield current
+        if current.__cause__ is not None:
+            current = current.__cause__
+        elif current.__context__ is not None and not current.__suppress_context__:
+            current = current.__context__
+        else:
+            current = None
+
+
+def format_exception_chain(exc: BaseException) -> str:
+    """Return a readable string for an exception and its chain."""
+    from traceback import format_exception  # lazy import keeps module light
+
+    buffer = StringIO()
+    first = True
+    for cause in iter_causes(exc):
+        if not first:
+            buffer.write("\n\n")
+        first = False
+        chunk = "".join(
+            format_exception(
+                cause.__class__,
+                cause,
+                cause.__traceback__,
+            )
+        ).rstrip()
+        buffer.write(chunk)
+    return buffer.getvalue()