update fields.md, index.md and schemas.md

Author: aminalaee

docs/fields.md

@@ -1,10 +1,20 @@
-Fields are usually declared as attributes on schema classes:
+Fields are passed as a dictionary to the Schema classes:
 
 ```python
-class Organisation(typesystem.Schema):
-    name = typesystem.String(title="Name", max_length=100)
-    date_created = typesystem.Date(title="Date created", default=datetime.date.today)
-    owner = typesystem.Reference(to=User, allow_null=True)
+import typesystem
+
+user_schema = typesystem.Schema(fields={"name": typesystem.String()})
+
+definitions = typesystem.Definitions()
+definitions["User"] = user_schema
+
+organization_schema = typesystem.Schema(
+    fields={
+        "name": typesystem.String(title="Name", max_length=100),
+        "date_created": typesystem.Date(title="Date created", default=datetime.date.today),
+        "owner": typesystem.Reference(to="User", allow_null=True, definitions=definitions),
+    }
+)
 ```
 
 Fields are always *required* in inputs, unless a *default* value is set.
@@ -20,6 +30,7 @@ All fields support the following arguments.
 * `description` - A string describing the input. **Default: `None`**
 * `default` - A value to be used if no input is provided for this field. May be a callable, such as `datetime.datetime.now`. **Default: `NO_DEFAULT`**
 * `allow_null` - A boolean determining if `None` values are valid. **Default: `False`**
+* `read_only` - A boolean determining if field should be considered as read-only, this is usually used in form rendering. **Default: `False`**
 
 ## Using fields directly
 
@@ -60,6 +71,7 @@ For example: `username = typesystem.String(max_length=100)`
 * `min_length` - A minimum number of characters that valid input stings may contain. **Default: `None`**
 * `pattern` - A regular expression that must match. This can be either a string or a compiled regular expression. E.g. `pattern="^[A-Za-z]+$"` **Default: `None`**
 * `format` - A string used to indicate a semantic type, such as `"email"`, `"url"`, or `"color"`. **Default: `None`**
+* `coerce_types` - A boolean determining if type casting should be done, E.g. changing `None` to `""` if `allow_blank`. **Default: `True`**
 
 ### Text
 
@@ -176,7 +188,7 @@ extra_metadata = typesystem.Object(properties=typesystem.String(max_length=100))
 Schema classes implement their validation behaviour by generating an `Object`
 field, and automatically determining the `properties` and `required` attributes.
 
-You'll typically want to use `typesystem.Reference(to=SomeSchema)` rather than
+You'll typically want to use `typesystem.Reference(to="SomeSchema")` rather than
 using the `Object` field directly, but it can be useful if you have a more
 complex data structure that you need to validate.
 
@@ -196,9 +208,9 @@ Used to reference a nested schema.
 For example:
 
 ```python
-owner = typesystem.Reference(to=User, allow_null=True)
+owner = typesystem.Reference(to="User", allow_null=True, definitions=definitions)
 ```
 
 **Arguments**:
 
-* `to` - A schema class or field instance. **Required**
+* `to` - Name of schema defined in definitions. **Required**

docs/index.md

@@ -1,8 +1,8 @@
 # TypeSystem
 
 <p>
-<a href="https://travis-ci.org/encode/typesystem">
-    <img src="https://travis-ci.org/encode/typesystem.svg?branch=master" alt="Build Status">
+<a href="https://github.com/encode/typesystem/actions">
+    <img src="https://github.com/encode/typesystem/workflows/Test%20Suite/badge.svg" alt="Build Status">
 </a>
 <a href="https://codecov.io/gh/encode/typesystem">
     <img src="https://codecov.io/gh/encode/typesystem/branch/master/graph/badge.svg" alt="Coverage">
