Special classes¶

This part of documentation is about special classes which can be used to deeply change the behaviour of the pyramid_georest API via subclassing.

The filter system¶

Filter¶

class pyramid_georest.lib.rest.Filter(model_description, definition=None)[source]¶

__init__(model_description, definition=None)[source]¶

The class which represents the filter.

Parameters:

definition (dict) –
The values which are assigned to the object. The definition of the Filter. It has to be dict like {“mode”: “OR/AND”, “clauses”: []}. The clauses are also dict objects with the pattern:
```
{
    "column_name": "<name>",
    "operator": "<see static method decide_operator for further detail>",
    "value":<value>
}
```
It is possible to pack a definition of filter inside the clause array. This enables complex queries.
model_description (pyramid_georest.lib.description.ModelDescription) – The description of the model which is being filtered.

filter(query)[source]¶

The actual filter execution against the database via the constructed clause from the FilterDefinition object.

Parameters:	query (sqlalchemy.orm.query.Query) – The query where the filter should be applied to.
Returns:	The query with the applied filter
Return type:	sqlalchemy.orm.query.Query

FilterBlock¶

class pyramid_georest.lib.rest.FilterBlock(model_description, definition=None)[source]¶

__init__(model_description, definition=None)[source]¶

The class which represents the filter block.

Parameters:

definition (dict) –
The values which are assigned to the object. The definition of the Filter. It has to be dict like {“mode”: “OR/AND”, “clauses”: []}. The clauses are also dict objects with the pattern:
```
{
    "column_name": "<name>",
    "operator": "<see static method decide_operator for further detail>",
    "value":<value>
}
```
It is possible to pack a definition of filter inside the clause array. This enables complex queries.
model_description (pyramid_georest.lib.description.ModelDescription) – The description of the model which is being filtered.

add_clause(clause_definition)[source]¶

The class which represents the clause block.

Parameters:	clause_definition (dict) – The values which are assigned to the object.

decide_mode()[source]¶

This method is used to match the mode and construct a clause list in which are each single filter clause is combined by logical expression like OR or AND. If you need some other behaviour, it is possible to overwrite this method to implement your own matching or do some pre/post processing.

Returns:	The combined clause blocks which wrapped in a sqlalchemy readable way
Return type:	sqlalchemy.sql.elements.BooleanClauseList

Clause¶

class pyramid_georest.lib.rest.Clause(definition, model_description)[source]¶

__init__(definition, model_description)[source]¶

The class which represents the clause block.

Parameters:	definition (dict) – The values which are assigned to the object. model_description (pyramid_georest.lib.description.ModelDescription) – The description of the model which is being filtered.
Raises:	`HTTPBadRequest`

decide_geometric_operation(srid)[source]¶

Decides the simple cases of geometric filter operations.

Parameters:	srid (int) – The SRID/EPSG number to define the coordinate system of the geometry attribute.
Returns:	The clause element
Return type:	sqlalchemy.sql.expression._BinaryExpression
Raises:	`HTTPBadRequest`

static decide_geometric_operator_(operator)[source]¶

Maps the passed operator to the correct database method operator :param operator: The Operator from api request. :type operator: str

Returns:	str

decide_multi_geometries()[source]¶

This method decides if the clause will contain geometry collections (in the value or in the database or in both). If it does it is necessary to “unpack” all collections to make them valid for geometric operations in database. If it does not it uses a normal geometric operation.

Returns:	The clause element
Return type:	sqlalchemy.sql.expression._BinaryExpression
Raises:	`HTTPBadRequest`

decide_operator()[source]¶

This method is used by the filter object to make a simple matching between the passed operators and the operators which are useable for filtering against the database. There are only some base operators implemented by default. If you like some more specific ones feel free to subclass this class and overwrite this method with your special behaviour and matching. Note that this method does not only do the matching thing. It constructs the whole binary expression. So you can get some influence on this process too.

Returns:	The clause element
Return type:	sqlalchemy.sql.expression._BinaryExpression
Raises:	`HTTPBadRequest`

extract_geometry_collection_db(db_path, srid)[source]¶

Decides the geometry collections cases of geometric filter operations when the database contains multi geometries but the passed geometry does not. The multi geometry will be extracted to it’s sub parts for operation.

