{"author":null,"author_email":"DrivenData , Jay Qi ","bugtrack_url":null,"classifiers":["Framework :: Pydantic","Framework :: Pydantic :: 2","Intended Audience :: Developers","License :: OSI Approved :: MIT License","Operating System :: OS Independent","Programming Language :: Python :: 3","Programming Language :: Python :: 3.10","Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.12","Programming Language :: Python :: 3.13","Programming Language :: Python :: 3.9"],"description":"# sortedcontainers-pydantic\n\n[![PyPI](https://img.shields.io/pypi/v/sortedcontainers-pydantic.svg)](https://pypi.org/project/sortedcontainers-pydantic/)\n[![conda-forge feedstock](https://img.shields.io/conda/vn/conda-forge/sortedcontainers-pydantic.svg)](https://github.com/conda-forge/sortedcontainers-pydantic-feedstock)\n[![Supported Python versions](https://img.shields.io/pypi/pyversions/sortedcontainers-pydantic)](https://pypi.org/project/sortedcontainers-pydantic/)\n[![tests](https://github.com/drivendataorg/sortedcontainers-pydantic/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/drivendataorg/sortedcontainers-pydantic/actions/workflows/tests.yml?query=branch%3Amain)\n[![codecov](https://codecov.io/gh/drivendataorg/sortedcontainers-pydantic/branch/main/graph/badge.svg)](https://codecov.io/gh/drivendataorg/sortedcontainers-pydantic)\n\nThis package extends [sortedcontainers](https://github.com/grantjenks/python-sortedcontainers/), a fast pure-Python library for sorted mutable collections, to work with [Pydantic](https://docs.pydantic.dev/latest/)'s models, validation, and serialization.\n\nThe easiest way to get started is to simply import `SortedDict`, `SortedList`, or `SortedSet` from `sortedcontainers_pydantic` instead of from `sortedcontainers`.\n\n```python\nfrom pydantic import BaseModel, TypeAdapter\nfrom sortedcontainers_pydantic import SortedList\n\nclass MyModel(BaseModel):\n sorted_list: SortedList[int]\n\nMyModel(sorted_list=[3.0, 1.0, 2.0])\n#> MyModel(sorted_list=SortedList([1, 2, 3]))\n\nMyModel.model_validate_json('{\"sorted_list\": [3, 1, 2]}')\n#> MyModel(sorted_list=SortedList([1, 2, 3]))\n\nMyModel(sorted_list=[3, 1, 2]).model_dump_json()\n#> '{\"sorted_list\":[1,2,3]}'\n\nTypeAdapter(SortedList).validate_python([3, 1, 2])\n#> SortedList([1, 2, 3])\n\nTypeAdapter(SortedList).validate_json(\"[3, 1, 2]\")\n#> SortedList([1, 2, 3])\n```\n\n^{Reproducible example created by [reprexlite](https://github.com/jayqi/reprexlite) v1.0.0}\n\nFor additional alternative ways to declare types from this library, see the [\"Usage approaches\"](#usage-approaches) section below.\n\nThis library also supports key functions to customize sorting behavior. See the [\"Specifying a key function with `Key`\"](#specifying-a-key-function-with-key) section for further details.\n\n## Installation\n\nsortedcontainers-pydantic is available on [PyPI](https://pypi.org/project/sortedcontainers-pydantic/). You can install it with\n\n```bash\npip install sortedcontainers-pydantic\n```\n\nIt is also available on [conda-forge](https://github.com/conda-forge/sortedcontainers-pydantic-feedstock). You can install it with\n\n```bash\nconda install sortedcontainers-pydantic --channel conda-forge\n```\n\n## Usage approaches\n\nThere are three different ways you can use `sortedcontainers-pydantic`.\n\n### 1. Import from sortedcontainers_pydantic\n\nThe library has subclasses of sortedcontainers's `SortedDict`, `SortedList`, and `SortedSet` with [Pydantic's special methods](https://docs.pydantic.dev/latest/concepts/types/#customizing-validation-with-__get_pydantic_core_schema__) that enable validation and serialization. To use them, simply import classes of the same name from `sortedcontainers_pydantic`.\n\n```python\nfrom pydantic import BaseModel\nfrom sortedcontainers_pydantic import SortedList\n\nclass MyModel(BaseModel):\n sorted_list: SortedList[int]\n\nMyModel(sorted_list=[3.0, 1.0, 2.0])\n#> MyModel(sorted_list=SortedList([1, 2, 3]))\n\nMyModel.model_validate_json('{\"sorted_list\": [3, 1, 2]}')\n#> MyModel(sorted_list=SortedList([1, 2, 3]))\n```\n\n### 2. Use the annotation pattern\n\n_New in sortedcontainers-pydantic v2.0.0_\n\nThe library has special annotation objects `SortedDictPydanticAnnotation`, `SortedListPydanticAnnotation`, and `SortedSetPydanticAnnotation` that can be attached to sortedcontainers's `SortedDict`, `SortedList`, and `SortedSet`, respectively, using `typing.Annotated`. This implements the [annotated pattern](https://docs.pydantic.dev/latest/concepts/types/#handling-third-party-types) supported by Pydantic.\n\n```python\nfrom typing import Annotated\n\nfrom pydantic import BaseModel\nfrom sortedcontainers import SortedList\nfrom sortedcontainers_pydantic import SortedListPydanticAnnotation\n\nclass MyModel(BaseModel):\n sorted_list: Annotated[SortedList[int], SortedListPydanticAnnotation]\n\nMyModel(sorted_list=[3.0, 1.0, 2.0])\n#> MyModel(sorted_list=SortedList([1, 2, 3]))\n```\n\nUnlike approach 1, the type being used is the original class from sortedcontainers and not a subclass.\n\n### 3. Use the wrapper type aliases\n\n_New in sortedcontainers-pydantic v2.0.0_\n\nYou can also use the wrapper types `AnnotatedSortedDict`, `AnnotatedSortedList`, or `AnnotatedSortedSet`. These are simply type aliases implementing approach 2.\n\n```python\nfrom pydantic import BaseModel\nfrom sortedcontainers_pydantic import AnnotatedSortedList\n\nAnnotatedSortedList\n#> typing.Annotated[sortedcontainers.sortedlist.SortedList[~_T], ]\n\nclass MyModel(BaseModel):\n sorted_list: AnnotatedSortedList[int]\n\nMyModel(sorted_list=[3.0, 1.0, 2.0])\n#> MyModel(sorted_list=SortedList([1, 2, 3]))\n```\n\n## Specifying a key function with `Key`\n\n_New in sortedcontainers-pydantic v2.0.0_\n\nYou can specify a key function to control sorting. The key should be a callable that takes a single argument. It will be run on every element to generate a key for making comparisons. To specify a key, instantiate the `Key` special annotation object wrapping it, and attach it with `typing.Annotated`. This works with any of the three approaches.\n\n### Example using `Key` with approach 1\n\n```python\nfrom typing import Annotated\n\nfrom pydantic import BaseModel\nfrom sortedcontainers_pydantic import Key, SortedList\n\nclass MyModel(BaseModel):\n sorted_list: Annotated[SortedList[int], Key(lambda x: -x)]\n\nMyModel(sorted_list=[3.0, 1.0, 2.0])\n#> MyModel(sorted_list=SortedKeyList([3, 2, 1], key= at 0x10ae058a0>))\n```\n\n### Example using `Key` with approach 2\n\n```python\nfrom typing import Annotated\n\nfrom pydantic import BaseModel\nfrom sortedcontainers import SortedList\nfrom sortedcontainers_pydantic import Key, SortedListPydanticAnnotation\n\nclass MyModel(BaseModel):\n sorted_list: Annotated[SortedList[int], SortedListPydanticAnnotation, Key(lambda x: -x)]\n\nMyModel(sorted_list=[3.0, 1.0, 2.0])\n#> MyModel(sorted_list=SortedKeyList([3, 2, 1], key= at 0x10aa4a520>))\n```\n\n### Example using `Key` with approach 3\n\n```python\nfrom typing import Annotated\n\nfrom pydantic import BaseModel\nfrom sortedcontainers_pydantic import AnnotatedSortedList, Key\n\nclass MyModel(BaseModel):\n sorted_list: Annotated[AnnotatedSortedList[int], Key(lambda x: -x)]\n\nMyModel(sorted_list=[3.0, 1.0, 2.0])\n#> MyModel(sorted_list=SortedKeyList([3, 2, 1], key= at 0x10ca65080>))\n```\n\n---\n\n^{Reproducible examples created by [reprexlite](https://github.com/jayqi/reprexlite) v1.0.0}\n","description_content_type":"text/markdown","docs_url":null,"download_url":null,"downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":null,"home_page":null,"keywords":"pydantic, sorted, sorteddict, sortedlist, sortedset","license":"MIT License","license_expression":null,"license_files":["LICENSE"],"maintainer":null,"maintainer_email":null,"name":"sortedcontainers-pydantic","package_url":"https://pypi.org/project/sortedcontainers-pydantic/","platform":null,"project_url":"https://pypi.org/project/sortedcontainers-pydantic/","project_urls":{"Bug Tracker":"https://github.com/jayqi/sortedcontainers-pydantic/issues","Homepage":"https://github.com/jayqi/sortedcontainers-pydantic/","Repository":"https://github.com/jayqi/sortedcontainers-pydantic"},"provides_extra":["tests"],"release_url":"https://pypi.org/project/sortedcontainers-pydantic/2.0.0/","requires_dist":["pydantic-core","pydantic>=2","sortedcontainers","pytest>=6; extra == \"tests\""],"requires_python":">=3.9","summary":"Pydantic support for the sortedcontainers package.","version":"2.0.0","yanked":false,"yanked_reason":null}

Dependency	Optional
pydantic	false
pydantic-core	false
sortedcontainers	false
pytest	true

Package search

sortedcontainers-pydantic

project_urls

Dependencies

All package metadata

Releases