# Type-safe data interchange for Python
JSON is a popular message interchange format employed in API design for its simplicity, readability, flexibility and wide support. However, `json.dump` and `json.load` offer no direct support when working with Python data classes employing type annotations. This package offers services for working with strongly-typed Python classes: serializing objects to JSON, deserializing JSON to objects, and producing a JSON schema that matches the data class, e.g. to be used in an OpenAPI specification.
Unlike [orjson](https://github.com/ijl/orjson), this package supports both serializing and deserializing complex types such as data classes, UUIDs, decimals, etc., and allows specifying custom serialization and deserialization hooks. It doesn't require introducing custom classes in your class inheritance chain (such as `BaseModel` in [pydantic dataclasses](https://pydantic-docs.helpmanual.io/usage/dataclasses/)), making it suitable for operating on classes defined in third-party modules.
## Features
This package offers the following services:
* JSON serialization and de-serialization
* Generate a JSON object from a Python object (`serialization.object_to_json`)
* Parse a JSON object into a Python object (`serialization.json_to_object`)
* JSON schema
* Generate a JSON schema from a Python type (`schema.classdef_to_schema`)
* Validate a JSON object against a Python type (`schema.validate_object`)
* Type information
* Extract documentation strings (a.k.a. docstring) from types (`docstring.parse_type`)
* Inspect types, including generics (package `inspection`)
These services come with full support for complex types like data classes, named tuples and generics.
In the context of this package, a *JSON object* is the (intermediate) Python object representation produced by `json.loads` from a *JSON string*. In contrast, a *JSON string* is the string representation generated by `json.dumps` from the (intermediate) Python object representation.
## Use cases
* Writing a cloud function (lambda) that communicates with JSON messages received as HTTP payload or websocket text messages
* Verifying if an API endpoint receives well-formed input
* Generating a type schema for an OpenAPI specification to impose constraints on what messages an API can receive (see [python-openapi](https://pypi.org/project/python-openapi/))
* Parsing JSON configuration files into a Python object
## Usage
Consider the following class definition:
```python
@dataclass
class Example:
"A simple data class with multiple properties."
bool_value: bool = True
int_value: int = 23
float_value: float = 4.5
str_value: str = "string"
datetime_value: datetime.datetime = datetime.datetime(1989, 10, 23, 1, 45, 50)
guid_value: uuid.UUID = uuid.UUID("f81d4fae-7dec-11d0-a765-00a0c91e6bf6")
```
First, we serialize the object to JSON with
```python
source = Example()
json_obj = object_to_json(source)
```
Here, the variable `json_obj` has the value:
```python
{
"bool_value": True,
"int_value": 23,
"float_value": 4.5,
"str_value": "string",
"datetime_value": "1989-10-23T01:45:50",
"guid_value": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
}
```
Next, we restore the object from JSON with
```python
target = json_to_object(Example, json_obj)
```
Here, `target` holds the restored data class object:
```python
Example(
bool_value=True,
int_value=23,
float_value=4.5,
str_value="string",
datetime_value=datetime.datetime(1989, 10, 23, 1, 45, 50),
guid_value=uuid.UUID("f81d4fae-7dec-11d0-a765-00a0c91e6bf6"),
)
```
We can also produce the JSON schema corresponding to the Python class:
```python
json_schema = json.dumps(classdef_to_schema(Example), indent=4)
```
which yields
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"bool_value": {
"type": "boolean",
"default": true
},
"int_value": {
"type": "integer",
"default": 23
},
"float_value": {
"type": "number",
"default": 4.5
},
"str_value": {
"type": "string",
"default": "string"
},
"datetime_value": {
"type": "string",
"format": "date-time",
"default": "1989-10-23T01:45:50"
},
"guid_value": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false,
"required": [
"bool_value",
"int_value",
"float_value",
"str_value",
"datetime_value",
"guid_value"
],
"title": "A simple data class with multiple properties."
}
```
If a type has a Python docstring, then `title` and `description` fields in the JSON schema are populated from the text in the documentation string.
## Standards
For producing a JSON schema, the following JSON schema standards are supported:
* [Draft 7](https://json-schema.org/specification-links.html#draft-7)
* [Draft 2019-09](https://json-schema.org/specification-links.html#draft-2019-09-formerly-known-as-draft-8)
* [Draft 2020-12](https://json-schema.org/specification-links.html#2020-12)
## Conversion table
The following table shows the conversion types the package employs:
| Python type | JSON schema type | Behavior |
| -- | -- | -- |
| None | null |
| bool | boolean |
| int | integer |
| float | number |
| str | string |
| decimal.Decimal | number |
| bytes | string | represented with Base64 content encoding |
| datetime | string | constrained to match ISO 8601 format `2018-11-13T20:20:39+00:00` |
| date | string | constrained to match ISO 8601 format `2018-11-13` |
| time | string | constrained to match ISO 8601 format `20:20:39+00:00` |
| UUID | string | constrained to match UUID format `f81d4fae-7dec-11d0-a765-00a0c91e6bf6` |
| Enum | *value type* | stores the enumeration value type (typically integer or string) |
| Optional[**T**] | *depends on inner type* | reads and writes **T** if present |
| Union[**T1**, **T2**, ...] | *depends on concrete type* | serializes to the appropriate inner type; deserializes from the first matching type |
| list[**T**] | array | recursive in **T** |
| dict[**K**, **V**] | object | recursive in **V**, keys are coerced into string |
| dict[Enum, **V**] | object | recursive in **V**, keys are of enumeration value type and coerced into string |
| set[**T**] | array | recursive in **T**, container has uniqueness constraint |
| tuple[**T1**, **T2**, ...] | array | array has fixed length, each element has specific type |
| Literal[**const**] | *type matching* **const** | export the literal value as a constant value |
| data class | object | iterates over fields of data class |
| named tuple | object | iterates over fields of named tuple |
| regular class | object | iterates over `dir(obj)` |
| JsonArray | array | untyped JSON array |
| JsonObject | object | untyped JSON object |
| Any | oneOf | a union of all basic JSON schema types |
| Annotated[**T**, ...] | *depends on* **T** | outputs value for **T**, applies constraints and format based on auxiliary type information |
## JSON schema examples
### Simple basic types
| Python type | JSON schema |
| -- | -- |
| bool | `{"type": "boolean"}` |
| int | `{"type": "integer"}` |
| float | `{"type": "number"}` |
| str | `{"type": "string"}` |
| bytes | `{"type": "string", "contentEncoding": "base64"}` |
### Simple built-in types
| Python type | JSON schema |
| -- | -- |
| decimal.Decimal | `{"type": "number"}` |
| datetime.date | `{"type": "string", "format": "date"}` |
| uuid.UUID | `{"type": "string", "format": "uuid"}` |
### Enumeration types
```python
class Side(enum.Enum):
LEFT = "L"
RIGHT = "R"
```
```json
{"enum": ["L", "R"], "type": "string"}
```
### Container types
| Python type | JSON schema |
| -- | -- |
| list[int] | `{"type": "array", "items": {"type": "integer"}}` |
| dict[str, int] | `{"type": "object", "additionalProperties": {"type": "integer"}}` |
| set[int] | `{"type": "array", "items": {"type": "integer"}, "uniqueItems": True}}` |
| tuple[int, str] | `{"type": "array", "minItems": 2, "maxItems": 2, "prefixItems": [{"type": "integer"}, {"type": "string"}]}` |
### Annotated types
Range:
```python
Annotated[int, IntegerRange(23, 82)])
```
```json
{
"type": "integer",
"minimum": 23,
"maximum": 82,
}
```
Precision:
```python
Annotated[decimal.Decimal, Precision(9, 6)])
```
```json
{
"type": "number",
"multipleOf": 0.000001,
"exclusiveMinimum": -1000,
"exclusiveMaximum": 1000,
}
```
### Fixed-width types
Fixed-width integer (e.g. `uint64`) and floating-point (e.g. `float32`) types are annotated types defined in the package `strong_typing.auxiliary`. Their signature is recognized when generating a schema, and a `format` property is written instead of minimum and maximum constraints.
`int32`:
```python
int32 = Annotated[int, Signed(True), Storage(4), IntegerRange(-2147483648, 2147483647)]
```
```json
{"format": "int32", "type": "integer"}
```
`uint64`:
```python
uint64 = Annotated[int, Signed(False), Storage(8), IntegerRange(0, 18446744073709551615)]
```
```json
{"format": "uint64", "type": "integer"}
```
### Any type
```json
{
"oneOf": [
{"type": "null"},
{"type": "boolean"},
{"type": "number"},
{"type": "string"},
{"type": "array"},
{"type": "object"},
]
}
```
## Custom serialization and de-serialization
If a composite object (e.g. a dataclass or a plain Python class) has a `to_json` member function, then this function is invoked to produce a JSON object representation from an instance.
If a composite object has a `from_json` class function (a.k.a. `@classmethod`), then this function is invoked, passing the JSON object as an argument, to produce an instance of the corresponding type.
## Custom types
It is possible to declare custom types when generating a JSON schema. For example, the following class definition has the annotation `@json_schema_type`, which will register a JSON schema subtype definition under the path `#/definitions/AzureBlob`, which will be referenced later with `$ref`:
```python
_regexp_azure_url = re.compile(
r"^https?://([^.]+)\.blob\.core\.windows\.net/([^/]+)/(.*)$")
@dataclass
@json_schema_type(
schema={
"type": "object",
"properties": {
"mimeType": {"type": "string"},
"blob": {
"type": "string",
"pattern": _regexp_azure_url.pattern,
},
},
"required": ["mimeType", "blob"],
"additionalProperties": False,
}
)
class AzureBlob(Blob):
...
```
You can use `@json_schema_type` without the `schema` parameter to register the type name but have the schema definition automatically derived from the Python type. This is useful if the type is reused across the type hierarchy:
```python
@json_schema_type
class Image:
...
class Study:
left: Image
right: Image
```
Here, the two properties of `Study` (`left` and `right`) will refer to the same subtype `#/definitions/Image`.
## Union types
Serializing a union type entails serializing the active member type.
De-serializing discriminated (tagged) union types is based on a disjoint set of property values with type annotation `Literal[...]`. Consider the following example:
```python
@dataclass
class ClassA:
name: Literal["A", "a"]
value: str
@dataclass
class ClassB:
name: Literal["B", "b"]
value: str
```
Here, JSON representations of `ClassA` and `ClassB` are indistinguishable based on property names alone. However, the property `name` for `ClassA` can only take values `"A"` and `"a"`, and property `name` for `ClassB` can only take values `"B"` and `"b"`, hence a JSON object such as
```json
{ "name": "A", "value": "string" }
```
uniquely identifies `ClassA`, and can never match `ClassB`. The de-serializer can instantiate the appropriate class, and populate properties of the newly created instance.
Tagged union types must have at least one property of a literal type, and the values for that type must be all different.
When de-serializing regular union types that have no type tags, the first successfully matching type is selected. It is a parse error if all union member types have been exhausted without a finding match.
## Name mangling
If a Python class has a property augmented with an underscore (`_`) as per [PEP 8](https://www.python.org/dev/peps/pep-0008/#descriptive-naming-styles) to avoid conflict with a Python keyword (e.g. `for` or `in`), the underscore is removed when reading from or writing to JSON.
Raw data
{
"_id": null,
"home_page": null,
"name": "json-strong-typing",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Levente Hunyadi <hunyadi@gmail.com>",
"keywords": "json-schema, json-parsing, json-serialization, docstring-documentation, type-inspection",
"author": null,
"author_email": "Levente Hunyadi <hunyadi@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/e9/61/3b6e3605a5174f2694e2a2fbe04e01a18477fa7c6f1245fcbaac6936eb6f/json_strong_typing-0.4.0.tar.gz",
"platform": null,
"description": "# Type-safe data interchange for Python\r\n\r\nJSON is a popular message interchange format employed in API design for its simplicity, readability, flexibility and wide support. However, `json.dump` and `json.load` offer no direct support when working with Python data classes employing type annotations. This package offers services for working with strongly-typed Python classes: serializing objects to JSON, deserializing JSON to objects, and producing a JSON schema that matches the data class, e.g. to be used in an OpenAPI specification.\r\n\r\nUnlike [orjson](https://github.com/ijl/orjson), this package supports both serializing and deserializing complex types such as data classes, UUIDs, decimals, etc., and allows specifying custom serialization and deserialization hooks. It doesn't require introducing custom classes in your class inheritance chain (such as `BaseModel` in [pydantic dataclasses](https://pydantic-docs.helpmanual.io/usage/dataclasses/)), making it suitable for operating on classes defined in third-party modules.\r\n\r\n## Features\r\n\r\nThis package offers the following services:\r\n\r\n* JSON serialization and de-serialization\r\n * Generate a JSON object from a Python object (`serialization.object_to_json`)\r\n * Parse a JSON object into a Python object (`serialization.json_to_object`)\r\n* JSON schema\r\n * Generate a JSON schema from a Python type (`schema.classdef_to_schema`)\r\n * Validate a JSON object against a Python type (`schema.validate_object`)\r\n* Type information\r\n * Extract documentation strings (a.k.a. docstring) from types (`docstring.parse_type`)\r\n * Inspect types, including generics (package `inspection`)\r\n\r\nThese services come with full support for complex types like data classes, named tuples and generics.\r\n\r\nIn the context of this package, a *JSON object* is the (intermediate) Python object representation produced by `json.loads` from a *JSON string*. In contrast, a *JSON string* is the string representation generated by `json.dumps` from the (intermediate) Python object representation.\r\n\r\n## Use cases\r\n\r\n* Writing a cloud function (lambda) that communicates with JSON messages received as HTTP payload or websocket text messages\r\n* Verifying if an API endpoint receives well-formed input\r\n* Generating a type schema for an OpenAPI specification to impose constraints on what messages an API can receive (see [python-openapi](https://pypi.org/project/python-openapi/))\r\n* Parsing JSON configuration files into a Python object\r\n\r\n## Usage\r\n\r\nConsider the following class definition:\r\n\r\n```python\r\n@dataclass\r\nclass Example:\r\n \"A simple data class with multiple properties.\"\r\n\r\n bool_value: bool = True\r\n int_value: int = 23\r\n float_value: float = 4.5\r\n str_value: str = \"string\"\r\n datetime_value: datetime.datetime = datetime.datetime(1989, 10, 23, 1, 45, 50)\r\n guid_value: uuid.UUID = uuid.UUID(\"f81d4fae-7dec-11d0-a765-00a0c91e6bf6\")\r\n```\r\n\r\nFirst, we serialize the object to JSON with\r\n```python\r\nsource = Example()\r\njson_obj = object_to_json(source)\r\n```\r\n\r\nHere, the variable `json_obj` has the value:\r\n```python\r\n{\r\n \"bool_value\": True,\r\n \"int_value\": 23,\r\n \"float_value\": 4.5,\r\n \"str_value\": \"string\",\r\n \"datetime_value\": \"1989-10-23T01:45:50\",\r\n \"guid_value\": \"f81d4fae-7dec-11d0-a765-00a0c91e6bf6\",\r\n}\r\n```\r\n\r\nNext, we restore the object from JSON with\r\n```python\r\ntarget = json_to_object(Example, json_obj)\r\n```\r\n\r\nHere, `target` holds the restored data class object:\r\n```python\r\nExample(\r\n bool_value=True,\r\n int_value=23,\r\n float_value=4.5,\r\n str_value=\"string\",\r\n datetime_value=datetime.datetime(1989, 10, 23, 1, 45, 50),\r\n guid_value=uuid.UUID(\"f81d4fae-7dec-11d0-a765-00a0c91e6bf6\"),\r\n)\r\n```\r\n\r\nWe can also produce the JSON schema corresponding to the Python class:\r\n```python\r\njson_schema = json.dumps(classdef_to_schema(Example), indent=4)\r\n```\r\nwhich yields\r\n```json\r\n{\r\n \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\r\n \"type\": \"object\",\r\n \"properties\": {\r\n \"bool_value\": {\r\n \"type\": \"boolean\",\r\n \"default\": true\r\n },\r\n \"int_value\": {\r\n \"type\": \"integer\",\r\n \"default\": 23\r\n },\r\n \"float_value\": {\r\n \"type\": \"number\",\r\n \"default\": 4.5\r\n },\r\n \"str_value\": {\r\n \"type\": \"string\",\r\n \"default\": \"string\"\r\n },\r\n \"datetime_value\": {\r\n \"type\": \"string\",\r\n \"format\": \"date-time\",\r\n \"default\": \"1989-10-23T01:45:50\"\r\n },\r\n \"guid_value\": {\r\n \"type\": \"string\",\r\n \"format\": \"uuid\"\r\n }\r\n },\r\n \"additionalProperties\": false,\r\n \"required\": [\r\n \"bool_value\",\r\n \"int_value\",\r\n \"float_value\",\r\n \"str_value\",\r\n \"datetime_value\",\r\n \"guid_value\"\r\n ],\r\n \"title\": \"A simple data class with multiple properties.\"\r\n}\r\n```\r\n\r\nIf a type has a Python docstring, then `title` and `description` fields in the JSON schema are populated from the text in the documentation string.\r\n\r\n## Standards\r\n\r\nFor producing a JSON schema, the following JSON schema standards are supported:\r\n\r\n* [Draft 7](https://json-schema.org/specification-links.html#draft-7)\r\n* [Draft 2019-09](https://json-schema.org/specification-links.html#draft-2019-09-formerly-known-as-draft-8)\r\n* [Draft 2020-12](https://json-schema.org/specification-links.html#2020-12)\r\n\r\n## Conversion table\r\n\r\nThe following table shows the conversion types the package employs:\r\n\r\n| Python type | JSON schema type | Behavior |\r\n| -- | -- | -- |\r\n| None | null |\r\n| bool | boolean |\r\n| int | integer |\r\n| float | number |\r\n| str | string |\r\n| decimal.Decimal | number |\r\n| bytes | string | represented with Base64 content encoding |\r\n| datetime | string | constrained to match ISO 8601 format `2018-11-13T20:20:39+00:00` |\r\n| date | string | constrained to match ISO 8601 format `2018-11-13` |\r\n| time | string | constrained to match ISO 8601 format `20:20:39+00:00` |\r\n| UUID | string | constrained to match UUID format `f81d4fae-7dec-11d0-a765-00a0c91e6bf6` |\r\n| Enum | *value type* | stores the enumeration value type (typically integer or string) |\r\n| Optional[**T**] | *depends on inner type* | reads and writes **T** if present |\r\n| Union[**T1**, **T2**, ...] | *depends on concrete type* | serializes to the appropriate inner type; deserializes from the first matching type |\r\n| list[**T**] | array | recursive in **T** |\r\n| dict[**K**, **V**] | object | recursive in **V**, keys are coerced into string |\r\n| dict[Enum, **V**] | object | recursive in **V**, keys are of enumeration value type and coerced into string |\r\n| set[**T**] | array | recursive in **T**, container has uniqueness constraint |\r\n| tuple[**T1**, **T2**, ...] | array | array has fixed length, each element has specific type |\r\n| Literal[**const**] | *type matching* **const** | export the literal value as a constant value |\r\n| data class | object | iterates over fields of data class |\r\n| named tuple | object | iterates over fields of named tuple |\r\n| regular class | object | iterates over `dir(obj)` |\r\n| JsonArray | array | untyped JSON array |\r\n| JsonObject | object | untyped JSON object |\r\n| Any | oneOf | a union of all basic JSON schema types |\r\n| Annotated[**T**, ...] | *depends on* **T** | outputs value for **T**, applies constraints and format based on auxiliary type information |\r\n\r\n## JSON schema examples\r\n\r\n### Simple basic types\r\n\r\n| Python type | JSON schema |\r\n| -- | -- |\r\n| bool | `{\"type\": \"boolean\"}` |\r\n| int | `{\"type\": \"integer\"}` |\r\n| float | `{\"type\": \"number\"}` |\r\n| str | `{\"type\": \"string\"}` |\r\n| bytes | `{\"type\": \"string\", \"contentEncoding\": \"base64\"}` |\r\n\r\n### Simple built-in types\r\n\r\n| Python type | JSON schema |\r\n| -- | -- |\r\n| decimal.Decimal | `{\"type\": \"number\"}` |\r\n| datetime.date | `{\"type\": \"string\", \"format\": \"date\"}` |\r\n| uuid.UUID | `{\"type\": \"string\", \"format\": \"uuid\"}` |\r\n\r\n### Enumeration types\r\n\r\n```python\r\nclass Side(enum.Enum):\r\n LEFT = \"L\"\r\n RIGHT = \"R\"\r\n```\r\n```json\r\n{\"enum\": [\"L\", \"R\"], \"type\": \"string\"}\r\n```\r\n\r\n### Container types\r\n\r\n| Python type | JSON schema |\r\n| -- | -- |\r\n| list[int] | `{\"type\": \"array\", \"items\": {\"type\": \"integer\"}}` |\r\n| dict[str, int] | `{\"type\": \"object\", \"additionalProperties\": {\"type\": \"integer\"}}` |\r\n| set[int] | `{\"type\": \"array\", \"items\": {\"type\": \"integer\"}, \"uniqueItems\": True}}` |\r\n| tuple[int, str] | `{\"type\": \"array\", \"minItems\": 2, \"maxItems\": 2, \"prefixItems\": [{\"type\": \"integer\"}, {\"type\": \"string\"}]}` |\r\n\r\n### Annotated types\r\n\r\nRange:\r\n```python\r\nAnnotated[int, IntegerRange(23, 82)])\r\n```\r\n```json\r\n{\r\n \"type\": \"integer\",\r\n \"minimum\": 23,\r\n \"maximum\": 82,\r\n}\r\n```\r\n\r\nPrecision:\r\n```python\r\nAnnotated[decimal.Decimal, Precision(9, 6)])\r\n```\r\n```json\r\n{\r\n \"type\": \"number\",\r\n \"multipleOf\": 0.000001,\r\n \"exclusiveMinimum\": -1000,\r\n \"exclusiveMaximum\": 1000,\r\n}\r\n```\r\n\r\n### Fixed-width types\r\n\r\nFixed-width integer (e.g. `uint64`) and floating-point (e.g. `float32`) types are annotated types defined in the package `strong_typing.auxiliary`. Their signature is recognized when generating a schema, and a `format` property is written instead of minimum and maximum constraints.\r\n\r\n`int32`:\r\n```python\r\nint32 = Annotated[int, Signed(True), Storage(4), IntegerRange(-2147483648, 2147483647)]\r\n```\r\n\r\n```json\r\n{\"format\": \"int32\", \"type\": \"integer\"}\r\n```\r\n\r\n`uint64`:\r\n```python\r\nuint64 = Annotated[int, Signed(False), Storage(8), IntegerRange(0, 18446744073709551615)]\r\n```\r\n\r\n```json\r\n{\"format\": \"uint64\", \"type\": \"integer\"}\r\n```\r\n\r\n### Any type\r\n\r\n```json\r\n{\r\n \"oneOf\": [\r\n {\"type\": \"null\"},\r\n {\"type\": \"boolean\"},\r\n {\"type\": \"number\"},\r\n {\"type\": \"string\"},\r\n {\"type\": \"array\"},\r\n {\"type\": \"object\"},\r\n ]\r\n}\r\n```\r\n\r\n## Custom serialization and de-serialization\r\n\r\nIf a composite object (e.g. a dataclass or a plain Python class) has a `to_json` member function, then this function is invoked to produce a JSON object representation from an instance.\r\n\r\nIf a composite object has a `from_json` class function (a.k.a. `@classmethod`), then this function is invoked, passing the JSON object as an argument, to produce an instance of the corresponding type.\r\n\r\n## Custom types\r\n\r\nIt is possible to declare custom types when generating a JSON schema. For example, the following class definition has the annotation `@json_schema_type`, which will register a JSON schema subtype definition under the path `#/definitions/AzureBlob`, which will be referenced later with `$ref`:\r\n\r\n```python\r\n_regexp_azure_url = re.compile(\r\n r\"^https?://([^.]+)\\.blob\\.core\\.windows\\.net/([^/]+)/(.*)$\")\r\n\r\n@dataclass\r\n@json_schema_type(\r\n schema={\r\n \"type\": \"object\",\r\n \"properties\": {\r\n \"mimeType\": {\"type\": \"string\"},\r\n \"blob\": {\r\n \"type\": \"string\",\r\n \"pattern\": _regexp_azure_url.pattern,\r\n },\r\n },\r\n \"required\": [\"mimeType\", \"blob\"],\r\n \"additionalProperties\": False,\r\n }\r\n)\r\nclass AzureBlob(Blob):\r\n ...\r\n```\r\n\r\nYou can use `@json_schema_type` without the `schema` parameter to register the type name but have the schema definition automatically derived from the Python type. This is useful if the type is reused across the type hierarchy:\r\n\r\n```python\r\n@json_schema_type\r\nclass Image:\r\n ...\r\n\r\nclass Study:\r\n left: Image\r\n right: Image\r\n```\r\n\r\nHere, the two properties of `Study` (`left` and `right`) will refer to the same subtype `#/definitions/Image`.\r\n\r\n## Union types\r\n\r\nSerializing a union type entails serializing the active member type.\r\n\r\nDe-serializing discriminated (tagged) union types is based on a disjoint set of property values with type annotation `Literal[...]`. Consider the following example:\r\n\r\n```python\r\n@dataclass\r\nclass ClassA:\r\n name: Literal[\"A\", \"a\"]\r\n value: str\r\n\r\n\r\n@dataclass\r\nclass ClassB:\r\n name: Literal[\"B\", \"b\"]\r\n value: str\r\n```\r\n\r\nHere, JSON representations of `ClassA` and `ClassB` are indistinguishable based on property names alone. However, the property `name` for `ClassA` can only take values `\"A\"` and `\"a\"`, and property `name` for `ClassB` can only take values `\"B\"` and `\"b\"`, hence a JSON object such as\r\n```json\r\n{ \"name\": \"A\", \"value\": \"string\" }\r\n```\r\nuniquely identifies `ClassA`, and can never match `ClassB`. The de-serializer can instantiate the appropriate class, and populate properties of the newly created instance.\r\n\r\nTagged union types must have at least one property of a literal type, and the values for that type must be all different.\r\n\r\nWhen de-serializing regular union types that have no type tags, the first successfully matching type is selected. It is a parse error if all union member types have been exhausted without a finding match.\r\n\r\n## Name mangling\r\n\r\nIf a Python class has a property augmented with an underscore (`_`) as per [PEP 8](https://www.python.org/dev/peps/pep-0008/#descriptive-naming-styles) to avoid conflict with a Python keyword (e.g. `for` or `in`), the underscore is removed when reading from or writing to JSON.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Type-safe data interchange for Python data classes",
"version": "0.4.0",
"project_urls": {
"Homepage": "https://github.com/hunyadi/strong_typing",
"Source": "https://github.com/hunyadi/strong_typing"
},
"split_keywords": [
"json-schema",
" json-parsing",
" json-serialization",
" docstring-documentation",
" type-inspection"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "58dd8b3cdb02167e6c1a59806f87a0c3e0b7b8f9f29937ad43c39fcba5dc91b0",
"md5": "4784e172a3a7dd7622e2d44a3e7f793c",
"sha256": "399f897cf782a43a5c360321f8d2ab424af6730ea2357410ca0c903dc96b2fb1"
},
"downloads": -1,
"filename": "json_strong_typing-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4784e172a3a7dd7622e2d44a3e7f793c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 49417,
"upload_time": "2025-07-20T18:08:28",
"upload_time_iso_8601": "2025-07-20T18:08:28.777141Z",
"url": "https://files.pythonhosted.org/packages/58/dd/8b3cdb02167e6c1a59806f87a0c3e0b7b8f9f29937ad43c39fcba5dc91b0/json_strong_typing-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e9613b6e3605a5174f2694e2a2fbe04e01a18477fa7c6f1245fcbaac6936eb6f",
"md5": "ef2c97caa042ed704280d53816531eca",
"sha256": "bd4932d4be4a08725096efe9520e1b784757697b8be1039ebed520edc840eb63"
},
"downloads": -1,
"filename": "json_strong_typing-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "ef2c97caa042ed704280d53816531eca",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 57152,
"upload_time": "2025-07-20T18:08:30",
"upload_time_iso_8601": "2025-07-20T18:08:30.323611Z",
"url": "https://files.pythonhosted.org/packages/e9/61/3b6e3605a5174f2694e2a2fbe04e01a18477fa7c6f1245fcbaac6936eb6f/json_strong_typing-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-20 18:08:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hunyadi",
"github_project": "strong_typing",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "jsonschema",
"specs": [
[
">=",
"4.24"
]
]
},
{
"name": "typing_extensions",
"specs": [
[
">=",
"4.14"
]
]
},
{
"name": "build",
"specs": []
},
{
"name": "mypy",
"specs": []
},
{
"name": "ruff",
"specs": []
}
],
"lcname": "json-strong-typing"
}
JSON
