2. API Reference
This section describes the external API of the nocaselist project. Any internal symbols and APIs are omitted.
2.1. Class NocaseList
- class nocaselist.NocaseList(iterable=())[source]
A case-insensitive and case-preserving list.
The list is case-insensitive: Whenever items of the list are looked up by value or item values are compared, that is done case-insensitively. The case-insensitivity is defined by performing the lookup or comparison on the result of the
__casefold__()
method on the on list items. None is allowed as a list value and will not be case folded.The list is case-preserving: Whenever the value of list items is returned, they have the lexical case that was originally specified when adding or updating the item.
Except for the case-insensitivity of its items, it behaves like, and is in fact derived from, the built-in
list
class in order to facilitate type checks.The implementation maintains a second list with the casefolded items of the inherited list, and ensures that both lists are in sync.
The list supports serialization via the Python
pickle
module. To save space and time, only the originally cased list is serialized.Initialize the list with the items in the specified iterable.
Methods
Append the specified value as a new item to the end of the list (and return None).
Remove all items from the list (and return None).
Return a shallow copy of the list.
Return the number of times the specified value occurs in the list, comparing the value and the list items case-insensitively.
Extend the list by the items in the specified iterable (and return None).
Return the index of the first item that is equal to the specified value, comparing the value and the list items case-insensitively.
Insert a new item with specified value before the item at the specified index (and return None).
Return the value of the item at the specified index and also remove it from the list.
Remove the first item from the list whose value is equal to the specified value (and return None), comparing the value and the list items case-insensitively.
Reverse the items in the list in place (and return None).
Sort the items in the list in place (and return None).
Attributes
Details
- static __casefold__(value: AnyStr) AnyStr [source]
This method implements the case-insensitive behavior of the class.
It returns a case-insensitive form of the input value by calling a “casefold method” on the value. The input value will not be None.
The casefold method called by this method is
str.casefold()
. If that method does not exist on the key value (e.g. because it is a byte string),bytes.lower()
is called, for compatibility with earlier versions of the package.This method can be overridden by users in order to change the case-insensitive behavior of the class. See Overriding the default casefold method for details.
- Parameters
- Returns
Case-insensitive form of the input value.
- Return type
- Raises
AttributeError – The value does not have the casefold method.
- __getstate__()[source]
Called when pickling the object, see
object.__getstate__()
.In order to save space and time, only the list with the originally cased items is saved, but not the second list with the casefolded items.
- __setstate__(state)[source]
Called when unpickling the object, see
object.__setstate__()
.
- __setitem__(index: Union[SupportsIndex, slice], value: Optional[AnyStr]) None [source]
Update the value of the item at an existing index or slice in the list.
Invoked using
ncl[index] = value
.- Raises
AttributeError – The value does not have the casefold method.
- __delitem__(index: Union[SupportsIndex, slice]) None [source]
Delete an item at an existing index or slice from the list.
Invoked using
del ncl[index]
.
- __contains__(value: Optional[AnyStr]) bool [source]
Return a boolean indicating whether the list contains at least one item with the value, by looking it up case-insensitively.
Invoked using
value in ncl
.- Raises
AttributeError – The value does not have the casefold method.
- __add__(other: Iterable[Optional[AnyStr]]) NocaseList [source]
Return a new
NocaseList
object that contains the items from the left hand operand (self
) and the items from the right hand operand (other
).The right hand operand (
other
) must be an instance oflist
(includingNocaseList
) ortuple
. The operands are not changed.Invoked using e.g.
ncl + other
- Raises
TypeError – The other iterable is not a list or tuple
- __iadd__(other: Iterable[Optional[AnyStr]]) NocaseList [source]
Extend the left hand operand (
self
) by the items from the right hand operand (other
).The
other
parameter must be an iterable but is otherwise not restricted in type. Thus, if it is a string, the characters of the string are added as distinct items to the list.Invoked using
ncl += other
.
- __mul__(number: int) NocaseList [source]
Return a new
NocaseList
object that contains the items from the left hand operand (self
) as many times as specified by the right hand operand (number
).A number <= 0 causes the returned list to be empty.
The left hand operand (
self
) is not changed.Invoked using
ncl * number
.
- __rmul__(number: int) NocaseList [source]
Return a new
NocaseList
object that contains the items from the right hand operand (self
) as many times as specified by the left hand operand (number
).A number <= 0 causes the returned list to be empty.
The right hand operand (
self
) is not changed.Invoked using
number * ncl
.
- __imul__(number: int) NocaseList [source]
Change the left hand operand (
self
) so that it contains the items from the original left hand operand (self
) as many times as specified by the right hand operand (number
).A number <= 0 will empty the left hand operand.
Invoked using
ncl *= number
.
- __reversed__() NocaseList [source]
Return a shallow copy of the list that has its items reversed in order.
Invoked using
reversed(ncl)
.
- __eq__(other: object) bool [source]
Return a boolean indicating whether the list and the other list are equal, by comparing corresponding list items case-insensitively.
The other list may be a
NocaseList
object or any other iterable. In all cases, the comparison takes place case-insensitively.Invoked using e.g.
ncl == other
.- Raises
AttributeError – A value in the other list does not have the casefold method.
- __ne__(other: object) bool [source]
Return a boolean indicating whether the list and the other list are not equal, by comparing corresponding list items case-insensitively.
The other list may be a
NocaseList
object or any other iterable. In all cases, the comparison takes place case-insensitively.Invoked using e.g.
ncl != other
.- Raises
AttributeError – A value in the other list does not have the casefold method.
- __gt__(other: object) bool [source]
Return a boolean indicating whether the list is greater than the other list, by comparing corresponding list items case-insensitively.
The other list may be a
NocaseList
object or any other iterable. In all cases, the comparison takes place case-insensitively.Invoked using e.g.
ncl > other
.- Raises
AttributeError – A value in the other list does not have the casefold method.
- __lt__(other: object) bool [source]
Return a boolean indicating whether the list is less than the other list, by comparing corresponding list items case-insensitively.
The other list may be a
NocaseList
object or any other iterable. In all cases, the comparison takes place case-insensitively.Invoked using e.g.
ncl < other
.- Raises
AttributeError – A value in the other list does not have the casefold method.
- __ge__(other: object) bool [source]
Return a boolean indicating whether the list is greater than or equal to the other list, by comparing corresponding list items case-insensitively.
The other list may be a
NocaseList
object or any other iterable. In all cases, the comparison takes place case-insensitively.Invoked using e.g.
ncl >= other
.- Raises
AttributeError – A value in the other list does not have the casefold method.
- __le__(other: object) bool [source]
Return a boolean indicating whether the list is less than or equal to the other list, by comparing corresponding list items case-insensitively.
The other list may be a
NocaseList
object or any other iterable. In all cases, the comparison takes place case-insensitively.Invoked using e.g.
ncl <= other
.- Raises
AttributeError – A value in the other list does not have the casefold method.
- count(value: Optional[AnyStr]) int [source]
Return the number of times the specified value occurs in the list, comparing the value and the list items case-insensitively.
- Raises
AttributeError – The value does not have the casefold method.
- copy() NocaseList [source]
Return a shallow copy of the list.
- index(value: Optional[AnyStr], start: SupportsIndex = 0, stop: SupportsIndex = 9223372036854775807) int [source]
Return the index of the first item that is equal to the specified value, comparing the value and the list items case-insensitively.
The search is limited to the index range defined by the specified
start
andstop
parameters, wherebystop
is the index of the first item after the search range.- Raises
AttributeError – The value does not have the casefold method.
ValueError – No such item is found.
- append(value: Optional[AnyStr]) None [source]
Append the specified value as a new item to the end of the list (and return None).
- Raises
AttributeError – The value does not have the casefold method.
- extend(values: Iterable) None [source]
Extend the list by the items in the specified iterable (and return None).
- Raises
AttributeError – A value in the iterable does not have the casefold method.
- insert(index: SupportsIndex, value: Optional[AnyStr]) None [source]
Insert a new item with specified value before the item at the specified index (and return None).
- Raises
AttributeError – The value does not have the casefold method.
- pop(index: SupportsIndex = -1) Optional[AnyStr] [source]
Return the value of the item at the specified index and also remove it from the list.
- remove(value: Optional[AnyStr]) None [source]
Remove the first item from the list whose value is equal to the specified value (and return None), comparing the value and the list items case-insensitively.
- Raises
AttributeError – The value does not have the casefold method.
- sort(*, key: Optional[Callable] = None, reverse: bool = False) None [source]
Sort the items in the list in place (and return None).
The sort is stable, in that the order of two (case-insensitively) equal elements is maintained.
By default, the list is sorted in ascending order of its casefolded item values. If a key function is given, it is applied once to each casefolded list item and the list is sorted in ascending or descending order of their key function values.
The
reverse
flag can be set to sort in descending order.