bases

Useful base classes.

Classes:

Dictable(*args, **kwargs)	The basic structure of a class that can be converted into a dictionary.
Lineup([initlist])	List-like type with fluent methods and some star players.
NamedList([initlist])	A list with a name.
UserFloat([value])	Class which simulates a float.
UserList([initlist])	Typed version of collections.UserList.

Data:

_F	Invariant TypeVar bound to domdf_python_tools.bases.UserFloat.
_LU	Invariant TypeVar bound to domdf_python_tools.bases.Lineup.
_S	Invariant TypeVar bound to domdf_python_tools.bases.UserList.

Functions:

namedlist([name])

A factory function to return a custom list subclass with a name.

Type Variables

_F = TypeVar(_F, bound=UserFloat)

Type:    TypeVar

Invariant TypeVar bound to domdf_python_tools.bases.UserFloat.

_LU = TypeVar(_LU, bound=Lineup)

Type:    TypeVar

Invariant TypeVar bound to domdf_python_tools.bases.Lineup.

_S = TypeVar(_S, bound=UserList)

Type:    TypeVar

Invariant TypeVar bound to domdf_python_tools.bases.UserList.

_T = TypeVar(_T)

Type:    TypeVar

Invariant TypeVar.

_V = TypeVar(_V)

Type:    TypeVar

Invariant TypeVar.

Dictable

class Dictable(*args, **kwargs)

Bases: Iterable[Tuple[str, ~_V]]

The basic structure of a class that can be converted into a dictionary.

Methods:

__eq__(other)	Return self == other.
__iter__()	Iterate over the attributes of the class.
__repr__()	Return a string representation of the Dictable.
__str__()	Return str(self).

__eq__(other)

Return self == other.

Return type

bool

__iter__()

Iterate over the attributes of the class.

Return type

Iterator[Tuple[str, ~_V]]

__repr__()

Return a string representation of the Dictable.

Return type

str

__str__()

Return str(self).

Return type

str

UserList

class UserList(initlist=None)

Bases: MutableSequence[~_T]

Typed version of collections.UserList.

Class that simulates a list. The instance’s contents are kept in a regular list, which is accessible via the data attribute of UserList instances. The instance’s contents are initially set to a copy of list, defaulting to the empty list [].

New in version 0.10.0.

Parameters

initlist (Optional[Iterable[~_T]]) – The initial values to populate the UserList with. Default [].

Subclassing requirements

Subclasses of UserList are expected to offer a constructor which can be called with either no arguments or one argument. List operations which return a new sequence attempt to create an instance of the actual implementation class. To do so, it assumes that the constructor can be called with a single parameter, which is a sequence object used as a data source.

If a derived class does not wish to comply with this requirement, all of the special methods supported by this class will need to be overridden; please consult the sources for information about the methods which need to be provided in that case.

Methods:

__add__(other)	Return self + value.
__contains__(item)	Return key in self.
__delitem__(i)	Delete self[key].
__eq__(other)	Return self == other.
__ge__(other)	Return self >= other.
__getitem__(i)	Return self[key].
__gt__(other)	Return self > other.
__le__(other)	Return self <= other.
__lt__(other)	Return self < other.
__mul__(n)	Return self * value.
__radd__(other)	Return value + self.
__repr__()	Return a string representation of the UserList.
__rmul__(n)	Return self * value.
__setitem__(i, item)	Set self[key] to value.
append(item)	Append item to the end of the UserList.
clear()	Remove all items from the UserList.
copy()	Returns a copy of the UserList.
count(item)	Returns the number of occurrences of item in the UserList.
extend(other)	Extend the NamedList by appending elements from other.
index(item, *args)	Returns the index of the fist element matching item.
insert(i, item)	Insert item at position i in the UserList.
pop([i])	Removes and returns the item at index i.
remove(item)	Removes the first occurrence of item from the list.
reverse()	Reverse the list in place.
sort(*[, key, reverse])	Sort the list in ascending order and return None.

Attributes:

data	A real list object used to store the contents of the UserList.

__add__(other)

Return self + value.

Return type

~_S

__contains__(item)

Return key in self.

Return type

bool

__delitem__(i)

Delete self[key].

__eq__(other)

Return self == other.

Return type

bool

__ge__(other)

Return self >= other.

Return type

bool

__getitem__(i)

Return self[key].

