Version 0.3.0 (#98)

Co-authored-by: Amin Alaee <[email protected]>

Author: lovelydinosaur

docs/examples.md

@@ -15,18 +15,21 @@ uvicorn
 **app.py**
 
 ```python
+import typesystem
+import uvicorn
 from starlette.applications import Starlette
 from starlette.responses import JSONResponse
 from starlette.routing import Route
-import typesystem
-import uvicorn
 
 users = []
 
 
-class User(typesystem.Schema):
-    username = typesystem.String(max_length=100)
-    is_admin = typesystem.Boolean(default=False)
+user_schema = typesystem.Schema(
+    fields={
+        "username": typesystem.String(max_length=100),
+        "is_admin": typesystem.Boolean(default=False),
+    }
+)
 
 
 async def list_users(request):
@@ -39,7 +42,7 @@ async def add_user(request):
     if errors:
         return JSONResponse(dict(errors), status_code=400)
     users.append(user)
-    return JSONResponse(dict(user))
+    return JSONResponse(user)
 
 
 app = Starlette(debug=True, routes=[
@@ -73,56 +76,55 @@ uvicorn
 **app.py**
 
 ```python
+import typesystem
+import uvicorn
 from starlette.applications import Starlette
 from starlette.responses import RedirectResponse
-from starlette.routing import Route, Mount
+from starlette.routing import Mount, Route
 from starlette.staticfiles import StaticFiles
 from starlette.templating import Jinja2Templates
-import typesystem
-import uvicorn
 
 forms = typesystem.Jinja2Forms(package="bootstrap4")
 templates = Jinja2Templates(directory="templates")
 statics = StaticFiles(directory="statics", packages=["bootstrap4"])
 bookings = []
 
 
-class BookingSchema(typesystem.Schema):
-    start_date = typesystem.Date(title="Start date")
-    end_date = typesystem.Date(title="End date")
-    room = typesystem.Choice(
-        title="Room type",
-        choices=[
-            ("double", "Double room"),
-            ("twin", "Twin room"),
-            ("single", "Single room"),
-        ],
-    )
-    include_breakfast = typesystem.Boolean(title="Include breakfast", default=False)
-
-    def __str__(self):
-        breakfast = (
-            "(with breakfast)" if self.include_breakfast else "(without breakfast)"
-        )
-        return f"Booking for {self.room} from {self.start_date} to {self.end_date}"
+booking_schema = typesystem.Schema(
+    fields={
+        "start_date": typesystem.Date(title="Start date"),
+        "end_date": typesystem.Date(title="End date"),
+        "room": typesystem.Choice(
+            title="Room type",
+            choices=[
+                ("double", "Double room"),
+                ("twin", "Twin room"),
+                ("single", "Single room"),
+            ],
+        ),
+        "include_breakfast": typesystem.Boolean(
+            title="Include breakfast", default=False
+        ),
+    }
+)
 
 
 async def homepage(request):
-    form = forms.Form(BookingSchema)
+    form = forms.create_form(booking_schema)
     context = {"request": request, "form": form, "bookings": bookings}
     return templates.TemplateResponse("index.html", context)
 
 
 async def make_booking(request):
     data = await request.form()
-    booking, errors = BookingSchema.validate_or_error(data)
+    booking, errors = booking_schema.validate_or_error(data)
     if errors:
-        form = forms.Form(BookingSchema, values=data, errors=errors)
+        form = forms.create_form(booking_schema)
         context = {"request": request, "form": form, "bookings": bookings}
         return templates.TemplateResponse("index.html", context)
 
     bookings.append(booking)
-    return RedirectResponse(request.url_for("homepage"))
+    return RedirectResponse(request.url_for("homepage"), status_code=303)
 
 
 app = Starlette(

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
 
@@ -181,7 +193,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.
 
@@ -201,12 +213,13 @@ 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**
+* `definitions` - `Definitions` instance. **Required**
 
 ## Other data types
 

docs/forms.md

@@ -8,17 +8,21 @@ import typesystem
 
 forms = typesystem.Jinja2Forms(package="typesystem")  # Use the default templates.
 
-class BookingSchema(typesystem.Schema):
-    start_date = typesystem.Date(title="Start date")
-    end_date = typesystem.Date(title="End date")
-    room = typesystem.Choice(title="Room type", choices=[
-        ('double', 'Double room'),
-        ('twin', 'Twin room'),
-        ('single', 'Single room')
-    ])
-    include_breakfast = typesystem.Boolean(title="Include breakfast", default=False)
-
-form = forms.Form(BookingSchema)
+booking_schema = typesystem.Schema(
+    fields={
+        "start_date": typesystem.Date(title="Start date"),
+        "end_date": typesystem.Date(title="End date"),
+        "room": typesystem.Choice(title="Room type", choices=[
+            ('double', 'Double room'),
+            ('twin', 'Twin room'),
+            ('single', 'Single room')
+        ]),
+        "include_breakfast": typesystem.Boolean(title="Include breakfast", default=False),
+
+    }
+)
+
+form = forms.create_form(booking_schema)
 print(form)
 ```
 
@@ -34,26 +38,26 @@ Notice that only the fields in the form are rendered. The surrounding `<form>`,
 ```html
 <tr>
     <td>
-        <label for="form-bookingschema-start-date">Start date</label>
+        <label for="start-date">Start date</label>
     </td>
     <td>
-        <input type="date" id="form-bookingschema-start-date" name="start_date" required>
+        <input type="date" id="start-date" name="start_date" required >
     </td>
 </tr>
 <tr>
     <td>
-        <label for="form-bookingschema-end-date">End date</label>
+        <label for="end-date">End date</label>
     </td>
     <td>
-        <input type="date" id="form-bookingschema-end-date" name="end_date" required>
+        <input type="date" id="end-date" name="end_date" required >
     </td>
 </tr>
 <tr>
     <td>
-        <label for="form-bookingschema-room">Room type</label>
+        <label for="room">Room type</label>
     </td>
     <td>
-        <select id="form-bookingschema-room" name="room">
+        <select id="room" name="room">
             <option></option>
             <option value="double">Double room</option>
             <option value="twin">Twin room</option>
@@ -63,10 +67,10 @@ Notice that only the fields in the form are rendered. The surrounding `<form>`,
 </tr>
 <tr>
     <td>
-        <label for="form-bookingschema-include-breakfast">Include breakfast</label>
+        <label for="include-breakfast">Include breakfast</label>
     </td>
     <td>
-        <input type="checkbox" id="form-bookingschema-include-breakfast" name="include_breakfast" value="true">
+        <input type="checkbox" id="include-breakfast" name="include_breakfast" value="true" >
     </td>
 </tr>
 ```
@@ -92,15 +96,7 @@ We can include values in a form like so:
 
 ```python
 initial_values = {'room': 'double', 'include_breakfast': True}
-form = forms.Form(BookingSchema, values=initial_values)
-```
-
-We can also include validation errors:
-
-```python
-booking, errors = BookingSchema.validate_or_error(data)
-if errors:
-    form = forms.Form(BookingSchema, values=data, errors=errors)
+form = forms.create_form(booking_schema, values=initial_values)
 ```
 
 ## Customizing field rendering

docs/index.md

@@ -50,30 +50,30 @@ $ pip3 install typesystem[pyyaml]
 ```python
 import typesystem
 
-class Artist(typesystem.Schema):
-    name = typesystem.String(max_length=100)
-
-class Album(typesystem.Schema):
-    title = typesystem.String(max_length=100)
-    release_date = typesystem.Date()
-    artist = typesystem.Reference(Artist)
-
-album = Album.validate({
+artist_schema = typesystem.Schema(
+    fields={
+        "name": typesystem.String(max_length=100)
+    }
+)
+
+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)
+    }
+)
+
+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'}}
 ```
 
@@ -82,7 +82,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/json_schema.md

@@ -1,4 +1,4 @@
-TypeSystem can convert Schema classes or Field instances to/from JSON Schema.
+TypeSystem can convert Schema or Field instances to/from JSON Schema.
 
 !!! note
     TypeSystem only supports `$ref` pointers that use the standard "definitions"
@@ -15,20 +15,21 @@ Let's define a schema, and dump it out into a JSON schema document:
 import json
 import typesystem
 
-class BookingSchema(typesystem.Schema):
-    start_date = typesystem.Date(title="Start date")
-    end_date = typesystem.Date(title="End date")
-    room = typesystem.Choice(
-        title="Room type",
-        choices=[
-            ("double", "Double room"),
-            ("twin", "Twin room"),
-            ("single", "Single room"),
-        ],
-    )
-    include_breakfast = typesystem.Boolean(title="Include breakfast", default=False)
+booking_schema = typesystem.Schema(
+    fields={
+        "start_date": typesystem.Date(title="Start date"),
+        "end_date": typesystem.Date(title="End date"),
+        "room": typesystem.Choice(title="Room type", choices=[
+            ('double', 'Double room'),
+            ('twin', 'Twin room'),
+            ('single', 'Single room')
+        ]),
+        "include_breakfast": typesystem.Boolean(title="Include breakfast", default=False),
 
-schema = typesystem.to_json_schema(BookingSchema)
+    }
+)
+
+schema = typesystem.to_json_schema(booking_schema)
 print(json.dumps(schema, indent=4))
 ```