python-benedict

The Python dictionary for humans dealing with evil/complex data.

Features

Full keypath support (using the dot syntax by default)
Many utility and parse methods to retrieve data as needed (all methods listed below)
Give benediction :) to dict values before they are returned (they receive benedict casting)
Easy I/O operations with most common formats: base64, json, query-string, toml, yaml, xml
100% backward-compatible (you can replace existing dicts without pain)

Requirements

Python 2.7, 3.4, 3.5, 3.6, 3.7

Installation

Run pip install python-benedict

Testing

Run tox / python setup.py test

Usage

benedict is a dict subclass, so it is possible to use it as a normal dictionary (you can just cast an existing dict).

Import

from benedict import benedict

Init

Create a new instance:

d = benedict()

... or cast an existing dict:

d = benedict(existing_dict)

If the existing dict keys contain the keypath separator a ValueError will be raised.

In this case you should need to use a custom keypath separator.

Keypath

. is the default keypath separator.

d = benedict()

# set values by keypath
d['profile.firstname'] = 'Fabio'
d['profile.lastname'] = 'Caccamo'
print(d) # -> { 'profile':{ 'firstname':'Fabio', 'lastname':'Caccamo' } }
print(d['profile']) # -> { 'firstname':'Fabio', 'lastname':'Caccamo' }

# check if keypath exists in dict
print('profile.lastname' in d) # -> True

# delete value by keypath
del d['profile.lastname']

Custom keypath separator

You can customize the keypath separator passing the keypath_separator argument in the constructor.

d = benedict(existing_dict, keypath_separator='/')

API

Keypath methods

keypaths

# Return a list of all keypaths in the dict.
d.keypaths()

Utility methods

These methods are common utilities that will speed up your everyday work.

clean

# Clean the current dict removing all empty values: None, '', {}, [], ().
# If strings, dicts or lists flags are False, related empty values will not be deleted.
d.clean(strings=True, dicts=True, lists=True)

deepcopy

# Return a deepcopy of the dict.
d.deepcopy()

dump

# Return a readable representation of any dict/list.
s = benedict.dump(d.keypaths())
print(s)

dump_items

# Return a readable representation of the dict for the given key (optional).
s = d.dump_items(key=None)
print(s)

filter

# Return a filtered dict using the given predicate function.
# Predicate function receives key, value arguments and should return a bool value.
predicate = lambda k, v: v is not None
d.filter(predicate)

Parse methods

These methods are wrappers of the get method, they parse data trying to return it in the expected type.

get_bool

# Get value by key or keypath trying to return it as bool.
# Values like `1`, `true`, `yes`, `on`, `ok` will be returned as `True`.
d.get_bool(key, default=False)

get_bool_list

# Get value by key or keypath trying to return it as list of bool values.
# If separator is specified and value is a string it will be splitted.
d.get_bool_list(key, default=[], separator=',')

get_datetime

# Get value by key or keypath trying to return it as datetime.
# If format is not specified it will be autodetected.
# If options and value is in options return value otherwise default.
d.get_datetime(key, default=None, format=None, options=[])

get_datetime_list

# Get value by key or keypath trying to return it as list of datetime values.
# If separator is specified and value is a string it will be splitted.
d.get_datetime_list(key, default=[], format=None, separator=',')

get_decimal

# Get value by key or keypath trying to return it as Decimal.
# If options and value is in options return value otherwise default.
d.get_decimal(key, default=Decimal('0.0'), options=[])

get_decimal_list

# Get value by key or keypath trying to return it as list of Decimal values.
# If separator is specified and value is a string it will be splitted.
d.get_decimal_list(key, default=[], separator=',')

get_dict

# Get value by key or keypath trying to return it as dict.
# If value is a json string it will be automatically decoded.
d.get_dict(key, default={})

get_email

# Get email by key or keypath and return it.
# If value is blacklisted it will be automatically ignored.
# If check_blacklist is False, it will be not ignored even if blacklisted.
d.get_email(key, default='', options=None, check_blacklist=True)

get_float

# Get value by key or keypath trying to return it as float.
# If options and value is in options return value otherwise default.
d.get_float(key, default=0.0, options=[])

get_float_list

# Get value by key or keypath trying to return it as list of float values.
# If separator is specified and value is a string it will be splitted.
d.get_float_list(key, default=[], separator=',')

get_int

# Get value by key or keypath trying to return it as int.
# If options and value is in options return value otherwise default.
d.get_int(key, default=0, options=[])

get_int_list

# Get value by key or keypath trying to return it as list of int values.
# If separator is specified and value is a string it will be splitted.
d.get_int_list(key, default=[], separator=',')

get_list

# Get value by key or keypath trying to return it as list.
# If separator is specified and value is a string it will be splitted.
d.get_list(key, default=[], separator=',')

get_list_item

# Get list by key or keypath and return value at the specified index.
# If separator is specified and list value is a string it will be splitted.
d.get_list_item(key, index=0, default=None, separator=',')

get_phonenumber

# Get phone number by key or keypath and return a dict with different formats (e164, international, national).
# If country code is specified (alpha 2 code), it will be used to parse phone number correctly.
d.get_phonenumber(key, country_code=None, default=None)

get_slug

# Get value by key or keypath trying to return it as slug.
# If options and value is in options return value otherwise default.
d.get_slug(key, default='', options=[])

get_slug_list

# Get value by key or keypath trying to return it as list of slug values.
# If separator is specified and value is a string it will be splitted.
d.get_slug_list(key, default=[], separator=',')

get_str

# Get value by key or keypath trying to return it as string.
# Encoding issues will be automatically fixed.
# If options and value is in options return value otherwise default.
d.get_str(key, default='', options=[])

get_str_list

# Get value by key or keypath trying to return it as list of str values.
# If separator is specified and value is a string it will be splitted.
d.get_str_list(key, default=[], separator=',')

License

Released under MIT License.

Metadata

Release files for python-benedict 0.5.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for python-benedict 0.5.1
File	Size	Uploaded
python-benedict-0.5.1.tar.gz	10.8 kB	Jul 10, 2019	Details

Built distribution (wheel)

Table of built distributions (wheels) for python-benedict 0.5.1
File	Interpreter	ABI	Platform	Reset
python_benedict-0.5.1-py2-none-any.whl 13.1 kB Jul 10, 2019	Python 2	none	any	Details

Total release size: 24.0 kB

Release files / python-benedict-0.5.1.tar.gz

Download URL	python-benedict-0.5.1.tar.gz
Size	10.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`9bd5fade9cbd9b79b8bdafc353a8e37796567a67cbdb9b563f6027a3a5c22ec7`
BLAKE2b-256 checksum How to use checksums	`2bec24949fad4fa1f389b2f7152362d6c678cc270926cd19780958adf713ec7d`
Upload date	Jul 10, 2019
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/1.13.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.0.1 requests-toolbelt/0.9.1 tqdm/4.32.1 CPython/3.6.3`

Release files / python_benedict-0.5.1-py2-none-any.whl

Download URL	python_benedict-0.5.1-py2-none-any.whl
Size	13.1 kB
Tags	Python 2
SHA-256 checksum How to use checksums	`37261d93f2dd15de8d1c36b46c0b95d7d751b9ac3baaf4af3a0d732b1d9cb73c`
BLAKE2b-256 checksum How to use checksums	`7b603c4fb912773f6eb90d7a6e6ef7e9db5b07eee671783a6c3ed0f41cdc566c`
Upload date	Jul 10, 2019
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/1.13.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.0.1 requests-toolbelt/0.9.1 tqdm/4.32.1 CPython/3.6.3`