Return type

Union[~_T, MutableSequence[~_T]]

Overloads

• __getitem__(i: int) -> ~_T

• __getitem__(i: slice) -> MutableSequence[~_T]

__gt__(other)

Return self > other.

Return type

bool

__le__(other)

Return self <= other.

Return type

bool

__lt__(other)

Return self < other.

Return type

bool

__mul__(n)

Return self * value.

Return type

~_S

__radd__(other)

Return value + self.

__repr__()

Return a string representation of the UserList.

Return type

str

__rmul__(n)

Return self * value.

Return type

~_S

__setitem__(i, item)

Set self[key] to value.

Overloads

• __setitem__(i: int, o: ~_T)

• __setitem__(i: slice, o: Iterable[~_T] )

append(item)

Append item to the end of the UserList.

clear()

Remove all items from the UserList.

copy()

Returns a copy of the UserList.

Return type

~_S

count(item)

Returns the number of occurrences of item in the UserList.

Return type

int

data

Type:    List[~_T]

A real list object used to store the contents of the UserList.

extend(other)

Extend the NamedList by appending elements from other.

Parameters

other (Iterable[~_T])

index(item, *args)

Returns the index of the fist element matching item.

Parameters

• item (~_T)

• args

Raises

ValueError – if the item is not present.

Return type

int

insert(i, item)

Insert item at position i in the UserList.

pop(i=- 1)

Removes and returns the item at index i.

Raises

IndexError – if list is empty or index is out of range.

Return type

~_T

remove(item)

Removes the first occurrence of item from the list.

Parameters

item (~_T)

Raises

ValueError – if the item is not present.

reverse()

Reverse the list in place.

sort(*, key=None, reverse=False)

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

NamedList

Both NamedList and namedlist() can be used to create a named list.

namedlist() can be used as follows:

>>> ShoppingList = namedlist("ShoppingList")
>>> shopping_list = ShoppingList(["egg and bacon", "egg sausage and bacon", "egg and spam", "egg bacon and spam"])
>>>

If you wish to create a subclass with additional features it is recommended to subclass from NamedList rather than from namedlist(). For example, do this:

>>> class ShoppingList(NamedList):
...     pass
>>>

and not this:

>>> class ShoppingList(namedlist())
...     pass
>>>

This avoids any potential issues with mypy.

class NamedList(initlist=None)

Bases: UserList[~_T]

A list with a name.

The name of the list is taken from the name of the subclass.

Changed in version 0.10.0: NamedList now subclasses UserList rather than collections.UserList.

namedlist(name='NamedList')

A factory function to return a custom list subclass with a name.

Parameters

name (str) – The name of the list. Default 'NamedList'.

Return type

Type[NamedList]

UserFloat

class UserFloat(value=0.0)

Bases: Real

Class which simulates a float.

New in version 1.6.0.

Parameters

value (Union[SupportsFloat, SupportsIndex, str, bytes, bytearray]) – The values to initialise the UserFloat with. Default 0.0.

Methods:

__abs__()	Return abs(self).
__add__(other)	Return self + value.
__bool__()	Return self != 0.
__complex__()	Return complex(self).
__divmod__(other)	Return divmod(self, value).
__eq__(other)	Return self == other.
__float__()	Return float(self).
__floordiv__(other)	Return self // value.
__ge__(other)	Return self >= other.
__gt__(other)	Return self > other.
__int__()	Return int(self).
__le__(other)	Return self <= other.
__lt__(other)	Return self < other.
__mod__(other)	Return self % value.
__mul__(other)	Return self * value.
__ne__(other)	Return self != other.
__neg__()	Return - self.
__pos__()	Return + self.
__pow__(other[, mod])	Return pow(self, value, mod).
__radd__(other)	Return value + self.
__rdivmod__(other)	Return divmod(value, self).
__repr__()	Return a string representation of the UserFloat.
__rfloordiv__(other)	Return value // self.
__rmod__(other)	Return value % self.
__rmul__(other)	Return value * self.
__round__([ndigits])	Round the UserFloat to ndigits decimal places, defaulting to 0.
__rpow__(other[, mod])	Return pow(value, self, mod).
__rsub__(other)	Return value - self.
__rtruediv__(other)	Return value / self.
__str__()	Return str(self).
__sub__(other)	Return value - self.
__truediv__(other)	Return self / value.
__trunc__()	Truncates the float to an integer.
as_integer_ratio()	Returns the float as a fraction.
fromhex(string)	Create a floating-point number from a hexadecimal string.
hex()	Returns the hexadecimal (base 16) representation of the float.
is_integer()	Returns whether the float is an integer.

