nocaselist - A case-insensitive list for Python

The project web site is: https://github.com/pywbem/nocaselist

Introduction

Functionality

Class nocaselist.NocaseList is a case-insensitive list that preserves the lexical case of its items.

Example:

$ python
>>> from nocaselist import NocaseList
>>> list1 = NocaseList(['Alpha', 'Beta'])

>>> print(list1)  # Any access is case-preserving
['Alpha', 'Beta']

>>> 'ALPHA' in list1  # Any lookup or comparison is case-insensitive
True

The NocaseList class supports the functionality of the built-in list class of Python 3.8 on all Python versions it supports (except for being case-insensitive, of course). This includes the clear() and copy() methods added in Python 3.3 to the built-in list class.

The case-insensitivity is achieved by matching any key values as their casefolded values. By default, the casefolding is performed as follows:

On Python 3, with str.casefold() for unicode string keys and with bytes.lower() for byte string keys.
On Python 2, with str.lower().

The str.casefold() method implements the casefolding algorithm described in Default Case Folding in The Unicode Standard.

The default casefolding can be overridden with a user-defined casefold method.

Overriding the default casefold method

The case-insensitive behavior of the NocaseList class is implemented in its __casefold__() method. That method returns the casefolded value for the case-insensitive list items.

The default implementation of the __casefold__() method calls str.casefold() on Python 3 and str.lower() on Python 2. The str.casefold() method implements the casefolding algorithm described in Default Case Folding in The Unicode Standard.

If it is necessary to change the case-insensitive behavior of the NocaseList class, that can be done by overriding its __casefold__() method.

The following Python 3 example shows how your own casefold method would be used, that normalizes the value in addition to casefolding it:

from NocaseList import NocaseList
from unicodedata import normalize

class MyNocaseList(NocaseList):

    @staticmethod
    def __casefold__(value):
        return normalize('NFKD', value).casefold()

mylist = MyNocaseList()

# Add item with combined Unicode character "LATIN CAPITAL LETTER C WITH CEDILLA"
mylist.append("\u00C7")

# Look up item with combination sequence of lower case "c" followed by "COMBINING CEDILLA"
"c\u0327" in mylist  # True

Supported environments

The package does not have any dependencies on the type of operating system and is regularly tested in GitHub Actions on the following operating systems:

Ubuntu, Windows, macOS

The package is supported and tested on the following Python versions:

Python: 2.7, 3.5 and all higher 3.x versions

Installing

The following command installs the latest version of nocaselist that is released on PyPI into the active Python environment:

$ pip install nocaselist

To install an older released version of nocaselist, Pip supports specifying a version requirement. The following example installs nocaselist version 0.1.0 from PyPI into the active Python environment:

$ pip install nocaselist==0.1.0

If you need to get a certain new functionality or a new fix that is not yet part of a version released to PyPI, Pip supports installation from a Git repository. The following example installs nocaselist from the current code level in the master branch of the nocaselist repository:

$ pip install git+https://github.com/pywbem/nocaselist.git@master#egg=nocaselist

Verifying the installation

You can verify that nocaselist is installed correctly by importing the package into Python (using the Python environment you installed it to):

$ python -c "import nocaselist; print('ok')"
ok

Package version

The version of the nocaselist package can be accessed by programs using the nocaselist.__version__ variable:

nocaselist._version.__version__ = '1.1.2'

The full version of this package including any development levels, as a string.

Possible formats for this version string are:

“M.N.P.dev1”: Development level 1 of a not yet released version M.N.P
“M.N.P”: A released version M.N.P

Note: For tooling reasons, the variable is shown as nocaselist._version.__version__, but it should be used as nocaselist.__version__.

Compatibility and deprecation policy

The nocaselist project uses the rules of Semantic Versioning 2.0.0 for compatibility between versions, and for deprecations. The public interface that is subject to the semantic versioning rules and specificically to its compatibility rules are the APIs and commands described in this documentation.

The semantic versioning rules require backwards compatibility for new minor versions (the ‘N’ in version ‘M.N.P’) and for new patch versions (the ‘P’ in version ‘M.N.P’).

Thus, a user of an API or command of the nocaselist project can safely upgrade to a new minor or patch version of the nocaselist package without encountering compatibility issues for their code using the APIs or for their scripts using the commands.

In the rare case that exceptions from this rule are needed, they will be documented in the Change log.

Occasionally functionality needs to be retired, because it is flawed and a better but incompatible replacement has emerged. In the nocaselist project, such changes are done by deprecating existing functionality, without removing it immediately.

The deprecated functionality is still supported at least throughout new minor or patch releases within the same major release. Eventually, a new major release may break compatibility by removing deprecated functionality.

Any changes at the APIs or commands that do introduce incompatibilities as defined above, are described in the Change log.

Deprecation of functionality at the APIs or commands is communicated to the users in multiple ways:

It is described in the documentation of the API or command
It is mentioned in the change log.
It is raised at runtime by issuing Python warnings of type DeprecationWarning (see the Python warnings module).

Since Python 2.7, DeprecationWarning messages are suppressed by default. They can be shown for example in any of these ways:

By specifying the Python command line option: -W default
By invoking Python with the environment variable: PYTHONWARNINGS=default

It is recommended that users of the nocaselist project run their test code with DeprecationWarning messages being shown, so they become aware of any use of deprecated functionality.

Here is a summary of the deprecation and compatibility policy used by the nocaselist project, by version type:

New patch version (M.N.P -> M.N.P+1): No new deprecations; no new functionality; backwards compatible.
New minor release (M.N.P -> M.N+1.0): New deprecations may be added; functionality may be extended; backwards compatible.
New major release (M.N.P -> M+1.0.0): Deprecated functionality may get removed; functionality may be extended or changed; backwards compatibility may be broken.

API Reference

This section describes the external API of the nocaselist project. Any internal symbols and APIs are omitted.

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`	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)[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.lower() on Python 2, and on Python 3 it is str.casefold(), falling back to bytes.lower() if it does not exist.

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 unicode or bytes) – Input value. Will not be None.
Returns: Case-insensitive form of the input value.
Return type: str or unicode or bytes
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.

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 the casefold 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 the casefold 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.