| Name | collectiondict JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | Helpers to create dictionaries that collect values into collections |
| upload_time | 2025-02-16 14:36:12 |
| maintainer | None |
| docs_url | None |
| author | Max Görner |
| requires_python | >=3.9 |
| license | BSD-3-Clause |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# collectiondict - Create multidicts more easily
This package simplifies the creation of multimappings from various sources. It
provides the functions `collectiondict`, `reverse_mapping` and
`reverse_multimapping`. In all three cases the return value will be of type
`dict[_ValueT, Collection[_KeyT]]`.
All three functions expect the target collection to be provided as an argument.
The supported collections are fixed. Only the built-in collections `Counter`,
`frozenset`, `list`, `set`, and `tuple` as well as their subclasses are
supported. If a unsupported collection is passed, an exception is raised.
However, `mypy` will warn about it.
Due to the limits of Pythons type annotations, it is not possible to specify
the correct return type for the custom classes. Thus, custom classes are
supported but the return type is inferred to be the parent class (e.g. `set`),
as opposed to be the class passed in (e.g. `class MySet(set)`).
In order to have the best type inference, it is recommended to **cast** `clct_t`
to specify the value type. Passing a specialised collection class is **not**
supported currently. The examples show how to use a cast.
## collectiondict
Given any stream of key-value tuples, this function creates a multi-dictionary
which maps all values to the corresponding key. Thus, `collectiondict(clct,
stream)` is similar to `dict(stream)` but does not discard values. It is
conceptually similar to [multidict](https://pypi.org/project/multidict/) but
much broader with respect to the supported types.
The implementation tries to be memory efficient and performant. It is possible
to use it on extremely large streams, as long as the end result fits in memory.
Thus, if a list of the stream consumes more than half of the available memory,
`collectiondict` can still be used. For deduplicating collections, e.g. `set`,
the stream could exceed available memory, as long as the key-value pairs do
not. One of the examples covers this scenario.
Simple usage using `set`:
>>> from collectiondict import collectiondict
>>> collectiondict(set, [("a", 1), ("b", 2), ("a", 3)])
{'a': {1, 3}, 'b': {2}}
Usage using `frozenset` and a cast to have the best type inference:
>>> import typing as t
>>> from collectiondict import collectiondict
>>> clct = t.cast(t.Type[frozenset[int]], frozenset)
>>> collectiondict(clct, [("a", 1), ("b", 2), ("a", 3)])
{'a': frozenset({1, 3}), 'b': frozenset({2})}
Scenario that might exceed memory:
>>> from collectiondict import collectiondict
>>> N=1000 # could be humongous, e.g. 10**20
>>> collectiondict(set, ((str(n%2), n%3) for n in range(N)))
{'0': {0, 1, 2}, '1': {0, 1, 2}}
## reverse_mapping
Given a mapping, e.g. a dictionary, from keys to values, this function reverses
the mapping so it maps from values to keys. The keys are collected in a
collection specified by passing a constructor as argument.
Simple usage using `set`:
>>> from collectiondict import reverse_mapping
>>> reverse_mapping(set, {1: "foobar", 2: "blablubb", 3: "foobar"})
{'foobar': {1, 3}, 'blablubb': {2}}
Usage using `frozenset` and a cast to have the best type inference:
>>> import typing as t
>>> from collectiondict import reverse_mapping
>>> clct = t.cast(t.Type[frozenset[int]], frozenset)
>>> reverse_mapping(clct, {1: "foobar", 2: "blablubb", 3: "foobar"})
{'foobar': frozenset({1, 3}), 'blablubb': frozenset({2})}
## reverse_multimapping
Given a mapping, e.g. a dictionary, from keys to an iterable of values, this
function reverses the mapping so it maps from values to keys. The keys are
collected in a collection specified by passing a constructor as argument.
Simple usage using `set`:
>>> from collectiondict import reverse_multimapping
>>> reverse_multimapping(set, {1: "abc", 2: "bcd", 3: "a"})
{'a': {1, 3}, 'b': {1, 2}, 'c': {1, 2}, 'd': {2}}
Usage using `frozenset` and a cast to have the best type inference:
>>> import typing as t
>>> from collectiondict import reverse_multimapping
>>> clct = t.cast(t.Type[frozenset[int]], frozenset)
>>> reverse_multimapping(clct, {1: [13, 37], 2: [13, 42], 3: [42]})
{13: frozenset({1, 2}), 37: frozenset({1}), 42: frozenset({2, 3})}
Since `reverse_multimapping` is its own inverse, there is also a nice roundtrip
behaviour:
>>> import typing as t
>>> from collectiondict import reverse_multimapping
>>> start = {1: {13, 37}, 2: {13, 42}, 3: {42}}
>>> reversed_ = reverse_multimapping(set, start)
>>> roundtripped = reverse_multimapping(set, reversed_)
>>> start == roundtripped
True
Raw data
{
"_id": null,
"home_page": null,
"name": "collectiondict",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Max G\u00f6rner",
"author_email": "5477952+MaxG87@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/0f/28/bb1af58428b9908e7242c774381e7c398129b288485ed2359ab4ec0b8bcf/collectiondict-1.0.0.tar.gz",
"platform": null,
"description": "# collectiondict - Create multidicts more easily\n\nThis package simplifies the creation of multimappings from various sources. It\nprovides the functions `collectiondict`, `reverse_mapping` and\n`reverse_multimapping`. In all three cases the return value will be of type\n`dict[_ValueT, Collection[_KeyT]]`.\n\nAll three functions expect the target collection to be provided as an argument.\nThe supported collections are fixed. Only the built-in collections `Counter`,\n`frozenset`, `list`, `set`, and `tuple` as well as their subclasses are\nsupported. If a unsupported collection is passed, an exception is raised.\nHowever, `mypy` will warn about it.\n\nDue to the limits of Pythons type annotations, it is not possible to specify\nthe correct return type for the custom classes. Thus, custom classes are\nsupported but the return type is inferred to be the parent class (e.g. `set`),\nas opposed to be the class passed in (e.g. `class MySet(set)`).\n\nIn order to have the best type inference, it is recommended to **cast** `clct_t`\nto specify the value type. Passing a specialised collection class is **not**\nsupported currently. The examples show how to use a cast.\n\n\n## collectiondict\n\nGiven any stream of key-value tuples, this function creates a multi-dictionary\nwhich maps all values to the corresponding key. Thus, `collectiondict(clct,\nstream)` is similar to `dict(stream)` but does not discard values. It is\nconceptually similar to [multidict](https://pypi.org/project/multidict/) but\nmuch broader with respect to the supported types.\n\nThe implementation tries to be memory efficient and performant. It is possible\nto use it on extremely large streams, as long as the end result fits in memory.\nThus, if a list of the stream consumes more than half of the available memory,\n`collectiondict` can still be used. For deduplicating collections, e.g. `set`,\nthe stream could exceed available memory, as long as the key-value pairs do\nnot. One of the examples covers this scenario.\n\nSimple usage using `set`:\n\n >>> from collectiondict import collectiondict\n >>> collectiondict(set, [(\"a\", 1), (\"b\", 2), (\"a\", 3)])\n {'a': {1, 3}, 'b': {2}}\n\nUsage using `frozenset` and a cast to have the best type inference:\n\n >>> import typing as t\n >>> from collectiondict import collectiondict\n >>> clct = t.cast(t.Type[frozenset[int]], frozenset)\n >>> collectiondict(clct, [(\"a\", 1), (\"b\", 2), (\"a\", 3)])\n {'a': frozenset({1, 3}), 'b': frozenset({2})}\n\nScenario that might exceed memory:\n\n >>> from collectiondict import collectiondict\n >>> N=1000 # could be humongous, e.g. 10**20\n >>> collectiondict(set, ((str(n%2), n%3) for n in range(N)))\n {'0': {0, 1, 2}, '1': {0, 1, 2}}\n\n\n## reverse_mapping\n\nGiven a mapping, e.g. a dictionary, from keys to values, this function reverses\nthe mapping so it maps from values to keys. The keys are collected in a\ncollection specified by passing a constructor as argument.\n\nSimple usage using `set`:\n\n >>> from collectiondict import reverse_mapping\n >>> reverse_mapping(set, {1: \"foobar\", 2: \"blablubb\", 3: \"foobar\"})\n {'foobar': {1, 3}, 'blablubb': {2}}\n\nUsage using `frozenset` and a cast to have the best type inference:\n\n >>> import typing as t\n >>> from collectiondict import reverse_mapping\n >>> clct = t.cast(t.Type[frozenset[int]], frozenset)\n >>> reverse_mapping(clct, {1: \"foobar\", 2: \"blablubb\", 3: \"foobar\"})\n {'foobar': frozenset({1, 3}), 'blablubb': frozenset({2})}\n\n\n## reverse_multimapping\n\nGiven a mapping, e.g. a dictionary, from keys to an iterable of values, this\nfunction reverses the mapping so it maps from values to keys. The keys are\ncollected in a collection specified by passing a constructor as argument.\n\nSimple usage using `set`:\n\n >>> from collectiondict import reverse_multimapping\n >>> reverse_multimapping(set, {1: \"abc\", 2: \"bcd\", 3: \"a\"})\n {'a': {1, 3}, 'b': {1, 2}, 'c': {1, 2}, 'd': {2}}\n\nUsage using `frozenset` and a cast to have the best type inference:\n\n >>> import typing as t\n >>> from collectiondict import reverse_multimapping\n >>> clct = t.cast(t.Type[frozenset[int]], frozenset)\n >>> reverse_multimapping(clct, {1: [13, 37], 2: [13, 42], 3: [42]})\n {13: frozenset({1, 2}), 37: frozenset({1}), 42: frozenset({2, 3})}\n\nSince `reverse_multimapping` is its own inverse, there is also a nice roundtrip\nbehaviour:\n\n >>> import typing as t\n >>> from collectiondict import reverse_multimapping\n >>> start = {1: {13, 37}, 2: {13, 42}, 3: {42}}\n >>> reversed_ = reverse_multimapping(set, start)\n >>> roundtripped = reverse_multimapping(set, reversed_)\n >>> start == roundtripped\n True\n\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Helpers to create dictionaries that collect values into collections",
"version": "1.0.0",
"project_urls": {
"Changelog": "https://github.com/MaxG87/collectiondict/blob/main/CHANGELOG.md",
"Homepage": "https://github.com/MaxG87/collectiondict/",
"Issues": "https://github.com/MaxG87/collectiondict/issues",
"Repository": "https://github.com/MaxG87/collectiondict/"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c06d97f23557126b25131f307f90060808d24887e070b6583a1ca651a74c92a6",
"md5": "76fcb2b1fa3835f6573b0afc5ae96021",
"sha256": "f8247ff1dc956e2c3cc43c77beefdeaa49eab6a1d5f3d4d5c9ba0b0f8819faca"
},
"downloads": -1,
"filename": "collectiondict-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "76fcb2b1fa3835f6573b0afc5ae96021",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 7671,
"upload_time": "2025-02-16T14:36:11",
"upload_time_iso_8601": "2025-02-16T14:36:11.290727Z",
"url": "https://files.pythonhosted.org/packages/c0/6d/97f23557126b25131f307f90060808d24887e070b6583a1ca651a74c92a6/collectiondict-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0f28bb1af58428b9908e7242c774381e7c398129b288485ed2359ab4ec0b8bcf",
"md5": "fc65048da7659b7669e08ca0f5fcf50b",
"sha256": "d3ea755377910d5ee555a30a6d3c1e847a4533f564fef7d06d5e5920f0988941"
},
"downloads": -1,
"filename": "collectiondict-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "fc65048da7659b7669e08ca0f5fcf50b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 5154,
"upload_time": "2025-02-16T14:36:12",
"upload_time_iso_8601": "2025-02-16T14:36:12.591479Z",
"url": "https://files.pythonhosted.org/packages/0f/28/bb1af58428b9908e7242c774381e7c398129b288485ed2359ab4ec0b8bcf/collectiondict-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-16 14:36:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MaxG87",
"github_project": "collectiondict",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "collectiondict"
}
