wraps 0.5.0

Meaningful and safe wrapping types.

wraps

Meaningful and safe wrapping types.

Installing

Python 3.7 or above is required.

pip

Installing the library with pip is quite simple:

$ pip install wraps

Alternatively, the library can be installed from the source:

$ git clone https://github.com/nekitdev/wraps.git
$ cd wraps
$ python -m pip install .

poetry

You can add wraps as a dependency with the following command:

$ poetry add wraps

Or by directly specifying it in the configuration like so:

[tool.poetry.dependencies]
wraps = "^0.5.0"

Alternatively, you can add it directly from the source:

[tool.poetry.dependencies.wraps]
git = "https://github.com/nekitdev/wraps.git"

Examples

Option

Option[T] type represents an optional value: every option is either Some[T] and contains a value, or Null, and does not.

Here is an example of using wrap_option to catch any errors:

from typing import List, TypeVar
from wraps import wrap_option

T = TypeVar("T", covariant=True)


class Array(List[T]):
    @wrap_option
    def get(self, index: int) -> T:
        return self[index]


array = Array([1, 2, 3])

print(array.get(0).unwrap())  # 1
print(array.get(5).unwrap_or(0))  # 0

Result

Result[T, E] is the type used for returning and propagating errors. It has two variants, Ok[T], representing success and containing a value, and Error[E], representing error and containing an error value.

from enum import Enum

from wraps import Error, Ok, Result


class DivideError(Enum):
    DIVISION_BY_ZERO = "division by zero"


def divide(numerator: float, denominator: float) -> Result[float, DivideError]:
    return Ok(numerator / denominator) if denominator else Error(DivideError.DIVISION_BY_ZERO)

Early Return

Early return functionality (like the question-mark (?) operator in Rust) is implemented via early methods (for both Option and Result types) combined with the @early_option and @early_result decorators respectively.

from wraps import Option, early_option, wrap_option


@wrap_option[ValueError]
def parse(string: str) -> float:
    return float(string)


@wrap_option[ZeroDivisionError]
def divide(numerator: float, denominator: float) -> float:
    return numerator / denominator


@early_option
def function(x: str, y: str) -> Option[float]:
    return divide(parse(x).early(), parse(y).early())

Decorators

In Python 3.9 the restrictions on the decorators' syntax have been lifted, which allows for nifty syntax which can be seen above. On older versions of Python, one can use:

from wraps import wrap_option

@wrap_option
def parse(string: str) -> int:
    return int(string)

However, this isn't the best way to handle errors, as any normal errors will be caught, without a way to distinguish between them. To counter this, one can use WrapOption directly, passing the concrete error type:

from wraps import WrapOption

wrap_value_error = WrapOption(ValueError)


@wrap_value_error
def parse(string: str) -> int:
    return int(string)

Documentation

You can find the documentation here.

Support

If you need support with the library, you can send us an email or refer to the official Discord server.

Changelog

You can find the changelog here.

Security Policy

You can find the Security Policy of wraps here.

Contributing

If you are interested in contributing to wraps, make sure to take a look at the Contributing Guide, as well as the Code of Conduct.

License

wraps is licensed under the MIT License terms. See License for details.