gws.base.model
¶
Data models.
A data model, or simply Model, is an object that deals with Features from external sources, like database tables, shape files, gml responses etc.
A mission of a Model is to read Features from a source and convert them to a form suitable for the client representation. An editable Model can, moreover, receive Features from the client and store them back in a source (not necessarily the same one).
Features¶
A Feature is a collection of named attributes. One of these attributes can optionally
act as a unique ID (uid
), and another one can be the feature geometry (shape
).
There are three kinds of objects that represent Features:
The Feature
object (gws.core.types.IFeature) is an internal representation of a Feature.
It provides storage for attributes and convenience methods to extract or mutate them.
A Feature
also contains client views
, which are chunks of HTML rendered by templates.
The FeatureRecord
object (gws.core.types.FeatureRecord) is a data-only object, that
only contains a dict of attributes and, optionally, some metadata properties,
depending on the source. For example, GML feature records usually contain the layer name.
The FeatureProps
object (gws.core.types.FeatureProps) contains data necessary to display
a Feature in the client. When viewing Features, client only needs their shape
and views
.
In the edit context, FeatureProps
also contains a dict of attributes.
Operation modes¶
Models are used to perform several abstract operations:
view
- the client provides a SearchQuery (gws.core.types.SearchQuery) and expects a list of matching FeatureProps, suitable for viewingedit
- the same asview
, but the Props are suitable for editing (e.g. contain attributes)init
- the client requests a new empty Feature to be initialized and sent backcreate
- the client sends feature props and wants to create new features in the sourceupdate
- the client sends feature props and wants to update existing featuresdelete
- the client sends feature props and wants respective features to be deleted
Fields¶
A Model usually contains a collection of Field
objects (gws.core.types.IModelField).
A Field deals with a subset of feature data and can convert it between representations and validate it.
When a Model performs an operation, it is delegated to all its Fields in turn.
A Model without fields, called “ad-hoc” or “default” Model, can only perform view
operations.
It simply copies attributes between Features and FeatureRecords.
There are two types of Fields: “scalar” Fields represent one or multiple attributes (columns) in the Source itself, “related” Fields represent Features from other Models, linked to the current Model.
Permissions¶
To perform a model operation, the user must have a permission to do so. The permissions (gws.core.types.Access) are interpreted as follows:
read
- can performview
operationwrite
- can performedit
andupdate
create
- can performedit
,init
andcreate
delete
- can performedit
anddelete
It is an error to perform a model operation without permission.
Each Field can also have permissions, interpreted as follows:
read
- the content of the field can be read from the sourcewrite
- user input for this field can be written to the source
It is not an error to attempt to read or write a field without permission. The attempt is just silently ignored.
If a Field has fixed or default values defined, these are applied regardless of Field permissions. Field “read” permissions are applied when a Feature is converted to Props, “write” permissions - when it’s converted to a Record.
Workflows¶
When an operation is about to be performed, the system creates a ModelContext
data object (mc
),
which contains:
operation mode (
view
,edit
etc)User performing the operation
current Project
other properties, mostly database related
Models provide methods to perform operations, while Fields contain callback methods, which are invoked by a Model.
For example, the update
workflow is designed like this:
class Model
def update_features (features)
for each feature
attach an empty FeatureRecord to feature
open a transaction in the Source
for each field in this model
invoke "before_update" callback for each field
this callback is expected to transfer data from feature.attributes to feature.record
write changes to the source, using feature.uid as a key and feature.record as data
(e.g. UPDATE source SET ... WHERE id=feature.uid)
for each field in this model
invoke "after_update" callback for each field
this callback is expected to synchronize updated data, e.g. update a linked model
commit the transaction
Source code: gws.base.model
Submodules¶
Package Contents¶
- class gws.base.model.Config(*args, **kwargs)¶
Bases:
gws.ConfigWithAccess
Model configuration
- fields: list[gws.ext.config.modelField] | None¶
model fields
- loadingStrategy: gws.FeatureLoadingStrategy | None¶
loading strategy for features
- title: str = ''¶
model title
- isEditable: bool = False¶
this model is editable
- withAutoFields: bool = False¶
autoload non-configured model fields from the source
- excludeColumns: list[str] | None¶
exclude columns names from autoload
- withTableView: bool = True¶
enable table view for this model
- tableViewColumns: list[TableViewColumn] | None¶
fields to include in the table view
- templates: list[gws.ext.config.template] | None¶
feature templates
- sort: list[gws.SortOptions] | None¶
default sorting
- class gws.base.model.Object¶
Bases:
gws.Model
Data Model.
- configure()¶
Configuration hook.
- post_configure()¶
Post-configuration hook.
- configure_model()¶
Model configuration protocol.
- configure_provider()¶
- configure_sources()¶
- configure_fields()¶
- configure_auto_fields()¶
- configure_uid()¶
- configure_geometry()¶
- configure_sort()¶
- configure_templates()¶
- props(user)¶
Generate a
Props
struct for this object.- Parameters:
user – The user for which the props should be generated.
- table_view_columns(user)¶
- field(name)¶
- validate_feature(feature, mc)¶
- get_features(uids, mc)¶
- find_features(search, mc)¶
- feature_from_props(props, mc)¶
- feature_to_props(feature, mc)¶
- feature_to_view_props(feature, mc)¶
- class gws.base.model.Props(*args, **kwargs)¶
Bases:
gws.Props
Object properties.
- canCreate: bool¶
- canDelete: bool¶
- canRead: bool¶
- canWrite: bool¶
- isEditable: bool¶
- fields: list[gws.ext.props.modelField]¶
- geometryCrs: str | None¶
- geometryName: str | None¶
- geometryType: gws.GeometryType | None¶
- layerUid: str | None¶
- loadingStrategy: gws.FeatureLoadingStrategy¶
- supportsGeometrySearch: bool¶
- supportsKeywordSearch: bool¶
- tableViewColumns: list[TableViewColumn]¶
- title: str¶
- uid: str¶
- uidName: str | None¶