Some¶

Bases: Option[T]

Option variant representing the presence of a value.

Attributes:

Name	Type	Description
`value`	`T`	The contained value.

Example:

>>> import pyochain as pc
>>> pc.Some(42)
Some(42)

Source code in src/pyochain/_results/_option.py

@dataclass(slots=True)
class Some[T](Option[T]):
    """Option variant representing the presence of a value.

    Attributes:
        value (T): The contained value.

    Example:
    ```python
    >>> import pyochain as pc
    >>> pc.Some(42)
    Some(42)

    ```

    """

    value: T

    def __repr__(self) -> str:
        return f"Some({self.value!r})"

    def is_some(self) -> bool:
        return True

    def is_none(self) -> bool:
        return False

    def unwrap(self) -> T:
        return self.value

value `instance-attribute` ¶

value: T

and_ ¶

and_(optb: Option[U]) -> Option[U]

Returns NONE if the option is NONE, otherwise returns optb.

This is similar to and_then, except that the value is passed directly instead of through a closure.

Parameters:

Name	Type	Description	Default
`optb`	`Option[U]`	The option to return if the original option is `NONE`	required

Returns: Option[U]: NONE if the original option is NONE, otherwise optb.

Example:

>>> import pyochain as pc
>>> pc.Some(2).and_(pc.NONE)
NONE
>>> pc.NONE.and_(pc.Some("foo"))
NONE
>>> pc.Some(2).and_(pc.Some("foo"))
Some('foo')
>>> pc.NONE.and_(pc.NONE)
NONE

Source code in src/pyochain/_results/_option.py

def and_[U](self, optb: Option[U]) -> Option[U]:
    """Returns `NONE` if the option is `NONE`, otherwise returns optb.

    This is similar to `and_then`, except that the value is passed directly instead of through a closure.

    Args:
        optb (Option[U]): The option to return if the original option is `NONE`
    Returns:
        Option[U]: `NONE` if the original option is `NONE`, otherwise `optb`.

    Example:
    ```python
    >>> import pyochain as pc
    >>> pc.Some(2).and_(pc.NONE)
    NONE
    >>> pc.NONE.and_(pc.Some("foo"))
    NONE
    >>> pc.Some(2).and_(pc.Some("foo"))
    Some('foo')
    >>> pc.NONE.and_(pc.NONE)
    NONE

    ```
    """
    return optb if self.is_some() else NONE

and_then ¶

and_then(
    f: Callable[Concatenate[T, P], Option[R]], *args: P.args, **kwargs: P.kwargs
) -> Option[R]

Calls a function if the option is Some, otherwise returns None.

Parameters:

Name	Type	Description	Default
`f`	`Callable[Concatenate[T, P], Option[R]]`	The function to call with the `Some` value.	required
`*args`	`P.args`	Additional positional arguments to pass to f.	`()`
`**kwargs`	`P.kwargs`	Additional keyword arguments to pass to f.	`{}`

Returns:

Type	Description
`Option[R]`	Option[R]: The result of the function if `Some`, otherwise `None`.

Example:

>>> import pyochain as pc
>>> def sq(x: int) -> Option[int]:
...     return pc.Some(x * x)
>>> def nope(x: int) -> Option[int]:
...     return pc.NONE
>>> pc.Some(2).and_then(sq).and_then(sq)
Some(16)
>>> pc.Some(2).and_then(sq).and_then(nope)
NONE
>>> pc.Some(2).and_then(nope).and_then(sq)
NONE
>>> pc.NONE.and_then(sq).and_then(sq)
NONE

Source code in src/pyochain/_results/_option.py

def and_then[**P, R](
    self,
    f: Callable[Concatenate[T, P], Option[R]],
    *args: P.args,
    **kwargs: P.kwargs,
) -> Option[R]:
    """Calls a function if the option is `Some`, otherwise returns `None`.

    Args:
        f (Callable[Concatenate[T, P], Option[R]]): The function to call with the `Some` value.
        *args (P.args): Additional positional arguments to pass to f.
        **kwargs (P.kwargs): Additional keyword arguments to pass to f.

    Returns:
        Option[R]: The result of the function if `Some`, otherwise `None`.

    Example:
    ```python
    >>> import pyochain as pc
    >>> def sq(x: int) -> Option[int]:
    ...     return pc.Some(x * x)
    >>> def nope(x: int) -> Option[int]:
    ...     return pc.NONE
    >>> pc.Some(2).and_then(sq).and_then(sq)
    Some(16)
    >>> pc.Some(2).and_then(sq).and_then(nope)
    NONE
    >>> pc.Some(2).and_then(nope).and_then(sq)
    NONE
    >>> pc.NONE.and_then(sq).and_then(sq)
    NONE

    ```
    """
    return f(self.unwrap(), *args, **kwargs) if self.is_some() else NONE

expect ¶

expect(msg: str) -> T

Returns the contained Some value.

Raises an exception with a provided message if the value is None.

Parameters:

Name	Type	Description	Default
`msg`	`str`	The message to include in the exception if the result is `None`.	required

Returns:

Name	Type	Description
`T`	`T`	The contained `Some` value.

Raises:

Type	Description
`OptionUnwrapError`	If the result is `None`.

Example:

>>> import pyochain as pc
>>> pc.Some("value").expect("fruits are healthy")
'value'
>>> pc.NONE.expect("fruits are healthy")
Traceback (most recent call last):
    ...
pyochain._results._option.OptionUnwrapError: fruits are healthy (called `expect` on a `None`)

Source code in src/pyochain/_results/_option.py

