Metadata-Version: 2.5
Name: result-type
Version: 0.1.1
Summary: A minimal, fully typed Result type for explicit error handling in Python (inspired by Rust).
Project-URL: Homepage, https://github.com/AI-Alchemy-Hub/result-type
Project-URL: Repository, https://github.com/AI-Alchemy-Hub/result-type
Project-URL: Issues, https://github.com/AI-Alchemy-Hub/result-type/issues
Author-email: Satya Prakash Nigam <spnigam25@yahoo.com>
License: MIT
License-File: LICENSE
Keywords: either,error-handling,functional,result,rust,typing
Classifier: Development Status :: 4 - Beta
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: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown


# result-type

[![PyPI version](https://img.shields.io/pypi/v/result-type)](https://pypi.org/project/result-type/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/AI-Alchemy-Hub/result-type/blob/main/LICENSE)
[![CI](https://github.com/AI-Alchemy-Hub/result-type/actions/workflows/tests.yml/badge.svg)](https://github.com/AI-Alchemy-Hub/result-type/actions)

A minimal, fully typed `Result` type for explicit error handling in Python — inspired by Rust.

---

## Installation

```bash
pip install result-type
```

---

## Quick Start

```python
from result_type import Ok, Err, Result

def divide(a: float, b: float) -> Result[float, str]:
    if b == 0:
        return Err("division by zero")
    return Ok(a / b)

result = divide(10, 2)

if result.is_ok():
    print(result.unwrap())          # 5.0
else:
    print(result.unwrap_err())
```

---

### Chaining Example

```python
def parse_number(text: str) -> Result[int, str]:
    try:
        return Ok(int(text))
    except ValueError:
        return Err(f"'{text}' is not a valid integer")

def reciprocal(n: int) -> Result[float, str]:
    if n == 0:
        return Err("division by zero")
    return Ok(1 / n)

result = (
    parse_number("10")
    .and_then(reciprocal)
    .map(lambda x: round(x, 3))
)

print(result)   # Ok(0.1)
```

---

### map_err Example

```python
result = parse_number("abc").map_err(lambda e: f"Error: {e}")
print(result)   # Err("Error: 'abc' is not a valid integer")
```

---

## API

| Method              | Description                                              |
|---------------------|----------------------------------------------------------|
| `Ok(value)`         | Creates a successful result                              |
| `Err(error)`        | Creates a failed result                                  |
| `.is_ok()`          | Returns `True` if the result is `Ok`                     |
| `.is_err()`         | Returns `True` if the result is `Err`                    |
| `.unwrap()`         | Returns the value or raises `ValueError` if `Err`        |
| `.unwrap_err()`     | Returns the error or raises `ValueError` if `Ok`         |
| `.map(func)`        | Applies `func` to the value if `Ok`, otherwise returns the `Err` unchanged |
| `.map_err(func)`    | Applies `func` to the error if `Err`, otherwise returns the `Ok` unchanged |
| `.and_then(func)`   | Chains another `Result`-returning function (flat map)    |

---

## Why this package?

Python’s traditional exception-based error handling is powerful, but there are situations where you want **explicit**, **typed**, and **composable** error handling without throwing exceptions.

`result-type` provides a tiny, zero-dependency `Result[T, E]` type inspired by Rust’s `Result`. It helps you write clearer and more predictable code, especially in data pipelines, parsers, validators, and service layers.

---

## Features

- Fully typed (works great with `mypy` and modern IDEs)
- Immutable (`frozen=True`)
- Zero runtime dependencies
- Tiny and focused API
- Clear error messages when misusing `.unwrap()` / `.unwrap_err()`

---

## Contributing

Contributions are welcome!  

- Fork the repository and create a feature branch.  
- Install dev dependencies:  
  ```bash
  pip install -e .[dev]
  ```
- Run tests with:  
  ```bash
  pytest
  ```
- Open a pull request with a clear description of your changes.

---

## License

MIT 