{"id":14976117,"url":"https://github.com/wyfo/apischema","last_synced_at":"2025-05-14T22:09:41.902Z","repository":{"id":37431726,"uuid":"201204205","full_name":"wyfo/apischema","owner":"wyfo","description":"JSON (de)serialization, GraphQL and JSON schema generation using Python typing.","archived":false,"fork":false,"pushed_at":"2025-03-31T17:51:27.000Z","size":6997,"stargazers_count":234,"open_issues_count":24,"forks_count":18,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-13T19:39:29.505Z","etag":null,"topics":["dataclasses","graphql","graphql-python","graphql-relay","graphql-schema","graphql-server","json","json-api","json-schema","json-schema-generator","openapi","pypy3","python","python-typing","serialization","validation"],"latest_commit_sha":null,"homepage":"https://wyfo.github.io/apischema/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wyfo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["wyfo"]}},"created_at":"2019-08-08T07:33:15.000Z","updated_at":"2025-03-26T06:11:20.000Z","dependencies_parsed_at":"2023-02-19T12:30:35.336Z","dependency_job_id":"c031be33-ca6e-45e6-874e-d868db5f9009","html_url":"https://github.com/wyfo/apischema","commit_stats":{"total_commits":532,"total_committers":14,"mean_commits":38.0,"dds":"0.12030075187969924","last_synced_commit":"a35301341c71d354b2553ae3dabc5262be521756"},"previous_names":[],"tags_count":55,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wyfo%2Fapischema","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wyfo%2Fapischema/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wyfo%2Fapischema/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wyfo%2Fapischema/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wyfo","download_url":"https://codeload.github.com/wyfo/apischema/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254038848,"owners_count":22004177,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dataclasses","graphql","graphql-python","graphql-relay","graphql-schema","graphql-server","json","json-api","json-schema","json-schema-generator","openapi","pypy3","python","python-typing","serialization","validation"],"created_at":"2024-09-24T13:53:20.520Z","updated_at":"2025-05-14T22:09:36.890Z","avatar_url":"https://github.com/wyfo.png","language":"Python","funding_links":["https://github.com/sponsors/wyfo"],"categories":["Python"],"sub_categories":[],"readme":"# apischema\n\nJSON (de)serialization, GraphQL and JSON schema generation using Python typing.\n\n*apischema* makes your life easier when dealing with API data.\n\n## Documentation\n\n[https://wyfo.github.io/apischema/](https://wyfo.github.io/apischema/)\n\n## Install\n```shell\npip install apischema\n```\nIt requires only Python 3.8+. *PyPy3* is also fully supported.\n\n## Why another library?\n\n(If you wonder how this differs from the *pydantic* library, see the [dedicated section of the documentation](https://wyfo.github.io/apischema/dev/difference_with_pydantic) — there are many differences.)\n\nThis library fulfills the following goals:\n\n- stay as close as possible to the standard library (dataclasses, typing, etc.) — as a consequence we do not need plugins for editors/linters/etc.;\n- avoid object-oriented limitations — do not require a base class — thus handle easily every type (`Foo`, `list[Bar]`, `NewType(Id, int)`, etc.) the same way.\n- be adaptable, provide tools to support any types (ORM, etc.);\n- avoid dynamic things like using raw strings for attributes name - play nicely with your IDE.\n\nNo known alternative achieves all of this, and apischema is also [(a lot) faster](https://wyfo.github.io/apischema/dev/optimizations_and_benchmark#benchmark) than all of them.\n\nOn top of that, because APIs are not only JSON, *apischema* is also a complete GraphQL library\n\n\u003e Actually, *apischema* is even adaptable enough to enable support of competitor libraries in a few dozens of line of code ([pydantic support example](https://wyfo.github.io/apischema/dev/examples/pydantic_support) using [conversions feature](https://wyfo.github.io/apischema/dev/conversions))\n\n## Example\n\n```python\nfrom collections.abc import Collection\nfrom dataclasses import dataclass, field\nfrom uuid import UUID, uuid4\n\nimport pytest\nfrom graphql import print_schema\n\nfrom apischema import ValidationError, deserialize, serialize\nfrom apischema.graphql import graphql_schema\nfrom apischema.json_schema import deserialization_schema\n\n\n# Define a schema with standard dataclasses\n@dataclass\nclass Resource:\n    id: UUID\n    name: str\n    tags: set[str] = field(default_factory=set)\n\n\n# Get some data\nuuid = uuid4()\ndata = {\"id\": str(uuid), \"name\": \"wyfo\", \"tags\": [\"some_tag\"]}\n# Deserialize data\nresource = deserialize(Resource, data)\nassert resource == Resource(uuid, \"wyfo\", {\"some_tag\"})\n# Serialize objects\nassert serialize(Resource, resource) == data\n# Validate during deserialization\nwith pytest.raises(ValidationError) as err:  # pytest checks exception is raised\n    deserialize(Resource, {\"id\": \"42\", \"name\": \"wyfo\"})\nassert err.value.errors == [\n    {\"loc\": [\"id\"], \"err\": \"badly formed hexadecimal UUID string\"}\n]\n# Generate JSON Schema\nassert deserialization_schema(Resource) == {\n    \"$schema\": \"http://json-schema.org/draft/2020-12/schema#\",\n    \"type\": \"object\",\n    \"properties\": {\n        \"id\": {\"type\": \"string\", \"format\": \"uuid\"},\n        \"name\": {\"type\": \"string\"},\n        \"tags\": {\n            \"type\": \"array\",\n            \"items\": {\"type\": \"string\"},\n            \"uniqueItems\": True,\n            \"default\": [],\n        },\n    },\n    \"required\": [\"id\", \"name\"],\n    \"additionalProperties\": False,\n}\n\n\n# Define GraphQL operations\ndef resources(tags: Collection[str] | None = None) -\u003e Collection[Resource] | None:\n    ...\n\n\n# Generate GraphQL schema\nschema = graphql_schema(query=[resources], id_types={UUID})\nschema_str = \"\"\"\\\ntype Query {\n  resources(tags: [String!]): [Resource!]\n}\n\ntype Resource {\n  id: ID!\n  name: String!\n  tags: [String!]!\n}\"\"\"\nassert print_schema(schema) == schema_str\n```\n*apischema* works out of the box with your data model.\n\n\u003e This example and further ones are using *pytest* API because they are in fact run as tests in the library CI\n\n### Run the documentation examples\n\nAll documentation examples are written using the last Python minor version — currently 3.10 — in order to provide up-to-date documentation. Because Python 3.10 specificities (like [PEP 585](https://www.python.org/dev/peps/pep-0604/)) are used, this version is \"mandatory\" to execute the examples as-is.\n\nIn addition to *pytest*, some examples use third-party libraries like *SQLAlchemy* or *attrs*. All of this dependencies can be downloaded using the `examples` extra with\n```shell\npip install apischema[examples]\n```\n\nOnce dependencies are installed, you can simply copy-paste examples and execute them, using the proper Python version. \n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwyfo%2Fapischema","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwyfo%2Fapischema","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwyfo%2Fapischema/lists"}