def expect(self, msg: str) -> T:
    """Returns the contained `Some` value.

    Raises an exception with a provided message if the value is `None`.

    Args:
        msg (str): The message to include in the exception if the result is `None`.

    Returns:
        T: The contained `Some` value.

    Raises:
        OptionUnwrapError: If the result is `None`.

    Example:
    ```python
    >>> import pyochain as pc
    >>> pc.Some("value").expect("fruits are healthy")
    'value'
    >>> pc.NONE.expect("fruits are healthy")
    Traceback (most recent call last):
        ...
    pyochain._results._option.OptionUnwrapError: fruits are healthy (called `expect` on a `None`)

    ```
    """
    if self.is_some():
        return self.unwrap()
    msg = f"{msg} (called `expect` on a `None`)"
    raise OptionUnwrapError(msg)

filter ¶

filter(
    predicate: Callable[Concatenate[T, P], R], *args: P.args, **kwargs: P.kwargs
) -> Option[T]

Returns None if the option is None, otherwise calls predicate with the wrapped value.

This function works similar to Iter.filter in the sense that we only keep the value if it matches a predicate.

You can imagine the Option[T] being an iterator over one or zero elements.

Parameters:

Name	Type	Description	Default
`predicate`	`Callable[Concatenate[T, P], R]`	The predicate to apply to the contained value.	required
`*args`	`P.args`	Additional positional arguments to pass to predicate.	`()`
`**kwargs`	`P.kwargs`	Additional keyword arguments to pass to predicate.	`{}`

Returns:

Type	Description
`Option[T]`	Option[T]: `Some[T]` if predicate returns true (where T is the wrapped value), `NONE` if predicate returns false.

Examples:

>>> import pyochain as pc
>>>
>>> def is_even(n: int) -> bool:
...     return n % 2 == 0
>>>
>>> pc.NONE.filter(is_even)
NONE
>>> pc.Some(3).filter(is_even)
NONE
>>> pc.Some(4).filter(is_even)
Some(4)

Source code in src/pyochain/_results/_option.py

def filter[**P, R](
    self,
    predicate: Callable[Concatenate[T, P], R],
    *args: P.args,
    **kwargs: P.kwargs,
) -> Option[T]:
    """Returns None if the option is None, otherwise calls predicate with the wrapped value.

    This function works similar to `Iter.filter` in the sense that we only keep the value if it matches a predicate.

    You can imagine the `Option[T]` being an iterator over one or zero elements.

    Args:
        predicate (Callable[Concatenate[T, P], R]): The predicate to apply to the contained value.
        *args (P.args): Additional positional arguments to pass to predicate.
        **kwargs (P.kwargs): Additional keyword arguments to pass to predicate.

    Returns:
        Option[T]: `Some[T]` if predicate returns true (where T is the wrapped value), `NONE` if predicate returns false.


    Examples:
    ```python
    >>> import pyochain as pc
    >>>
    >>> def is_even(n: int) -> bool:
    ...     return n % 2 == 0
    >>>
    >>> pc.NONE.filter(is_even)
    NONE
    >>> pc.Some(3).filter(is_even)
    NONE
    >>> pc.Some(4).filter(is_even)
    Some(4)

    ```
    """
    return (
        self
        if self.is_some() and predicate(self.unwrap(), *args, **kwargs)
        else NONE
    )

flatten ¶

flatten() -> Option[U]

Flattens a nested Option.

Converts an Option[Option[U]] into an Option[U] by removing one level of nesting.

Equivalent to Option.and_then(lambda x: x).

Returns:

Type	Description
`Option[U]`	Option[U]: The flattened option.

Example:

>>> import pyochain as pc
>>> pc.Some(pc.Some(42)).flatten()
Some(42)
>>> pc.Some(pc.NONE).flatten()
NONE
>>> pc.NONE.flatten()
NONE

Source code in src/pyochain/_results/_option.py

def flatten[U](self: Option[Option[U]]) -> Option[U]:
    """Flattens a nested `Option`.

    Converts an `Option[Option[U]]` into an `Option[U]` by removing one level of nesting.

    Equivalent to `Option.and_then(lambda x: x)`.

    Returns:
        Option[U]: The flattened option.

    Example:
    ```python
    >>> import pyochain as pc
    >>> pc.Some(pc.Some(42)).flatten()
    Some(42)
    >>> pc.Some(pc.NONE).flatten()
    NONE
    >>> pc.NONE.flatten()
    NONE

    ```
    """
    return self.and_then(lambda x: x)

from_ `staticmethod` ¶

from_(value: V | None) -> Option[V]

Creates an Option[V] from a value that may be None.

Parameters:

Name	Type	Description	Default
`value`	`V \| None`	The value to convert into an `Option[V]`.	required

Returns:

Type	Description
`Option[V]`	Option[V]: `Some(value)` if the value is not `None`, otherwise `NONE`.

Example:

>>> import pyochain as pc
>>> pc.Option.from_(42)
Some(42)
>>> pc.Option.from_(None)
NONE

Source code in src/pyochain/_results/_option.py

@staticmethod
def from_[V](value: V | None) -> Option[V]:
    """Creates an `Option[V]` from a value that may be `None`.

    Args:
        value (V | None): The value to convert into an `Option[V]`.

    Returns:
        Option[V]: `Some(value)` if the value is not `None`, otherwise `NONE`.

    Example:
    ```python
    >>> import pyochain as pc
    >>> pc.Option.from_(42)
    Some(42)
    >>> pc.Option.from_(None)
    NONE

    ```
    """
    return cast(Option[V], Some(value) if value is not None else NONE)

inspect ¶

inspect(f: Callable[[T], object]) -> Option[T]

Applies a function to the contained Some value, returning the original Option.

This mirrors :meth:Result.inspect, allowing side effects (logging, debugging, metrics, etc.) on the wrapped value without changing it.

Parameters:

Name	Type	Description	Default
`f`	`Callable[[T], object]`	Function to apply to the `Some` value.	required

Returns:

Type	Description
`Option[T]`	Option[T]: The original option, unchanged.

Example:

