Skip to content

SAFRSBase

Thomas Pollet edited this page Apr 5, 2020 · 4 revisions

class safrs.base.SAFRSBase(*args, **kwargs)

Bases: flask_sqlalchemy.model.Model

This SQLAlchemy mixin implements Json Serialization for SAFRS SQLalchemy Persistent Objects Serialization itself is performed by the to_dict method Initialization and instantiation are quite complex because we rely on the DB schema

The jsonapi id is generated from the primary keys of the columns

This class is mostly used as a sqla model mixin therefore the object attributes should not match column names or sqla attribute names, this is why most of the methods & properties have (or should have, hindsight is great :/) the distinguishing s prefix

_init_(*args, **kwargs)

Object initialization:

  • set the named attributes and add the object to the database
  • create relationships

_module_( = 'safrs.base')

static _new_(cls, **kwargs)

If an object with given arguments already exists, this object is instantiated

classmethod _get_swagger_doc_object_model()

Create a schema for object creation and updates through the HTTP PATCH and POST interfaces The schema is created using the sqlalchemy database schema. So there is a one-to-one mapping between json input data and db columns :return: swagger doc

_s_auto_commit( = True)

classmethod _s_check_perm(property_name, permission='r')

Check the column permission (read/write) Goal is to extend this in the future :param column_name: column name :permission: :return: Boolean

_s_column_names( = [])

_s_columns( = [])

classmethod _s_count()

returning None will cause our jsonapi to perform a count() on the result this can be overridden with a cached value for performance on large tables (>1G)

classmethod _s_filter(filter_args)

Apply a filter to this model :param filter_args: filter to apply, passed as a request URL parameter :return: sqla query object

classmethod _s_get_jsonapi_rpc_methods()

  • Returns

    a list of jsonapi_rpc methods for this class

  • Return type

    list

_s_jsonapi_attrs()

  • Returns

    list of jsonapi attribute names

At the moment we expect the column name to be equal to the column name Things will go south if this isn’t the case and we should use the cls.mapper._polymorphic_properties instead

_s_jsonapi_encode()

  • Returns

    Encoded object according to the jsonapi specification:

`

data = {

“attributes”: { … },
“id”: “…”,
“links”: { … },
“relationships”: { … },
“type”: “…”
}\`

classmethod _s_meta()

What is returned in the “meta” part may be implemented by the app

_s_parse_attr_value(attr_name, attr_val)

Try to fetch and parse the (jsonapi attribute) value for a db column from the kwargs :param kwargs: :param column: database column :return parsed value:

_s_patch(**attributes)

update the object attributes :param

**

attributes:

classmethod _s_post(**attributes)

This method is called when a new item is created with a POST to the json api

  • Parameters

    attributes – the jsonapi “data” attributes

  • Returns

    new cls instance

_s_post performs attribute sanitization and calls cls.init The attributes may contain an “id” if cls.allow_client_generated_ids is True

_s_query()

ClassPropertyDescriptor

_s_relationship_names()

ClassPropertyDescriptor

_s_relationships()

  • Returns

    the relationships used for jsonapi (de/)serialization

classmethod _s_sample()

  • Returns

    a sample instance for the API documentation, i.e. the first item in the DB

classmethod _s_sample_dict()

  • Returns

    a sample to be used as an example payload in the swagger example

classmethod _s_sample_id()

  • Returns

    a sample id for the API documentation, i.e. the first item in the DB

_s_type( = 'SAFRSBase')

_s_url()

  • Parameters

    url_prefix

  • Returns

    endpoint url of this instance

allow_client_generated_ids( = False)

db_commit( = True)

exclude_attrs( = [])

exclude_rels( = [])

classmethod get_endpoint(url_prefix=None, type=None)

  • Parameters

    • url_prefix – URL prefix used by the app

    • type – endpoint type, e.g. “instance”

  • Returns

    the API endpoint

  • Return type

    str

classmethod get_instance(item=None, failsafe=False)

  • Parameters

    • item – instance id or dict { “id” : .. “type” : ..}

    • failsafe – indicates whether we want an exception to be raised in case the id is not found

  • Returns

    Instance or None. An error is raised if an invalid id is used

classmethod get_swagger_doc(http_method)

  • Parameters

    http_method – the http method for which to retrieve the documentation

  • Returns

    swagger body and response dictionaries

  • Return type

    tuple

Create a swagger api model based on the sqlalchemy schema.

http_methods( = {'DELETE', 'GET', 'PATCH', 'POST', 'PUT'})

id_type()

  • Returns

    the object’s id type

property jsonapi_id()

  • Returns

    json:api id

  • Return type

    str

if the table/object has a single primary key “id”, it will return this id. In the other cases, the jsonapi “id” will be generated by the cls.id_type (typically by combining the PKs)

object_id( = 'SAFRSBaseId')

query()

ClassPropertyDescriptor

query_limit( = 50)

swagger_models( = {'collection': None, 'instance': None})

to_dict(fields=None)

Create a dictionary with all the instance “attributes” this method will be called by SAFRSJSONEncoder to serialize objects

  • Parameters

    fields – if set, fields to include in the result

  • Returns

    dictionary object

The optional fields attribute is used to implement jsonapi “Sparse Fieldsets” https://jsonapi.org/format/#fetching-sparse-fieldsets:

client MAY request that an endpoint return only specific fields in the response on a per-type basis by including a fields[TYPE] parameter. The value of the fields parameter MUST be a comma-separated (U+002C COMMA, “,”) list that refers to the name(s) of the fields to be returned. If a client requests a restricted set of fields for a given resource type, an endpoint MUST NOT include additional fields in resource objects of that type in its response.

url_prefix( = '')

Clone this wiki locally