# srtlst
_a simple, generically type-annotated, sorted list_
[](https://mypy-lang.org/)
### usage
Create a sorted list like this:
```python
>>> from srtlst import SortedList
>>> s = SortedList([5, 3, 1])
>>> print(s)
[1, 3, 5]
```
A `SortedList` mimics a regular `list` in most ways, but remains sorted:
```python
>>> s = SortedList([5, 3, 1])
>>> s.extend([6, 2, 4])
>>> print(s)
[1, 2, 3, 4, 5, 6]
```
You can use `add()` instead of `insert()` or `append()`:
```python
>>> s = SortedList([5, 3, 1])
>>> s.add(3)
>>> s.add(2)
>>> print(s)
[1, 2, 3, 3, 5]
```
If you need your data to be sorted in descending order use the optional `reverse` parameter:
```python
>>> s = SortedList([1, 2, 3], reverse=True)
>>> s.add(4)
>>> print(s)
[4, 3, 2, 1]
```
If your data is not inherently sortable, or you want to sort it in a non-default way, you can use `SortedListByKey`
and supply a function to sort it (just like with `sorted()`):
```python
>>> from srtlst import SortedListByKey
>>> my_function = lambda x: x * (-1) ** x
>>> s = SortedListByKey([1, 2, 3, 4], key=my_function)
>>> print(s)
[3, 1, 2, 4]
```
`SortedListByKey` behaves like a `SortedList` in all other ways, and indeed inherits from it.
However, when type checking, a `SortedList` only accepts values for which a less-than (`<`) method is defined (`__lt__()`).
`SortedListByKey` accepts any type of object, as long as an appropriate key function is provided.
The key function must return comparable values for the items in the list.
### installation
No surprises here:
```shell
$ pip install srtlst
```
### type checking
`SortedList` and `SortedListByKey` are type-hinted according to [PEP 484](https://peps.python.org/pep-0484/)
and the `srtlst` library is itself checked using `mypy --strict`.
Type hints for both containers can be provided using type arguments, just like with `list` and other containers:
```python
s: SortedList[int] = SortedList([3, 2, 1])
```
### performance
This library aims to provide a simple sorted list without any dependencies which is ready for use.
Some of the list operations are reimplemented to take advantage of the list's sortedness using Python's standard `bisect` library.
This library should suit your needs if you just want to keep stuff sorted, without having to implement the bookkeeping yourself.
However, if your sorting needs arise from the need for performance, you should also consider this library:
[sortedcontainers](https://grantjenks.com/docs/sortedcontainers/).
### documentation
Documentation is work in progress. For now the Python's built-in help function can be of service:
```python
>>> from srtlst import SortedList
>>> help(SortedList)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/exoriente/srtlst",
"name": "srtlst",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "sorted,list,simple,container,sorting,bisect,typed,mypy",
"author": "exoriente",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/f2/9b/cd7a7627a004cbd2a3b7e32478cf32dda6780bf0f54429802465d9367e39/srtlst-0.2.0.tar.gz",
"platform": null,
"description": "# srtlst\n\n_a simple, generically type-annotated, sorted list_\n\n\n[](https://mypy-lang.org/)\n\n### usage\n\nCreate a sorted list like this:\n\n```python\n>>> from srtlst import SortedList\n>>> s = SortedList([5, 3, 1])\n>>> print(s)\n[1, 3, 5]\n```\n\nA `SortedList` mimics a regular `list` in most ways, but remains sorted:\n\n```python\n>>> s = SortedList([5, 3, 1])\n>>> s.extend([6, 2, 4])\n>>> print(s)\n[1, 2, 3, 4, 5, 6]\n```\n\nYou can use `add()` instead of `insert()` or `append()`:\n\n```python\n>>> s = SortedList([5, 3, 1])\n>>> s.add(3)\n>>> s.add(2)\n>>> print(s)\n[1, 2, 3, 3, 5]\n```\n\nIf you need your data to be sorted in descending order use the optional `reverse` parameter:\n\n```python\n>>> s = SortedList([1, 2, 3], reverse=True)\n>>> s.add(4)\n>>> print(s)\n[4, 3, 2, 1]\n```\n\nIf your data is not inherently sortable, or you want to sort it in a non-default way, you can use `SortedListByKey`\nand supply a function to sort it (just like with `sorted()`):\n\n```python\n>>> from srtlst import SortedListByKey\n>>> my_function = lambda x: x * (-1) ** x\n>>> s = SortedListByKey([1, 2, 3, 4], key=my_function)\n>>> print(s)\n[3, 1, 2, 4]\n```\n\n`SortedListByKey` behaves like a `SortedList` in all other ways, and indeed inherits from it.\nHowever, when type checking, a `SortedList` only accepts values for which a less-than (`<`) method is defined (`__lt__()`).\n\n`SortedListByKey` accepts any type of object, as long as an appropriate key function is provided.\nThe key function must return comparable values for the items in the list.\n\n### installation\n\nNo surprises here:\n\n```shell\n$ pip install srtlst\n```\n\n### type checking\n\n`SortedList` and `SortedListByKey` are type-hinted according to [PEP 484](https://peps.python.org/pep-0484/)\nand the `srtlst` library is itself checked using `mypy --strict`.\n\nType hints for both containers can be provided using type arguments, just like with `list` and other containers:\n\n```python\ns: SortedList[int] = SortedList([3, 2, 1])\n```\n\n### performance\n\nThis library aims to provide a simple sorted list without any dependencies which is ready for use.\nSome of the list operations are reimplemented to take advantage of the list's sortedness using Python's standard `bisect` library.\n\nThis library should suit your needs if you just want to keep stuff sorted, without having to implement the bookkeeping yourself.\nHowever, if your sorting needs arise from the need for performance, you should also consider this library:\n[sortedcontainers](https://grantjenks.com/docs/sortedcontainers/). \n\n### documentation\n\nDocumentation is work in progress. For now the Python's built-in help function can be of service:\n\n```python\n>>> from srtlst import SortedList\n>>> help(SortedList)\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "a simple, generically type-annotated, sorted list",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/exoriente/srtlst",
"Repository": "https://github.com/exoriente/srtlst"
},
"split_keywords": [
"sorted",
"list",
"simple",
"container",
"sorting",
"bisect",
"typed",
"mypy"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b875c6fb4fba649020c3f11600e82ff0867c2d87f2222b665cba1312257f48bd",
"md5": "c7a7c9ffb7ebb54f10e695a45a98cda5",
"sha256": "3bfa2a80b3e824708d194ad15452c2ee7e149207dd9246f5f56adbba16d77165"
},
"downloads": -1,
"filename": "srtlst-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c7a7c9ffb7ebb54f10e695a45a98cda5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 7670,
"upload_time": "2023-05-18T19:36:39",
"upload_time_iso_8601": "2023-05-18T19:36:39.633770Z",
"url": "https://files.pythonhosted.org/packages/b8/75/c6fb4fba649020c3f11600e82ff0867c2d87f2222b665cba1312257f48bd/srtlst-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f29bcd7a7627a004cbd2a3b7e32478cf32dda6780bf0f54429802465d9367e39",
"md5": "bb3821d53024829b7f21ab5dde343aa0",
"sha256": "afe71c1b2f667f17d66f303ffc3e0560226615250c8a99e822f565e8bcb3b005"
},
"downloads": -1,
"filename": "srtlst-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "bb3821d53024829b7f21ab5dde343aa0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 6145,
"upload_time": "2023-05-18T19:36:41",
"upload_time_iso_8601": "2023-05-18T19:36:41.692113Z",
"url": "https://files.pythonhosted.org/packages/f2/9b/cd7a7627a004cbd2a3b7e32478cf32dda6780bf0f54429802465d9367e39/srtlst-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-18 19:36:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "exoriente",
"github_project": "srtlst",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "srtlst"
}
JSON