>>> import pyochain as pc
>>> seen: list[int] = []
>>> pc.Some(2).inspect(lambda x: seen.append(x))
Some(2)
>>> seen
[2]
>>> pc.NONE.inspect(lambda x: seen.append(x))
NONE
>>> seen
[2]

Source code in src/pyochain/_results/_option.py

def inspect(self, f: Callable[[T], object]) -> Option[T]:
    """Applies a function to the contained `Some` value, returning the original `Option`.

    This mirrors :meth:`Result.inspect`, allowing side effects
    (logging, debugging, metrics, etc.) on the wrapped value without changing it.

    Args:
        f (Callable[[T], object]): Function to apply to the `Some` value.

    Returns:
        Option[T]: The original option, unchanged.

    Example:
    ```python
    >>> import pyochain as pc
    >>> seen: list[int] = []
    >>> pc.Some(2).inspect(lambda x: seen.append(x))
    Some(2)
    >>> seen
    [2]
    >>> pc.NONE.inspect(lambda x: seen.append(x))
    NONE
    >>> seen
    [2]

    ```
    """
    if self.is_some():
        f(self.unwrap())
    return self

into ¶

into(func: Callable[Concatenate[Self, P], R], *args: P.args, **kwargs: P.kwargs) -> R

Convert Self to R.

This method allows to pipe the instance into an object or function that can convert Self into another type.

Conceptually, this allow to do x.into(f) instead of f(x), hence keeping a functional chaining style.

This is a core method, shared by all pyochain wrappers, that allows chaining operations in a functional style.

Parameters:

Name	Type	Description	Default
`func`	`Callable[Concatenate[Self, P], R]`	Function for conversion.	required
`*args`	`P.args`	Positional arguments to pass to the function.	`()`
`**kwargs`	`P.kwargs`	Keyword arguments to pass to the function.	`{}`

Returns:

Name	Type	Description
`R`	`R`	The converted value.

Example:

>>> import pyochain as pc
>>> def maybe_sum(data: pc.Seq[int]) -> pc.Option[int]:
...     match data.length():
...         case 0:
...             return pc.NONE
...         case _:
...             return pc.Some(data.sum())
>>>
>>> pc.Seq(range(5)).into(maybe_sum).unwrap()
10

Source code in src/pyochain/_core/_main.py

def into[**P, R](
    self,
    func: Callable[Concatenate[Self, P], R],
    *args: P.args,
    **kwargs: P.kwargs,
) -> R:
    """Convert `Self` to `R`.

    This method allows to pipe the instance into an object or function that can convert `Self` into another type.

    Conceptually, this allow to do x.into(f) instead of f(x), hence keeping a functional chaining style.

    This is a core method, shared by all pyochain wrappers, that allows chaining operations in a functional style.

    Args:
        func (Callable[Concatenate[Self, P], R]): Function for conversion.
        *args (P.args): Positional arguments to pass to the function.
        **kwargs (P.kwargs): Keyword arguments to pass to the function.

    Returns:
        R: The converted value.

    Example:
    ```python
    >>> import pyochain as pc
    >>> def maybe_sum(data: pc.Seq[int]) -> pc.Option[int]:
    ...     match data.length():
    ...         case 0:
    ...             return pc.NONE
    ...         case _:
    ...             return pc.Some(data.sum())
    >>>
    >>> pc.Seq(range(5)).into(maybe_sum).unwrap()
    10

    ```
    """
    return func(self, *args, **kwargs)

is_none ¶

is_none() -> bool

Source code in src/pyochain/_results/_option.py

def is_none(self) -> bool:
    return False

is_none_or ¶

is_none_or(
    func: Callable[Concatenate[T, P], bool], *args: P.args, **kwargs: P.kwargs
) -> bool

Returns true if the option is a None or the value inside of it matches a predicate.

Parameters:

Name	Type	Description	Default
`func`	`Callable[Concatenate[T, P], bool]`	The predicate to apply to the contained value.	required
`*args`	`P.args`	Additional positional arguments to pass to func.	`()`
`**kwargs`	`P.kwargs`	Additional keyword arguments to pass to func.	`{}`

Returns:

Name	Type	Description
`bool`	`bool`	`True` if the option is `None` or the predicate returns `True` for the contained value, `False` otherwise.

Examples:

>>> import pyochain as pc
>>> pc.Some(2).is_none_or(lambda x: x > 1)
True
>>> pc.Some(0).is_none_or(lambda x: x > 1)
False
>>> pc.NONE.is_none_or(lambda x: x > 1)
True
>>> pc.Some("hello").is_none_or(lambda x: len(x) > 1)
True

Source code in src/pyochain/_results/_option.py

def is_none_or[**P](
    self, func: Callable[Concatenate[T, P], bool], *args: P.args, **kwargs: P.kwargs
) -> bool:
    """Returns true if the option is a None or the value inside of it matches a predicate.

    Args:
        func (Callable[Concatenate[T, P], bool]): The predicate to apply to the contained value.
        *args (P.args): Additional positional arguments to pass to func.
        **kwargs (P.kwargs): Additional keyword arguments to pass to func.

    Returns:
        bool: `True` if the option is `None` or the predicate returns `True` for the contained value, `False` otherwise.

    Examples:
    ```python
    >>> import pyochain as pc
    >>> pc.Some(2).is_none_or(lambda x: x > 1)
    True
    >>> pc.Some(0).is_none_or(lambda x: x > 1)
    False
    >>> pc.NONE.is_none_or(lambda x: x > 1)
    True
    >>> pc.Some("hello").is_none_or(lambda x: len(x) > 1)
    True

    ```
    """
    return self.is_none() or func(self.unwrap(), *args, **kwargs)

is_some ¶

is_some() -> bool

Source code in src/pyochain/_results/_option.py

def is_some(self) -> bool:
    return True

is_some_and ¶

is_some_and(
    predicate: Callable[Concatenate[T, P], bool], *args: P.args, **kwargs: P.kwargs
) -> bool