__abs__()

Return abs(self).

Return type

~_F

__add__(other)

Return self + value.

Return type

~_F

__bool__()

Return self != 0.

Return type

bool

__complex__()

Return complex(self).

complex(self) == complex(float(self), 0)

Return type

complex

__divmod__(other)

Return divmod(self, value).

Return type

Tuple[~_F, ~_F]

__eq__(other)

Return self == other.

Return type

bool

__float__()

Return float(self).

Return type

float

__floordiv__(other)

Return self // value.

Return type

~_F

__ge__(other)

Return self >= other.

Return type

bool

__gt__(other)

Return self > other.

Return type

bool

__int__()

Return int(self).

Return type

int

__le__(other)

Return self <= other.

Return type

bool

__lt__(other)

Return self < other.

Return type

bool

__mod__(other)

Return self % value.

Return type

~_F

__mul__(other)

Return self * value.

Return type

~_F

__ne__(other)

Return self != other.

Return type

bool

__neg__()

Return - self.

Return type

~_F

__pos__()

Return + self.

Return type

~_F

__pow__(other, mod=None)

Return pow(self, value, mod).

Return type

~_F

__radd__(other)

Return value + self.

Return type

~_F

__rdivmod__(other)

Return divmod(value, self).

Return type

Tuple[~_F, ~_F]

__repr__()

Return a string representation of the UserFloat.

Return type

str

__rfloordiv__(other)

Return value // self.

Return type

~_F

__rmod__(other)

Return value % self.

Return type

~_F

__rmul__(other)

Return value * self.

Return type

~_F

__round__(ndigits=None)

Round the UserFloat to ndigits decimal places, defaulting to 0.

If ndigits is omitted or None, returns an int, otherwise returns a float. Rounds half toward even.

Parameters

ndigits (Optional[int]) – Default None.

Return type

Union[int, float]

__rpow__(other, mod=None)

Return pow(value, self, mod).

Return type

~_F

__rsub__(other)

Return value - self.

Return type

~_F

__rtruediv__(other)

Return value / self.

Return type

~_F

__str__()

Return str(self).

Return type

str

__sub__(other)

Return value - self.

Return type

~_F

__truediv__(other)

Return self / value.

Return type

~_F

__trunc__()

Truncates the float to an integer.

Return type

int

as_integer_ratio()

Returns the float as a fraction.

Return type

Tuple[int, int]

classmethod fromhex(string)

Create a floating-point number from a hexadecimal string.

Parameters

string (str)

Return type

~_F

hex()

Returns the hexadecimal (base 16) representation of the float.

Return type

str

is_integer()

Returns whether the float is an integer.

Return type

bool

Lineup

class Lineup(initlist=None)

Bases: UserList[~_T]

List-like type with fluent methods and some star players.

Methods:

append(item)	Append item to the end of the UserList.
clear()	Remove all items from the UserList.
extend(other)	Extend the NamedList by appending elements from other.
insert(i, item)	Insert item at position i in the UserList.
remove(item)	Removes the first occurrence of item from the list.
replace(what, with_)	Replace the first instance of what with with_.
reverse()	Reverse the list in place.
sort(*[, key, reverse])	Sort the list in ascending order and return the self.

append(item)

Append item to the end of the UserList.

Return type

~_LU

clear()

Remove all items from the UserList.

Return type

~_LU

extend(other)

Extend the NamedList by appending elements from other.

Parameters

other (Iterable[~_T])

Return type

~_LU

insert(i, item)

Insert item at position i in the UserList.

Return type

~_LU

remove(item)

Removes the first occurrence of item from the list.

Parameters

item (~_T)

Return type

~_LU

Raises

ValueError – if the item is not present.

replace(what, with_)

Replace the first instance of what with with_.

Parameters

• what (~_T) – The object to find and replace.

• with_ (~_T) – The new value for the position in the list.

Return type

~_LU

reverse()

Reverse the list in place.

Return type

~_LU

sort(*, key=None, reverse=False)

Sort the list in ascending order and return the self.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

Return type

~_LU