python-benedict 0.9.0

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

python-benedict

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

Index

• Features
• Requirements
• Installation
• Usage
  • Basics
  • Keypath
    • List keypaths
    • Custom keypath separator
    • Disable keypath functionality
• API
  • I/O
    • from_json
    • from_toml
    • from_xml
    • from_yaml
    • to_json
    • to_toml
    • to_xml
    • to_yaml
  • Parse
    • get_bool
    • get_bool_list
    • get_datetime
    • get_datetime_list
    • get_decimal
    • get_decimal_list
    • get_dict
    • get_email
    • get_float
    • get_float_list
    • get_int
    • get_int_list
    • get_list
    • get_list_item
    • get_phonenumber
    • get_slug
    • get_slug_list
    • get_str
    • get_str_list
  • Utility
    • clean
    • clone
    • dump
    • filter
    • flatten
    • merge
    • remove
    • subset
• Testing
• License

Features

• Full keypath support (using the dot syntax by default)
• Easy I/O operations with most common formats: json, toml, xml, yaml
• 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)
• 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

Usage

Basics

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

from benedict import benedict

# create a new instance
d = benedict()

# or cast an existing dict
d = benedict(existing_dict)

# or in a Django view
params = benedict(request.GET.items())
page = params.get_int('p', 0)

Keypath

. is the default keypath separator.

If you cast an existing dict and its keys contain the keypath separator a ValueError will be raised.

In this case you should use a custom keypath separator or disable keypath support.

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']

List keypaths

You can list all the keypaths available in the dict:

# return a list of all keypaths in the dict.
k = d.keypaths()
print(k)

Custom keypath separator

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

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

Disable keypath functionality

You can disable the keypath functionality passing keypath_separator=None in the constructor.

d = benedict(existing_dict, keypath_separator=None)

API

I/O

These methods simplify I/O operations with most common formats: json, toml, xml, yaml

• from_json

# Try to load/decode a json encoded data and return it as dict instance.
# Accept as first argument: url, filepath or string.
# A ValueError is raised in case of failure.
benedict.from_json(s)

• from_toml

# Try to load/decode a toml encoded data and return it as dict instance.
# Accept as first argument: url, filepath or string.
# A ValueError is raised in case of failure.
benedict.from_toml(s)

• from_xml

# Try to load/decode a xml encoded data and return it as dict instance.
# Accept as first argument: url, filepath or string.
# A ValueError is raised in case of failure.
benedict.from_xml(s)

• from_yaml

# Try to load/decode a yaml encoded data and return it as dict instance.
# Accept as first argument: url, filepath or string.
# A ValueError is raised in case of failure.
benedict.from_yaml(s)

• to_json

# Return the dict instance encoded in json format and optionally save it at the specified filepath.
# It's possible to pass custom options to the encoder using kwargs, eg. sort_keys=True.
# A ValueError is raised in case of failure.
s = d.to_json(filepath='', **kwargs)

• to_toml

# Return the dict instance encoded in toml format and optionally save it at the specified filepath.
# It's possible to pass custom options to the encoder using kwargs.
# A ValueError is raised in case of failure.
s = d.to_toml(filepath='', **kwargs)

• to_xml

# Return the dict instance encoded in xml format and optionally save it at the specified filepath.
# It's possible to pass custom options to the encoder using kwargs.
# A ValueError is raised in case of failure.
s = d.to_xml(filepath='', **kwargs)

• to_yaml

# Return the dict instance encoded in yaml format and optionally save it at the specified filepath.
# It's possible to pass custom options to the encoder using kwargs.
# A ValueError is raised in case of failure.
s = d.to_yaml(filepath='', **kwargs)

Parse

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=',')

Utility

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)

• clone

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

• dump

# Return a readable representation of any dict/list.
# This method can be used both as static method or instance method.
s = benedict.dump(d.keypaths())
print(s)
# or
d = benedict()
print(d.dump())

• 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)

• flatten

# Return a flatten dict using the given separator to concat nested dict keys.
d.flatten(separator='_')

• merge

# Merge one or more dictionary objects into current instance (deepupdate).
# Sub-dictionaries keys will be merged toghether.
d.merge(a, b, c)

• remove

# Remove multiple keys from the dict.
d.remove(['firstname', 'lastname', 'email'])

• subset

# Return a dict subset for the given keys.
d.subset(['firstname', 'lastname', 'email'])

Testing

• Run tox / python setup.py test

License

Released under MIT License.