Coverage for gws-app/gws/base/ows/server/__init__.py: 100%
3 statements
« prev ^ index » next coverage.py v7.16.2, created at 2026-10-05 13:35 +0200
1"""OWS services.
3Base for the OWS services (``WMS``, ``WMTS``, ``WFS``, ``CSW``) implemented in ``gws.plugin.ows_server``.
5Submodules
6----------
8- ``service``: base class for services (:obj:`gws.base.ows.server.service.Object`) and its configuration.
9 Configures supported CRSs and bounds, image formats, templates and metadata, parses
10 incoming requests, dispatches them to the operation handlers and provides helpers
11 to create template, XML, image and legend responses.
12- ``request``: the service request (:obj:`gws.base.ows.server.request.Object`), which reads and validates
13 OWS parameters, resolves the project and collects the layer caps, and ``TemplateArgs``,
14 the arguments passed to service templates.
15- ``core``: data structures: ``LayerCaps``, ``FeatureCollection``, ``FeatureCollectionMember``, ``MetadataCollection``.
16- ``layer_caps``: creates ``LayerCaps`` for layers, matches layer and feature names and creates XML schemas.
17- ``error``: OWS exception classes and their XML and image responses. Each class corresponds to an
18 OWS exception code, as defined in OGC standards; the class name is the code.
19- ``templatelib``: helper functions used by service templates to generate common XML fragments.
20- ``action``: the ``ows`` action that serves the configured services over HTTP.
22Configuration
23-------------
25A service (``owsService``) can be global or project-bound. A global service can be used with any project.
27When invoked, the service locates the project (the bound project or ``projectUid`` for global services)
28and collects all suitable layers from the project.
30Layers can control their presence in OWS services using ``withOws`` and ``ows`` configs.
32The ``ows`` action is required to serve OWS services over http.
34Example::
36 actions+ { type "ows" }
38 owsServices+ {
39 type "wms"
40 uid "my_wms"
41 supportedCrs [ 3857 25832 ]
42 }
44The service is then available at ``/_/owsService/serviceUid/my_wms``.
46XML Namespaces
47--------------
49A ``WFS`` service requires each involved layer to have a configured XML namespace (with ``ows.featureName <ns>:name`` or ``ows.xmls <ns>``).
50Additionally, custom namespaces must be configured globally using ``Application.xml`` config.
52For some layers, we can autogenerate schemas for custom namespaces on the fly from the layer data.
53To use an autogenerated schema, the ``schemaLocation`` attribute for a namespace must be ``https://<server>/_/owsXml/namespace/<ns>.xsd``
54and the ``ows`` action must be enabled globally.
56Workflow
57--------
59- the ``ows`` action receives a request and locates the Service object
60- the service initializes the ``Request`` (:obj:`gws.base.ows.server.request.Object`), which determines the operation and version
61- the request locates the Project and creates a list of ``LayerCaps`` (:obj:`gws.base.ows.server.core.LayerCaps`)
62 for the layers the user can read; groups have ``children`` and ``leaves``. The list is cached per service, project and user roles
63- the service dispatches the request to the handler method of the operation (``OwsOperation.handlerName``)
64- the handler filters the caps according to parameters like ``LAYERS`` or ``TYPENAMES`` and creates a list of suitable leaf layers
65- for image requests, like ``GetMap``, the leaves are rendered, the result is converted to the requested image format and returned
66- for search requests, the service searches the leaves and creates ``FeatureCollection`` objects
67- for search and capabilities requests, a suitable template is located and rendered
68- errors are converted to OWS exception documents (:obj:`gws.base.ows.server.error.Error`)
70Example of a service template, using ``templatelib``::
72 import gws.base.ows.server as server
73 import gws.base.ows.server.templatelib as tpl
74 from gws.lib.xmlx import tag
76 def main(ta: server.TemplateArgs):
77 return tpl.to_xml_response(
78 ta,
79 tag('Capabilities', tpl.ows_service_identification(ta), tpl.ows_service_provider(ta)),
80 )
83Formats
84-------
86Standard service templates are python templates which use :func:`gws.lib.xmlx.tag` to generate nested XML responses.
88Standard image formats are ``image/png`` and ``image/jpeg``.
90Users can configure their own templates and image formats. The "supported formats" lists in OWS capabilities documents
91are created automatically, based on configured templates and image formats.
94References
95----------
97OGC Standards:
99- OpenGIS Web Map Service (WMS) Implementation Specification 1.3.0 06-042
100 https://portal.ogc.org/files/?artifact_id=14416
102- Web Map Service 1.1.1 01-068r3
103 https://portal.ogc.org/files/?artifact_id=1081&format=pdf
105- OpenGIS Web Map Tile Service Implementation Standard 1.0.0 07-057r7
106 https://portal.ogc.org/files/?artifact_id=35326
108- OpenGIS Web Feature Service 2.0 Interface Standard (also ISO 19142) 2.0 09-025r1
109 https://portal.ogc.org/files/?artifact_id=39967
111- OpenGIS Web Feature Service (WFS) Implementation Specification 1.1.0 04-094
112 https://portal.ogc.org/files/?artifact_id=8339
114- OGC Web Coverage Service (WCS) Interface Standard - Core, version 2.1 17-089r1
115 https://portal.opengeospatial.org/files/17-089r1
117- OGC Web Service Common Implementation Specification 2.0.0 06-121r9
118 https://portal.ogc.org/files/?artifact_id=38867
120Other implementations:
122- https://mapserver.org/ogc/wms_server.html
123- https://docs.geoserver.org/latest/en/user/services/wms/reference.html
124- https://mapserver.org/ogc/wfs_server.html
125- https://docs.geoserver.org/latest/en/user/services/wfs/reference.html
126- https://mapserver.org/ogc/wcs_server.html
127- https://docs.geoserver.org/latest/en/user/services/wcs/reference.html
128"""
130from .core import (
131 LayerCaps,
132 FeatureCollection,
133 FeatureCollectionMember,
134 MetadataCollection,
135)
136from . import service, layer_caps, request, error
137from .request import TemplateArgs