@@ -44,30 +44,30 @@ $ pip3 install jinja2
 ```python
 import typesystem
 
-class Artist(typesystem.Schema):
-    name = typesystem.String(max_length=100)
+artist_schema = typesystem.Schema(
+    fields={
+        "name": typesystem.String(max_length=100)
+    }
+)
 
-class Album(typesystem.Schema):
-    title = typesystem.String(max_length=100)
-    release_date = typesystem.Date()
-    artist = typesystem.Reference(Artist)
+definitions = typesystem.Definitions()
+definitions["Artist"] = artist_schema
 
-album = Album.validate({
+album_schema = typesystem.Schema(
+    fields={
+        "title": typesystem.String(max_length=100),
+        "release_date": typesystem.Date(),
+        "artist": typesystem.Reference("Artist", definitions=definitions)
+    }
+)
+
+album = album_schema.validate({
     "title": "Double Negative",
     "release_date": "2018-09-14",
     "artist": {"name": "Low"}
 })
 
 print(album)
-# Album(title='Double Negative', release_date=datetime.date(2018, 9, 14), artist=Artist(name='Low'))
-
-print(album.release_date)
-# datetime.date(2018, 9, 14)
-
-print(album['release_date'])
-# '2018-09-14'
-
-print(dict(album))
 # {'title': 'Double Negative', 'release_date': '2018-09-14', 'artist': {'name': 'Low'}}
 ```
 
@@ -76,7 +76,7 @@ print(dict(album))
 There are plenty of other great validation libraries for Python out there,
 including [Marshmallow](https://github.com/marshmallow-code/marshmallow),
 [Schematics](https://github.com/schematics/schematics),
-[Voluptuous](https://github.com/alecthomas/voluptuous), and many others.
+[Voluptuous](https://github.com/alecthomas/voluptuous), [Pydantic](https://github.com/samuelcolvin/pydantic/) and many others.
 
 TypeSystem exists because I want a data validation library that offers
 first-class support for:

docs/schemas.md

@@ -1,15 +1,24 @@
-Let's start by defining some schema classes.
+Let's start by defining some schemas.
 
 ```python
 import typesystem
 
-class Artist(typesystem.Schema):
-    name = typesystem.String(max_length=100)
+artist_schema = typesystem.Schema(
+    fields={
+        "name": typesystem.String(max_length=100)
+    }
+)
 
-class Album(typesystem.Schema):
-    title = typesystem.String(max_length=100)
-    release_date = typesystem.Date()
-    artist = typesystem.Reference(Artist)
+definitions = typesystem.Definitions()
+definitions["Artist"] = artist_schema
+
+album_schema = typesystem.Schema(
+    fields={
+        "title": typesystem.String(max_length=100),
+        "release_date": typesystem.Date(),
+        "artist": typesystem.Reference("Artist", definitions=definitions)
+    }
+)
 ```
 
 We've got some incoming user data that we'd like to validate against our schema.
@@ -25,18 +34,18 @@ data = {
 We can validate the data against a Schema by using `.validate(data)`.
 
 ```python
-album = Album.validate(data)
+album = album_schema.validate(data)
 ```
 
-If validation succeeds, this will return an `Album` instance.
+If validation succeeds, this will return an `dict`.
 
 If validation fails, a `ValidationError` will be raised.
 
 Alternatively we can use `.validate_or_error(data)`, which will return a
 two-tuple of `(value, error)`. Either one of `value` or `error` will be `None`.
 
 ```python
-album, error = Album.validate_or_error(data)
+album, error = album_schema.validate_or_error(data)
 if error:
     ...
 else:
@@ -53,7 +62,7 @@ invalid_data = {
     'release_date': '2018.09.14',
     'artist': {'name': 'x' * 1000}
 }
-album, error = Album.validate_or_error(invalid_data)
+album, error = album_schema.validate_or_error(invalid_data)
 
 print(dict(error))
 # {'release_date': 'Must be a valid date format.', 'artist': {'name': 'Must have no more than 100 characters.'}}
@@ -65,7 +74,7 @@ If you want more precise information about exactly what error messages exist,
 you can access each individual message with `error.messages()`:
 
 ```python
-album, error = Album.validate_or_error(invalid_data)
+album, error = album_schema.validate_or_error(invalid_data)
 
 for message in error.messages():
     print(f'{message.index!r}, {message.code!r}, {message.text!r})')
@@ -75,79 +84,46 @@ for message in error.messages():
 
 ## Working with schema instances
 
-Schema instances are returned by calls to `.validate()`.
+Python dictionaries are returned by calls to `.validate()`.
 
 ```python
 data = {
     'title': 'Double Negative',
     'release_date': '2018-09-14',
     'artist': {'name': 'Low'}
 }
-album = Album.validate(data)
-print(album)
-# Album(title='Double Negative', release_date=datetime.date(2018, 9, 14), artist=Artist(name='Low'))
-```
-
-Attributes on schemas return native python data types.
-
-```python
-print(type(album.release_date))
-# <class 'datetime.date'>
-```
+album = album_schema.validate(data)
 
-Schema instances present a dict-like interface, allowing them to be easily serialized.
-
-```python
-print(dict(album))
+print(album)
 # {'title': 'Double Negative', 'release_date': '2018-09-14', 'artist': {'name': 'Low'}}
 ```
 
-Index lookup on schema instances returns serialized datatypes.
+You can also `serialize` data using the schema instance:
 
 ```python
-print(type(album['release_date']))
-# <class 'str'>
+artist = artist_schema.serialize({'name': 'Low'})
+album = album_schema.serialize({'title': 'Double Negative', 'artist': artist})
 ```
 
-You can also instantiate schema instances directly.
+If `serialize` directly, validation is not done and data returned may be sparsely populated.
+Any unused attributes without a default will not be returned.
 
 ```python
-artist = Artist(name='Low')
-album = Album(title='Double Negative', release_date='2018-09-14', artist=artist)
-```
-
-When instantiating with keyword arguments, each keyword argument will be validated.
-
-If instantiated directly, schema instances may be sparsely populated. Any unused
-attributes without a default will not be set on the instance.
+artist = artist_schema.serialize({'name': 'Low'})
+album = album_schema.serialize({'title': 'Double Negative', 'artist': artist})
 
-```python
-artist = Artist(name='Low')
-album = Album(title='Double Negative', artist=artist)
 print(album)
-# Album(title='Double Negative', artist=Artist(name='Low')) [sparse]
-album.release_date
-# AttributeError: 'Album' object has no attribute 'release_date'
-print(dict(album))
-{'title': 'Double Negative', 'artist': {'name': 'Low'}}
+# {'title': 'Double Negative', 'artist': {'name': 'Low'}} [sparse]
+
+album['release_date']
+# KetError: 'release_date'
 ```
 
-Sparsely populated instances can be useful for cases of loading data from database,
+Sparsely serialized data can be useful for cases of loading data from database,
 when you do not need to retrieve all the fields, or for cases of loading nested
 data where no database join has been made, and only the primary key of the relationship
 is known.
 
-You can also instantiate a schema from an object instance or dictionary.
-
-```python
-new_album = Album(album)
-```
-
-Note that data validation is not applied when instantiating a schema instance
-directly from an instance or dictionary. This should be used when creating
-instances against a data source that is already known to be validated, such as
-when loading existing instances from a database.
-
 ## Using strict validation
 
 By default, additional properties in the incoming user data is ignored.
@@ -162,19 +138,10 @@ data = {
 ```
 
 After validating against the schema, the `num_tracks` property is not present
-on the `album` instance.
+in the returned data.
 
 ```python
-album = Album.validate(data)
-album.num_tracks
-# AttributeError: 'Album' object has no attribute 'num_tracks'
-```
-
-If you use strict validation, additional properties becomes an error instead.
-
-```python
-album, error = Album.validate_or_error(data, strict=True)
-
-print(dict(error))
-# {'num_tracks': 'Invalid property name.'}
+album = album_schema.validate(data)
+album['num_tracks]
+# KeyError: 'num_tracks'
 ```

mkdocs.yml

@@ -20,5 +20,8 @@ nav:
 
 markdown_extensions:
   - admonition
+  - pymdownx.highlight
+  - pymdownx.superfences
+  - codehilite
   - markdown.extensions.codehilite:
       guess_lang: false

typesystem/schemas.py

@@ -72,7 +72,9 @@ def validate(self, value: typing.Any) -> typing.Any:
 
         return validated
 
-    def serialize(self, obj: typing.Any) -> typing.Any:
+    def serialize(
+        self, obj: typing.Any
+    ) -> typing.Optional[typing.Dict[str, typing.Any]]:
         if obj is None:
             return None