# apfel.core.common

*module*

Common yet miscellaneous utilities functions.

[View source](https://github.com/Yixuan-Wang/apfel/blob/main/src/apfel/core/common.py#L1-L1)

## apfel.core.common.apply

*function*

```python
def apply(value: T, func: Callable[[T], R], /) -> R
```

Applies a single-argument function to a value.
For chained calls, see [`pipe`][apfel.core.common.pipe].

See also [:python <code><del>apply</del></code>](https://docs.python.org/2.7/library/functions.html#apply) from Python 2.7.

This function is different from [`Value.apply`][apfel.container.value.Value.apply],
which is an implementation of [`Applicative`][apfel.core.monad.Applicative]
who requires the function to be wrapped in `Value`.
In contrast, this function accepts arbitrary callables.

This function is exposed in the [package namespace](../prelude.md#package-namespace)
and the [builtins namespace](../prelude.md#builtins-namespace).

**Parameters**

- `value` (`T`) — The value to be passed to the function.
- `func` (`Callable[[T], R]`) — The function to apply.

**Returns**

- `R` (`R`) — The result of applying the function to the value.

[View source](https://github.com/Yixuan-Wang/apfel/blob/main/src/apfel/core/common.py#L9-L31)

## apfel.core.common.identity

*function*

```python
def identity(value: T, /) -> T
```

Returns the sole argument passed to it doing nothing.

This function is exposed in the [package namespace](../prelude.md#package-namespace)
and the [builtins namespace](../prelude.md#builtins-namespace).

**Parameters**

- `value` (`T`) — Any object.

**Returns**

- `T` (`T`) — The same object passed to it.

[View source](https://github.com/Yixuan-Wang/apfel/blob/main/src/apfel/core/common.py#L34-L47)

## apfel.core.common.imperative

*function*

```python
def imperative(*exprs: *tuple[*Ts, R]) -> R
```

Returns the last expression passed into the function.
If no expression are passed, returns `None`, per Python's convention.

This function is exposed in the [package namespace](../prelude.md#package-namespace)
and the [builtins namespace](../prelude.md#builtins-namespace).

**Parameters**

- `*exprs` (`*tuple[*Ts, R]`) (default: `()`) — Any number of expressions.

**Returns**

- `R` (`R`) — The last expression passed into the function.

[View source](https://github.com/Yixuan-Wang/apfel/blob/main/src/apfel/core/common.py#L50-L64)

## apfel.core.common.not_none

*function*

```python
def not_none(value: T | None, /) -> T
```

Type narrowing: assert the value isn't None.

This function is exposed in the [package namespace](../prelude.md#package-namespace).

**Parameters**

- `value` (`T`) — Any value that type-checked to be `None`, but guarantees to be non-`None`.

**Returns**

- `T` (`T`) — The same value passed to it.

**Raises**

- `ValueError` — if the input is actually `None`.

[View source](https://github.com/Yixuan-Wang/apfel/blob/main/src/apfel/core/common.py#L67-L93)

## apfel.core.common.pipe

*function*

```python
def pipe(value: T | Any, /, *funcs: Callable[[T], T] | *tuple[*tuple[Callable[[Any], Any], ...], Callable[[Any], R]] | Callable[[Any], Any]) -> T | T1 | T2 | T3 | T4 | R | Any
```

Pipes a value through a sequence of functions.
For single function application, see [`apply`][apfel.core.common.apply].

See also [`Value.update`][apfel.container.value.Value.update],
[`FunctionObject.__rand__`][apfel.core.function_object.FunctionObject.__rand__].
See also [:haskell `&`](https://hackage.haskell.org/package/base/docs/Data-Function.html#v:-38-), [:julia `|>`](https://docs.julialang.org/en/v1/manual/functions/#Function-composition-and-piping) or roughly [:rlang `%>%`](https://magrittr.tidyverse.org/reference/pipe.html).

This function is exposed in the [package namespace](../prelude.md#package-namespace)
and the [builtins namespace](../prelude.md#builtins-namespace).

**Parameters**

- `value` (`T`) — The initial value to be piped.
- `*funcs` (`Callable[[Any], Any]`) (default: `()`) — A sequence of functions to apply to the value.

**Returns**

- `Any` (`T | T1 | T2 | T3 | T4 | R | Any`) — The final result after applying all functions.

[View source](https://github.com/Yixuan-Wang/apfel/blob/main/src/apfel/core/common.py#L96-L119)

## apfel.core.common.todo

*function*

```python
def todo(message: str | None = None, /) -> NoReturn
```

Marks an unimplemented location that **might** be implemented in the future.
See [:rust `todo!`](https://doc.rust-lang.org/std/macro.todo.html) for usage.

This function is exposed in the [package namespace](../prelude.md#package-namespace)
and the [builtins namespace](../prelude.md#builtins-namespace).

**Parameters**

- `message` (`str | None`) (default: `None`) — The extra message to be displayed.

**Raises**

- `NotImplementedError` — Always.

[View source](https://github.com/Yixuan-Wang/apfel/blob/main/src/apfel/core/common.py#L122-L136)

## apfel.core.common.unimplemented

*function*

```python
def unimplemented(message: str | None = None, /) -> NoReturn
```

Marks an unimplemented location that **might not** be implemented in the future.
See [:rust `unimplemented!`](https://doc.rust-lang.org/std/macro.unimplemented.html) for usage.

This function is exposed in the [package namespace](../prelude.md#package-namespace)
and the [builtins namespace](../prelude.md#builtins-namespace).

**Parameters**

- `message` (`str | None`) (default: `None`) — The extra message to be displayed.

**Raises**

- `NotImplementedError` — Always.

[View source](https://github.com/Yixuan-Wang/apfel/blob/main/src/apfel/core/common.py#L139-L153)