Parameters:	srid (int) – The SRID/EPSG number to define the coordinate system of the geometry attribute. db_path (str) – The point separated string of schema_name.table_name.column_name from which we can construct a correct SQL statement.
Returns:	The clause element.
Return type:	sqlalchemy.sql.elements.BooleanClauseList
Raises:	`HTTPBadRequest`

extract_geometry_collection_input(db_path, srid)[source]¶

Decides the geometry collections cases of geometric filter operations when the database contains multi geometries but the passed geometry does not. The multi geometry will be extracted to it’s sub parts for operation.

Parameters:	srid (int) – The SRID/EPSG number to define the coordinate system of the geometry attribute. db_path (str) – The point separated string of schema_name.table_name.column_name from which we can construct a correct SQL statement.
Returns:	The clause element.
Return type:	sqlalchemy.sql.elements.BooleanClauseList
Raises:	`HTTPBadRequest`

extract_geometry_collection_input_and_db(db_path, srid)[source]¶

Decides the geometry collections cases of geometric filter operations when the database contains multi geometries but the passed geometry does not. The multi geometry will be extracted to it’s sub parts for operation.

Parameters:	srid (int) – The SRID/EPSG number to define the coordinate system of the geometry attribute. db_path (str) – The point separated string of schema_name.table_name.column_name from which we can construct a correct SQL statement.
Returns:	The clause element.
Return type:	sqlalchemy.sql.elements.BooleanClauseList
Raises:	`HTTPBadRequest`

The render system¶

RestfulJson¶

class pyramid_georest.lib.renderer.RestfulJson(info)[source]¶

This represents a standard pyramid renderer which can consume a list of database instances and renders them to json. It is important to use the Base which is provided by this package. Because this class delivers additional methods.

__init__(info)[source]¶: Constructor: info will be an object having the following attributes: name (the renderer name), package (the package that was ‘current’ at the time the renderer was registered), type (the renderer type name), registry (the current application registry) and settings (the deployment settings dictionary).

static association_formatter(association)[source]¶

Handles special case of association list provided by sqlalchemy.

Parameters:	association (sqlalchemy.ext.associationproxy._AssociationList) – A sqlalchemy association object which should be converted
Returns:	A list containing the association
Return type:	list of str

column_values_as_serializable(results)[source]¶

The most important method in rendering process. Here the values are transformed to serializable representations.

Parameters:	results (dict) – The database records wrapped in a dictionary.
Returns:	A list containing all records with serializable values.
Return type:	list of dict

static date_formatter(date)[source]¶

Formats a date object into a string base iso representation.

Parameters:	date (datetime.datetime) – A date object which should be converted
Returns:	A string which represents the date object
Return type:	str

static float_formatter(number)[source]¶

Formats a floating point number to its pythonic correct float representation.

Parameters:	number (decimal.Decimal) – A floating point number be converted.
Returns:	The formatted float.
Return type:	float

geometry_formatter(geometry)[source]¶

Formats a geoalchemy 2 WKB element into its WKT string representation.

Parameters:	geometry (geoalchemy2.WKBElement) – A geoalchemy wkb element object which should be converted.
Returns:	A WKT formatted string
Return type:	str

to_str(results)[source]¶

Translates result dictionary into a string.

Parameters:	results (dict) – The database records wrapped in a dictionary.
Returns:	The serialized string containing database records.
Return type:	str

RestfulGeoJson¶

class pyramid_georest.lib.renderer.RestfulGeoJson(info)[source]¶

This represents a standard pyramid renderer which can consume a list of database instances and renders them to json. It is important to use the Base which is provided by this package. Because this class delivers additional methods.

__init__(info)[source]¶: Constructor: info will be an object having the following attributes: name (the renderer name), package (the package that was ‘current’ at the time the renderer was registered), type (the renderer type name), registry (the current application registry) and settings (the deployment settings dictionary).

association_formatter(association)¶

Handles special case of association list provided by sqlalchemy.

Parameters:	association (sqlalchemy.ext.associationproxy._AssociationList) – A sqlalchemy association object which should be converted
Returns:	A list containing the association
Return type:	list of str

