nocasedict - A case-insensitive ordered dictionary for Python

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

Introduction

Functionality

Class nocasedict.NocaseDict is a case-insensitive ordered dictionary that preserves the original lexical case of its keys.

Example:

$ python
>>> from nocasedict import NocaseDict

>>> dict1 = NocaseDict({'Alpha': 1, 'Beta': 2})

>>> dict1['ALPHA']  # Lookup by key is case-insensitive
1

>>> print(dict1)  # Keys are returned with the original lexical case
NocaseDict({'Alpha': 1, 'Beta': 2})

The NocaseDict class supports the functionality of the built-in dict class of Python 3.8 on all Python versions it supports with the following exceptions (and the case-insensitivity of course):

• The iter..(), view..() and has_key() methods are only present on Python 2, consistent with the built-in dict class.

• The keys(), values() and items() methods return a list on Python 2 and a dictionary view on Python 3, consistent with the built-in dict 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.

Functionality can be added using mixin classes:

• HashableMixin mixin class: Adds case-insensitive hashability.

• KeyableByMixin() mixin generator function: Adds ability to get the key from an attribute of the value object.

Why yet another case-insensitive dictionary: We found that all previously existing case-insensitive dictionary packages on Pypi either had flaws, were not well maintained, or did not support the Python versions we needed.

Overriding the default casefold method

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

That method returns the casefolded key that is used for the case-insensitive lookup of dictionary items.

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

from nocasedict import NocaseDict
from unicodedata import normalize

class MyNocaseDict(NocaseDict):

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

mydict = MyNocaseDict()

# Add item with combined Unicode character "LATIN CAPITAL LETTER C WITH CEDILLA"
mydict["\u00C7"] = "value"

# Look up item with combination sequence of lower case "c" followed by "COMBINING CEDILLA"
value = mydict["c\u0327"]  # succeeds

Installation

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 nocasedict that is released on PyPI into the active Python environment:

$ pip install nocasedict

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

$ pip install nocasedict==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 nocasedict from the current code level in the master branch of the nocasedict repository:

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

Verifying the installation

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

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

Package version

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

nocasedict._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 nocasedict._version.__version__, but it should be used as nocasedict.__version__.

Compatibility and deprecation policy

The nocasedict 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 nocasedict project can safely upgrade to a new minor or patch version of the nocasedict 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 nocasedict 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 nocasedict 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 nocasedict 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 nocasedict project. Any internal symbols and APIs are omitted.

Class NocaseDict

class nocasedict.NocaseDict(*args, **kwargs)

A case-insensitive and case-preserving ordered dictionary.

The dictionary is case-insensitive: When items of the dictionary are looked up by key or keys are compared by the dictionary, 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 key value. None is allowed as a key value and will not be case folded.

The dictionary is case-preserving: When keys are returned, they have the lexical case that was originally specified when adding or updating the item.

The dictionary is ordered: The dictionary maintains the order in which items were added for all Python versions supported by this package. This is consistent with the ordering behavior of the built-in dict class starting with Python 3.7.

The NocaseDict class is derived from the abstract base class collections.abc.MutableMapping and not from the dict class, because of the unique implementation of NocaseDict, which maintains a single dictionary with the casefolded keys, and values that are tuples (original key, value). This supports key based lookup with a single dictionary lookup. Users that need to test whether an object is a dictionary should do that with isinstance(obj, Mapping) or isinstance(obj, MutableMapping).

The provided key and value objects will be referenced from the dictionary without being copied, consistent with the built-in dict class.

Except for the case-insensitivity of its keys, the NocaseDict class behaves like the built-in dict class starting with Python 3.7 (where it is guaranteed to be ordered), so its documentation applies completely.

The NocaseDict class itself provides no added functionality compared to the built-in dict class. This package provides mixin classes for adding functionality:

• HashableMixin mixin class: Adds case-insensitive hashability.

• KeyableByMixin() mixin generator function: Adds ability to get the key from an attribute of the value object.

Example of usage:

from nocasedict import NocaseDict

dict1 = NocaseDict({'Alpha': 1, 'Beta': 2})

print(dict1['ALPHA'])  # Lookup by key is case-insensitive
# 1

print(dict1)  # Access of keys is case-preserving
# NocaseDict({'Alpha': 1, 'Beta': 2})

Parameters