Returns true if the option is a Some and the value inside of it matches a predicate.

Parameters:

Name	Type	Description	Default
`predicate`	`Callable[Concatenate[T, P], bool]`	The predicate to apply to the contained value.	required
`*args`	`P.args`	Additional positional arguments to pass to predicate.	`()`
`**kwargs`	`P.kwargs`	Additional keyword arguments to pass to predicate.	`{}`

Returns:

Name	Type	Description
`bool`	`bool`	`True` if the option is `Some` and the predicate returns `True` for the contained value, `False` otherwise.

Examples:

>>> import pyochain as pc
>>> x = pc.Some(2)
>>> x.is_some_and(lambda x: x > 1)
True

>>> x = pc.Some(0)
>>> x.is_some_and(lambda x: x > 1)
False
>>> x = pc.NONE
>>> x.is_some_and(lambda x: x > 1)
False
>>> x = pc.Some("hello")
>>> x.is_some_and(lambda x: len(x) > 1)
True

Source code in src/pyochain/_results/_option.py

def is_some_and[**P](
    self,
    predicate: Callable[Concatenate[T, P], bool],
    *args: P.args,
    **kwargs: P.kwargs,
) -> bool:
    """Returns true if the option is a Some and the value inside of it matches a predicate.

    Args:
        predicate (Callable[Concatenate[T, P], bool]): The predicate to apply to the contained value.
        *args (P.args): Additional positional arguments to pass to predicate.
        **kwargs (P.kwargs): Additional keyword arguments to pass to predicate.

    Returns:
        bool: `True` if the option is `Some` and the predicate returns `True` for the contained value, `False` otherwise.

    Examples:
    ```python
    >>> import pyochain as pc
    >>> x = pc.Some(2)
    >>> x.is_some_and(lambda x: x > 1)
    True

    >>> x = pc.Some(0)
    >>> x.is_some_and(lambda x: x > 1)
    False
    >>> x = pc.NONE
    >>> x.is_some_and(lambda x: x > 1)
    False
    >>> x = pc.Some("hello")
    >>> x.is_some_and(lambda x: len(x) > 1)
    True

    ```
    """
    return self.is_some() and predicate(self.unwrap(), *args, **kwargs)

iter ¶

iter() -> Iter[T]

Creates an Iter over the optional value.

If the option is Some(value), the iterator yields value.
If the option is NONE, the iterator yields nothing.

Equivalent to Iter((self,)).

Returns:

Type	Description
`Iter[T]`	Iter[T]: An iterator over the optional value.

Example:

>>> import pyochain as pc
>>> pc.Some(42).iter().next()
Some(42)
>>> pc.NONE.iter().next()
NONE

Source code in src/pyochain/_results/_option.py

def iter(self) -> Iter[T]:
    """Creates an `Iter` over the optional value.

    - If the option is `Some(value)`, the iterator yields `value`.
    - If the option is `NONE`, the iterator yields nothing.

    Equivalent to `Iter((self,))`.

    Returns:
        Iter[T]: An iterator over the optional value.

    Example:
    ```python
    >>> import pyochain as pc
    >>> pc.Some(42).iter().next()
    Some(42)
    >>> pc.NONE.iter().next()
    NONE

    ```
    """
    from .._iter import Iter

    return Iter((self.unwrap(),)) if self.is_some() else Iter(())

map ¶

map(f: Callable[Concatenate[T, P], R], *args: P.args, **kwargs: P.kwargs) -> Option[R]

Maps an Option[T] to Option[U].

Done by applying a function to a contained Some value, leaving a None value untouched.

Parameters:

Name	Type	Description	Default
`f`	`Callable[Concatenate[T, P], R]`	The function to apply to the `Some` value.	required
`*args`	`P.args`	Additional positional arguments to pass to f.	`()`
`**kwargs`	`P.kwargs`	Additional keyword arguments to pass to f.	`{}`

Returns:

Type	Description
`Option[R]`	Option[R]: A new `Option` with the mapped value if `Some`, otherwise `None`.

Example:

>>> import pyochain as pc
>>> pc.Some("Hello, World!").map(len)
Some(13)
>>> pc.NONE.map(len)
NONE

Source code in src/pyochain/_results/_option.py

def map[**P, R](
    self, f: Callable[Concatenate[T, P], R], *args: P.args, **kwargs: P.kwargs
) -> Option[R]:
    """Maps an `Option[T]` to `Option[U]`.

    Done by applying a function to a contained `Some` value,
    leaving a `None` value untouched.

    Args:
        f (Callable[Concatenate[T, P], R]): The function to apply to the `Some` value.
        *args (P.args): Additional positional arguments to pass to f.
        **kwargs (P.kwargs): Additional keyword arguments to pass to f.

    Returns:
        Option[R]: A new `Option` with the mapped value if `Some`, otherwise `None`.

    Example:
    ```python
    >>> import pyochain as pc
    >>> pc.Some("Hello, World!").map(len)
    Some(13)
    >>> pc.NONE.map(len)
    NONE

    ```
    """
    return Some(f(self.unwrap(), *args, **kwargs)) if self.is_some() else NONE

map_or ¶

map_or(
    default: R, f: Callable[Concatenate[T, P], R], *args: P.args, **kwargs: P.kwargs
) -> R

Returns the result of applying a function to the contained value if Some, otherwise returns the default value.

Parameters:

Name	Type	Description	Default
`default`	`R`	The default value to return if NONE.	required
`f`	`Callable[Concatenate[T, P], R]`	The function to apply to the contained value.	required
`*args`	`P.args`	Additional positional arguments to pass to f.	`()`
`**kwargs`	`P.kwargs`	Additional keyword arguments to pass to f.	`{}`

Returns:

Name	Type	Description
`R`	`R`	The result of f(self.unwrap()) if Some, otherwise default.

Example:

