file: README.md
Project description
Python Super Collections
Dictionaries as you dreamed them when you were a kid.
Instantly Convert json and YAML files into objects with attributes.
import json
from super_collections import SuperDict
with open('my_file.json', 'r') as file:
data = json.load(file)
document = SuperDict(data)
print(document.author) # instead of document['author']
for document in document.blocks: # instead of document['blocks']
...
print(document.blocks[3].name) # instead of document['blocks'][3]['name'] -- eek! 🤢
How it works
There are several packages that quickly convert json or YAML files into dictionaries that contain dictionaries, lists etc.
If you want to properly use those data structures in Python, one solution is to create specific classes.
But sometimes, it is overkill. You just want your app to quickly load structured data and navigate through them.
That's where the super-collections package (SuperDict a SuperList) comes handy.
Superdicts
📝 Definition
A superdictionnary is a dictionary whose keys (at least those that are valid identifiers) are automatically accessible as attributes, with the *dot notation.
d = SuperDict({'foo':5, 'bar': 'hello'})
# instead of writing d['foo']
d.foo = 7
Several other languages, such as Javascript, LUA, Ruby, and PHP offer that dot notation in some form or other. However, implementing that idea is not as straightforward as it seems. The idea of superdictionaries in Python has been around for some time (see the superdict packagage by Yuri Shevchuk, 2015).
📝 Property
If a SuperDict object contains a value that is itself a dictionary, that dictionary is then converted in turn into a SuperDict.
Superlists
A superlist is a list where all dictionary items have been (automagically) converted to superdictionnaries.
⚠️ Superlists are indispensable
They were the missing piece of the jigsaw puzzle; without them, it is not possible to convert deep data structures into supercollections.
Why Combining SuperDicts with SuperLists?
The structure of JSON, YAML or HTML data is generally a deeply nested combination of dictionaries and lists. Using superdictionaries alone would not be sufficient, since lists within the data contained in a list would still contain regular (unconverted) dictionaries; this would require you to switch back to the standard dictionary access method.
By combining superdictionaries and superlists, it is possible to ensure that all nested dictionaries within lists will also be converted to SuperDicts, allowing for a consistent dot notation throughout the entire data structure.
💡 Deep conversion
SuperLists objects, combined with SuperDicts make sure that the most complex datastructures (from json or YAML) can be recursively converted into well-behaved Python objects.
Install
From the repository
pip install super-collections
Usage
from super_collections import SuperDict, SuperList
d = SuperDict({'foo':5, 'bar': 'hello'})
l = SuperList([5, 7, 'foo', {'foo': 5}])
You can cast any dictionary and list into its "Super" equivalent when you want, and you are off to the races.
The casting is recursive i.e. in the case above, you can assert:
l[-1].foo == 5
All methods of dict and list are available.
Those objects are self documented. d.properties()
is a generator
that lists all keys that are available as attributes.
The __dir__()
method (accessible with dir()
) is properly updated with
those additional properties.
list(d.properties())
> ['foo', 'bar']
dir(d)
> ['__class__', ..., 'bar', 'clear', 'copy', 'foo', 'fromkeys', 'get', 'items', 'keys', 'pop', 'popitem', 'properties', 'setdefault', 'to_hjson', 'to_json', 'update', 'values']
This means the auto-complete feature might be available for the attributes of a SuperDict within a code editor (if the dictionary was statically declared in the code); or in an advanced REPL (such as bpython).
The methods dict.update(other_dict)
and list.extend(other_list)
automatically cast the contents into SuperDict and SuperList as needed.
Remarks
Restrictions
- In a SuperDict, only keys that are valid Python identifiers
can be accessed as attributes. If 'bar' is a key of object
foo
, you can writefoo.bar
; but you can't writebecause 'hello world' is not a valid Python identifier; you will have to access that specific value with the "dictionary" notation:foo.hello world
foo['hello world']
. - Similarly, you can't use pre-existing methods of the
dict
class:keys
,items
,update
, etc. as properties; as well as theproperties
method itself (wich is specific to SuperDict). In that case again, use the dictionary notation to access the value (d['items']
, etc.). Those keys that cannot be accessed as attributes are said to be masked. If you are uncertain which are available, just useSuperDict.properties()
. method. - Updating a single element (
d['foo']
for a SuperDict andl[5]
for a SuperList) does not perfom any casting. That's to avoid crazy recursive situations, while giving you fine grain control on what you want to do (just cast withSuperDict()
andSuperList()
).
Does it work?
Yes. It is tested with pytest. See the test
directory for examples.
When are superdictionaries and superlists not recommended?
SuperDicts (and SuperLists) classes are most useful when the program you are writing is consuming loosely structured data (json, YAML, HTML) you have every reason to believe they are sufficiently well-formed: typically data exported from existing APIs or Web sources.
⚠️ Caution
super-collections may not be the best tool when source data come from a source whose quality is unsufficiently guaranteed for your needs, or is untrusted.
If you want to impose strongly formatted data structures in your code, one solution is to create dataclasses; especially those of Pydantic, which make implicit and explicit controls on the integrity of the source data.
Related data structures and ideas
These projects contain ideas that inspired or predated super-collections.
Standard Python
collections.namedtuple
: tuples with dot notation (standard python class)types.SimpleNamespace
: objects with arbitrary attributes (standard python class)- All Python classes have a dict attribute, used at the foundation to implement the dot notation in the language, with the relative standard methods (
__setattr__()
, etc.) and functions (setattr()
, etc.). - In modern Python, the
dict
class has ordered keys (by insertion order) and is subclassable.
Dot notation on dictionaries
- addict (Github)
- DotMap: subclasses and MutableMapping and OrderedDict (Github)
- SuperDict: subclasses
dict
(Github) - dotty_dict: wrapper (Github)
Using superlists to complement superdictionaries
- Packages that write to and read from files, such as shelve (standard), json, YAML, Beautifulsoup, etc. heavily rely on a combination of dictionaries and lists. BeautifulSoup in particular supports dot notation.
- In general, the construction of any syntactic or semantic tree requires both dictionaries and lists.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for super_collections-0.5.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 907d35b25dc4070910e8254bf2f5c928348af1cf8a1f1e8259e06c666e902cff |
|
MD5 | 347b3ea0c052c630a42d3398a7bcf6b3 |
|
BLAKE2b-256 | 076d58de58c521e7fb79bceb4da90d55250070bb4adfa3c870b82519a561c79d |