column_values_as_serializable(results)[source]¶

The most important method in rendering process. Here the values are transformed to serializable representations. It especially takes care of producing a valid GeoJSON FeatureCollection.

Parameters:	results (dict) – The database records wrapped in a dictionary.
Returns:	A dictionary in GeoJSON FeatureCollection style containing all records with serializable values.
Return type:	dict

date_formatter(date)¶

Formats a date object into a string base iso representation.

Parameters:	date (datetime.datetime) – A date object which should be converted
Returns:	A string which represents the date object
Return type:	str

float_formatter(number)¶

Formats a floating point number to its pythonic correct float representation.

Parameters:	number (decimal.Decimal) – A floating point number be converted.
Returns:	The formatted float.
Return type:	float

geometry_formatter(geometry)[source]¶

Formats the passed geoalchemy2 geometry WKB element into its valid GeoJSON representation. This is a list of coordinate tuples.

Parameters:	geometry (geoalchemy2.WKBElement) – A geoalchemy wkb element object which should be converted.
Returns:	A list of coordinates formatted string
Return type:	list
Raises:	`HTTPServerError` – If the geometry type is not supported.

static geometry_type_formatter(geometry)[source]¶

Delivers the shapely geometry type description of geoalchemy 2 WKB element.

Parameters:	geometry (geoalchemy2.WKBElement) – A geoalchemy wkb element object which should be converted.
Returns:	A string representing a shapely valid geometry type.
Return type:	str

to_str(results)¶

Translates result dictionary into a string.

Parameters:	results (dict) – The database records wrapped in a dictionary.
Returns:	The serialized string containing database records.
Return type:	str

The proxy system¶

RenderProxy¶

class pyramid_georest.lib.renderer.RenderProxy[source]¶

__init__()[source]¶

A proxy which matches a renderer to a format which is passed in the url. It implements some basic renderers but is fully extend able. You can add renderers via the add renderer method. Please note that all renderers which are added to the proxy need to be added to the pyramid config before. Otherwise a error will be thrown on startup of the application. Please note in advance that the renderer system of pyramid works in a global way. It is your responsibility to ensure each renderer added is unique by its name. Please keep this in mind when some thing is not generating the output you want. Than it probably happens that you accidentally over wrote some renderer in another part of the application.

For further information see the pyramid renderer documetation

add_renderer(delivery_format, renderer_name)[source]¶

Adds a matching to the render proxy’s matching dict. It is possible to overwrite an existing one. If you do, a notice (warning) is printed to your server logs.

Parameters:	delivery_format (str) – The format string to which the renderer should be bound to (e.g. “json”, “xml”, ...) renderer_name (str) – The name of the renderer which was used to assign it to the pyramid applications configuration.
Raises:	`ConfigurationError`

render(request, result, model_description)[source]¶

Execute the rendering process by matching the requested format to the mapped renderer. If no renderer could be found a error is raised.

Parameters:	request (pyramid.request.Request) – The request which comes all the way through the application from the client result (list of sqlalchemy.ext.declarative.DeclarativeMeta) – A list of database records found for the request. model_description (pyramid_georest.lib.description.ModelDescription) – The description object of the data set which will be rendered.
Returns:	An pyramid response object.
Return type:	pyramid.response.Response
Raises:	`HTTPNotFound`

AdapterProxy¶

class pyramid_georest.lib.renderer.AdapterProxy[source]¶

__init__()[source]¶

A proxy which matches a client side adapter script to a adapter name which is passed in the url as format parameter. It implements some basic adapters but is fully extend able. You can add renderers via the “add_adapters” method.

This enables you to provide every client side base implementation you like which is bound to a restful resource.

add_adapter(delivery_format, adapter_renderer_path)[source]¶

Adds a matching to the render proxy’s matching dict. It is possible to overwrite an existing one. If you do, a notice (warning) is printed to your server logs.

Parameters:	delivery_format (str) – The format string to which the renderer should be bound to (e.g. “json”, “xml”, ...) adapter_renderer_path (str) – The name of the renderer which was used to assign it to the pyramid applications configuration.
Raises:	`ConfigurationError`

static extend_return_params(params)[source]¶

This method enables the developer to extend the parameter which are send to the template.

