| Name | super-collections JSON |
| Version |
0.5.3
JSON |
| download |
| home_page | None |
| Summary | file: README.md |
| upload_time | 2024-10-12 05:11:19 |
| maintainer | None |
| docs_url | None |
| author | Laurent Franceschetti |
| requires_python | >=3.8 |
| license | MIT License Copyright (c) 2024 Laurent Franceschetti Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<div align="center">
# Python Super Collections
**Dictionaries as you dreamed them when you were a kid.**
Instantly Convert json and YAML files into objects with attributes.
</div>
```python
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! 🤢
```
________
<!-- To update, run the following command:
markdown-toc -i README.md
-->
<!-- toc -->
- [Python Super Collections](#python-super-collections)
- [How it works](#how-it-works)
- [Superdicts](#superdicts)
- [Superlists](#superlists)
- [Why Combining SuperDicts with SuperLists?](#why-combining-superdicts-with-superlists)
- [Install](#install)
- [From the repository](#from-the-repository)
- [Usage](#usage)
- [Remarks](#remarks)
- [Restrictions](#restrictions)
- [Does it work?](#does-it-work)
- [When are superdictionaries and superlists _not_ recommended?](#when-are-superdictionaries-and-superlists-not-recommended)
- [Related data structures and ideas](#related-data-structures-and-ideas)
- [Standard Python](#standard-python)
- [Dot notation on dictionaries](#dot-notation-on-dictionaries)
- [Using superlists to complement superdictionaries](#using-superlists-to-complement-superdictionaries)
<!-- tocstop -->
## 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** <br> A **superdictionnary** is a dictionary whose keys (at least those that are valid identifiers) are automatically accessible as attributes, with the **dot notation*.
```python
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](https://github.com/itdxer/superdict) packagage by Yuri
> Shevchuk, 2015).
> 📝 **Property** <br> 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** <br> 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** <br> 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
```sh
pip install super-collections
```
## Usage
```python
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:
```python
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.
```python
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](https://bpython-interpreter.org/)).
The methods `dict.update(other_dict)` and `list.extend(other_list)`
automatically cast the contents into SuperDict and SuperList as needed.
## Remarks
### Restrictions
1. 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 write `foo.bar`; but you can't
write ~~`foo.hello world`~~ because 'hello world' is not a
valid Python identifier;
you will have to access that specific value with the "dictionary" notation:
`foo['hello world']`.
2. Similarly, you can't use pre-existing methods of the
`dict` class: `keys`, `items`, `update`, etc. as properties; as well as the
`properties` 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 use `SuperDict.properties()`.
method.
3. Updating a single element (`d['foo']` for a SuperDict and `l[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 with `SuperDict()` and `SuperList()`).
### 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** <br> 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](https://docs.python.org/3/library/dataclasses.html); especially those of [Pydantic](https://docs.pydantic.dev/latest/concepts/dataclasses/), 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](https://docs.python.org/3/library/collections.html#collections.namedtuple))
* `types.SimpleNamespace`: objects with arbitrary attributes ([standard python class](https://docs.python.org/3/library/types.html#types.SimpleNamespace))
* 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](https://github.com/mewwts/addict) (Github)
* [DotMap](https://github.com/drgrib/dotmap): subclasses and MutableMapping and OrderedDict (Github)
* [SuperDict](https://github.com/itdxer/superdict): subclasses `dict` (Github)
* [dotty_dict](https://github.com/pawelzny/dotty_dict): wrapper (Github)
### Using superlists to complement superdictionaries
* Packages that write to and read from files, such as [shelve](https://docs.python.org/3/library/shelve.html) (standard), json, YAML, [Beautifulsoup](https://code.launchpad.net/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**.
Raw data
{
"_id": null,
"home_page": null,
"name": "super-collections",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Laurent Franceschetti",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/b8/05/d1b50919a0d206d77255217d96dea9ab34bd1eb965a21559380c48f9517e/super_collections-0.5.3.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n# Python Super Collections\n\n**Dictionaries as you dreamed them when you were a kid.**\n\nInstantly Convert json and YAML files into objects with attributes.\n</div>\n\n```python\nimport json\nfrom super_collections import SuperDict\nwith open('my_file.json', 'r') as file:\n data = json.load(file)\ndocument = SuperDict(data)\n\nprint(document.author) # instead of document['author'] \nfor document in document.blocks: # instead of document['blocks']\n ...\nprint(document.blocks[3].name) # instead of document['blocks'][3]['name'] -- eek! \ud83e\udd22\n\n```\n________\n\n<!-- To update, run the following command:\nmarkdown-toc -i README.md \n-->\n\n<!-- toc -->\n\n- [Python Super Collections](#python-super-collections)\n - [How it works](#how-it-works)\n - [Superdicts](#superdicts)\n - [Superlists](#superlists)\n - [Why Combining SuperDicts with SuperLists?](#why-combining-superdicts-with-superlists)\n - [Install](#install)\n - [From the repository](#from-the-repository)\n - [Usage](#usage)\n - [Remarks](#remarks)\n - [Restrictions](#restrictions)\n - [Does it work?](#does-it-work)\n - [When are superdictionaries and superlists _not_ recommended?](#when-are-superdictionaries-and-superlists-not-recommended)\n - [Related data structures and ideas](#related-data-structures-and-ideas)\n - [Standard Python](#standard-python)\n - [Dot notation on dictionaries](#dot-notation-on-dictionaries)\n - [Using superlists to complement superdictionaries](#using-superlists-to-complement-superdictionaries)\n\n<!-- tocstop -->\n\n## How it works\n\nThere are several packages that quickly convert json or YAML files into \ndictionaries that contain dictionaries, lists etc.\n\nIf you want to properly use those data structures in Python, one solution is \nto create specific classes.\n\nBut sometimes, it is overkill. You just want your app to quickly load\nstructured data and navigate through them.\n\nThat's where the **super-collections** package (**SuperDict** a **SuperList**) comes handy.\n\n### Superdicts\n\n\n> \ud83d\udcdd **Definition** <br> A **superdictionnary** is a dictionary whose keys (at least those that are valid identifiers) are automatically accessible as attributes, with the **dot notation*.\n\n```python\nd = SuperDict({'foo':5, 'bar': 'hello'})\n\n# instead of writing d['foo']\nd.foo = 7\n```\n\n> Several other languages, such as Javascript, LUA, Ruby, and PHP offer that **dot notation**\n> in some form or other. However, implementing that idea is not as\n> straightforward as it seems.\n> The idea of superdictionaries in Python has been around for some time\n> (see the [superdict](https://github.com/itdxer/superdict) packagage by Yuri \n> Shevchuk, 2015).\n\n\n\n> \ud83d\udcdd **Property** <br> If a SuperDict object contains a value that is itself a dictionary, that dictionary is then converted in turn into a SuperDict.\n\n### Superlists\nA **superlist** is a list where all dictionary items have been\n(automagically) converted to **superdictionnaries**.\n\n> \u26a0\ufe0f **Superlists are indispensable** <br> They were the missing piece of the jigsaw puzzle;\n> without them, it is not possible to convert deep data structures into supercollections. \n\n### Why Combining SuperDicts with SuperLists?\n\nThe 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. \n\nBy combining superdictionaries and superlists, \nit 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.\n\n> \ud83d\udca1 **Deep conversion** <br> SuperLists objects, combined with SuperDicts make sure that the most complex\n> datastructures (from json or YAML) can be recursively converted into \n> well-behaved Python objects.\n\n\n\n\n## Install\n\n\n### From the repository\n\n```sh\npip install super-collections\n```\n\n## Usage\n\n```python\nfrom super_collections import SuperDict, SuperList\n\nd = SuperDict({'foo':5, 'bar': 'hello'})\nl = SuperList([5, 7, 'foo', {'foo': 5}])\n```\n\nYou can cast any dictionary and list into its \"Super\" equivalent when you want, and you are off to the races. \n\n**The casting is recursive** i.e. in the case above, you can assert:\n\n```python\nl[-1].foo == 5\n```\n\nAll methods of dict and list are available.\n\n\nThose objects are self documented. `d.properties()` is a generator\nthat lists all keys that are available as attributes.\n\nThe `__dir__()` method (accessible with `dir()`) is properly updated with\nthose additional properties.\n\n```python\nlist(d.properties())\n> ['foo', 'bar']\ndir(d)\n> ['__class__', ..., 'bar', 'clear', 'copy', 'foo', 'fromkeys', 'get', 'items', 'keys', 'pop', 'popitem', 'properties', 'setdefault', 'to_hjson', 'to_json', 'update', 'values']\n```\n\nThis means the **auto-complete feature** might be available\nfor the attributes of a SuperDict within a code editor (if the dictionary was\nstatically declared in the code); or in an advanced REPL\n(such as [bpython](https://bpython-interpreter.org/)).\n\nThe methods `dict.update(other_dict)` and `list.extend(other_list)` \nautomatically cast the contents into SuperDict and SuperList as needed.\n\n## Remarks\n\n### Restrictions\n\n1. In a SuperDict, **only keys that are valid Python identifiers\n can be accessed as attributes**. If 'bar' is a key of object `foo`,\n you can write `foo.bar`; but you can't\n write ~~`foo.hello world`~~ because 'hello world' is not a \n valid Python identifier; \n you will have to access that specific value with the \"dictionary\" notation: \n `foo['hello world']`.\n2. Similarly, you can't use pre-existing methods of the\n `dict` class: `keys`, `items`, `update`, etc. as properties; as well as the\n `properties` method itself (wich is specific to SuperDict).\n In that case again, use the dictionary notation to access\n the value (`d['items']`, etc.). Those keys that\n cannot be accessed as attributes are said to be **masked**.\n If you are uncertain which are available, just use `SuperDict.properties()`.\n method.\n3. Updating a single element (`d['foo']` for a SuperDict and `l[5]`\n for a SuperList) does not perfom any casting. That's to avoid crazy\n recursive situations, while giving\n you fine grain control on what you want to do \n (just cast with `SuperDict()` and `SuperList()`).\n\n\n### Does it work?\n\nYes. It is tested with pytest. See the `test` directory for examples.\n\n### When are superdictionaries and superlists _not_ recommended?\n\nSuperDicts (and SuperLists) classes are most useful when the program you are\nwriting is consuming loosely structured data (json, YAML, HTML)\nyou have every reason to believe they\nare sufficiently well-formed: typically data exported from existing APIs\nor Web sources.\n\n> \u26a0\ufe0f **Caution** <br> super-collections may not be the best \n> tool when source data come from a source whose quality\n> is unsufficiently guaranteed for your needs, or is untrusted.\n\nIf you want to impose strongly formatted data structures in your code, one solution is \nto create [dataclasses](https://docs.python.org/3/library/dataclasses.html); especially those of [Pydantic](https://docs.pydantic.dev/latest/concepts/dataclasses/), which make implicit and explicit\ncontrols on the integrity of the source data.\n\n## Related data structures and ideas\n\nThese projects contain ideas that inspired or predated super-collections.\n\n### Standard Python\n\n* `collections.namedtuple`: tuples with dot notation ([standard python class](https://docs.python.org/3/library/collections.html#collections.namedtuple))\n* `types.SimpleNamespace`: objects with arbitrary attributes ([standard python class](https://docs.python.org/3/library/types.html#types.SimpleNamespace))\n* 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.).\n* In modern Python, the `dict` class has ordered keys (by insertion order) and is subclassable.\n\n### Dot notation on dictionaries\n\n* [addict](https://github.com/mewwts/addict) (Github)\n* [DotMap](https://github.com/drgrib/dotmap): subclasses and MutableMapping and OrderedDict (Github)\n* [SuperDict](https://github.com/itdxer/superdict): subclasses `dict` (Github)\n* [dotty_dict](https://github.com/pawelzny/dotty_dict): wrapper (Github)\n\n### Using superlists to complement superdictionaries\n\n* Packages that write to and read from files, such as [shelve](https://docs.python.org/3/library/shelve.html) (standard), json, YAML, [Beautifulsoup](https://code.launchpad.net/beautifulsoup/), etc. heavily rely\n on a **combination of dictionaries and lists**. BeautifulSoup in particular supports dot notation.\n* In general, **the construction of any syntactic or semantic tree requires both dictionaries and lists**.\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 Laurent Franceschetti Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "file: README.md",
"version": "0.5.3",
"project_urls": {
"Source": "https://github.com/fralau/super-collections"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "076d58de58c521e7fb79bceb4da90d55250070bb4adfa3c870b82519a561c79d",
"md5": "347b3ea0c052c630a42d3398a7bcf6b3",
"sha256": "907d35b25dc4070910e8254bf2f5c928348af1cf8a1f1e8259e06c666e902cff"
},
"downloads": -1,
"filename": "super_collections-0.5.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "347b3ea0c052c630a42d3398a7bcf6b3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8436,
"upload_time": "2024-10-12T05:11:18",
"upload_time_iso_8601": "2024-10-12T05:11:18.626613Z",
"url": "https://files.pythonhosted.org/packages/07/6d/58de58c521e7fb79bceb4da90d55250070bb4adfa3c870b82519a561c79d/super_collections-0.5.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b805d1b50919a0d206d77255217d96dea9ab34bd1eb965a21559380c48f9517e",
"md5": "e2880303c703ceebd11ea4ba6051b31b",
"sha256": "94c1ec96c0a0d5e8e7d389ed8cde6882ac246940507c5e6b86e91945c2968d46"
},
"downloads": -1,
"filename": "super_collections-0.5.3.tar.gz",
"has_sig": false,
"md5_digest": "e2880303c703ceebd11ea4ba6051b31b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 10178,
"upload_time": "2024-10-12T05:11:19",
"upload_time_iso_8601": "2024-10-12T05:11:19.888715Z",
"url": "https://files.pythonhosted.org/packages/b8/05/d1b50919a0d206d77255217d96dea9ab34bd1eb965a21559380c48f9517e/super_collections-0.5.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-12 05:11:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fralau",
"github_project": "super-collections",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "super-collections"
}