>>> import pyochain as pc
>>> pc.Some(2).map_or(0, lambda x: x * 10)
20
>>> pc.NONE.map_or(0, lambda x: x * 10)
0

Source code in src/pyochain/_results/_option.py

def map_or[**P, R](
    self,
    default: R,
    f: Callable[Concatenate[T, P], R],
    *args: P.args,
    **kwargs: P.kwargs,
) -> R:
    """Returns the result of applying a function to the contained value if Some, otherwise returns the default value.

    Args:
        default (R): The default value to return if NONE.
        f (Callable[Concatenate[T, P], R]): The function to apply to the contained value.
        *args (P.args): Additional positional arguments to pass to f.
        **kwargs (P.kwargs): Additional keyword arguments to pass to f.

    Returns:
        R: The result of f(self.unwrap()) if Some, otherwise default.

    Example:
    ```python
    >>> import pyochain as pc
    >>> pc.Some(2).map_or(0, lambda x: x * 10)
    20
    >>> pc.NONE.map_or(0, lambda x: x * 10)
    0

    ```
    """
    return f(self.unwrap(), *args, **kwargs) if self.is_some() else default

map_or_else ¶

map_or_else(default: Callable[[], R], f: Callable[[T], R]) -> R

Returns the result of applying a function to the contained value if Some, otherwise computes a default value.

Parameters:

Name	Type	Description	Default
`default`	`Callable[[], R]`	A function returning the default value if NONE.	required
`f`	`Callable[[T], R]`	The function to apply to the contained value.	required

Returns:

Name	Type	Description
`R`	`R`	The result of f(self.unwrap()) if Some, otherwise default().

Example:

>>> import pyochain as pc
>>> pc.Some(2).map_or_else(lambda: 0, lambda x: x * 10)
20
>>> pc.NONE.map_or_else(lambda: 0, lambda x: x * 10)
0

Source code in src/pyochain/_results/_option.py

def map_or_else[**P, R](self, default: Callable[[], R], f: Callable[[T], R]) -> R:
    """Returns the result of applying a function to the contained value if Some, otherwise computes a default value.

    Args:
        default (Callable[[], R]): A function returning the default value if NONE.
        f (Callable[[T], R]): The function to apply to the contained value.

    Returns:
        R: The result of f(self.unwrap()) if Some, otherwise default().

    Example:
    ```python
    >>> import pyochain as pc
    >>> pc.Some(2).map_or_else(lambda: 0, lambda x: x * 10)
    20
    >>> pc.NONE.map_or_else(lambda: 0, lambda x: x * 10)
    0

    ```
    """
    return f(self.unwrap()) if self.is_some() else default()

ok_or ¶

ok_or(err: E) -> Result[T, E]

Converts the option to a Result.

Parameters:

Name	Type	Description	Default
`err`	`E`	The error value to use if the option is `NONE`.	required

Returns:

Type	Description
`Result[T, E]`	Result[T, E]: `Ok(v)` if `Some(v)`, otherwise `Err(err)`.

Example:

>>> import pyochain as pc
>>> pc.Some(1).ok_or('fail')
Ok(1)
>>> pc.NONE.ok_or('fail')
Err('fail')

Source code in src/pyochain/_results/_option.py

def ok_or[E](self, err: E) -> Result[T, E]:
    """Converts the option to a `Result`.

    Args:
        err (E): The error value to use if the option is `NONE`.

    Returns:
        Result[T, E]: `Ok(v)` if `Some(v)`, otherwise `Err(err)`.

    Example:
    ```python
    >>> import pyochain as pc
    >>> pc.Some(1).ok_or('fail')
    Ok(1)
    >>> pc.NONE.ok_or('fail')
    Err('fail')

    ```
    """
    from ._result import Err, Ok

    return Ok(self.unwrap()) if self.is_some() else Err(err)

ok_or_else ¶

ok_or_else(err: Callable[[], E]) -> Result[T, E]

Converts the option to a Result.

Parameters:

Name	Type	Description	Default
`err`	`Callable[[], E]`	A function returning the error value if the option is NONE.	required

Returns:

Type	Description
`Result[T, E]`	Result[T, E]: Ok(v) if Some(v), otherwise Err(err()).

Example:

>>> import pyochain as pc
>>> pc.Some(1).ok_or_else(lambda: 'fail')
Ok(1)
>>> pc.NONE.ok_or_else(lambda: 'fail')
Err('fail')

Source code in src/pyochain/_results/_option.py

def ok_or_else[E](self, err: Callable[[], E]) -> Result[T, E]:
    """Converts the option to a Result.

    Args:
        err (Callable[[], E]): A function returning the error value if the option is NONE.

    Returns:
        Result[T, E]: Ok(v) if Some(v), otherwise Err(err()).

    Example:
    ```python
    >>> import pyochain as pc
    >>> pc.Some(1).ok_or_else(lambda: 'fail')
    Ok(1)
    >>> pc.NONE.ok_or_else(lambda: 'fail')
    Err('fail')

    ```
    """
    from ._result import Err, Ok

    return Ok(self.unwrap()) if self.is_some() else Err(err())

or_ ¶

or_(optb: Option[T]) -> Option[T]

Returns the option if it contains a value, otherwise returns optb.

Parameters:

Name	Type	Description	Default
`optb`	`Option[T]`	The option to return if the original option is `NONE`.	required

Returns:

Type	Description
`Option[T]`	Option[T]: The original option if it is `Some`, otherwise `optb`.

Examples:

>>> import pyochain as pc
>>> pc.Some(2).or_(pc.NONE)
Some(2)
>>> pc.NONE.or_(pc.Some(100))
Some(100)
>>> pc.Some(2).or_(pc.Some(100))
Some(2)
>>> pc.NONE.or_(pc.NONE)
NONE

Source code in src/pyochain/_results/_option.py