• *args –

  An optional single positional argument representing key-value pairs to initialize the dictionary from, in iteration order of the specified object. The argument must be one of:

  • a dictionary object, or more specifically an object that has a method keys() providing iteration through the keys and that supports subscription by key (e.g. ncd[key]) for accessing the values.

  • an iterable. If a key occurs more than once (case-insensitively), the last item for that key becomes the corresponding item in the dictionary. Each item in the iterable must be one of:

    • an iterable with exactly two items. The first item is used as the key, and the second item as the value.

    • an object with a key attribute, if the KeyableByMixin() mixin generator function is used. The value of the key attribute is used as the key, and the object itself as the value.

• **kwargs –

  Optional keyword arguments representing key-value pairs to add to the dictionary after being initialized from the positional argument.

  If a key being added is already present (case-insensitively) from the positional argument, key and value will be updated from the keyword argument.

  Before Python 3.7, the order of keyword arguments as specified in the call to the method was not guaranteed to be preserved for the method implementation, so passing more than one keyword argument may have resulted in arbitrary order of items in the dictionary.

To summarize, only the following types of init arguments are guaranteed to preserve the order of provided items after having been added to the new dictionary, across all Python versions supported by this package:

• Passing an iterable as a single positional argument, and passing at most one keyword argument.

• Passing an ordered dictionary/mapping as a single positional argument, and passing at most one keyword argument.

A UserWarning will be issued if the order of provided items in the arguments is not guaranteed to be preserved.

Examples for initializing:

from nocasedict import NocaseDict

dict1 = NocaseDict({'Alpha': 1, 'Beta': 2})
dict2 = NocaseDict(dict1)
dict3 = NocaseDict([('Alpha', 1), ('Beta', 2)])
dict4 = NocaseDict((('Alpha', 1), ('Beta', 2)))
dict5 = NocaseDict(Alpha=1, Beta=2)
dict6 = NocaseDict(dict1, BETA=3)

Raises

• TypeError – Expected at most 1 positional argument, got {n}.

• ValueError – Cannot unpack positional argument item #{i}.

Methods

clear	Remove all items from the dictionary.
copy	Return a copy of the dictionary.
fromkeys	Return a new NocaseDict object with keys from the specified iterable of keys, and values all set to the specified value.
get	Return the value of the item with an existing key (looked up case-insensitively), or if the key does not exist, a default value.
has_key	Python 2 only: Return a boolean indicating whether the dictionary contains an item with the key (looked up case-insensitively).
items	Return a view on (in Python 3) or a list of (in Python 2) the dictionary items in dictionary iteration order, where each item is a tuple of its key (in the original lexical case) and its value.
iteritems	Python 2 only: Return an iterator through the dictionary items in dictionary iteration order, where each item is a tuple of its key (in the original lexical case) and its value.
iterkeys	Python 2 only: Return an iterator through the dictionary keys (in the original lexical case) in dictionary iteration order.
itervalues	Python 2 only: Return an iterator through the dictionary values in dictionary iteration order.
keys	Return a view on (in Python 3) or a list of (in Python 2) the dictionary keys (in the original lexical case) in dictionary iteration order.
keys_nocase	Return a view on (in Python 3) or a list of (in Python 2) the casefolded dictionary keys in dictionary iteration order.
pop	Remove the item with the specified key if it exists (looked up case-insensitively), and return its value.
popitem	Remove the last dictionary item (in iteration order) and return it as a tuple (key, value).
setdefault	If an item with the key (looked up case-insensitively) does not exist, add an item with that key and the specified default value, and return the value of the item with the key.
update	Update the dictionary from key/value pairs.
values	Return a view on (in Python 3) or a list of (in Python 2) the dictionary values in dictionary iteration order.
viewitems	Python 2 only: Return a view on the dictionary items in dictionary order, where each item is a tuple of its key (in the original lexical case) and its value.
viewkeys	Python 2 only: Return a view on the dictionary keys (in the original lexical case) in dictionary iteration order.
viewvalues	Python 2 only: Return a view on the dictionary values in dictionary order.

Attributes

Details

static __casefold__(key)

This method implements the case-insensitive behavior of the class.

It returns a case-insensitive form of the input key by calling a “casefold method” on the key. The input key 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

key (str or unicode) – Input key. Will not be None.

Returns

Case-insensitive form of the input key.

Return type

str or unicode

Raises

AttributeError – The key does not have the casefold method.

__contains__(key)

Return a boolean indicating whether the dictionary contains an item with the key (looked up case-insensitively).

Invoked when using: key in ncd

Raises

AttributeError – The key does not have the casefold method.

__delitem__(key)

Delete the item with an existing key (looked up case-insensitively).

Invoked when using: del ncd[key]

Raises

• AttributeError – The key does not have the casefold method.

