wraps 0.1.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 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.1.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 SafeList(List[T]):
    @wrap_option
    def get(self, index: int) -> T:
        return self[index]


array = SafeList([0, 1, 2, 3])

print(array.get(0))  # Some(value=0)
print(array.get(7))  # Null()

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 wraps import Result, wrap_result


@wrap_result[ValueError]
def parse(string: str) -> int:
    return int(string)


def multiply(x: str, y: str) -> Result[int, ValueError]:
    # try to parse two strings and multiply results
    return parse(x).and_then(lambda m: parse(y).map(lambda n: m * n))


print(multiply("21", "2").unwrap())  # 42
print(multiply("!", "42").unwrap_error())  # invalid literal for `int` with base 10: `!`

In python versions before 3.9 (where grammar restrictions on decorators were relaxed), one can use wrap_result without a concrete type:

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

However this makes the types less specific, since Exception is caught instead of ValueError.

Instead, you can create a new concrete WrapResult[E] instance:

from wraps import WrapResult

wrap_value_error = WrapResult(ValueError)

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

Early Return

Early return functionality (? operator in Rust) is implemented via Q property (for both Option and Result types) combined with the @option_shortcut or @result_shortcut decorator respectively.

from wraps import Option, Some, option_shortcut, wrap_option


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


@option_shortcut
def try_add(x: str, y: str) -> Option[int]:
    m = parse(x).Q
    n = parse(y).Q

    return Some(m + n)

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.