Goldman
Goldman is an opinionated WSGI framework built on Falcon with batteries included.
It is JSON API 1.0 compliant & most compliments a CRUD+L type application currently using a postgres database (referred to as a store), however additional stores are on the roadmap. The framework can be used simply by defining your models with validations & you automatically get:
- Content negotiation
- JSON API query parameters including pagination
- Model based routing
- Serialization / Deserialization to & from REST endpoints
- Serialization / Deserialization to & from the store
- signalling using Blinker
- much much more
Resource Examples:
Need some examples? How about a few resources like an American & their Truck, you would define your resources like:
import goldman
from app.models import American, Truck
class API(goldman.API):
""" Subclass the goldman.API object & define resources """
RESOURCES = [
goldman.ModelResource(Truck),
goldman.ModelsResource(Truck),
goldman.RelatedResource(Truck),
goldman.ModelResource(American),
goldman.ModelsResource(American),
goldman.RelatedResource(American),
]
The above creates API end points supporing all CRUD+L type operations for the American & Truck models. This includes complex query parameters as documented in the JSON API specification. Pagination as well. The goldman.RelatedResource
is for handling a models relationships if present.
Model Examples:
To define a model we leverage & extend the awesome Schematics framework for serialization/deserialization & validation. This is different than (de)serialization over the wire which goldman does as well. From the same examples above the models could look like:
import goldman
from goldman.types import PhoneNumberType, ResourceType, ToManyType, ToOneType
from schematics.types import BooleanType, IntType, StringType
class American(goldman.BaseModel):
""" American model """
RTYPE = 'americans'
"""
The attrs below are the models fields
"""
rid = IntType(
from_rest=False,
rid=True,
)
rtype = ResourceType(RTYPE)
first_name = StringType(
max_length=150,
required=True,
)
last_name = StringType(
max_length=150,
required=True,
)
balding = BooleanType(default=True)
loves_freedom = BooleanType(default=True)
weight = IntType(min_value=250)
# relationships
trucks = ToManyType(
field='owner',
rtype='trucks',
)
class Truck(goldman.BaseModel):
""" Truck model """
RTYPE = 'trucks'
"""
The attrs below are the models fields
"""
rid = IntType(
from_rest=False,
rid=True,
)
rtype = ResourceType(RTYPE)
color = StringType(required=True)
mpg = IntType(max_value=10)
truck_bed_for_lovin = BooleanType(default=True)
# relationships
owner = ToOneType(rtype='americans')
The models fields will be cast to the appropriate data types for extra business logic, storage, & transport over the wire. Additionally, validations will be run with JSON API compliant exceptions. An enormous amount of work has been done to ensure strong exception handling with meaningful errors.
Stuff used to make this:
- Faclon core WSGI capability
- Psycopg2 for postgres integration
- Blinker for signalling events
- Schematics for the awesome object schema layer with validations & a bunch more
- Python-PhoneNumbers for phone number validations
- Python-US for state validations