vtjson 2.1.6__py3-none-any.whl → 2.1.8__py3-none-any.whl

vtjson/vtjson.py

@@ -121,7 +121,7 @@ class SchemaError(Exception):
     pass
 
 
-__version__ = "2.1.6"
+__version__ = "2.1.8"
 
 
 @dataclass

{vtjson-2.1.6.dist-info → vtjson-2.1.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: vtjson
-Version: 2.1.6
+Version: 2.1.8
 Summary: A lightweight package for validating JSON like Python objects
 Author-email: Michel Van den Bergh <michel.vandenbergh@uhasselt.be>
 Project-URL: Homepage, https://github.com/vdbergh/vtjson
@@ -24,14 +24,14 @@ A lightweight package for validating JSON like Python objects.
 
 ## Schemas
 
-Validation of JSON like Python objects is done according to a `schema` which is somewhat inspired by a typescript type. The format of a schema is more or less self explanatory. As an [example](https://raw.githubusercontent.com/vdbergh/vtjson/refs/heads/main/docs/example1.md) one may consult the schema of the run object in the mongodb database underlying the Fishtest web application <https://tests.stockfishchess.org/tests>.
+Validation of JSON like Python objects is done according to a `schema` which is somewhat inspired by a typescript type. The format of a schema is more or less self explanatory. As an example  one may consult the [schema of the run object](https://raw.githubusercontent.com/vdbergh/vtjson/refs/heads/main/docs/example1.md) in the mongodb database underlying the Fishtest web application <https://tests.stockfishchess.org/tests>.
 
 The following conventions are used:
 
 - As in typescript, a (string) key ending in `?` represents an optional key. The corresponding schema (the item the key points to) will only be used for validation when the key is present in the object that should be validated. A key can also be made optional by wrapping it as `optional_key(key)`.
 - If in a list/tuple the last entry is `...` (ellipsis) it means that the next to last entry will be repeated zero or more times. In this way generic types can be created. For example the schema `[str, ...]` represents a list of strings.
 
-As of version 2.1, a suitable adapted `vtjson` schema can be used as a Python type hint. Here is the above [example](https://raw.githubusercontent.com/vdbergh/vtjson/refs/heads/main/docs/example2.md) rewritten in a way that is compatible with type hints. E.g. if one wants to ensure that a run object obtained via an api has the correct type one can do
+As of version 2.1, a suitable adapted `vtjson` schema can be used as a Python type annotation. Here is the above example rewritten in a way that is [compatible with type annotations](https://raw.githubusercontent.com/vdbergh/vtjson/refs/heads/main/docs/example2.md). E.g. if one wants to ensure that a run object obtained via an api has the correct type one can do
 
 ```python
 from typing import assert_type
@@ -160,7 +160,7 @@ A schema can be, in order of precedence:
   ```
 
   where the optional argument `_deferred_compiles`  is an opaque data structure used for handling recursive schemas. If appropriate, the function `_compile` internally invokes the method `schema.__compile__` and this should produce an instance of the class `compiled_schema`. The method `__compile__` may invoke the function `_compile` again. If this happens then the optional argument `_deferred_compiles` should be passed unmodified. Please consult the source code of `vtjson` for more details.
-- A Python type hint such as `list[str]`. This is discussed further below.
+- A Python type annotation such as `list[str]`. This is discussed further below.
 - A Python type. In that case validation is done by checking membership. By convention the schema `float` matches both ints and floats. Similarly the schema `complex` matches ints and floats besides of course complex numbers.
 - A callable. Validation is done by applying the callable to the object. If applying the callable throws an exception then the corresponding message will be part of the non-validation message.
 - An instance of `Sequence` that is not an instance of `str` (e.g a `list` or a `tuple`). Validation is done by first checking membership of the schema type, and then performing validation for each of the entries of the object being validated against the corresponding entries of the schema.
@@ -168,7 +168,7 @@ A schema can be, in order of precedence:
 - A `set`. A set validates an object if the object is a set and the elements of the object are validated by an element of the schema.
 - An arbitrary Python object. Validation is done by checking equality of the schema and the object, except when the schema is `float`, in which case `math.isclose` is used. Below we call such an object a `const schema`.
 
-## Validating Mapping
+## Validating against Mapping schemas
 
 For a Mapping schema containing only `const keys` (i.e. keys corresponding to a `const schema`) the interpretation is obvious (see the introductory example above). Below we discuss the validation of an object against a Mapping schema in the general case.
 
@@ -182,25 +182,26 @@ For a Mapping schema containing only `const keys` (i.e. keys corresponding to a
 
 A consequence of this algorithm is that non-const keys are automatically optional. So applying the wrapper `optional_key` to them is meaningless and has no effect.
 
-## Type hints integration
+## Type annotations integration
 
-### Type hints as schemas
+### Type annotations as schemas
 
-`vtjson` recognizes the following type hints as schemas.
+`vtjson` recognizes the following type annotations as schemas.
 
 ```python
-Annotated, dict[...], Dict[...], list[...], List[...], tuple[...], Tuple[...],
-Protocol, NamedTuple, Literal, NewType, TypedDict, Union (or the equivalent operator |).
+Annotated, Mapping[...,...] and subtypes, Container[...] and subtypes,
+tuple[...], Tuple[...], Protocol, NamedTuple, Literal, NewType, TypedDict,
+Union (or the equivalent operator |), Any.
 ```
 
 For example `dict[str, str]` is translated internally into the schema `{str: str}`. See below for more information.
 
 ### Annotated
 
-- More general vtjson schemas can work along Python type hints by using the `typing.Annotated` contruct. The most naive way to do this is via
+- More general vtjson schemas can work along Python type annotations by using the `typing.Annotated` contruct. The most naive way to do this is via
 
   ```python
-  Annotated[type_hint, vtjson_schema, skip_first]
+  Annotated[type_annotation, vtjson_schema, skip_first]
   ```
 
   For example
@@ -209,8 +210,8 @@ For example `dict[str, str]` is translated internally into the schema `{str: str
   Annotated[list[object], [int, str, float], skip_first]
   ```
 
-  A type checker such as `mypy` will only see the type hint (`list[object]` in the example), whereas vtjson will only see the vtjson schema (`[int, str, float]` in the example). `skip_first` is a built-in short hand for `Apply(skip_first=True)` (see below) which directs vtjson to ignore the first argument of an `Annotated` schema.
-- In some use cases a vtjon_schema will meaningfully refine a Python type or type hint. In that case one should not use `skip_first`. For example:
+  A type checker such as `mypy` will only see the type annotation (`list[object]` in the example), whereas vtjson will only see the vtjson schema (`[int, str, float]` in the example). `skip_first` is a built-in short hand for `Apply(skip_first=True)` (see below) which directs vtjson to ignore the first argument of an `Annotated` schema.
+- In some use cases a vtjon_schema will meaningfully refine a Python type or type annotation. In that case one should not use `skip_first`. For example:
 
   ```python
   Annotated[datetime, fields({"tzinfo": timezone.utc})]
@@ -225,18 +226,18 @@ For example `dict[str, str]` is translated internally into the schema `{str: str
   ```
 
   matches even integers.
-- If one wants to pre-compile a schema and still use it as a type hint (assuming it is valid as such) then one can do:
+- If one wants to pre-compile a schema and still use it as a type annotation (assuming it is valid as such) then one can do:
 
   ```python
   schema = <schema definition>
   Schema = Annotated[schema, compile(schema), skip_first]
   ```
 
-### Supported type hints
+### Supported type annotations
 
-Note that Python imposes strong restrictions on what constitutes a valid type hint but `vtjson` is much more lax about this. Enforcing the restrictions is left to the type checkers or the Python interpreter.
+Note that Python imposes strong restrictions on what constitutes a valid type annotation but `vtjson` is much more lax about this. Enforcing the restrictions is left to the type checkers or the Python interpreter.
 
-- `TypedDict`. A TypedDict type hint is translated into a `dict` schema. E.g.
+- `TypedDict`. A TypedDict type annotation is translated into a `dict` schema. E.g.
 
   ```python
   class Movie(TypedDict):
@@ -270,16 +271,18 @@ Note that Python imposes strong restrictions on what constitutes a valid type hi
 
 - `NewType` is translated into a `set_name` schema. E.g. `NewType('Movie', str)` becomes `set_name(str, 'Movie')`
 
-- `dict[...]` and `Dict[...]` are translated into the equivalent `dict` schemas. E.g. `dict[str, str]`  becomes `{str: str}`.
-
 - `tuple[...]` and `Tuple[...]` are translated into the equivalent `tuple` schemas.
 
-- `list[...]` and `List[...]` are translated into the equivalent `list` schemas.
+- `Mapping[S, T]` and subtypes validate those objects that are members of the origin type (a subclass of `Mapping`) and whose (key, value) pairs match `(S, T)`.
+
+- `Container[T]` and subtypes validate those objects that are members of the origin type (a subclass of `Container`) and whose elements match `T`.
 
 - `Union` and the `|` operator are translated into `union`.
 
 - `Literal` is also translated into `union`.
 
+- `Any` is translated into `anything`.
+
 ### Apply objects
 
 - If the list of arguments of an Annotated schema includes Apply objects then those modify the treatement of the arguments that come before them. We already encountered `skip_first` which is a built-in alias for `Apply(skip_first=True)`. The full signature of `Apply` is
@@ -306,7 +309,7 @@ Vtjson includes the command
 safe_cast(schema, object)
 ```
 
-(where `schema` should be a valid type hint) that functions exactly like `cast` except that it also verifies at run time that the given object matches the given schema.
+(where `schema` should be a valid type annotation) that functions exactly like `cast` except that it also verifies at run time that the given object matches the given schema.
 
 ## Creating types
 

vtjson-2.1.8.dist-info/RECORD

@@ -0,0 +1,9 @@
+vtjson/__init__.py,sha256=oLX4JH6_R7dYtTiGfBG3pQGR21IArspifdmZilbuGOw,68
+vtjson/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vtjson/vtjson.py,sha256=rpgDncJmLcr6yoU2Ibh2pyubJJIyWXgxxvAWuMNfy_s,69567
+vtjson-2.1.8.dist-info/AUTHORS,sha256=qmxaXxaIO-YPNHJAZ0dcCrnPCs1x9ocbtMksiy4i80M,21
+vtjson-2.1.8.dist-info/LICENSE,sha256=n7xW-zX8xBLHzCdqWIMRuMzBD_ACLcNCwio0LEkKt1o,1077
+vtjson-2.1.8.dist-info/METADATA,sha256=ayfdkXUD6NbZ-7iOj9rbyI2WBfH7OW_URMug__SeleY,24323
+vtjson-2.1.8.dist-info/WHEEL,sha256=R06PA3UVYHThwHvxuRWMqaGcr-PuniXahwjmQRFMEkY,91
+vtjson-2.1.8.dist-info/top_level.txt,sha256=9DlSF3l63igcvnYPcj117F2hzOW4Nx0N-JBoW3jjBZM,7
+vtjson-2.1.8.dist-info/RECORD,,

vtjson-2.1.6.dist-info/RECORD

@@ -1,9 +0,0 @@
-vtjson/__init__.py,sha256=oLX4JH6_R7dYtTiGfBG3pQGR21IArspifdmZilbuGOw,68
-vtjson/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-vtjson/vtjson.py,sha256=UO58eUc0yShJ9Nm8zvhc3egHUzfLcLXdlj2TpKxtmYE,69567
-vtjson-2.1.6.dist-info/AUTHORS,sha256=qmxaXxaIO-YPNHJAZ0dcCrnPCs1x9ocbtMksiy4i80M,21
-vtjson-2.1.6.dist-info/LICENSE,sha256=n7xW-zX8xBLHzCdqWIMRuMzBD_ACLcNCwio0LEkKt1o,1077
-vtjson-2.1.6.dist-info/METADATA,sha256=-PFoASAchEaDMOxJfx8icFTmVMxbfLFEkK9btIfWn28,24054
-vtjson-2.1.6.dist-info/WHEEL,sha256=R06PA3UVYHThwHvxuRWMqaGcr-PuniXahwjmQRFMEkY,91
-vtjson-2.1.6.dist-info/top_level.txt,sha256=9DlSF3l63igcvnYPcj117F2hzOW4Nx0N-JBoW3jjBZM,7
-vtjson-2.1.6.dist-info/RECORD,,