deprecate_keys

class dkey.deprecate_keys(dictionary, *args)

Wrapper for dicts that allows to set certain keys as deprecated.

__init__(dictionary, *args)

Construct the wrapper class.

Internally, the items are stored in the same order as the given dictionary (CPython >=3.6). The deprecated old keys that were replaced with new ones are positioned just before their respective new keys.

Parameters:

• dictionary (dict) – The dictionary to wrap
• *args – Zero or more keys that should show deprecation warnings. Use dkey.dkey for each key.

__contains__(key)

Return True if the given key key is in this dict, else False.

Warns if the given key is deprecated.

Parameters:key – The key to search in this dict. Returns:IsInDict – True if the given key is in this dict. False, otherwise. Return type:bool Warns:CustomWarning – Warns with the warning stored for the given key if the key is deprecated.

__delitem__(key)

Remove the item with key key and its associated value.

Warns if the given key is deprecated.

Parameters:key – The key of the item which to remove. Raises:KeyError – Raises a KeyError if the given key does not exist Warns:CustomWarning – Warns with the warning stored for the given key if the key is deprecated. Further access to the given key will not spawn additional warnings.

__eq__(other)

Return True if identical to other.

Warns if either this or other contains deprecated keys.

Parameters:other – The other object to compare this one to Returns:True if they are equal, False otherwise Return type:bool Warns:CustomWarning – Warns with the warnings stored for all contained keys.

__getitem__(key)

Get the value of the item of the given key key.

Warns if the given key is deprecated. If the key does not exist, it will behave the same as a normal dict, i.e. it will raise a KeyError.

Parameters:key – The key for which to return the value Returns:The value stored for the given key Return type:value Raises:KeyError – If the key is not found Warns:CustomWarning – Warns with the warning stored for the given key if the key is deprecated.

__iter__()

Return an iterator over the keys of the dictionary.

Warns for each deprecated item accessed.

Returns:Iterator – An iterator over the wrapped dict Return type:iterator Warns:CustomWarning – Warns whenever a deprecated item in the dict is returned. Each item will warn with its set warning type and message.

__len__()

Return the number of items in the dict.

Will raise warnings, if the dict contains deprecated values. One for each deprecated value.

Returns:The number of items in the dict Return type:int Warns:CustomWarning – Warns for each deprecated item in the dictionary before returning.

__ne__(other)

Return True if not identical to other.

Warns if either this or other contains deprecated keys.

Parameters:other – The other object to compare this one to Returns:True if they are not equal, False otherwise Return type:bool Warns:CustomWarning – Warns with the warnings stored for all contained keys.

__setitem__(key, value)

Set the value of the item of the given key key to value.

Warns if the given key is deprecated.

Parameters:

• key – The key under which to store the given value
• value – The value to store

Warns:

CustomWarning – Warns with the warning stored for the given key if the key is deprecated. Further access to the given key will not spawn additional warnings.

clear()

Remove all entries from the dict.

Will also remove all deprecation warnings and all keys.

copy()

Return a shallow copy of this wrapped dict.

Will return a wrapped dict that, as the original, will warn with the deprecation warnings set for this dict.

Returns:copy – A shallow copy of the underlying dict and a shallow copy of the underlying deprecation key structure. Return type:deprecate_keys

get(key, default=None)

Get the value stored under key or default if this key doesn’t exist.

This function is the same as deprecate_keys.__getitem__ except that it does not throw for non existing keys, but returns the given default value instead.

Parameters:

• key – The key for which to return the value
• optional (default,) – The value to return, if the given key is not stored in the dict. Defaults to None if not given.

Returns:

The value stored for key or default if key is not in the dict.

Return type:

value

items()

Return a new view of the dictionary’s items: iterator of (key, value) pairs.

Works the same as the plain dict.items function except that it warns about all deprecated keys contained before returning.

Returns:Basically an iterator over (key, value) pairs of the dict. For more information about dict views see: dictionary view Return type:dict_items Warns:CustomWarning – Warns for each deprecated item in the dictionary before returning.

keys()

Return a new view of the dictionary’s keys.

Works the same as the plain dict.keys function except that it warns about all deprecated keys before returning the view.

Returns:Basically an iterator over the contained keys of the dict. For more information about dict views see: dictionary view Return type:dict_keys Warns:CustomWarning – Warns for each deprecated item in the dictionary before returning.

pop(key, default=<object object>)

Remove and return the item with key key.

If the key is not in the dict and no default value is set, this function will raise an exception. If a default value is given, this value will be returned instead.

Parameters:

• key – The key to pop
• default (optional) – The value to return if the given key is not in the dict. If non is given, an exception is raised instead.

Returns:

The value of the key given or the given default value, or if no default value is given, an exception is raised.

Return type:

value

Raises:

KeyError – If key is not in the dict and no default value is given, this function raises a KeyError.

Warns:

CustomWarning – Warns if the popped item is a deprecated key. The deprecation information for this key is removed.

popitem()

Pop an item from the dict.

This function has the same behaviour as dict.popitem. Therefore, for Python < 3.6 this function will pop an arbitrary item, whereas for Python >= 3.6 this function will raise the last item added to this dict. If the dict is empty, this function will raise a KeyError.

Returns:

• key – The key popped
• value – The associated value of the popped key

Raises:KeyError – If the dict is empty. Warns:CustomWarning – Warns if the popped item is a deprecated key. The deprecation information for this key is removed.

values()

Return a new view of the dictionary’s values.

Works the same as the plain dict.values function except that it warns about all deprecated keys associated with returned values before returning the view.

Returns:Basically an iterator over the contained values of the dict. For more information about dict views see: dictionary view Return type:dict_values Warns:CustomWarning – Warns for each deprecated item in the dictionary before returning.

dkey

dkey.dkey(*args, deprecated_in=None, removed_in=None, details=None, warning_type='developer')

Convert a key into a deprecation lookup dict.

To use the dkey.deprecate_keys function it is easiest to generate its input with this function. This function generates:

• A key removed deprecation warning object if one key is provided
• A key replaced deprecation warning object if two keys are provided

Parameters:

• *args – One or two keys. If one key is passed, it is assumed that this key will be removed in the future. If two keys are passed, it is assumed that the second key is the replacement for the first one.
• deprecated_in (str, optional) – Version in which this key was deprecated. If given, will appear in the warning message.
• removed_in (str, optional) – Version in which this key will be removed and will no longer work. If given, will appear in the warning message.
• details (str, optional) – Will remove the default final sentence (do no longer use, or use xxx from now on).
• warning_type ({'developer', 'end user', ArbitraryWarning}, optional) –

  The warning type to use when the old key is accessed

  By default, deprecation warnings are intended for developers only which means a any:DeprecationWarning is used which isn’t shown to end users. If it should be shown to end users, this can be done by passing ‘end user’ which will raise FutureWarning. If you want to use your custom warning type this is also possible.

  Note

  Your custom warning must work with warnings.warn

Returns:

A dict that can be used as a deprecated key input for dkey.deprecate_keys.

Return type:

dict

Raises:

ValueError – If zero or more than two keys are passed to this function.