# richset
[](https://badge.fury.io/py/richset)
[](https://pypi.python.org/pypi/richset/)
[](https://codecov.io/gh/kitsuyui/python-richset)
[](https://opensource.org/licenses/BSD-3-Clause)
richset interporlates with set, dict, and list.
## Motivations and Concepts
- richset provides useful functions for common use cases of set, dict, and list.
- builtin set, dict and list requires many boilerplate codes.
- Pure Python package.
- Fully typing supported.
- No magic. No meta-programming.
## Install
```sh
$ pip install richset
```
## Usage
```python
from dataclasses import dataclass
from richset import RichSet
@dataclass(frozen=True)
class Something:
id: int
name: str
richset = RichSet.from_list([
Something(1, 'one'),
Something(2, 'two'),
Something(3, 'three'),
])
```
### Conversions
```python
richset.to_list() # => [Something(1, 'one'), Something(2, 'one'), Something(3, 'three')]
richset.to_tuple() # => (Something(1, 'one'), Something(2, 'two'), Something(3, 'three'))
richset.to_set() # => {Something(1, 'one'), Something(2, 'two'), Something(3, 'three')}
richset.to_frozenset() # => frozenset({Something(1, 'one'), Something(2, 'two'), Something(3, 'three')})
richset.to_dict(lambda s: s.id) # => {1: Something(1, 'one'), 2: Something(2, 'two'), 3: Something(3, 'three')}
```
`to_dict()` takes second argument `duplicated` which is a choice of `'error'`, `'first'` or `'last'`.
- if `duplicated` is `'error'`, then `to_dict()` raises `ValueError` if there is a duplicated key.
- if `duplicated` is `'first'`, then `to_dict()` picks the first one of duplicated key.
- if `duplicated` is `'last'`, then `to_dict()` picks the last one of duplicated key.
`to_dict_of_list()` is similar to `to_dict()` but it returns a dict of list.
```python
richset.to_dict_of_list(lambda s: s.name) # => {'john': [Something(1, 'john'), Something(2, 'john')], 'jane': [Something(3, 'jane')]}
```
### List accessors
```python
richset.first() # => returns first item `Something(1, 'one')` or raise Error (if empty)
richset.get_first() # => returns first item `Something(1, 'one')` or None (if empty)
richset.last() # => returns last item `Something(3, 'three')` or raise Error (if empty)
richset.get_last() # => returns last item `Something(3, 'three')` or None (if empty)
richset.nth(2) # => returns 3rd item `Something(3, 'three')` or raise Error (if empty)
richset.get_nth(2) # => returns 3rd item `Something(3, 'three')` or None (if empty)
richset.one() # => returns one item `Something(1, 'one')` or raise Error (if empty)
richset.get_one() # => returns one item `Something(1, 'one')` or None (if empty)
```
Note: `get_first`, `get_last`, `get_nth` and `get_one` accept `default` argument that returns specified value instead of None.
```python
richset.get_nth(100, default=Something(-1, 'default')) # => Something(-1, 'default')
```
### List basic manipulations
```python
richset.pushed(Something(4, 'four')).to_list() # => [Something(1, 'one'), Something(2, 'two'), Something(3, 'three'), Something(4, 'four')]
richset.unshift(Something(4, 'four')).to_list() # => [Something(4, 'four'), Something(1, 'one'), Something(2, 'two'), Something(3, 'three')]
richset.popped() # => Something(3, 'three'), RichSet([Something(1, 'one'), Something(2, 'two')])
richset.shift() # => Something(1, 'one'), RichSet([Something(2, 'two'), Something(3, 'three')])
richset.slice(1, 2).to_list() # => [Something(2, 'two')]
richset.divide_at(1) # => RichSet([Something(1, 'one')]), RichSet([Something(2, 'two'), Something(3, 'three')])
```
- `pushed_all()` and `unshift_all()` are similar to `pushed()` and `unshift()` but they accept multiple items.
- `popped_n()` and `shift_n()` are similar to `popped()` and `shift()` but they accept count of items.
### List functional manipulations
```python
richset.unique(lambda s: s.id) # => unique by id
richset.map(lambda s: s.id).to_list() # => [1, 2]
richset.filter(lambda s: s.id > 1).to_list() # => [Something(2, 'two'), Something(3, 'three')]
```
### Search
```python
richset.index(lambda s: s.id == 2) # => 1
richset.indices(lambda s: s.id == 2) # => [1]
richset.search_first(lambda s: s.id == 2) # => Something(2, 'two')
richset.search_last(lambda s: s.id == 2) # => Something(2, 'two')
richset.search_all(lambda s: s.id == 2) # => [Something(2, 'two')]
richset.contains(lambda s: s.id == 2) # => True
richset.has(Something(2, 'two')) # => True
```
### Sorts
```python
richset.sorted(key=lambda s: s.name, reverse=True).to_list() # => [Something(2, 'two'), Something(3, 'three'), Something(1, 'one')]
richset.reversed().to_list() # => [Something(3, 'three'), Something(2, 'two'), Something(1, 'one')]
```
### Statistics
```python
richset.is_empty() # => True if empty
richset.is_not_empty() # => True if not empty
richset.size() # => 3
richset.count(lambda s: s.id > 1) # => 2
```
### Set operations
```python
richset = RichSet.from_list([
Something(3, 'three'),
Something(4, 'four'),
Something(5, 'five'),
])
richset2 = RichSet.from_list([
Something(3, 'three'),
Something(4, 'four'),
Something(6, 'six'),
])
```
```python
richset.union(richset2).to_set() # => {Something(3, 'three'), Something(4, 'four'), Something(5, 'five'), Something(6, 'six')}
richset.intersection(richset2).to_set() # => {Something(3, 'three'), Something(4, 'four')}
richset.difference(richset2).to_set() # => {Something(5, 'five')}
richset.symmetric_difference(richset2).to_set() # => {Something(5, 'five'), Something(6, 'six')}
richset.cartesian_product(richset2).to_set() # => {(Something(3, 'three'), Something(3, 'three')), (Something(3, 'three'), Something(4, 'four')), (Something(3, 'three'), Something(6, 'six')), (Something(4, 'four'), Something(3, 'three')), (Something(4, 'four'), Something(4, 'four')), (Something(4, 'four'), Something(6, 'six')), (Something(5, 'five'), Something(3, 'three')), (Something(5, 'five'), Something(4, 'four')), (Something(5, 'five'), Something(6, 'six'))}
richset.zip(richset2).to_set() # => {(Something(3, 'three'), Something(3, 'three')), (Something(4, 'four'), Something(4, 'four')), (Something(5, 'five'), Something(6, 'six')}
```
Also `is_subset()`, `is_superset()`, `is_disjoint()`, `is_equal_as_set()` and `zip_longest()` are available.
### Grouping
```python
richset.group_by(lambda item: item.id % 2) # => {1: RichSet(records=(Something(id=1, name='one'), Something(id=3, name='three'))), 0: RichSet(records=(Something(id=2, name='two'),))}
richset.size_of_group_by(lambda item: item.id % 2) # => {1: 2, 0: 1}
richset.count_of_group_by(key=lambda item: item.id % 2, predicate=lambda item: item.name.startswith('t')) # => {1: 1, 0: 1}
richset.aggregate_by(key=lambda r: r.id % 2, fn=lambda a, b: a + b.name, initial='') # => {1: 'onethree', 0: 'two'}
```
## Paging
```python
richset.page(1, 2).to_list() # => [Something(1, 'one'), Something(2, 'two')]
richset.split_into_pages(2).to_list() # => [RichSet([Something(1, 'one'), Something(2, 'two')]), RichSet([Something(3, 'three')])]
```
# LICENSE
The 3-Clause BSD License. See also LICENSE file.
Raw data
{
"_id": null,
"home_page": "https://github.com/kitsuyui/python-richset",
"name": "richset",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Yui Kitsu",
"author_email": "kitsuyui+github@kitsuyui.com",
"download_url": "https://files.pythonhosted.org/packages/85/ba/83a8bd90f6dc3a42af141bbbcdec811b8aa80ddc4e295eae294a0f835cb2/richset-0.3.0.tar.gz",
"platform": null,
"description": "# richset\n\n[](https://badge.fury.io/py/richset)\n[](https://pypi.python.org/pypi/richset/)\n[](https://codecov.io/gh/kitsuyui/python-richset)\n[](https://opensource.org/licenses/BSD-3-Clause)\n\nrichset interporlates with set, dict, and list.\n\n## Motivations and Concepts\n\n- richset provides useful functions for common use cases of set, dict, and list.\n- builtin set, dict and list requires many boilerplate codes.\n- Pure Python package.\n- Fully typing supported.\n- No magic. No meta-programming.\n\n## Install\n\n```sh\n$ pip install richset\n```\n\n## Usage\n\n```python\nfrom dataclasses import dataclass\nfrom richset import RichSet\n\n\n@dataclass(frozen=True)\nclass Something:\n id: int\n name: str\n\n\nrichset = RichSet.from_list([\n Something(1, 'one'),\n Something(2, 'two'),\n Something(3, 'three'),\n])\n```\n\n### Conversions\n\n```python\nrichset.to_list() # => [Something(1, 'one'), Something(2, 'one'), Something(3, 'three')]\nrichset.to_tuple() # => (Something(1, 'one'), Something(2, 'two'), Something(3, 'three'))\nrichset.to_set() # => {Something(1, 'one'), Something(2, 'two'), Something(3, 'three')}\nrichset.to_frozenset() # => frozenset({Something(1, 'one'), Something(2, 'two'), Something(3, 'three')})\nrichset.to_dict(lambda s: s.id) # => {1: Something(1, 'one'), 2: Something(2, 'two'), 3: Something(3, 'three')}\n```\n\n`to_dict()` takes second argument `duplicated` which is a choice of `'error'`, `'first'` or `'last'`.\n\n- if `duplicated` is `'error'`, then `to_dict()` raises `ValueError` if there is a duplicated key.\n- if `duplicated` is `'first'`, then `to_dict()` picks the first one of duplicated key.\n- if `duplicated` is `'last'`, then `to_dict()` picks the last one of duplicated key.\n\n`to_dict_of_list()` is similar to `to_dict()` but it returns a dict of list.\n\n```python\nrichset.to_dict_of_list(lambda s: s.name) # => {'john': [Something(1, 'john'), Something(2, 'john')], 'jane': [Something(3, 'jane')]}\n```\n\n### List accessors\n\n```python\nrichset.first() # => returns first item `Something(1, 'one')` or raise Error (if empty)\nrichset.get_first() # => returns first item `Something(1, 'one')` or None (if empty)\nrichset.last() # => returns last item `Something(3, 'three')` or raise Error (if empty)\nrichset.get_last() # => returns last item `Something(3, 'three')` or None (if empty)\nrichset.nth(2) # => returns 3rd item `Something(3, 'three')` or raise Error (if empty)\nrichset.get_nth(2) # => returns 3rd item `Something(3, 'three')` or None (if empty)\nrichset.one() # => returns one item `Something(1, 'one')` or raise Error (if empty)\nrichset.get_one() # => returns one item `Something(1, 'one')` or None (if empty)\n```\n\nNote: `get_first`, `get_last`, `get_nth` and `get_one` accept `default` argument that returns specified value instead of None.\n\n```python\nrichset.get_nth(100, default=Something(-1, 'default')) # => Something(-1, 'default')\n```\n\n### List basic manipulations\n\n```python\nrichset.pushed(Something(4, 'four')).to_list() # => [Something(1, 'one'), Something(2, 'two'), Something(3, 'three'), Something(4, 'four')]\nrichset.unshift(Something(4, 'four')).to_list() # => [Something(4, 'four'), Something(1, 'one'), Something(2, 'two'), Something(3, 'three')]\nrichset.popped() # => Something(3, 'three'), RichSet([Something(1, 'one'), Something(2, 'two')])\nrichset.shift() # => Something(1, 'one'), RichSet([Something(2, 'two'), Something(3, 'three')])\nrichset.slice(1, 2).to_list() # => [Something(2, 'two')]\nrichset.divide_at(1) # => RichSet([Something(1, 'one')]), RichSet([Something(2, 'two'), Something(3, 'three')])\n```\n\n- `pushed_all()` and `unshift_all()` are similar to `pushed()` and `unshift()` but they accept multiple items.\n- `popped_n()` and `shift_n()` are similar to `popped()` and `shift()` but they accept count of items.\n\n### List functional manipulations\n\n```python\nrichset.unique(lambda s: s.id) # => unique by id\nrichset.map(lambda s: s.id).to_list() # => [1, 2]\nrichset.filter(lambda s: s.id > 1).to_list() # => [Something(2, 'two'), Something(3, 'three')]\n```\n\n### Search\n\n```python\nrichset.index(lambda s: s.id == 2) # => 1\nrichset.indices(lambda s: s.id == 2) # => [1]\nrichset.search_first(lambda s: s.id == 2) # => Something(2, 'two')\nrichset.search_last(lambda s: s.id == 2) # => Something(2, 'two')\nrichset.search_all(lambda s: s.id == 2) # => [Something(2, 'two')]\nrichset.contains(lambda s: s.id == 2) # => True\nrichset.has(Something(2, 'two')) # => True\n```\n\n### Sorts\n\n```python\nrichset.sorted(key=lambda s: s.name, reverse=True).to_list() # => [Something(2, 'two'), Something(3, 'three'), Something(1, 'one')]\nrichset.reversed().to_list() # => [Something(3, 'three'), Something(2, 'two'), Something(1, 'one')]\n```\n\n### Statistics\n\n```python\nrichset.is_empty() # => True if empty\nrichset.is_not_empty() # => True if not empty\nrichset.size() # => 3\nrichset.count(lambda s: s.id > 1) # => 2\n```\n\n### Set operations\n\n```python\nrichset = RichSet.from_list([\n Something(3, 'three'),\n Something(4, 'four'),\n Something(5, 'five'),\n])\nrichset2 = RichSet.from_list([\n Something(3, 'three'),\n Something(4, 'four'),\n Something(6, 'six'),\n])\n```\n\n```python\nrichset.union(richset2).to_set() # => {Something(3, 'three'), Something(4, 'four'), Something(5, 'five'), Something(6, 'six')}\nrichset.intersection(richset2).to_set() # => {Something(3, 'three'), Something(4, 'four')}\nrichset.difference(richset2).to_set() # => {Something(5, 'five')}\nrichset.symmetric_difference(richset2).to_set() # => {Something(5, 'five'), Something(6, 'six')}\nrichset.cartesian_product(richset2).to_set() # => {(Something(3, 'three'), Something(3, 'three')), (Something(3, 'three'), Something(4, 'four')), (Something(3, 'three'), Something(6, 'six')), (Something(4, 'four'), Something(3, 'three')), (Something(4, 'four'), Something(4, 'four')), (Something(4, 'four'), Something(6, 'six')), (Something(5, 'five'), Something(3, 'three')), (Something(5, 'five'), Something(4, 'four')), (Something(5, 'five'), Something(6, 'six'))}\nrichset.zip(richset2).to_set() # => {(Something(3, 'three'), Something(3, 'three')), (Something(4, 'four'), Something(4, 'four')), (Something(5, 'five'), Something(6, 'six')}\n```\n\nAlso `is_subset()`, `is_superset()`, `is_disjoint()`, `is_equal_as_set()` and `zip_longest()` are available.\n\n### Grouping\n\n```python\nrichset.group_by(lambda item: item.id % 2) # => {1: RichSet(records=(Something(id=1, name='one'), Something(id=3, name='three'))), 0: RichSet(records=(Something(id=2, name='two'),))}\nrichset.size_of_group_by(lambda item: item.id % 2) # => {1: 2, 0: 1}\nrichset.count_of_group_by(key=lambda item: item.id % 2, predicate=lambda item: item.name.startswith('t')) # => {1: 1, 0: 1}\nrichset.aggregate_by(key=lambda r: r.id % 2, fn=lambda a, b: a + b.name, initial='') # => {1: 'onethree', 0: 'two'}\n```\n\n## Paging\n\n```python\nrichset.page(1, 2).to_list() # => [Something(1, 'one'), Something(2, 'two')]\nrichset.split_into_pages(2).to_list() # => [RichSet([Something(1, 'one'), Something(2, 'two')]), RichSet([Something(3, 'three')])]\n```\n\n# LICENSE\n\nThe 3-Clause BSD License. See also LICENSE file.\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "richset interpolate between list, dict, set and iterables.",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/kitsuyui/python-richset"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "df36737e7dc6015f86c35d7591aec1f30f35ada8145b36a266074f98efcc296e",
"md5": "fe1dd70fa4e3963bc645ee696b79f031",
"sha256": "32c253e3da9f4a46a9fb31e2d6ce23ea46451332ed8f89744be359c550b1b7b3"
},
"downloads": -1,
"filename": "richset-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fe1dd70fa4e3963bc645ee696b79f031",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8604,
"upload_time": "2023-10-06T05:13:45",
"upload_time_iso_8601": "2023-10-06T05:13:45.189653Z",
"url": "https://files.pythonhosted.org/packages/df/36/737e7dc6015f86c35d7591aec1f30f35ada8145b36a266074f98efcc296e/richset-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "85ba83a8bd90f6dc3a42af141bbbcdec811b8aa80ddc4e295eae294a0f835cb2",
"md5": "bdce01ed110ed807046f1c298469a924",
"sha256": "f4901da79689e36676774e91e8935654512caef4d42764b6590e9be805b06147"
},
"downloads": -1,
"filename": "richset-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "bdce01ed110ed807046f1c298469a924",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 29452,
"upload_time": "2023-10-06T05:13:47",
"upload_time_iso_8601": "2023-10-06T05:13:47.222885Z",
"url": "https://files.pythonhosted.org/packages/85/ba/83a8bd90f6dc3a42af141bbbcdec811b8aa80ddc4e295eae294a0f835cb2/richset-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-06 05:13:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kitsuyui",
"github_project": "python-richset",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "richset"
}
JSON
