ExType

Extype stands for extensible types, a Python package that enables extending types.

Installation

pip install extype

Alternatively, you can install through git (make sure to have pip 22.0 or higher):

python -m pip install --upgrade pip
pip install git+https://github.com/xpodev/extype/

Usage

First, in your Python code, import the package:

import extype

Then, you can use the built-in extensions for the builtin types. In order to apply these extensions, import the extend_all module from the extype.builtin_extensions package:

from extype.builtin_extensions import extend_all

This will apply the extensions to all builtins we support, as a side-effect of the import (to extend only some builtins, you can use the dedicated modules, see below).

Sometimes you don't want to apply all the extensions that we provide, but only for some specific type(s).

Say, for example, we only want to apply the provided extensions for list. We'll need to manually apply them like so:

from extype.builtin_extensions import list_ext

list_ext.extend()

Note: All built-in extension modules have an extend function which will apply the extensions in the module to the relevant type.

Currently, we provide the following extensions:

file	extended types
coroutine_ext.py	coroutine (async functions)
dict_ext.py	dict_keys, dict_values, dict_items
float_ext.py	float
function_ext.py	FunctionType, LambdaType
int_ext.py	int
list_ext.py	list
seq_ext.py	map, filter, range, zip
str_ext.py	str

Then you can use these extensions. Here's an example of using the list.map extension:

print([1, 2, 3].map(lambda x: x + 1))  # [2, 3, 4]

There's a list of all the built-in extensions here

Creating your own extensions

You can create your own extension methods, with which you can extend any type you want! (not only builtins) For example, let's make our own tofloat function in the int type. What we want to have at the end is:

x = 10
print(isinstance(x.tofloat(), float))  # True

First, we'll need some tools:

from extype import extension, extend_type_with

Next, we'll define our class which will hold the extension method. Note that this class will not get instantiated. It is also recommended to make this class inherit the type you want to extend, so you get better typing support.

class IntExtension(int):  # inheriting `int` for typing
  @extension  # marks this method to be added as an extension
  def tofloat(self):  # self will be of the same type we extend, which, in this case, is `int`
    return float(self)  # convert the int to float and return the result

After we create the class which will contain the extension methods, we need to apply them to the types we want to extend:

extend_type_with(int, IntExtension)

Now, we can run the code from above:

x = 10
print(isinstance(x.tofloat(), float))  # True

We can also apply multiple extensions to the same type or even the same extension to multiple types.

Only methods marked with @extension will be added as extension methods.

Note: Extending a type will extend it in all modules, not just the one that called the extend_type_with, so make sure you don't override an existing function, unless, of course, it is what you want.

Free-threaded Python

ExType supports the free-threaded build of Python (3.14t and later) and does not re-enable the GIL when imported. Extending a type is thread-safe, but other threads that are using the type at the same time may see either the old or the new behavior until extend_type_with returns. It is recommended to apply your extensions at import time, before starting other threads.

Features

• Exteranlly extend type via another type
• Basic support for magic method extensions
  • Number protocol
  • Mapping protocol
  • Sequence protocol
• Add support for reverse methods (e.g. __radd__)
• Make this features/todo list look nicer
• Add support for the rich comparison function

Maintainers

Build & Installation

We use Hatch to manage the build environment, and mesonpy to build the package.

First, install Hatch: https://hatch.pypa.io/latest/install/. We recommend using pipx.

After you've installed Hatch, you can build the package with the following command:

hatch run install_editable

With this, you can start using the package in your code. Spawn shell within the build environment:

hatch shell

It'll rebuild the package every time you import it, so you can test your changes. If you don't want to rebuild the package every time you import it, you can install it with:

hatch run install

But note that any changes you make won't be reflected in the installed package.

To build the wheel, you can use:

hatch run dist:build

This will build the wheel for all python versions, and put it in the dist folder.

Testing

To run tests for all python versions, run:

hatch run dist:test

To run tests for a specific python version, run:

hatch run +py=39 dist:test

Both commands will build, install the package into an isolated environment, and run the tests in it.

Releasing