params (dict): The dictionary which holds the params.

Returns:	The extended dictionary
Return type:	dict

render(request, model_description)[source]¶

Execute the rendering process by matching the requested format to the mapped renderer. If no renderer could be found a error is raised.

Parameters:	request (pyramid.request.Request) – The request which comes all the way through the application from the client model_description (pyramid_georest.lib.description.ModelDescription) – The description object of the data set which will be rendered.
Returns:	An pyramid response object
Return type:	pyramid.response.Response
Raises:	`HTTPNotFound`

The description system¶

ModelDescription¶

class pyramid_georest.lib.description.ModelDescription(model, dictionary=None)[source]¶

__init__(model, dictionary=None)[source]¶

A class to construct a description of a sqlalchemy model. It offers a method to get this description in a machine readable way. => as_dict

Parameters:	model (sqlalchemy.ext.declarative.DeclarativeMeta) – The sqlalchemy model which should be described. dictionary (`str`, optional) – The pass to a dictionary. It has to be in the pyramid form

as_dict()[source]¶

Delivers the objects content as an dict.

Returns:	An python dict with the description of the mapped database table.
Return type:	dict

is_valid_column(column_name)[source]¶

Parameters:	column_name (unicode) – The column name which should be validated.
Returns:	Whether the column name was valid for this model or not.
Return type:	bool

ColumnDescription¶

class pyramid_georest.lib.description.ColumnDescription(column, name, dictionary=None)[source]¶

Simple to use object to hold all useful information about sqlalchemy column.

This class has several public attributes you can use:

column¶: sqlalchemy.schema.Column – The Column which should be the description for.

is_geometry_column¶: bool – The switch which gives info if this is a geometric column.

srid¶: int – Default is to 0 (zero). It is only set during init process when this is a geometric column.

column_name¶: str – The name of represented column.

header¶: str – The translated name of column if a dictionary was provided otherwise its simply the column_name. This might be useful if client side needs to show data in some table.

type¶: str – The description of column database type.

is_primary_key¶: bool – Whether this is primary key column or not.

has_foreign_keys¶: bool – Whether this column has foreign keys or not.

foreign_key_names¶: list – The names of the foreign keys. Obviously this is a empty list if has_foreign_keys is false.

length¶: int – Information about the length of database type.

precision¶: int or None – Precision of floating point number if this is a float type.

scale¶: int or None – Scale of number type.

nullable¶: bool – Whether this column has NOTNULL constraint or not.

default¶: int or str or float – The database defined default value to use if this column value is NULL/None.

__init__(column, name, dictionary=None)[source]¶

A class to construct a description of a column. It offers a method to get this description in a machine readable way. => as_dict

Parameters:	column (sqlalchemy.schema.Column) – The Column which should be the description for. name (str) – The column name dictionary (str or None) – The pass to a dictionary. It has to be in the pyramid form

description.ColumnDescription = <class 'pyramid_georest.lib.description.ColumnDescription'>¶

as_dict()[source]¶

Delivers the objects content as an dict.

Returns:	An dictionary representing a description of the column in a application readable way.
Return type:	dict

RelationDescription¶

class pyramid_georest.lib.description.RelationDescription(relationship, name, dictionary=None)[source]¶

__init__(relationship, name, dictionary=None)[source]¶

A class to construct a description of a relationship property. It offers a method to get this description in a machine readable way. => as_dict

Parameters:	relationship (sqlalchemy.orm.properties.RelationshipProperty) – The object which should be described name (str) – The name of the element which should be described dictionary (str or None) – The pass to a dictionary. It has to be in the pyramid form

as_dict()[source]¶

Delivers the objects content as an dict.

Returns:	An dictionary representing a description of the relationship in a application readable way
Return type:	dict

translate¶

pyramid_georest.lib.description.translate(string_to_translate, dictionary, lang='de')[source]¶

A method which is able to translate a string with a given dictionary path on the file system. It acts in pyramid way. See: pyramid i18 documentation

Parameters:	string_to_translate (str) – The string which should be translated. dictionary (str) – The dictionary which is used for translation. lang (str) – The language to which the string should be translated.
Returns:	The translated string
Return type:	str