dkey 0.1.0

Package to deprecate dict keys

# dkey - deprecating dict keys

[](https://travis-ci.org/NOhs/dkey) [](https://coveralls.io/github/NOhs/dkey?branch=master) [](https://dkey.readthedocs.io/en/latest/?badge=latest) [](https://badge.fury.io/py/dkey) [](https://opensource.org/licenses/MIT) [](https://www.codacy.com/app/NOhs/dkey?utm_source=github.com&utm_medium=referral&utm_content=NOhs/dkey&utm_campaign=Badge_Grade)

This module provides a thin wrapper that can be used to set certain keys in dictionaries as deprecated. This allows
e.g. for an easy way to gently push out interface changes instead of just introducing breaking changes without any
prior warnings.

## Usage example

### Replacing or removing keys

```python
from dkey import deprecate_keys

def customer_info():
# old version
# return {
# 'name': 'Smith',
# 'age': 24,
# 'cleartext password': 'password'
# }
# new version, 'name' does not have to appear anymore in the dict
return deprecate_keys(
{
'first name': 'Adam',
'last name': 'Smith',
'age': 24
},
dkey('name', 'last name'),
dkey('cleartext password',))

def my_func():
customer = customer_info()

# Worked with the old version, will warn to use 'last name' in the future
# and will return 'last name' which is the replacement for 'name'
print(customer['name'])

# Worked with the old version, will warn that in future release
# 'cleartext password' will no longer be available
print(customer['cleartext password'])
```

Several things are done here:

- To ensure nothing breaks, access to the new dict with the old key still works

- For key replacements, old keys are simply mapped to the new object (no duplication is created)

- For key removals, old keys will raise a warning but are still in the dict

- To ensure developers are made aware of the deprecation a `DeprecationWarning` is
raised which automatically tells which old key to replace with what, or which
key is no longer available.

## Customisation and configuration

To give more specialised warning messages or to indicate since when this function is deprecated, etc. please
have a look at the documentation website which explains all available options:

[Documentation](https://dkey.readthedocs.io/)

## Limitations

- No deprecation warnings can be generated to indicate that the number of entries of the dict has change.
- No automatic docstring changes are possible at the moment