def or_(self, optb: Option[T]) -> Option[T]:
    """Returns the option if it contains a value, otherwise returns optb.

    Args:
        optb (Option[T]): The option to return if the original option is `NONE`.

    Returns:
        Option[T]: The original option if it is `Some`, otherwise `optb`.

    Examples:
    ```python
    >>> import pyochain as pc
    >>> pc.Some(2).or_(pc.NONE)
    Some(2)
    >>> pc.NONE.or_(pc.Some(100))
    Some(100)
    >>> pc.Some(2).or_(pc.Some(100))
    Some(2)
    >>> pc.NONE.or_(pc.NONE)
    NONE

    ```
    """
    return self if self.is_some() else optb

or_else ¶

or_else(f: Callable[[], Option[T]]) -> Option[T]

Returns the Option[T] if it contains a value, otherwise calls a function and returns the result.

Parameters:

Name	Type	Description	Default
`f`	`Callable[[], Option[T]]`	The function to call if the option is `None`.	required

Returns:

Type	Description
`Option[T]`	Option[T]: The original `Option` if it is `Some`, otherwise the result of the function.

Example:

>>> import pyochain as pc
>>> def nobody() -> Option[str]:
...     return pc.NONE
>>> def vikings() -> Option[str]:
...     return pc.Some("vikings")
>>> pc.Some("barbarians").or_else(vikings)
Some('barbarians')
>>> pc.NONE.or_else(vikings)
Some('vikings')
>>> pc.NONE.or_else(nobody)
NONE

Source code in src/pyochain/_results/_option.py

def or_else(self, f: Callable[[], Option[T]]) -> Option[T]:
    """Returns the `Option[T]` if it contains a value, otherwise calls a function and returns the result.

    Args:
        f (Callable[[], Option[T]]): The function to call if the option is `None`.

    Returns:
        Option[T]: The original `Option` if it is `Some`, otherwise the result of the function.

    Example:
    ```python
    >>> import pyochain as pc
    >>> def nobody() -> Option[str]:
    ...     return pc.NONE
    >>> def vikings() -> Option[str]:
    ...     return pc.Some("vikings")
    >>> pc.Some("barbarians").or_else(vikings)
    Some('barbarians')
    >>> pc.NONE.or_else(vikings)
    Some('vikings')
    >>> pc.NONE.or_else(nobody)
    NONE

    ```
    """
    return self if self.is_some() else f()

reduce ¶

reduce(other: Option[T], func: Callable[[T, T], T]) -> Option[T]

Reduces two options into one, using the provided function if both are Some.

If self is Some(s) and other is Some(o), this method returns Some(func(s, o)).

Otherwise, if only one of self and other is Some, that value is returned.

If both self and other are NONE, NONE is returned.

Parameters:

Name	Type	Description	Default
`other`	`Option[T]`	The second option.	required
`func`	`Callable[[T, T], T]`	The function to apply to the unwrapped values.	required

Returns:

Type	Description
`Option[T]`	Option[T]: The resulting option after reduction.

Examples:

>>> import pyochain as pc
>>> s12 = pc.Some(12)
>>> s17 = pc.Some(17)
>>>
>>> def add(a: int, b: int) -> int:
...     return a + b
>>>
>>> s12.reduce(s17, add)
Some(29)
>>> s12.reduce(pc.NONE, add)
Some(12)
>>> pc.NONE.reduce(s17, add)
Some(17)
>>> pc.NONE.reduce(pc.NONE, add)
NONE

Source code in src/pyochain/_results/_option.py

def reduce[U](self, other: Option[T], func: Callable[[T, T], T]) -> Option[T]:
    """Reduces two options into one, using the provided function if both are Some.

    If **self** is `Some(s)` and **other** is `Some(o)`, this method returns `Some(func(s, o))`.

    Otherwise, if only one of **self** and **other** is `Some`, that value is returned.

    If both **self** and **other** are `NONE`, `NONE` is returned.

    Args:
        other (Option[T]): The second option.
        func (Callable[[T, T], T]): The function to apply to the unwrapped values.

    Returns:
        Option[T]: The resulting option after reduction.

    Examples:
    ```python
    >>> import pyochain as pc
    >>> s12 = pc.Some(12)
    >>> s17 = pc.Some(17)
    >>>
    >>> def add(a: int, b: int) -> int:
    ...     return a + b
    >>>
    >>> s12.reduce(s17, add)
    Some(29)
    >>> s12.reduce(pc.NONE, add)
    Some(12)
    >>> pc.NONE.reduce(s17, add)
    Some(17)
    >>> pc.NONE.reduce(pc.NONE, add)
    NONE

    ```
    """
    if self.is_some() and other.is_some():
        return Some(func(self.unwrap(), other.unwrap()))
    if self.is_some():
        return self
    if other.is_some():
        return other
    return NONE

tap ¶

tap(
    func: Callable[Concatenate[Self, P], Any], *args: P.args, **kwargs: P.kwargs
) -> Self

Tap into the chain to perform side effects without altering the data.

Parameters:

Name	Type	Description	Default
`func`	`Callable[Concatenate[Self, P], Any]`	Function to apply to the instance for side effects.	required
`*args`	`P.args`	Positional arguments to pass to the function.	`()`
`**kwargs`	`P.kwargs`	Keyword arguments to pass to the function.	`{}`

Returns:

Name	Type	Description
`Self`	`Self`	The instance itself for chaining.

Example:

>>> import pyochain as pc
>>> pc.Seq([1, 2, 3, 4]).tap(print).last()
Seq(1, 2, 3, 4)
4

Source code in src/pyochain/_core/_main.py

