Overview

apischema

JSON (de)serialization, GraphQL and JSON schema generation using Python typing.

apischema makes your life easier when dealing with API data.

Install

pip install apischema

It requires only Python 3.6+ (and dataclasses official backport for version 3.6 only)

PyPy3 is fully supported.

Why another library?

This library fulfills the following goals:

• stay as close as possible to the standard library (dataclasses, typing, etc.) — as a consequence we do not need plugins for editors/linters/etc.;
• be adaptable, provide tools to support any types (ORM, etc.);
• avoid dynamic things like using raw strings for attributes name - play nicely with your IDE.

No known alternative achieves all of this, and apischema is also faster than all of them.

On top of that, because APIs are not only JSON, apischema is also a complete GraphQL library

Note

Actually, apischema is even adaptable enough to enable support of competitor libraries in a few dozens of line of code (pydantic support example using conversions feature)

Example

from collections.abc import Collection
from dataclasses import dataclass, field
from uuid import UUID, uuid4

from graphql import print_schema
from pytest import raises

from apischema import ValidationError, deserialize, serialize
from apischema.graphql import graphql_schema
from apischema.json_schema import deserialization_schema


# Define a schema with standard dataclasses
@dataclass
class Resource:
    id: UUID
    name: str
    tags: set[str] = field(default_factory=set)


# Get some data
uuid = uuid4()
data = {"id": str(uuid), "name": "wyfo", "tags": ["some_tag"]}
# Deserialize data
resource = deserialize(Resource, data)
assert resource == Resource(uuid, "wyfo", {"some_tag"})
# Serialize objects
assert serialize(Resource, resource) == data
# Validate during deserialization
with raises(ValidationError) as err:  # pytest checks exception is raised
    deserialize(Resource, {"id": "42", "name": "wyfo"})
assert err.value.errors == [
    {"loc": ["id"], "msg": "badly formed hexadecimal UUID string"}
]
# Generate JSON Schema
assert deserialization_schema(Resource) == {
    "$schema": "http://json-schema.org/draft/2020-12/schema#",
    "type": "object",
    "properties": {
        "id": {"type": "string", "format": "uuid"},
        "name": {"type": "string"},
        "tags": {
            "type": "array",
            "items": {"type": "string"},
            "uniqueItems": True,
            "default": [],
        },
    },
    "required": ["id", "name"],
    "additionalProperties": False,
}


# Define GraphQL operations
def resources(tags: Collection[str] | None = None) -> Collection[Resource] | None:
    ...


# Generate GraphQL schema
schema = graphql_schema(query=[resources], id_types={UUID})
schema_str = """\
type Query {
  resources(tags: [String!]): [Resource!]
}

type Resource {
  id: ID!
  name: String!
  tags: [String!]!
}
"""
assert print_schema(schema) == schema_str

apischema works out of the box with your data model.

Note

This example and further ones are using pytest API because they are in fact run as tests in the library CI

Run the documentation examples

All documentation examples are written using the last Python minor version — currently 3.9 — in order to provide up-to-date documentation. Because Python 3.9 specificities (like PEP 585) are used, this version is "mandatory" to execute the examples as-is.

Also, as stated above, examples are using pytest.raises as it is the most convenient way to test an exception is raised — and because it's simpler for the CI wrapping.

Moreover, apischema has a graphql-core dependency when it comes to example involving GraphQL.

Lastly, some examples of the Examples section use third-party libraries: SQLAlchemy, attrs and pydantic.

All of these dependencies can be downloaded using the examples dependencies with

pip install apischema[examples]

Once dependencies are installed, you can simply copy-paste examples and execute them, using the proper Python version.

FAQ

What is the difference between apischema and pydantic?

See the dedicated section — there are many differences.

I already have my data model with my SQLAlchemy/ORM tables, will I have to duplicate my code, making one dataclass per table?

No, apischema works with user-defined types as well as types from foreign libraries. Using the conversion feature, you can add default serialization for all your tables, or register a different serializer that you can select according to your API endpoint, or both.

I need more accurate validation than "ensure this is an integer and not a string ", can I do that?

See the validation section. You can use standard JSON schema validation (maxItems, pattern, etc.) that will be embedded in your schema or add custom Python validators for each class/fields/NewType you want.

Let's start the apischema tour.