2. API Reference

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 lower() method on list items. Therefore, list items must support the lower() method. If a list item does not do that, AttributeError is raised.

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 lower-cased 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

__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 lower cased items.

On Python 2, the ‘pickle’ module does not call __setstate__(), so this optimzation has only be implemented for Python 3.

__setstate__(state)[source]

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

On Python 2, the ‘pickle’ module does not call this method, so this optimzation has only be implemented for Python 3.

__setitem__(index, value)[source]

Update the value of the item at an existing index in the list.

Invoked using ncl[index] = value.

Raises:AttributeError – The value does not have a lower() method.
__delitem__(index)[source]

Delete an item at an existing index from the list.

Invoked using del ncl[index].

__contains__(value)[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 a lower() method.
__add__(other)[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 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)[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)[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)[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)[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__()[source]

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

Invoked using reversed(ncl).

__eq__(other)[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 a lower() method.
__ne__(other)[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 a lower() method.
__gt__(other)[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 a lower() method.
__lt__(other)[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 a lower() method.
__ge__(other)[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 a lower() method.
__le__(other)[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 a lower() method.
count(value)[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 a lower() method.
copy()[source]

Return a shallow copy of the list.

Note: This method is supported on Python 2 and Python 3, even though the built-in list class only supports it on Python 3.

clear()[source]

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

Note: This method is supported on Python 2 and Python 3, even though the built-in list class only supports it on Python 3.

index(value, start=0, stop=9223372036854775807)[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 and stop parameters, whereby stop is the index of the first item after the search range.

Raises:
append(value)[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 a lower() method.
extend(iterable)[source]

Extend the list by the items in the specified iterable (and return None).

Raises:AttributeError – A value in the iterable does not have a lower() method.
insert(index, value)[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 a lower() method.
pop(index=-1)[source]

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

remove(value)[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 a lower() method.
reverse()[source]

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

sort(key=None, reverse=False)[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 (lower-cased) item values. If a key function is given, it is applied once to each (lower-cased) 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.