`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)[source]

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

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

Attributes:

__class_getitem__

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)`.

__class_getitem__ = <bound method GenericAlias of <class 'domdf_python_tools.bases.Dictable'>>: Type: MethodType

__eq__(other)[source]

Return self == other.

Return type: bool

__iter__()[source]

Iterate over the attributes of the class.

Return type: Iterator[Tuple[str, ~_V]]

__repr__()[source]

Return a string representation of the Dictable.

Return type: str

__str__()[source]

Return str(self).

Return type: str

UserList

class UserList(initlist=None)[source]

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:

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

__add__(other)[source]

Return self + value.

Return type: ~_S

__class_getitem__ = <bound method GenericAlias of <class 'domdf_python_tools.bases.UserList'>>: Type: MethodType

__contains__(item)[source]

Return key in self.

Return type: bool

__delitem__(i)[source]: Delete self[key].

__eq__(other)[source]

Return self == other.

Return type: bool

__ge__(other)[source]

Return self >= other.

Return type: bool

__getitem__(i)[source]

Return self[key].

Return type

Union[~_T, MutableSequence[~_T]]

Overloads

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

__gt__(other)[source]

Return self > other.

Return type: bool

__le__(other)[source]

Return self <= other.

Return type: bool

__lt__(other)[source]

Return self < other.

Return type: bool

__mul__(n)[source]

Return self * value.

Return type: ~_S

__radd__(other)[source]: Return value + self.

__repr__()[source]

Return a string representation of the UserList.

Return type: str

__rmul__(n)

Return self * value.

Return type: ~_S

__setitem__(i, item)[source]

Set self[key] to value.

Overloads

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

append(item)[source]: Append item to the end of the UserList.

clear()[source]: Remove all items from the UserList.

copy()[source]

Returns a copy of the UserList.

Return type: ~_S

count(item)[source]

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)[source]

Extend the NamedList by appending elements from other.

Parameters: other (Iterable[~_T])

index(item, *args)[source]

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)[source]: Insert item at position i in the UserList.

pop(i=- 1)[source]

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)[source]

Removes the first occurrence of item from the list.

Parameters: item (~_T)
Raises: ValueError – if the item is not present.

reverse()[source]: Reverse the list in place.

sort(*, key=None, reverse=False)[source]

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)[source]

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')[source]

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)[source]

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__()[source]

Return abs(self).

Return type: ~_F

__add__(other)[source]

Return self + value.

Return type: ~_F

__bool__()[source]

Return self != 0.

Return type: bool

__complex__()[source]

Return complex(self).

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

Return type: complex

__divmod__(other)[source]

Return divmod(self, value).

Return type: Tuple[~_F, ~_F]

__eq__(other)[source]

Return self == other.

Return type: bool

__float__()[source]

Return float(self).

Return type: float

__floordiv__(other)[source]

Return self // value.

Return type: ~_F

__ge__(other)[source]

Return self >= other.

Return type: bool

__gt__(other)[source]

Return self > other.

Return type: bool

__int__()[source]

Return int(self).

Return type: int

__le__(other)[source]

Return self <= other.

Return type: bool

__lt__(other)[source]

Return self < other.

Return type: bool

__mod__(other)[source]

Return self % value.

Return type: ~_F

__mul__(other)[source]

Return self * value.

Return type: ~_F

__ne__(other)[source]

Return self != other.

Return type: bool

__neg__()[source]

Return - self.

Return type: ~_F

__pos__()[source]

Return + self.

Return type: ~_F

__pow__(other, mod=None)[source]

Return pow(self, value, mod).

Return type: ~_F

__radd__(other)[source]

Return value + self.

Return type: ~_F

__rdivmod__(other)[source]

Return divmod(value, self).

Return type: Tuple[~_F, ~_F]

__repr__()[source]

Return a string representation of the UserFloat.

Return type: str

__rfloordiv__(other)[source]

Return value // self.

Return type: ~_F

__rmod__(other)[source]

Return value % self.

Return type: ~_F

__rmul__(other)[source]

Return value * self.

Return type: ~_F

__round__(ndigits=None)[source]

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)[source]

Return pow(value, self, mod).

Return type: ~_F

__rsub__(other)[source]

Return value - self.

Return type: ~_F

__rtruediv__(other)[source]

Return value / self.

Return type: ~_F

__str__()[source]

Return str(self).

Return type: str

__sub__(other)[source]

Return value - self.

Return type: ~_F

__truediv__(other)[source]

Return self / value.

Return type: ~_F

__trunc__()[source]

Truncates the float to an integer.

Return type: int

as_integer_ratio()[source]

Returns the float as a fraction.

Return type: Tuple[int, int]

classmethod fromhex(string)[source]

Create a floating-point number from a hexadecimal string.

Parameters: string (str)
Return type: ~_F

hex()[source]

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

Return type: str

is_integer()[source]

Returns whether the float is an integer.

Return type: bool

Lineup

class Lineup(initlist=None)[source]

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)[source]

Append item to the end of the UserList.

Return type: ~_LU

clear()[source]

Remove all items from the UserList.

Return type: ~_LU

extend(other)[source]

Extend the NamedList by appending elements from other.

Parameters: other (Iterable[~_T])
Return type: ~_LU

insert(i, item)[source]

Insert item at position i in the UserList.

Return type: ~_LU

remove(item)[source]

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_)[source]

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()[source]

Reverse the list in place.

Return type: ~_LU

sort(*, key=None, reverse=False)[source]

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

bases

Type Variables

Dictable

UserList

NamedList

UserFloat

Lineup

`bases`