• KeyError – Key does not exist (case-insensitively).

__eq__(other)

Return a boolean indicating whether the dictionary and the other dictionary are equal, by matching items (case-insensitively) based on their keys, and then comparing the values of matching items for equality.

The other dictionary may be a NocaseDict object or any other mapping. In all cases, the matching of keys takes place case-insensitively.

Invoked when using e.g.: ncd == other

Raises

AttributeError – The key does not have the casefold method.

__getitem__(key)

Return the value of the item with an existing key (looked up case-insensitively).

Invoked when using e.g.: value = ncd[key]

Raises

• AttributeError – The key does not have the casefold method.

• KeyError – Key does not exist (case-insensitively).

__iter__()

Return an iterator through the dictionary keys (in the original lexical case) in dictionary iteration order.

Invoked when using: for key in ncd

__len__()

Return the number of items in the dictionary.

Invoked when using: len(ncd)

__ne__(other)

Return a boolean indicating whether the dictionary and the other dictionary are not equal, by negating the equality test.

The other dictionary may be a NocaseDict object or any other mapping. In all cases, the matching of keys takes place case-insensitively.

Invoked when using e.g.: ncd != other

Raises

AttributeError – The key does not have the casefold method.

__repr__()

Return a string representation of the dictionary that is suitable for debugging.

The order of items is in dictionary iteration order, and the keys are in the original lexical case.

Invoked when using e.g.: repr(ncd)

__reversed__()

Return an iterator for the reversed iteration order of the dictionary.

Invoked when using: reversed[ncd]

__setitem__(key, value)

Update the value of the item with an existing key (looked up case-insensitively), or if an item with the key does not exist, add an item with the specified key and value.

Invoked when using e.g.: ncd[key] = value

Raises

AttributeError – The key does not have the casefold method.

clear()

Remove all items from the dictionary.

copy()

Return a copy of the dictionary.

This is a middle-deep copy; the copy is independent of the original in all attributes that have mutable types except for:

• The values in the dictionary

Note that the Python functions copy.copy() and copy.deepcopy() can be used to create completely shallow or completely deep copies of objects of this class.

classmethod fromkeys(iterable, value=None)

Return a new NocaseDict object with keys from the specified iterable of keys, and values all set to the specified value.

Raises

AttributeError – The key does not have the casefold method.

get(key, default=None)

Return the value of the item with an existing key (looked up case-insensitively), or if the key does not exist, a default value.

Raises

AttributeError – The key does not have the casefold method.

has_key(key)

Python 2 only: Return a boolean indicating whether the dictionary contains an item with the key (looked up case-insensitively).

Raises

• AttributeError – The key does not have the casefold method.

• AttributeError – The method does not exist on Python 3.

items()

Return a view on (in Python 3) or a list of (in Python 2) the dictionary items in dictionary iteration order, where each item is a tuple of its key (in the original lexical case) and its value.

See Dictionary View Objects on Python 3 for details about view objects.

iteritems()

Python 2 only: Return an iterator through the dictionary items in dictionary iteration order, where each item is a tuple of its key (in the original lexical case) and its value.

Raises

AttributeError – The method does not exist on Python 3.

iterkeys()

Python 2 only: Return an iterator through the dictionary keys (in the original lexical case) in dictionary iteration order.

Raises

AttributeError – The method does not exist on Python 3.

itervalues()

Python 2 only: Return an iterator through the dictionary values in dictionary iteration order.

Raises

AttributeError – The method does not exist on Python 3.

keys()

Return a view on (in Python 3) or a list of (in Python 2) the dictionary keys (in the original lexical case) in dictionary iteration order.

See Dictionary View Objects on Python 3 for details about view objects.

keys_nocase()

Return a view on (in Python 3) or a list of (in Python 2) the casefolded dictionary keys in dictionary iteration order.

See Dictionary View Objects on Python 3 for details about view objects.

pop(key, default=<object object>)

Remove the item with the specified key if it exists (looked up case-insensitively), and return its value.

If an item with the key does not exist, the default value is returned if specified, otherwise KeyError is raised.

Raises

KeyError – Key does not exist (case-insensitively) and no default was specified.

popitem()

Remove the last dictionary item (in iteration order) and return it as a tuple (key, value).

The last item in iteration order is the last item that was added to the dictionary.

Raises

KeyError – Dictionary is empty.

setdefault(key, default=None)

If an item with the key (looked up case-insensitively) does not exist, add an item with that key and the specified default value, and return the value of the item with the key.

Raises

AttributeError – The key does not have the casefold method.

update(*args, **kwargs)

Update the dictionary from key/value pairs.

If a key is already present in the dictionary (looked up case-insensitively), its key and value is updated (without affecting its position in the dictionary iteration order). Otherwise, an item with the key and value is added to the dictionary.

The provided key and value objects will be referenced from the dictionary without being copied, consistent with the built-in dict class.

Parameters

• *args –

  An optional single positional argument representing key-value pairs to update the dictionary from, in iteration order of the specified object. The argument must be one of:

  • a dictionary object, or more specifically an object that has a method keys() providing iteration through the keys and that supports subscription by key for accessing the values.

  • an iterable. If a key occurs more than once (case-insensitively), the last item for that key becomes the corresponding item in the dictionary. Each item in the iterable must be one of:

    • an iterable with exactly two items. The first item is used as the key, and the second item as the value.

    • an object with a key attribute, if the KeyableByMixin() mixin generator function is used. The value of the key attribute is used as the key, and the object itself as the value.

• **kwargs –

  Optional keyword arguments representing key-value pairs to update the dictionary from, after having processed the positional argument.

  Before Python 3.7, the order of keyword arguments as specified in the call to the method was not guaranteed to be preserved for the method implementation, so passing more than one keyword argument may have resulted in arbitrary order of items in the dictionary.

Raises

• AttributeError – The key does not have the casefold method.

• TypeError – Expected at most 1 positional argument, got {n}.

• ValueError – Cannot unpack positional argument item #{i}.

values()

Return a view on (in Python 3) or a list of (in Python 2) the dictionary values in dictionary iteration order.

See Dictionary View Objects on Python 3 for details about view objects.

viewitems()

Python 2 only: Return a view on the dictionary items in dictionary order, where each item is a tuple of its key (in the original lexical case) and its value.

See Dictionary View Objects on Python 2 for details about view objects.

Raises

AttributeError – The method does not exist on Python 3.

viewkeys()

Python 2 only: Return a view on the dictionary keys (in the original lexical case) in dictionary iteration order.

See Dictionary View Objects on Python 2 for details about view objects.

Raises

AttributeError – The method does not exist on Python 3.

viewvalues()

Python 2 only: Return a view on the dictionary values in dictionary order.

See Dictionary View Objects on Python 2 for details about view objects.

Raises

AttributeError – The method does not exist on Python 3.

Mixin class HashableMixin

class nocasedict.HashableMixin

A mixin class that adds case-insensitive hashability to nocasedict.NocaseDict.

The derived class inheriting from HashableMixin must (directly or indirectly) inherit from NocaseDict.

Hashability allows objects of the derived class to be used as keys of dict and members of set, because these data structures use the hash values internally.

The hash value calculated by this mixin class uses the hash values of the keys and values of the dictionary in such a way that the hash value of the key is case-insensitive (i.e. it does not change for different lexical cases of a key), and the hash value of the dictionary is order-insensitive (i.e. it does not change for a different order of items).

Since NocaseDict objects are mutable, reliable use of the hash value requires that no items in the dictionary are added, removed or updated, while the dictionary object is used as a key (in another dictionary) or as a set member.

See hashable for more details.

Example:

from nocasedict import NocaseDict, HashableMixin

class MyDict(HashableMixin, NocaseDict):
    pass

mykey1 = MyDict(a=1, b=2)
mykey2 = MyDict(B=2, A=1)  # case- and order-insensitively equal

dict1 = {mykey1: 'foo'}  # Add item using first key

print(dict1[mykey2])  # Access item using second key
# 'foo'

Methods

Attributes

Details

__hash__()

Return a case-insensitive and order-insensitive hash value for the dictionary.

Mixin generator function KeyableByMixin()

nocasedict.KeyableByMixin(key_attr)

A generator function returning a mixin class that adds the ability to the nocasedict.NocaseDict class to initialize or update the dictionary from an iterable of objects, whereby a particular attribute of each object is used as the key.

This simplifies the initialization of dictionaries because simple lists or tuples of such objects can be provided.

The derived class inheriting from the returned mixin class must (directly or indirectly) inherit from NocaseDict.

Example:

from nocasedict import NocaseDict, KeyableByMixin

class MyDict(KeyableByMixin('name'), NocaseDict):
    pass

class Obj(object):
    def __init__(self, name, thing):
        self.name = name  # Will be used as the key
        self.thing = thing

md = MyDict([Obj('A', 1), Obj('B', 2)])

print(md)
# MyDict({'A': <__main__.Obj object at 0x10bc3d820>,
#         'B': <__main__.Obj object at 0x10bc89af0>})

Development

This section only needs to be read by developers of the nocasedict project, including people who want to make a fix or want to test the project.

Repository

The repository for the nocasedict project is on GitHub:

https://github.com/pywbem/nocasedict

Setting up the development environment

1. If you have write access to the Git repo of this project, clone it using its SSH link, and switch to its working directory:

   $ git clone git@github.com:pywbem/nocasedict.git
   $ cd nocasedict
   

   If you do not have write access, create a fork on GitHub and clone the fork in the way shown above.

2. It is recommended that you set up a virtual Python environment. Have the virtual Python environment active for all remaining steps.

3. Install the project for development. This will install Python packages into the active Python environment, and OS-level packages:

   $ make develop
   

4. This project uses Make to do things in the currently active Python environment. The command:

   $ make
   

   displays a list of valid Make targets and a short description of what each target does.

Building the documentation

The ReadTheDocs (RTD) site is used to publish the documentation for the project package at https://nocasedict.readthedocs.io/

This page is automatically updated whenever the Git repo for this package changes the branch from which this documentation is built.

In order to build the documentation locally from the Git work directory, execute:

$ make builddoc

The top-level document to open with a web browser will be build_doc/html/docs/index.html.

Testing

All of the following make commands run the tests in the currently active Python environment. Depending on how the nocasedict package is installed in that Python environment, either the directories in the main repository directory are used, or the installed package. The test case files and any utility functions they use are always used from the tests directory in the main repository directory.

The tests directory has the following subdirectory structure:

tests
 +-- unittest            Unit tests

There are multiple types of tests:

1. Unit tests

   These tests can be run standalone, and the tests validate their results automatically.

   They are run by executing:

   $ make test
   

   Test execution can be modified by a number of environment variables, as documented in the make help (execute make help).

   An alternative that does not depend on the makefile and thus can be executed from the source distribution archive, is:

   $ ./setup.py test
   

   Options for pytest can be passed using the --pytest-options option.

To run the unit tests in all supported Python environments, the Tox tool can be used. It creates the necessary virtual Python environments and executes make test (i.e. the unit tests) in each of them.

For running Tox, it does not matter which Python environment is currently active, as long as the Python tox package is installed in it:

$ tox                              # Run tests on all supported Python versions
$ tox -e py27                      # Run tests on Python 2.7

Testing from the source archives on Pypi or GitHub

The wheel distribution archives on Pypi (e.g. *.whl) contain only the files needed to run this package, but not the files needed to test it.

The source distribution archives on Pypi and GitHub (e.g. *.tar.gz) contain all files that are needed to run and to test this package. This allows testing the package without having to check out the entire repository, and is convenient for testing e.g. when packaging into OS-level packages. Nevertheless, the test files are not installed when installing these source distribution archives.

The following commands download the source distribution archive on Pypi for a particular version of the package into the current directory and unpack it:

$ pip download --no-deps --no-binary :all: nocasedict==1.0.0
$ tar -xf nocasedict-1.0.0.tar.gz
$ cd nocasedict-1.0.0
$ ls -1
-rw-r--r--   1 johndoe  staff    468 Jun 29 22:31 INSTALL.md
-rw-r--r--   1 johndoe  staff  26436 May 26 06:45 LICENSE.txt
-rw-r--r--   1 johndoe  staff    367 Jul  3 07:54 MANIFEST.in
-rw-r--r--   1 johndoe  staff   3451 Jul  3 07:55 PKG-INFO
-rw-r--r--   1 johndoe  staff   7665 Jul  2 23:20 README.rst
drwxr-xr-x  29 johndoe  staff    928 Jul  3 07:55 nocasedict
drwxr-xr-x   8 johndoe  staff    256 Jul  3 07:55 nocasedict.egg-info
-rw-r--r--   1 johndoe  staff   1067 Jun 29 22:31 requirements.txt
-rw-r--r--   1 johndoe  staff     38 Jul  3 07:55 setup.cfg
-rwxr-xr-x   1 johndoe  staff   7555 Jul  3 07:24 setup.py
-rw-r--r--   1 johndoe  staff   2337 Jul  2 23:20 test-requirements.txt
drwxr-xr-x  15 johndoe  staff    480 Jul  3 07:55 tests

This package, its dependent packages for running it, and its dependent packages for testing it can be installed with the package extra named “test”:

$ pip install .[test]

When testing in Linux distributions that include this package as an OS-level package, the corresponding OS-level packages would instead be installed for these dependent Python packages. The test-requirements.txt file shows which dependent Python packages are needed for testing this package.

Finally, the tests can be run using the setup.py script:

$ ./setup.py test

These commands are listed in the help of the setup.py script:

$ ./setup.py --help-commands

. . .

Extra commands:
  . . .
  test              Run unit tests using pytest
  . . .

The additional options supported by these commands are shown in their help:

$ ./setup.py test --help

. . .

Options for 'test' command:
  --pytest-options  additional options for pytest, as one argument

. . .

Note: The test command of setup.py is not the deprecated built-in command (see https://github.com/pypa/setuptools/issues/1684), but has been implemented in setup.py in such a way that it only runs the tests but does not install anything upfront. Therefore, this approach can be used for testing in Linux distributions that include this package as an OS-level package.

Contributing

Third party contributions to this project are welcome!

In order to contribute, create a Git pull request, considering this:

• Test is required.

• Each commit should only contain one “logical” change.

• A “logical” change should be put into one commit, and not split over multiple commits.

• Large new features should be split into stages.

• The commit message should not only summarize what you have done, but explain why the change is useful.

What comprises a “logical” change is subject to sound judgement. Sometimes, it makes sense to produce a set of commits for a feature (even if not large). For example, a first commit may introduce a (presumably) compatible API change without exploitation of that feature. With only this commit applied, it should be demonstrable that everything is still working as before. The next commit may be the exploitation of the feature in other components.

For further discussion of good and bad practices regarding commits, see:

• OpenStack Git Commit Good Practice

• How to Get Your Change Into the Linux Kernel

Further rules:

• The following long-lived branches exist and should be used as targets for pull requests:

  • master - for next functional version

  • stable_$MN - for fix stream of released version M.N.

• We use topic branches for everything!

  • Based upon the intended long-lived branch, if no dependencies

  • Based upon an earlier topic branch, in case of dependencies

  • It is valid to rebase topic branches and force-push them.

• We use pull requests to review the branches.

  • Use the correct long-lived branch (e.g. master or stable_0.2) as a merge target.

  • Review happens as comments on the pull requests.

  • At least one approval is required for merging.

• GitHub meanwhile offers different ways to merge pull requests. We merge pull requests by rebasing the commit from the pull request.

Releasing a version to PyPI

This section describes how to release a version of nocasedict to PyPI.

It covers all variants of versions that can be released:

• Releasing a new major version (Mnew.0.0) based on the master branch

• Releasing a new minor version (M.Nnew.0) based on the master branch

• Releasing a new update version (M.N.Unew) based on the stable branch of its minor version

The description assumes that the pywbem/nocasedict Github repo is cloned locally and its upstream repo is assumed to have the Git remote name origin.

Any commands in the following steps are executed in the main directory of your local clone of the pywbem/nocasedict Git repo.

1. Set shell variables for the version that is being released and the branch it is based on:

   • MNU - Full version M.N.U that is being released

   • MN - Major and minor version M.N of that full version

   • BRANCH - Name of the branch the version that is being released is based on

   When releasing a new major version (e.g. 1.0.0) based on the master branch:

   MNU=1.0.0
   MN=1.0
   BRANCH=master
   

   When releasing a new minor version (e.g. 0.9.0) based on the master branch:

   MNU=0.9.0
   MN=0.9
   BRANCH=master
   

   When releasing a new update version (e.g. 0.8.1) based on the stable branch of its minor version:

   MNU=0.8.1
   MN=0.8
   BRANCH=stable_${MN}
   

2. Create a topic branch for the version that is being released:

   git checkout ${BRANCH}
   git pull
   git checkout -b release_${MNU}
   

3. Edit the version file:

   vi nocasedict/_version.py
   

   and set the __version__ variable to the version that is being released:

   __version__ = 'M.N.U'
   

4. Edit the change log:

   vi docs/changes.rst
   

   and make the following changes in the section of the version that is being released:

   • Finalize the version.

   • Change the release date to today’s date.

   • Make sure that all changes are described.

   • Make sure the items shown in the change log are relevant for and understandable by users.

   • In the “Known issues” list item, remove the link to the issue tracker and add text for any known issues you want users to know about.

   • Remove all empty list items.

5. Commit your changes and push the topic branch to the remote repo:

   git status  # Double check the changed files
   git commit -asm "Release ${MNU}"
   git push --set-upstream origin release_${MNU}
   

6. On GitHub, create a Pull Request for branch release_M.N.U. This will trigger the CI runs.

   Important: When creating Pull Requests, GitHub by default targets the master branch. When releasing based on a stable branch, you need to change the target branch of the Pull Request to stable_M.N.

7. On GitHub, close milestone M.N.U.

8. On GitHub, once the checks for the Pull Request for branch start_M.N.U have succeeded, merge the Pull Request (no review is needed). This automatically deletes the branch on GitHub.

9. Add a new tag for the version that is being released and push it to the remote repo. Clean up the local repo:

   git checkout ${BRANCH}
   git pull
   git tag -f ${MNU}
   git push -f --tags
   git branch -d release_${MNU}
   

10. When releasing based on the master branch, create and push a new stable branch for the same minor version:

    git checkout -b stable_${MN}
    git push --set-upstream origin stable_${MN}
    git checkout ${BRANCH}
    

    Note that no GitHub Pull Request is created for any stable_* branch.

11. When releasing based on the master branch, activate the new version stable_M.N on ReadTheDocs:

    • Go to https://readthedocs.org/projects/nocasedict/versions/ and log in.

    • Activate the new version stable_M.N.

      This triggers a build of that version. Verify that the build succeeds and that new version is shown in the version selection popup at https://nocasedict.readthedocs.io/

12. On GitHub, edit the new tag M.N.U, and create a release description on it. This will cause it to appear in the Release tab.

    You can see the tags in GitHub via Code -> Releases -> Tags.

13. Upload the package to PyPI:

    make upload
    

    This will show the package version and will ask for confirmation.

    Attention! This only works once for each version. You cannot release the same version twice to PyPI.

    Verify that the released version arrived on PyPI at https://pypi.python.org/pypi/nocasedict/

Starting a new version

This section shows the steps for starting development of a new version of the nocasedict project in its Git repo.

This section covers all variants of new versions:

• Starting a new major version (Mnew.0.0) based on the master branch

• Starting a new minor version (M.Nnew.0) based on the master branch

• Starting a new update version (M.N.Unew) based on the stable branch of its minor version

The description assumes that the pywbem/nocasedict Github repo is cloned locally and its upstream repo is assumed to have the Git remote name origin.

Any commands in the following steps are executed in the main directory of your local clone of the pywbem/nocasedict Git repo.

1. Set shell variables for the version that is being started and the branch it is based on:

   • MNU - Full version M.N.U that is being started

   • MN - Major and minor version M.N of that full version

   • BRANCH - Name of the branch the version that is being started is based on

   When starting a new major version (e.g. 1.0.0) based on the master branch:

   MNU=1.0.0
   MN=1.0
   BRANCH=master
   

   When starting a new minor version (e.g. 0.9.0) based on the master branch:

   MNU=0.9.0
   MN=0.9
   BRANCH=master
   

   When starting a new minor version (e.g. 0.8.1) based on the stable branch of its minor version:

   MNU=0.8.1
   MN=0.8
   BRANCH=stable_${MN}
   

2. Create a topic branch for the version that is being started:

   git checkout ${BRANCH}
   git pull
   git checkout -b start_${MNU}
   

3. Edit the version file:

   vi nocasedict/_version.py
   

   and update the version to a draft version of the version that is being started:

   __version__ = 'M.N.U.dev1'
   

4. Edit the change log:

   vi docs/changes.rst
   

   and insert the following section before the top-most section:

   nocasedict M.N.U.dev1
   ---------------------
   
   Released: not yet
   
   **Incompatible changes:**
   
   **Deprecations:**
   
   **Bug fixes:**
   
   **Enhancements:**
   
   **Cleanup:**
   
   **Known issues:**
   
   * See `list of open issues`_.
   
   .. _`list of open issues`: https://github.com/pywbem/nocasedict/issues
   

5. Commit your changes and push them to the remote repo:

   git status  # Double check the changed files
   git commit -asm "Start ${MNU}"
   git push --set-upstream origin start_${MNU}
   

6. On GitHub, create a Pull Request for branch start_M.N.U.

   Important: When creating Pull Requests, GitHub by default targets the master branch. When starting a version based on a stable branch, you need to change the target branch of the Pull Request to stable_M.N.

7. On GitHub, create a milestone for the new version M.N.U.

   You can create a milestone in GitHub via Issues -> Milestones -> New Milestone.

8. On GitHub, go through all open issues and pull requests that still have milestones for previous releases set, and either set them to the new milestone, or to have no milestone.

9. On GitHub, once the checks for the Pull Request for branch start_M.N.U have succeeded, merge the Pull Request (no review is needed). This automatically deletes the branch on GitHub.

10. Update and clean up the local repo:

    git checkout ${BRANCH}
    git pull
    git branch -d start_${MNU}
    

Appendix

This section contains information that is referenced from other sections, and that does not really need to be read in sequence.

References

Python Glossary

• Python 2.7 Glossary

• Python 3 Glossary

Default Case Folding in The Unicode Standard

“Default Case Folding” in The Unicode Standard Version 15.0

Change log

nocasedict 1.1.2

Released: 2023-05-01

Incompatible changes:

• Removed support for Python 3.4. It is unsupported by the PSF since 3/2019 and recently, Github Actions removed the ubuntu18.04 image which was the last one with Python 3.4 support.

Bug fixes:

• Fixed coveralls issues with KeyError and HTTP 422 Unprocessable Entity.

nocasedict 1.1.1

Released: 2022-02-25

Bug fixes:

• Enabled Github Actions for stable branches.

• Addressed new issues of Pylint 2.16.

Enhancements:

• Resurrected support for byte string keys that was removed in version 1.1.0. (issue #139)

nocasedict 1.1.0

Released: 2023-01-21

Incompatible changes:

• The default casefolding method on Python 3 was changed from str.lower() to str.casefold(). This changes the matching of the case-insensitive keys. This shold normally be an improvement, but in case you find that you are negatively affected by this change, you can go back to the str.lower() method by overriding the NocaseDict.__casefold__() method with a method that calls str.lower(). (issue #122)

Enhancements:

• Added support for Python 3.11.

• Changed the default casefolding method on Python 3 to be str.casefold() in order to improve Unicode support. On Python 2, it remains str.lower(). Added support for user-defined casefolding. (issue #122)

nocasedict 1.0.4

Released: 2022-08-04

Bug fixes:

• Various bug fixes in dependencies and test environment

nocasedict 1.0.3

Released: 2022-03-27

Bug fixes:

• Mitigated the coveralls HTTP status 422 by pinning coveralls-python to <3.0.0 (issue #55).

• Fixed issues raised by new Pylint 2.9 and 2.10.

• Fixed a dependency error that caused importlib-metadata to be installed on Python 3.8, while it is included in the Python base.

• Disabled new Pylint issue ‘consider-using-f-string’, since f-strings were introduced only in Python 3.6.

• Fixed install error of wrapt 1.13.0 on Python 2.7 on Windows due to lack of MS Visual C++ 9.0 on GitHub Actions, by pinning it to <1.13.

• Fixed potential issue with Sphinx/docutils versions on Python 2.7.

• Fixed error when installing virtualenv in install test on Python 2.7.

• Fixed that the added setup.py commands (test, leaktest, installtest) were not displayed. They are now displayed at verbosity level 1 (using ‘-v’).

Enhancements:

• Enhanced test matrix on GitHub Actions to always include Python 2.7 and Python 3.4 on Ubuntu and Windows, and Python 2.7 and Python 3.5 on macOS.

• Support for Python 3.10: Added Python 3.10 in GitHub Actions tests, and in package metadata.

Cleanup:

• Removed old tools that were needed for travis and Appveyor but no longer on GitHub Actions: remove_duplicate_setuptools.py, retry.bat

nocasedict 1.0.2

Released: 2021-01-01

Enhancements:

• Migrated from Travis and Appveyor to GitHub Actions. This required changes in several areas including dependent packages used for testing and coverage. This did not cause any changes on dependent packages used for the installation of the package.

nocasedict 1.0.1

Released: 2020-10-04

Bug fixes:

• Test: Fixed issue with virtualenv raising AttributeError during installtest on Python 3.4. (see issue #61)

• Fixed UserWarning about unpreserved order of input items. (see issue #59)

Enhancements:

• Added checking for no expected warning. Adjusted a testcase to accomodate the new check. (see issue #65)

nocasedict 1.0.0

Released: 2020-09-11

Bug fixes:

• Test: Fixed that the reversed test against the built-in dict was attempted on Python 3.7, but the built-in dict became reversible only in Python 3.8. (See issue #49)

• Test: Fixed issue on pypy2 (Python 2.7) where the testcases for update() passed keyword arguments that had integer-typed argument names. That is supported by CPython 2.7 when passing them as a kwargs dict, but not by pypy2. Removed these testcases, because the support for that feature in CPython 2.7 is not part of the Python language.

• Docs: Fixed missing Python 2 only methods in RTD docs (See issue #52)

• Pylint: Accomodated new ‘raise-missing-from’ check in Pylint 2.6.0.

nocasedict 0.5.0

Released: 2020-07-29

Initial release