The version is taken from the latest vX.Y.Z git tag (see tools/version.py), so there's no version to bump in the code. Builds between releases get a development version, such as 1.3.1.dev4+gabc1234.

To release, publish a GitHub release with a new vX.Y.Z tag. This builds the wheels for all platforms and Python versions and uploads them to PyPI. The upload is refused if the wheels' version doesn't match the tag.

Built-in Extensions

Note: All of the following list extensions also exist on dict_keys, dict_values and dict_items.

list.all(self: List[T], fn: Callable[[T], bool] = bool) -> bool

Returns true if all elements, mapped through the given fn, are True.

list.any(self: List[T], fn: Callable[[T], bool] = bool) -> bool

Returns true if any of the elements, mapped through the given fn, is True.

list.map(self: List[T], fn: Callable[[T], U]) -> List[U]

Returns a new list whose elements are the result of applying the given function on each element in the original list.

list.reduce(self: List[T], fn: Callable[[T, T], T]) -> T

Reduces the list to a single value, using the given function as the reduction (combination) function.

Raises TypeError if the list is empty.

list.reduce(self: List[T], fn: Callable[[U, T], U], initial_value: U) -> U

Reduces the list to a single value, using the given function as the reduction (combination) function and the initial value.

list.filter(self: List[T], fn: Callable[[T], bool]) -> List[T]

Returns a new list containing all the elements that match the given predicate fn.

list.first(self: List[T]) -> T, raise IndexError

Returns the first element in the list, or raises an IndexError if the list is empty.

list.last(self: List[T]) -> T, raise IndexError

Returns the last element in the list, or raises IndexError if the list is empty.

coroutine.then(self: Awaitable[T], fn: Callable[[T], Awaitable[U] | U]) -> Awaitable[U]

Maps the result of the awaitable via an optionally async function. If the function is async, it is awaited in the context of the wrapped awaitable.

Example:

async def get_value():
    return 10

result = await get_value().then(lambda x: x * 2)  # result is 20

coroutine.catch(self: Awaitable[T], fn: Callable[[E], Awaitable[U] | U], *, exception: type[E] = Exception) -> Awaitable[T | U]

Catches an exception of the given type and calls the passed function with the caught exception.

If no exception was raised inside the wrapped awaitable, the function will not be called. The passed function can optionally return a value to be returned in case of an error. The passed function can be either sync or async. If it's async, it is awaited in the context of the wrapped awaitable.

Example:

async def might_fail():
    raise ValueError("error")

result = await might_fail().catch(lambda e: "default", exception=ValueError)  # result is "default"

float.round(self: float) -> int

Rounds the floating point number to the nearest integer.

float.round(self: float, ndigits: int) -> int | float

Round the floating point number to the nearest float with ndigits fraction digits.

# function @ functioin
function.__matmul__(self: Callable[[T], U], other: Callable[..., T]) -> Callable[..., U]

Compose 2 functions such that doing (foo @ bar)(*args, **kwargs) will have the same result as calling foo(bar(*args, **kwargs)).

int.hex(self: int) -> str

Returns the hexadecimal representation of the integer.

int.oct(self: int) -> str

Returns the octal representation of the integer.

int.bin(self: int) -> str

Returns the binary representation of the integer.

str.to_int(self: str, base: int = 10, default: T = ...) -> int | T

Converts the given string to an int with the given base. If it can't be converted and default is given, it is returned. Otherwise, a ValueError is thrown.

str.to_float(self: str, default: T = ...) -> float | T

Converts the given string to a float. If it can't be converted and default is given, it is returned. Otherwise, a ValueError is thrown.

• The following extensions are valid for map, filter, range and zip

.tolist(self: Iterable[T]) -> List[T]

Exhausts the iterble and creates a list from it.

.map(self: Iterable[T], fn: Callable[[T], U]) -> Iterable[U]

Maps the iterable with the given function to create a new iterable.

This does not iterates through the original iterable.

.filter(self: Iterable[T], fn: Callable[[T], bool]) -> Iterable[T]

Filters the iterable with the given function as the predicate function.

This does not iterates through the original iterable.