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=())

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	Append the specified value as a new item to the end of the list (and return None).
clear	Remove all items from the list (and return None).
copy	Return a shallow copy of the list.
count	Return the number of times the specified value occurs in the list, comparing the value and the list items case-insensitively.
extend	Extend the list by the items in the specified iterable (and return None).
index	Return the index of the first item that is equal to the specified value, comparing the value and the list items case-insensitively.
insert	Insert a new item with specified value before the item at the specified index (and return None).
pop	Return the value of the item at the specified index and also remove it from the list.
remove	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	Reverse the items in the list in place (and return None).
sort	Sort the items in the list in place (and return None).

Attributes

Details

static __casefold__(value: AnyStr) → AnyStr

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

value (str or bytes) – Input value. Will not be None.

Returns

Case-insensitive form of the input value.

Return type

str or bytes

Raises

AttributeError – The value does not have the casefold method.

__getstate__()

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)

Called when unpickling the object, see object.__setstate__().

__setitem__(index: Union[SupportsIndex, slice], value: Optional[AnyStr]) → None

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

Delete an item at an existing index or slice from the list.

Invoked using del ncl[index].

__contains__(value: Optional[AnyStr]) → bool

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

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 of list (including NocaseList) or tuple. 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

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

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

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

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

Return a shallow copy of the list that has its items reversed in order.

Invoked using reversed(ncl).

__eq__(other: object) → bool

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

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

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

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

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

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

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

Return a shallow copy of the list.

clear() → None

Remove all items from the list (and return None).

index(value: Optional[AnyStr], start: SupportsIndex = 0, stop: SupportsIndex = 9223372036854775807) → int

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 and stop parameters, whereby stop 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

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

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

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]

Return the value of the item at the specified index and also remove it from the list.

remove(value: Optional[AnyStr]) → None

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.

reverse() → None

Reverse the items in the list in place (and return None).

sort(*, key: Optional[Callable] = None, reverse: bool = False) → None

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.