goldman

An opinionated WSGI web framework


Keywords
framework, http, jsonapi, rest, web, wsgi
License
MIT
Install
pip install goldman==0.1.9

Documentation

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: