Main classes

This part of documentation is about the most often used classes of pyramid_georest. They are used for simple creation of a pyramid_georest API.

Api

class pyramid_georest.lib.rest.Api(url, config, name, read_method='GET', read_filter_method='POST', create_method='POST', update_method='PUT', delete_method='DELETE')

__init__(url, config, name, read_method='GET', read_filter_method='POST', create_method='POST', update_method='PUT', delete_method='DELETE')

A Object which holds the connection to the database and arbitrary numbers of services. It works like a proxy for the request. It decides which service will be finally called by reading the requested url parts and calls the appropriate service method.

In addition you can implement api wide behaviour like authorization be subclassing this class and adding some pre or post processing to the particular methods.

Parameters:

• url (str) – The connection string which is used to let the api connect with the desired database.
• must have the form as described here (It) – http://docs.sqlalchemy.org/en/latest/core/engines.html
• config (pyramid.config.Configurator) – The config of the hosting pyramid application.
• name (str) – The name which is used internally as an identifier of the api, to make it selectable between other api’s. This name must be unique all over the application. If not an error will be thrown on application start up.
• read_method (str) – The HTTP method which is used to match the routing to the API.
• read_filter_method (str) – The HTTP method which is used to match the routing to the API.
• create_method (str) – The HTTP method which is used to match the routing to the API.
• update_method (str) – The HTTP method which is used to match the routing to the API.
• delete_method (str) – The HTTP method which is used to match the routing to the API.

Raises:

LookupError

adapter(request)

The api wide method to receive the adapter request and passing it to the correct service. At this point it is possible to implement some post or pre processing by overwriting this method. The most common use case for this will be the implementation of an authorisation mechanism which has influence on the whole api. To have influence on special services please see the service class implementations adapter method.

Parameters:request (pyramid.request.Request) – The request which comes all the way through the application from the client. Returns:An pyramid response object Return type:pyramid.response.Response

add_service(service)

Add’s a service to the api.

Parameters:service (Service) – The service which should be added to the api. Raises:LookupError

count(request)

The api wide method to receive the count request and passing it to the correct service. At this point it is possible to implement some post or pre processing by overwriting this method. The most common use case for this will be the implementation of an authorisation mechanism which has influence on the whole api. To have influence on special services please see the service class implementations read method.

Parameters:request (pyramid.request.Request) – The request which comes all the way through the application from the client. Returns:An pyramid response object Return type:pyramid.response.Response

create(request)

The api wide method to receive the create request and passing it to the correct service. At this point it is possible to implement some post or pre processing by overwriting this method. The most common use case for this will be the implementation of an authorisation mechanism which has influence on the whole api. To have influence on special services please see the service class implementations create method.

Parameters:request (pyramid.request.Request) – The request which comes all the way through the application from the client. Returns:An pyramid response object Return type:pyramid.response.Response

delete(request)

The api wide method to receive the delete request and passing it to the correct service. At this point it is possible to implement some post or pre processing by overwriting this method. The most common use case for this will be the implementation of an authorisation mechanism which has influence on the whole api. To have influence on special services please see the service class implementations delete method.

Parameters:request (pyramid.request.Request) – The request which comes all the way through the application from the client. Returns:An pyramid response object Return type:pyramid.response.Response

find_service_by_definition(schema_name, table_name)

Little helper method to obtain a service from the api’s service list by it’s unique schema+table name combination.

Parameters:

• schema_name (str) – The database schema name the service is configured for.
• table_name (str) – The database table name the service is configured for.

Returns:

The found service.

Return type:

Service or None

find_service_by_request(request)

Little helper method to scrabble the requested service directly from the url which was requested.

Parameters:request (pyramid.request.Request) – The request which comes all the way through the application from the client Returns:The found service. Return type:Service Raises:HTTPNotFound

model(request)

The api wide method to receive the model request and passing it to the correct service. At this point it is possible to implement some post or pre processing by overwriting this method. The most common use case for this will be the implementation of an authorisation mechanism which has influence on the whole api. To have influence on special services please see the service class implementations model method.

Parameters:request (pyramid.request.Request) – The request which comes all the way through the application from the client. Returns:An pyramid response object Return type:pyramid.response.Response Raises:HTTPNotFound

provide_session(request)

This method provides a usable SQLAlchemy session instance. It is ensured, that this session is doomed independent from the behavior of the request (it installs a finished listener to the request)

Parameters:request (pyramid.request.Request) – The request of the pyramid web framework Returns:a usable instance of a SQLAlchemy Session Return type:Session

read(request)

The api wide method to receive the read request and passing it to the correct service. At this point it is possible to implement some post or pre processing by overwriting this method. The most common use case for this will be the implementation of an authorisation mechanism which has influence on the whole api. To have influence on special services please see the service class implementations read method.

Parameters:request (pyramid.request.Request) – The request which comes all the way through the application from the client. Returns:An pyramid response object Return type:pyramid.response.Response

show(request)

The api wide method to receive the show request and passing it to the correct service. At this point it is possible to implement some post or pre processing by overwriting this method. The most common use case for this will be the implementation of an authorisation mechanism which has influence on the whole api. To have influence on special services please see the service class implementations show method.

Parameters:request (pyramid.request.Request) – The request which comes all the way through the application from the client. Returns:An pyramid response object Return type:pyramid.response.Response

update(request)

The api wide method to receive the update request and passing it to the correct service. At this point it is possible to implement some post or pre processing by overwriting this method. The most common use case for this will be the implementation of an authorisation mechanism which has influence on the whole api. To have influence on special services please see the service class implementations update method.

Parameters:request (pyramid.request.Request) – The request which comes all the way through the application from the client. Returns:An pyramid response object Return type:pyramid.response.Response

Service

class pyramid_georest.lib.rest.Service(model, renderer_proxy=None, adapter_proxy=None)

__init__(model, renderer_proxy=None, adapter_proxy=None)

A object which represents an restful service. It offers all the necessary methods and is able to consume a renderer proxy. This way we assure a plug able system to use custom renderers. If some custom behaviour is wanted at all, you can achieve this by subclassing this class and adding some post or pre processing to the desired method.

Parameters:

• model (sqlalchemy.ext.declarative.DeclarativeMeta) – The model for which the service will be created for.
• renderer_proxy (RenderProxy or None) – A renderer proxy may be passed to achieve custom rendering.
• adapter_proxy (AdapterProxy or None) – An adapter which provides special client side library handling. It is a AdapterProxy per default.

adapter(request)

The method which is used by the api to deliver a client side usable adapter to handle the REST API.

Parameters:request (pyramid.request.Request) – The request which comes all the way through the application from the client Returns:The model description of this service. Return type:pyramid_georest.lib.description.ModelDescription

count(session, request, rest_filter=None)

The method which is used by the api to count the number of records in the database.

Parameters:

• session (sqlalchemy.orm.Session) – The session which is uesed to emit the query.
• request (pyramid.request.Request) – The request which comes all the way through the application from the client
• rest_filter (pyramid_georest.lib.rest.Filter or None) – The Filter which might be applied to the query in addition.

Returns:

The count of records found in the database.

Return type:

int

create(session, request, feature, passed_format)

The method which is used by the api to create exact one record in the database.

Parameters:

• request (pyramid.request.Request) – The request which comes all the way through the application
• the client (from) –
• session (sqlalchemy.orm.Session) – The sqlalchemy session object
• feature (dict) – The feature which should be created in database.
• passed_format (str) – The format which the feature is constructed of.

Returns:

A list of database records found for the

request.

Return type:

list of sqlalchemy.ext.declarative.DeclarativeMeta

delete(session, request, primary_keys)

The method which is used by the api to delete exact one record in the database.

Parameters:

• session (sqlalchemy.orm.Session) – The sqlalchemy session object
• request (pyramid.request.Request) – The request which comes all the way through the application
• the client (from) –
• primary_keys (list of str) – The primary keys which are used to filter the exact element.

Returns:

A list of database records found for the

request.

Return type:

list of sqlalchemy.ext.declarative.DeclarativeMeta

handle_geojson_(orm_object, feature)

Method to assign values from passed geojson feature to the corresponding model object. It takes care of correctly handle geometry values.

Parameters:

• orm_object (sqlalchemy.ext.declarative.DeclarativeMeta) – The orm model object which the values should be assigned to.
• feature (dict) – The feature which contains the values to be assigned to model instance.

handle_json_(orm_object, feature)

Method to assign values from passed json feature to the corresponding model object. It takes care of correctly handle geometry values.

Parameters:

• orm_object (sqlalchemy.ext.declarative.DeclarativeMeta) – The orm model object which the values should be assigned to.
• feature (dict) – The feature which contains the values to be assigned to model instance.

model(request)

The method which is used by the api to deliver a machine readable and serializable description of the underlying database table/model.

Parameters:request (pyramid.request.Request) – The request which comes all the way through the application from the client Returns:The model description of this service. Return type:pyramid_georest.lib.description.ModelDescription

static name_from_definition(schema_name, table_name)

Little helper method to get a comma separated string of schema and table name.

Parameters:

• schema_name (str) – The schema name
• table_name (str) – The table name

Returns:

schema name and table name concatenated in one string separated by comma.

Return type:

str

read(session, request, rest_filter=None, offset=None, limit=None, order_by=None, direction=None)

The method which is used by the api to read a bunch of records from the database.

Parameters:

• session (sqlalchemy.orm.Session) – The session which is uesed to emit the query.
• request (pyramid.request.Request) – The request which comes all the way through the application from the client
• rest_filter (pyramid_georest.lib.rest.Filter or None) – The Filter which might be applied to the query in addition.
• offset (int or None) – The offset which is used for paging reasons. It is only applied if limit is present too.
• limit (int or None) – The limit which is used for paging reason. It is only applied of offest is present too.
• order_by (str or None) – The column name which the sort is assigned to. It is only used if direction is present too.
• direction (str or None) – The direction which is used for sorting. It is only used if order_by is present too.

Returns:

A list of database records found for the

request.

Return type:

list of sqlalchemy.ext.declarative.DeclarativeMeta

show(session, request, primary_keys)

The method which is used by the api to read exact one record from the database.

Parameters:

• session (sqlalchemy.orm.Session) – The sqlalchemy session object
• request (pyramid.request.Request) – The request which comes all the way through the application
• the client (from) –
• primary_keys (list of str) – The primary keys which are used to filter the exact element.

Returns:

A list of database records found for the

request.

Return type:

list of sqlalchemy.ext.declarative.DeclarativeMeta

update(session, request, primary_keys, feature, passed_format)

The method which is used by the api to update exact one record in the database.

Parameters:

• session (sqlalchemy.orm.Session) – The sqlalchemy session object
• request (pyramid.request.Request) – The request which comes all the way through the application
• the client (from) –
• primary_keys (list of str) – The primary keys which are used to filter the exact element.
• feature (dict) – The feature which should be updated in database.
• passed_format (str) – The format which the feature is constructed of.

Returns:

A list of database records found for the

request.

Return type:

list of sqlalchemy.ext.declarative.DeclarativeMeta