def tap[**P](
    self,
    func: Callable[Concatenate[Self, P], Any],
    *args: P.args,
    **kwargs: P.kwargs,
) -> Self:
    """Tap into the chain to perform side effects without altering the data.

    Args:
        func (Callable[Concatenate[Self, P], Any]): Function to apply to the instance for side effects.
        *args (P.args): Positional arguments to pass to the function.
        **kwargs (P.kwargs): Keyword arguments to pass to the function.

    Returns:
        Self: The instance itself for chaining.

    Example:
    ```python
    >>> import pyochain as pc
    >>> pc.Seq([1, 2, 3, 4]).tap(print).last()
    Seq(1, 2, 3, 4)
    4

    ```
    """
    func(self, *args, **kwargs)
    return self

transpose ¶

transpose() -> Result[Option[T], E]

Transposes an Option of a Result into a Result of an Option.

Some(Ok[T]) is mapped to Ok(Some[T]), Some(Err[E]) is mapped to Err[E], and NONE will be mapped to Ok(NONE).

Returns:

Type	Description
`Result[Option[T], E]`	Result[Option[T], E]: The transposed result.

Examples:

>>> import pyochain as pc
>>> pc.Some(pc.Ok(5)).transpose()
Ok(Some(5))
>>> pc.NONE.transpose()
Ok(NONE)
>>> pc.Some(pc.Err("error")).transpose()
Err('error')

Source code in src/pyochain/_results/_option.py

def transpose[E](self: Option[Result[T, E]]) -> Result[Option[T], E]:
    """Transposes an `Option` of a `Result` into a `Result` of an `Option`.

    `Some(Ok[T])` is mapped to `Ok(Some[T])`, `Some(Err[E])` is mapped to `Err[E]`, and `NONE` will be mapped to `Ok(NONE)`.

    Returns:
        Result[Option[T], E]: The transposed result.

    Examples:
    ```python
    >>> import pyochain as pc
    >>> pc.Some(pc.Ok(5)).transpose()
    Ok(Some(5))
    >>> pc.NONE.transpose()
    Ok(NONE)
    >>> pc.Some(pc.Err("error")).transpose()
    Err('error')

    ```
    """
    from ._result import Err, Ok

    if self.is_some():
        inner = self.unwrap()
        if inner.is_ok():
            return Ok(Option.from_(inner.unwrap()))
        return Err(inner.unwrap_err())
    return Ok(Option.from_(None))

unwrap ¶

unwrap() -> T

Source code in src/pyochain/_results/_option.py

def unwrap(self) -> T:
    return self.value

unwrap_or ¶

unwrap_or(default: T) -> T

Returns the contained Some value or a provided default.

Parameters:

Name	Type	Description	Default
`default`	`T`	The value to return if the result is `None`.	required

Returns:

Name	Type	Description
`T`	`T`	The contained `Some` value or the provided default.

Example:

>>> import pyochain as pc
>>> pc.Some("car").unwrap_or("bike")
'car'
>>> pc.NONE.unwrap_or("bike")
'bike'

Source code in src/pyochain/_results/_option.py

def unwrap_or(self, default: T) -> T:
    """Returns the contained `Some` value or a provided default.

    Args:
        default (T): The value to return if the result is `None`.

    Returns:
        T: The contained `Some` value or the provided default.

    Example:
    ```python
    >>> import pyochain as pc
    >>> pc.Some("car").unwrap_or("bike")
    'car'
    >>> pc.NONE.unwrap_or("bike")
    'bike'

    ```
    """
    return self.unwrap() if self.is_some() else default

unwrap_or_else ¶

unwrap_or_else(f: Callable[[], T]) -> T

Returns the contained Some value or computes it from a function.

Parameters:

Name	Type	Description	Default
`f`	`Callable[[], T]`	A function that returns a default value if the result is `None`.	required

Returns:

Name	Type	Description
`T`	`T`	The contained `Some` value or the result of the function.

Example:

>>> import pyochain as pc
>>> k = 10
>>> pc.Some(4).unwrap_or_else(lambda: 2 * k)
4
>>> pc.NONE.unwrap_or_else(lambda: 2 * k)
20

Source code in src/pyochain/_results/_option.py

def unwrap_or_else(self, f: Callable[[], T]) -> T:
    """Returns the contained `Some` value or computes it from a function.

    Args:
        f (Callable[[], T]): A function that returns a default value if the result is `None`.

    Returns:
        T: The contained `Some` value or the result of the function.

    Example:
    ```python
    >>> import pyochain as pc
    >>> k = 10
    >>> pc.Some(4).unwrap_or_else(lambda: 2 * k)
    4
    >>> pc.NONE.unwrap_or_else(lambda: 2 * k)
    20

    ```
    """
    return self.unwrap() if self.is_some() else f()

unzip ¶

unzip() -> tuple[Option[T], Option[U]]

Unzips an Option of a tuple into a tuple of Options.

If the option is Some((a, b)), this method returns (Some(a), Some(b)). If the option is NONE, it returns (NONE, NONE).

Returns:

Type	Description
`tuple[Option[T], Option[U]]`	tuple[Option[T], Option[U]]: A tuple containing two options.

Example:

>>> import pyochain as pc
>>> pc.Some((1, 'a')).unzip()
(Some(1), Some('a'))
>>> pc.NONE.unzip()
(NONE, NONE)

Source code in src/pyochain/_results/_option.py

def unzip[U](self: Option[tuple[T, U]]) -> tuple[Option[T], Option[U]]:
    """Unzips an `Option` of a tuple into a tuple of `Option`s.

    If the option is `Some((a, b))`, this method returns `(Some(a), Some(b))`.
    If the option is `NONE`, it returns `(NONE, NONE)`.

    Returns:
        tuple[Option[T], Option[U]]: A tuple containing two options.

    Example:
    ```python
    >>> import pyochain as pc
    >>> pc.Some((1, 'a')).unzip()
    (Some(1), Some('a'))
    >>> pc.NONE.unzip()
    (NONE, NONE)

    ```
    """
    if self.is_some():
        a, b = self.unwrap()
        return Some(a), Some(b)
    return NONE, NONE

xor ¶

xor(optb: Option[T]) -> Option[T]

Returns Some if exactly one of self, optb is Some, otherwise returns NONE.

Parameters:

Name	Type	Description	Default
`optb`	`Option[T]`	The other option to compare with.	required

Returns:

Type	Description
`Option[T]`	Option[T]: `Some` value if exactly one option is `Some`, otherwise `NONE`.

Examples:

>>> import pyochain as pc
>>> pc.Some(2).xor(pc.NONE)
Some(2)
>>> pc.NONE.xor(pc.Some(2))
Some(2)
>>> pc.Some(2).xor(pc.Some(2))
NONE
>>> pc.NONE.xor(pc.NONE)
NONE

Source code in src/pyochain/_results/_option.py

def xor(self, optb: Option[T]) -> Option[T]:
    """Returns `Some` if exactly one of **self**, optb is `Some`, otherwise returns `NONE`.

    Args:
        optb (Option[T]): The other option to compare with.

    Returns:
        Option[T]: `Some` value if exactly one option is `Some`, otherwise `NONE`.

    Examples:
    ```python
    >>> import pyochain as pc
    >>> pc.Some(2).xor(pc.NONE)
    Some(2)
    >>> pc.NONE.xor(pc.Some(2))
    Some(2)
    >>> pc.Some(2).xor(pc.Some(2))
    NONE
    >>> pc.NONE.xor(pc.NONE)
    NONE

    ```
    """
    if self.is_some() and not optb.is_some():
        return self
    if not self.is_some() and optb.is_some():
        return optb
    return NONE

zip ¶

zip(other: Option[U]) -> Option[tuple[T, U]]

Returns an Option[tuple[T, U]] containing a tuple of the values if both options are Some, otherwise returns NONE.

Parameters:

Name	Type	Description	Default
`other`	`Option[U]`	The other option to zip with.	required

Returns:

Type	Description
`Option[tuple[T, U]]`	Option[tuple[T, U]]: Some((self, other)) if both are Some, otherwise NONE.

Example:

>>> import pyochain as pc
>>> pc.Some(1).zip(pc.Some('a'))
Some((1, 'a'))
>>> pc.Some(1).zip(pc.NONE)
NONE
>>> pc.NONE.zip(pc.Some('a'))
NONE

Source code in src/pyochain/_results/_option.py

def zip[U](self, other: Option[U]) -> Option[tuple[T, U]]:
    """Returns an `Option[tuple[T, U]]` containing a tuple of the values if both options are `Some`, otherwise returns `NONE`.

    Args:
        other (Option[U]): The other option to zip with.

    Returns:
        Option[tuple[T, U]]: Some((self, other)) if both are Some, otherwise NONE.

    Example:
    ```python
    >>> import pyochain as pc
    >>> pc.Some(1).zip(pc.Some('a'))
    Some((1, 'a'))
    >>> pc.Some(1).zip(pc.NONE)
    NONE
    >>> pc.NONE.zip(pc.Some('a'))
    NONE

    ```
    """
    if self.is_some() and other.is_some():
        return Some((self.unwrap(), other.unwrap()))
    return NONE

zip_with ¶

zip_with(other: Option[U], f: Callable[[T, U], R]) -> Option[R]

Zips self and another Option with function f.

If self is Some(s) and other is Some(o), this method returns Some(f(s, o)).

Otherwise, NONE is returned.

Parameters:

Name	Type	Description	Default
`other`	`Option[U]`	The second option.	required
`f`	`Callable[[T, U], R]`	The function to apply to the unwrapped values.	required

Returns:

Type	Description
`Option[R]`	Option[R]: The resulting option after applying the function.

Examples:

>>> from dataclasses import dataclass
>>> import pyochain as pc
>>>
>>> @dataclass
... class Point:
...     x: float
...     y: float
>>>
>>> x = pc.Some(17.5)
>>> y = pc.Some(42.7)
>>> x.zip_with(y, Point)
Some(Point(x=17.5, y=42.7))
>>> x.zip_with(pc.NONE, Point)
NONE

Source code in src/pyochain/_results/_option.py

def zip_with[U, R](self, other: Option[U], f: Callable[[T, U], R]) -> Option[R]:
    """Zips `self` and another `Option` with function `f`.

    If `self` is `Some(s)` and other is `Some(o)`, this method returns `Some(f(s, o))`.

    Otherwise, `NONE` is returned.

    Args:
        other (Option[U]): The second option.
        f (Callable[[T, U], R]): The function to apply to the unwrapped values.

    Returns:
        Option[R]: The resulting option after applying the function.

    Examples:
    ```python
    >>> from dataclasses import dataclass
    >>> import pyochain as pc
    >>>
    >>> @dataclass
    ... class Point:
    ...     x: float
    ...     y: float
    >>>
    >>> x = pc.Some(17.5)
    >>> y = pc.Some(42.7)
    >>> x.zip_with(y, Point)
    Some(Point(x=17.5, y=42.7))
    >>> x.zip_with(pc.NONE, Point)
    NONE

    ```
    """
    if self.is_some() and other.is_some():
        return Some(f(self.unwrap(), other.unwrap()))
    return NONE

Some¶

value instance-attribute ¶

and_ ¶

and_then ¶

expect ¶

filter ¶

flatten ¶

from_ staticmethod ¶

inspect ¶

into ¶

is_none ¶

is_none_or ¶

is_some ¶

is_some_and ¶

iter ¶

map ¶

map_or ¶

map_or_else ¶

ok_or ¶

ok_or_else ¶

or_ ¶

or_else ¶

reduce ¶

tap ¶

transpose ¶

unwrap ¶

unwrap_or ¶

unwrap_or_else ¶

unzip ¶

xor ¶

zip ¶

zip_with ¶

value `instance-attribute` ¶

from_ `staticmethod` ¶