diff --git a/.gitignore b/.gitignore index 286bfe78ef..ba92131023 100644 --- a/.gitignore +++ b/.gitignore @@ -27,6 +27,14 @@ __pycache__/ /doc/source/contrib/print_proxy.rst /doc/source/contrib/stats.rst /doc/source/api.rst +/doc/source/contrib/print_proxy/index.rst +/doc/source/contrib/print_proxy/mapfish-print.rst +/doc/source/contrib/print_proxy/xml2pdf.rst +/doc/source/contrib/data_sources/standard/models-main.rst +/doc/source/contrib/data_sources/standard/models-theme.rst +/doc/source/contrib/data_sources/standard/models.rst +/doc/source/contrib/data_sources/swisstopo/index.rst +/doc/source/contrib/data_sources/interlis_2_3/index.rst /doc/build/ # Standard configuration diff --git a/Makefile b/Makefile index b64ea11e8c..e4cb5c0500 100644 --- a/Makefile +++ b/Makefile @@ -336,7 +336,7 @@ docker-clean-all: docker compose run --rm oereb-make clean-all .PHONY: check -check: git-attributes lint test +check: git-attributes lint tests .PHONY: doc-latex doc-latex: ${VENV_ROOT}/requirements-timestamp @@ -349,7 +349,7 @@ doc-html: ${VENV_ROOT}/requirements-timestamp $(VENV_BIN)/sphinx-build -b html doc/source doc/build/html .PHONY: updates -updates: $(PIP_REQUIREMENTS) +updates: ${VENV_ROOT}/requirements-timestamp $(VENV_BIN)/pip list --outdated .PHONY: serve-dev diff --git a/doc/images/make.build.png b/doc/images/make.build.png new file mode 100644 index 0000000000..c894e66b72 Binary files /dev/null and b/doc/images/make.build.png differ diff --git a/doc/images/make.check.png b/doc/images/make.check.png new file mode 100644 index 0000000000..7ba61a18bb Binary files /dev/null and b/doc/images/make.check.png differ diff --git a/doc/images/make.clean-all.png b/doc/images/make.clean-all.png new file mode 100644 index 0000000000..b3478abcb4 Binary files /dev/null and b/doc/images/make.clean-all.png differ diff --git a/doc/images/make.clean.png b/doc/images/make.clean.png new file mode 100644 index 0000000000..0fd88ea337 Binary files /dev/null and b/doc/images/make.clean.png differ diff --git a/doc/images/make.development.ini.png b/doc/images/make.development.ini.png new file mode 100644 index 0000000000..a5dfca4dd1 Binary files /dev/null and b/doc/images/make.development.ini.png differ diff --git a/doc/images/make.doc-html.png b/doc/images/make.doc-html.png new file mode 100644 index 0000000000..989c09348b Binary files /dev/null and b/doc/images/make.doc-html.png differ diff --git a/doc/images/make.doc-latex.png b/doc/images/make.doc-latex.png new file mode 100644 index 0000000000..878607685c Binary files /dev/null and b/doc/images/make.doc-latex.png differ diff --git a/doc/images/make.docker-clean-all.png b/doc/images/make.docker-clean-all.png new file mode 100644 index 0000000000..99b3a75bcb Binary files /dev/null and b/doc/images/make.docker-clean-all.png differ diff --git a/doc/images/make.docker-tests.png b/doc/images/make.docker-tests.png new file mode 100644 index 0000000000..8c9715a0b0 Binary files /dev/null and b/doc/images/make.docker-tests.png differ diff --git a/doc/images/make.git-attributes.png b/doc/images/make.git-attributes.png new file mode 100644 index 0000000000..63e96ca920 Binary files /dev/null and b/doc/images/make.git-attributes.png differ diff --git a/doc/images/make.install.png b/doc/images/make.install.png new file mode 100644 index 0000000000..de671d35aa Binary files /dev/null and b/doc/images/make.install.png differ diff --git a/doc/images/make.lint.png b/doc/images/make.lint.png new file mode 100644 index 0000000000..1f918bbe17 Binary files /dev/null and b/doc/images/make.lint.png differ diff --git a/doc/images/make.serve-dev.png b/doc/images/make.serve-dev.png new file mode 100644 index 0000000000..ff8797c97b Binary files /dev/null and b/doc/images/make.serve-dev.png differ diff --git a/doc/images/make.serve.png b/doc/images/make.serve.png new file mode 100644 index 0000000000..00fdfb9c9d Binary files /dev/null and b/doc/images/make.serve.png differ diff --git a/doc/images/make.test-contrib-data_sources-interlis.png b/doc/images/make.test-contrib-data_sources-interlis.png new file mode 100644 index 0000000000..e66de06735 Binary files /dev/null and b/doc/images/make.test-contrib-data_sources-interlis.png differ diff --git a/doc/images/make.test-contrib-data_sources-standard.png b/doc/images/make.test-contrib-data_sources-standard.png new file mode 100644 index 0000000000..a1fcaf3c07 Binary files /dev/null and b/doc/images/make.test-contrib-data_sources-standard.png differ diff --git a/doc/images/make.test-contrib-print_proxy-mapfish_print.png b/doc/images/make.test-contrib-print_proxy-mapfish_print.png new file mode 100644 index 0000000000..dab7a43442 Binary files /dev/null and b/doc/images/make.test-contrib-print_proxy-mapfish_print.png differ diff --git a/doc/images/make.test-contrib-stats.png b/doc/images/make.test-contrib-stats.png new file mode 100644 index 0000000000..870cc526f2 Binary files /dev/null and b/doc/images/make.test-contrib-stats.png differ diff --git a/doc/images/make.test-core.png b/doc/images/make.test-core.png new file mode 100644 index 0000000000..0465fb479d Binary files /dev/null and b/doc/images/make.test-core.png differ diff --git a/doc/images/make.test-postgis.png b/doc/images/make.test-postgis.png new file mode 100644 index 0000000000..9653a5fffd Binary files /dev/null and b/doc/images/make.test-postgis.png differ diff --git a/doc/images/make.test-postgres.png b/doc/images/make.test-postgres.png new file mode 100644 index 0000000000..e00d688971 Binary files /dev/null and b/doc/images/make.test-postgres.png differ diff --git a/doc/images/make.tests.png b/doc/images/make.tests.png new file mode 100644 index 0000000000..503d11b73d Binary files /dev/null and b/doc/images/make.tests.png differ diff --git a/doc/images/make.updates.png b/doc/images/make.updates.png new file mode 100644 index 0000000000..ba3b4a7aa8 Binary files /dev/null and b/doc/images/make.updates.png differ diff --git a/doc/source/conf.py b/doc/source/conf.py index d515d5331a..2e169b0a48 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -17,19 +17,12 @@ # documentation root, use os.path.abspath to make it absolute, like shown here. # import os -from mako.template import Template -import sys -import inspect # sys.path.insert(0, os.path.abspath('.')) import re -import types import subprocess import sphinx_rtd_theme from pyramid_oereb.core.config import Config Config._config = {'srid': -1, 'app_schema': {'name': 'pyramid_oereb_main'}} -from pyramid_oereb.contrib.data_sources.standard.sources.plr import StandardThemeConfigParser # noqa E402 -import pyramid_oereb.contrib.data_sources.standard # noqa E402 -import pyramid_oereb.contrib.data_sources.standard.models.main # noqa E402 # -- General configuration ------------------------------------------------ @@ -65,73 +58,30 @@ '../../.venv/bin/mako-render' if os.path.exists('../../.venv/bin/mako-render') else 'mako-render', 'core/sources.rst.mako']).decode('utf-8')) -with open('standard/sources.rst', 'w') as sources: - sources.write(subprocess.check_output([ - '../../.venv/bin/mako-render' if os.path.exists('../../.venv/bin/mako-render') else 'mako-render', - 'standard/sources.rst.mako']).decode('utf-8')) - -with open('contrib/sources.rst', 'w') as sources: - sources.write(subprocess.check_output([ - '../../.venv/bin/mako-render' if os.path.exists('../../.venv/bin/mako-render') else 'mako-render', - 'contrib/sources.rst.mako']).decode('utf-8')) - -with open('contrib/print_proxy.rst', 'w') as sources: - sources.write(subprocess.check_output([ - '../../.venv/bin/mako-render' if os.path.exists('../../.venv/bin/mako-render') else 'mako-render', - 'contrib/print_proxy.rst.mako']).decode('utf-8')) - with open('contrib/stats.rst', 'w') as sources: sources.write(subprocess.check_output([ '../../.venv/bin/mako-render' if os.path.exists('../../.venv/bin/mako-render') else 'mako-render', 'contrib/stats.rst.mako']).decode('utf-8')) +target_paths = [ + 'contrib/data_sources/standard/index.rst', + 'contrib/data_sources/standard/models.rst', + 'contrib/data_sources/standard/models-main.rst', + 'contrib/data_sources/standard/models-theme.rst', + 'contrib/data_sources/standard/sources.rst', + 'contrib/data_sources/interlis_2_3/index.rst', + 'contrib/data_sources/oereblex/index.rst', + 'contrib/data_sources/swisstopo/index.rst', + 'contrib/data_sources/index.rst', + 'contrib/print_proxy/index.rst', + 'contrib/print_proxy/mapfish-print.rst', + 'contrib/print_proxy/xml2pdf.rst' +] -module_file_names = [] -module_name = 'pyramid_oereb.contrib.data_sources.standard.models.main' -file_name = 'pyramid_oereb_contrib_data_sources_standard_models_main' -module_file_names.append(file_name) -main_classes = [] -for name, obj in inspect.getmembers(pyramid_oereb.contrib.data_sources.standard.models.main): - if inspect.isclass(obj) and obj.__module__ == module_name: - main_classes.append(name) -with open('standard/models/{name}.rst'.format(name=file_name), 'w') as sources: - template = Template(filename='standard/models/models.rst.mako') - sources.write(template.render(**{'module_name': module_name, 'classes': main_classes})) - -conf_parser = StandardThemeConfigParser(source={ - "class": 'pyramid_oereb.contrib.data_sources.standard.sources.plr.DatabaseSource', - "params": { - "model_factory": "pyramid_oereb.contrib.data_sources.standard.models.theme.model_factory_string_pk", - "schema_name": "land_use_plans" - } -}) - -models = conf_parser.get_models() -modelnames = [modelname for modelname in dir(models) if modelname[0].isupper() and modelname != 'Base'] - -# create fake python module pyramid_oereb.contrib.data_sources.standard.factory_models -factory_models = types.ModuleType('FactoryModels', 'Virtual module for factory generated classes') -factory_models.__name__ = 'factory_models' -factory_models.__mro__ = [] -factory_models.__module__ = 'pyramid_oereb.contrib.data_sources.standard' -for modelname in modelnames: - model = models.__getattribute__(modelname) - model.__name__ = modelname - model.__module__ = 'pyramid_oereb.contrib.data_sources.standard.factory_models' - factory_models.__dict__.update({modelname: model}) - -pyramid_oereb.contrib.data_sources.standard.__dict__.update({'factory_models': factory_models}) -sys.modules['pyramid_oereb.contrib.data_sources.standard.factory_models'] = factory_models - -module_name = 'pyramid_oereb.contrib.data_sources.standard.factory_models' -file_name = module_name.replace('.', '_').lower() -module_file_names.append(file_name) -with open('standard/models/{name}.rst'.format(name=file_name), 'w') as sources: - template = Template(filename='standard/models/factory_models.rst.mako') - sources.write(template.render(**{'module_name': module_name, 'classes': modelnames})) - -with open('standard/models/index.rst', 'w') as sources: - template = Template(filename='standard/models/index.rst.mako') - sources.write(template.render(**{'module_file_names': module_file_names})) +for target_path in target_paths: + with open(target_path, 'w') as sources: + sources.write(subprocess.check_output([ + '../../.venv/bin/mako-render' if os.path.exists('../../.venv/bin/mako-render') else 'mako-render', + f'{target_path}.mako']).decode('utf-8')) # Add any paths that contain templates here, relative to this directory. templates_path = ['doc/_buildtemplates'] diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst index 60bad426a1..5bdea24ad4 100644 --- a/doc/source/configuration.rst +++ b/doc/source/configuration.rst @@ -109,48 +109,6 @@ structure. This method is recommended if you are using an existing database supp already containing all the necessary data but in a different structure. In this case you should check, if it is possible to transform the data by extending the existing models with a mapping to fit your structure. -The easiest example is a simple mapping of table and column names, if you use a different language. Using the -possibilities of SQLAlchemy, you could extend the existing -:ref:`api-pyramid_oereb-standard-models-motorways_building_lines-office` like this: - -.. code-block:: python - - from pyramid_oereb.lib.standard.models import motorways_building_lines - - class Office(motorways_building_lines.Office): - """ - The bucket to fill in all the offices you need to reference from public law restriction, - document, geometry. - - Attributes: - id (int): The identifier. This is used in the database only and must not be set manually. - If you don't like it - don't care about. - name (dict): The multilingual name of the office. - office_at_web (str): A web accessible url to a presentation of this office. - uid (str): The uid of this office from https - line1 (str): The first address line for this office. - line2 (str): The second address line for this office. - street (str): The streets name of the offices address. - number (str): The number on street. - postal_code (int): The ZIP-code. - city (str): The name of the city. - """ - __table_args__ = {'schema': 'baulinien_nationalstrassen'} - __tablename__ = 'amt' - id = sa.Column('oid', sa.Integer, primary_key=True) - office_at_web = sa.Column('amt_im_web', sa.String, nullable=True) - line1 = sa.Column('zeile1', sa.String, nullable=True) - line2 = sa.Column('zeile2', sa.String, nullable=True) - street = sa.Column('strasse', sa.String, nullable=True) - number = sa.Column('hausnr', sa.String, nullable=True) - postal_code = sa.Column('plz', sa.Integer, nullable=True) - city = sa.Column('ort', sa.String, nullable=True) - - (...) - -The only thing, you have to care about, if you want to stay using the standard sources, is to keep the class -name, the names of the properties and their data types. - After extending the models, do not forget to change the models module in the configuration of the topic's source. @@ -204,11 +162,11 @@ restrictions on implementing a custom source: 1. The source has to implement the method `read()` with the arguments used in its base source. For example, your custom real estate source has to accept the arguments defined in - :ref:`api-pyramid_oereb-lib-sources-real_estate-realestatebasesource`. + :ref:`api-pyramid_oereb-contrib-data_sources-standard-sources-real_estate-databasesource`. 2. The method `read()` has to add records of the corresponding type to the source' records list. Every source has list property called `records`. In case of a real estate source, the method `read()` has to - create one or more instances of the :ref:`api-pyramid_oereb-lib-records-real_estate-realestaterecord` + create one or more instances of the :ref:`api-pyramid_oereb-core-records-real_estate-realestaterecord` and add them to this list. This way, you should be able to create sources for nearly every possible data source. diff --git a/doc/source/contrib/data_sources/index.rst b/doc/source/contrib/data_sources/index.rst new file mode 100644 index 0000000000..4510799391 --- /dev/null +++ b/doc/source/contrib/data_sources/index.rst @@ -0,0 +1,29 @@ +.. _contrib-data-sources: + +Data Sources +------------ + +``pyramid_oereb`` provides a plugable system to offer an extendable system. The most +interesting part of that is probably the extension of what data sources should be +connected to the core system of ``pyramid_oereb``. + +As of now ``pyramid_oereb`` offers the following data sources (db structures) you can store +your data to: + +* :ref:`contrib-data-sources-standard` +* oereblex +* interlis 2.3 + + + +In addition there is a source to use with the address localisation: + +* swisstopo + +.. toctree:: + :hidden: + + standard/index + oereblex/index + interlis_2_3/index + swisstopo/index diff --git a/doc/source/contrib/data_sources/index.rst.mako b/doc/source/contrib/data_sources/index.rst.mako new file mode 100644 index 0000000000..4510799391 --- /dev/null +++ b/doc/source/contrib/data_sources/index.rst.mako @@ -0,0 +1,29 @@ +.. _contrib-data-sources: + +Data Sources +------------ + +``pyramid_oereb`` provides a plugable system to offer an extendable system. The most +interesting part of that is probably the extension of what data sources should be +connected to the core system of ``pyramid_oereb``. + +As of now ``pyramid_oereb`` offers the following data sources (db structures) you can store +your data to: + +* :ref:`contrib-data-sources-standard` +* oereblex +* interlis 2.3 + + + +In addition there is a source to use with the address localisation: + +* swisstopo + +.. toctree:: + :hidden: + + standard/index + oereblex/index + interlis_2_3/index + swisstopo/index diff --git a/doc/source/contrib/data_sources/interlis_2_3/index.rst.mako b/doc/source/contrib/data_sources/interlis_2_3/index.rst.mako new file mode 100644 index 0000000000..3778e91557 --- /dev/null +++ b/doc/source/contrib/data_sources/interlis_2_3/index.rst.mako @@ -0,0 +1,9 @@ +.. _contrib-data-sources-interlis-23: + +INTERLIS 2.3 +============ + + + +.. toctree:: + :hidden: diff --git a/doc/source/contrib/data_sources/oereblex/index.rst b/doc/source/contrib/data_sources/oereblex/index.rst new file mode 100644 index 0000000000..6e0835218a --- /dev/null +++ b/doc/source/contrib/data_sources/oereblex/index.rst @@ -0,0 +1,8 @@ +.. _contrib-data-sources-oereblex: + +ÖREBlex +======= + + +.. toctree:: + :hidden: diff --git a/doc/source/contrib/data_sources/oereblex/index.rst.mako b/doc/source/contrib/data_sources/oereblex/index.rst.mako new file mode 100644 index 0000000000..6e0835218a --- /dev/null +++ b/doc/source/contrib/data_sources/oereblex/index.rst.mako @@ -0,0 +1,8 @@ +.. _contrib-data-sources-oereblex: + +ÖREBlex +======= + + +.. toctree:: + :hidden: diff --git a/doc/source/contrib/data_sources/standard/index.rst.mako b/doc/source/contrib/data_sources/standard/index.rst.mako new file mode 100644 index 0000000000..a00d92210b --- /dev/null +++ b/doc/source/contrib/data_sources/standard/index.rst.mako @@ -0,0 +1,43 @@ +.. _contrib-data-sources-standard: + +Standard +^^^^^^^^ + +The standard data source is a binding to a database following the definitions of +`OeREBKRMkvs_V2_0 `__ +and `OeREBKRMtrsfr_V2_0 `__ +but adds some magic sugar for convenience. + +Exemplary schema of a standard database: + + .. image:: ../../../../images/standard_database_schema_example.png + :scale: 20 % + :align: center + +This structure is defined as models for SQL-Alchemy ORM and as a fitting set of +DataBaseSource-Adapters to hook it into the core of ``pyramid_oereb``. The models +defined in this contribution package describing 2 different structures. The ``main`` +definitions are used by ``pyramid_oereb`` application itself and contain the application +configuration as suggested in +`OeREBKRMkvs_V2_0 `__. +The ``theme`` definitions define a single ÖREB-Theme as it is suggested by +`OeREBKRMtrsfr_V2_0 `__. +Please be aware that for performance reasons the schematic mapping of SQL-Alchemy ORM +definitions and the linked INTERLIS models is not 1:1. + +The definition of main and theme schema share some classes. These are provided via +factory methods at modul level. These methods can be found here :ref:`contrib-data-sources-standard-models` + +* :ref:`contrib-data-sources-standard-models` +* :ref:`contrib-data-sources-standard-models-main` +* :ref:`contrib-data-sources-standard-models-theme` +* :ref:`contrib-data-sources-standard-sources` + + +.. toctree:: + :hidden: + + models + models-main + models-theme + sources diff --git a/doc/source/contrib/sources.rst.mako b/doc/source/contrib/data_sources/standard/models-main.rst.mako similarity index 72% rename from doc/source/contrib/sources.rst.mako rename to doc/source/contrib/data_sources/standard/models-main.rst.mako index 37909edd2b..5e3ef5acd0 100644 --- a/doc/source/contrib/sources.rst.mako +++ b/doc/source/contrib/data_sources/standard/models-main.rst.mako @@ -1,20 +1,23 @@ -.. _contrib-sources: +.. _contrib-data-sources-standard-models-main: -Sources -------- +ORM Main schema +``````````````` -<%! import glob, inspect, re, sys %> +<%! +import glob, inspect, re, sys +from pyramid_oereb.core.config import Config +Config._config = {'srid': -1, 'app_schema': {'name': 'pyramid_oereb_main'}} +%> <% modules = [m for m in sys.modules.keys() if m.startswith('pyramid_oereb')] -files = glob.glob('../../pyramid_oereb/contrib/data_sources/oereblex/sources/*.py') -files += glob.glob('../../pyramid_oereb/contrib/data_sources/swisstopo/*.py') -files += glob.glob('../../pyramid_oereb/contrib/data_sources/interlis_2_3/sources/*.py') +files = glob.glob('../../pyramid_oereb/contrib/data_sources/standard/models/main.py') modules = [ re.sub(r'\.__init__', '', f[6:-3].replace("/", ".")) for f in files ] - modules.sort() + delete_modules = [] + for i, module in enumerate(modules): try: __import__(module) @@ -39,16 +42,16 @@ underline = ['^', '`', '\'', '.', '~', '*'] .. automodule:: ${module} - %for cls in classes[module]: .. _api-${module.replace('.', '-').lower()}-${cls.lower()}: *${cls}* -${re.sub('.', underline[0], 'Class ' + cls)} +${underline[2]*len("*"+cls+"*")} .. autoclass:: ${module}.${cls} :members: :inherited-members: + :show-inheritance: .. automethod:: __init__ diff --git a/doc/source/contrib/data_sources/standard/models-theme.rst.mako b/doc/source/contrib/data_sources/standard/models-theme.rst.mako new file mode 100644 index 0000000000..19fb718bc6 --- /dev/null +++ b/doc/source/contrib/data_sources/standard/models-theme.rst.mako @@ -0,0 +1,59 @@ +.. _contrib-data-sources-standard-models-theme: + +ORM Theme schema +```````````````` + +<%! +import glob, inspect, re, sys +from pyramid_oereb.core.config import Config +Config._config = {'srid': -1, 'app_schema': {'name': 'pyramid_oereb_main'}} +%> +<% +modules = [m for m in sys.modules.keys() if m.startswith('pyramid_oereb')] +files = glob.glob('../../pyramid_oereb/contrib/data_sources/standard/models/theme.py') +modules = [ + re.sub(r'\.__init__', '', f[6:-3].replace("/", ".")) for f in files +] +modules.sort() + +delete_modules = [] + +for i, module in enumerate(modules): + try: + __import__(module) + except ImportError: + delete_modules.append(i) +delete_modules.reverse() +for i in delete_modules: + del modules[i] + +classes = {} +for module in modules: + classes[module] = [] + for name, obj in inspect.getmembers(sys.modules[module]): + if inspect.isclass(obj) and obj.__module__ == module: + classes[module].append(name) + +underline = ['^', '`', '\'', '.', '~', '*'] +%> + +%for module in modules: +.. _api-${module.replace('.', '-').lower()}: + +.. automodule:: ${module} + +%for cls in classes[module]: +.. _api-${module.replace('.', '-').lower()}-${cls.lower()}: + +*${module.split('.')[-1].title()} ${cls}* +${underline[2]*len("*"+module.split('.')[-1].title()+' '+cls+"*")} + +.. autoclass:: ${module}.${cls} + :members: + :inherited-members: + :show-inheritance: + + .. automethod:: __init__ + +%endfor +%endfor \ No newline at end of file diff --git a/doc/source/contrib/data_sources/standard/models.rst.mako b/doc/source/contrib/data_sources/standard/models.rst.mako new file mode 100644 index 0000000000..2086500cb6 --- /dev/null +++ b/doc/source/contrib/data_sources/standard/models.rst.mako @@ -0,0 +1,6 @@ +.. _contrib-data-sources-standard-models: + +ORM Common +`````````` +.. automodule:: pyramid_oereb.contrib.data_sources.standard.models + :members: diff --git a/doc/source/contrib/data_sources/standard/sources.rst b/doc/source/contrib/data_sources/standard/sources.rst new file mode 100644 index 0000000000..6331327bfe --- /dev/null +++ b/doc/source/contrib/data_sources/standard/sources.rst @@ -0,0 +1,328 @@ +.. _contrib-data-sources-standard-sources: + +Sources +``````` + + + + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources: + +.. automodule:: pyramid_oereb.contrib.data_sources.standard.sources + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-address: + +.. automodule:: pyramid_oereb.contrib.data_sources.standard.sources.address + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-address-databasesource: + +*Address* +''''''''' + +.. autoclass:: pyramid_oereb.contrib.data_sources.standard.sources.address.DatabaseSource + :members: + :inherited-members: + :show-inheritance: + + .. automethod:: __init__ + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-availability: + +.. automodule:: pyramid_oereb.contrib.data_sources.standard.sources.availability + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-availability-databasesource: + +*Availability* +'''''''''''''' + +.. autoclass:: pyramid_oereb.contrib.data_sources.standard.sources.availability.DatabaseSource + :members: + :inherited-members: + :show-inheritance: + + .. automethod:: __init__ + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-data_integration: + +.. automodule:: pyramid_oereb.contrib.data_sources.standard.sources.data_integration + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-data_integration-databasesource: + +*Data_Integration* +'''''''''''''''''' + +.. autoclass:: pyramid_oereb.contrib.data_sources.standard.sources.data_integration.DatabaseSource + :members: + :inherited-members: + :show-inheritance: + + .. automethod:: __init__ + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-disclaimer: + +.. automodule:: pyramid_oereb.contrib.data_sources.standard.sources.disclaimer + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-disclaimer-databasesource: + +*Disclaimer* +'''''''''''' + +.. autoclass:: pyramid_oereb.contrib.data_sources.standard.sources.disclaimer.DatabaseSource + :members: + :inherited-members: + :show-inheritance: + + .. automethod:: __init__ + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-document: + +.. automodule:: pyramid_oereb.contrib.data_sources.standard.sources.document + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-document-databasesource: + +*Document* +'''''''''' + +.. autoclass:: pyramid_oereb.contrib.data_sources.standard.sources.document.DatabaseSource + :members: + :inherited-members: + :show-inheritance: + + .. automethod:: __init__ + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-document_types: + +.. automodule:: pyramid_oereb.contrib.data_sources.standard.sources.document_types + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-document_types-databasesource: + +*Document_Types* +'''''''''''''''' + +.. autoclass:: pyramid_oereb.contrib.data_sources.standard.sources.document_types.DatabaseSource + :members: + :inherited-members: + :show-inheritance: + + .. automethod:: __init__ + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-general_information: + +.. automodule:: pyramid_oereb.contrib.data_sources.standard.sources.general_information + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-general_information-databasesource: + +*General_Information* +''''''''''''''''''''' + +.. autoclass:: pyramid_oereb.contrib.data_sources.standard.sources.general_information.DatabaseSource + :members: + :inherited-members: + :show-inheritance: + + .. automethod:: __init__ + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-glossary: + +.. automodule:: pyramid_oereb.contrib.data_sources.standard.sources.glossary + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-glossary-databasesource: + +*Glossary* +'''''''''' + +.. autoclass:: pyramid_oereb.contrib.data_sources.standard.sources.glossary.DatabaseSource + :members: + :inherited-members: + :show-inheritance: + + .. automethod:: __init__ + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-law_status: + +.. automodule:: pyramid_oereb.contrib.data_sources.standard.sources.law_status + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-law_status-databasesource: + +*Law_Status* +'''''''''''' + +.. autoclass:: pyramid_oereb.contrib.data_sources.standard.sources.law_status.DatabaseSource + :members: + :inherited-members: + :show-inheritance: + + .. automethod:: __init__ + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-legend: + +.. automodule:: pyramid_oereb.contrib.data_sources.standard.sources.legend + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-legend-databasesource: + +*Legend* +'''''''' + +.. autoclass:: pyramid_oereb.contrib.data_sources.standard.sources.legend.DatabaseSource + :members: + :inherited-members: + :show-inheritance: + + .. automethod:: __init__ + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-logo: + +.. automodule:: pyramid_oereb.contrib.data_sources.standard.sources.logo + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-logo-databasesource: + +*Logo* +'''''' + +.. autoclass:: pyramid_oereb.contrib.data_sources.standard.sources.logo.DatabaseSource + :members: + :inherited-members: + :show-inheritance: + + .. automethod:: __init__ + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-map_layering: + +.. automodule:: pyramid_oereb.contrib.data_sources.standard.sources.map_layering + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-map_layering-databasesource: + +*Map_Layering* +'''''''''''''' + +.. autoclass:: pyramid_oereb.contrib.data_sources.standard.sources.map_layering.DatabaseSource + :members: + :inherited-members: + :show-inheritance: + + .. automethod:: __init__ + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-municipality: + +.. automodule:: pyramid_oereb.contrib.data_sources.standard.sources.municipality + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-municipality-databasesource: + +*Municipality* +'''''''''''''' + +.. autoclass:: pyramid_oereb.contrib.data_sources.standard.sources.municipality.DatabaseSource + :members: + :inherited-members: + :show-inheritance: + + .. automethod:: __init__ + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-office: + +.. automodule:: pyramid_oereb.contrib.data_sources.standard.sources.office + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-office-databasesource: + +*Office* +'''''''' + +.. autoclass:: pyramid_oereb.contrib.data_sources.standard.sources.office.DatabaseSource + :members: + :inherited-members: + :show-inheritance: + + .. automethod:: __init__ + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-plr: + +.. automodule:: pyramid_oereb.contrib.data_sources.standard.sources.plr + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-plr-databasesource: + +*Plr* +''''' + +.. autoclass:: pyramid_oereb.contrib.data_sources.standard.sources.plr.DatabaseSource + :members: + :inherited-members: + :show-inheritance: + + .. automethod:: __init__ + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-plr-standardthemeconfigparser: + +*Plr* +''''' + +.. autoclass:: pyramid_oereb.contrib.data_sources.standard.sources.plr.StandardThemeConfigParser + :members: + :inherited-members: + :show-inheritance: + + .. automethod:: __init__ + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-real_estate: + +.. automodule:: pyramid_oereb.contrib.data_sources.standard.sources.real_estate + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-real_estate-databasesource: + +*Real_Estate* +''''''''''''' + +.. autoclass:: pyramid_oereb.contrib.data_sources.standard.sources.real_estate.DatabaseSource + :members: + :inherited-members: + :show-inheritance: + + .. automethod:: __init__ + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-real_estate_type: + +.. automodule:: pyramid_oereb.contrib.data_sources.standard.sources.real_estate_type + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-real_estate_type-databasesource: + +*Real_Estate_Type* +'''''''''''''''''' + +.. autoclass:: pyramid_oereb.contrib.data_sources.standard.sources.real_estate_type.DatabaseSource + :members: + :inherited-members: + :show-inheritance: + + .. automethod:: __init__ + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-theme: + +.. automodule:: pyramid_oereb.contrib.data_sources.standard.sources.theme + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-theme-databasesource: + +*Theme* +''''''' + +.. autoclass:: pyramid_oereb.contrib.data_sources.standard.sources.theme.DatabaseSource + :members: + :inherited-members: + :show-inheritance: + + .. automethod:: __init__ + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-theme_document: + +.. automodule:: pyramid_oereb.contrib.data_sources.standard.sources.theme_document + +.. _api-pyramid_oereb-contrib-data_sources-standard-sources-theme_document-databasesource: + +*Theme_Document* +'''''''''''''''' + +.. autoclass:: pyramid_oereb.contrib.data_sources.standard.sources.theme_document.DatabaseSource + :members: + :inherited-members: + :show-inheritance: + + .. automethod:: __init__ + diff --git a/doc/source/standard/sources.rst.mako b/doc/source/contrib/data_sources/standard/sources.rst.mako similarity index 77% rename from doc/source/standard/sources.rst.mako rename to doc/source/contrib/data_sources/standard/sources.rst.mako index f33f9f3c18..baacd33f07 100644 --- a/doc/source/standard/sources.rst.mako +++ b/doc/source/contrib/data_sources/standard/sources.rst.mako @@ -1,18 +1,19 @@ -.. _standard-sources: +.. _contrib-data-sources-standard-sources: Sources -------- +``````` -<%! import glob, inspect, re, sys %> +<%! import glob, inspect, re, sys%> <% modules = [m for m in sys.modules.keys() if m.startswith('pyramid_oereb')] -files = glob.glob('../../pyramid_oereb/core/sources/*.py') +files = glob.glob('../../pyramid_oereb/contrib/data_sources/standard/sources/*.py') modules = [ re.sub(r'\.__init__', '', f[6:-3].replace("/", ".")) for f in files ] - modules.sort() + delete_modules = [] + for i, module in enumerate(modules): try: __import__(module) @@ -37,16 +38,16 @@ underline = ['^', '`', '\'', '.', '~', '*'] .. automodule:: ${module} - %for cls in classes[module]: .. _api-${module.replace('.', '-').lower()}-${cls.lower()}: -*${module.split('.')[-1].title().replace('_', ' ')} ${cls}* -${re.sub('.', underline[0], module.split('.')[-1] + ' ' + cls)} +*${module.split('.')[-1].title()}* +${underline[2]*len("*"+module.split('.')[-1].title()+"*")} .. autoclass:: ${module}.${cls} :members: :inherited-members: + :show-inheritance: .. automethod:: __init__ diff --git a/doc/source/contrib/data_sources/swisstopo/index.rst.mako b/doc/source/contrib/data_sources/swisstopo/index.rst.mako new file mode 100644 index 0000000000..0e01c4d6cb --- /dev/null +++ b/doc/source/contrib/data_sources/swisstopo/index.rst.mako @@ -0,0 +1,10 @@ +.. _contrib-data-sources-swisstopo: + +Swisstopo Adapter +================= + + + + +.. toctree:: + :hidden: diff --git a/doc/source/contrib/index.rst b/doc/source/contrib/index.rst index 5c7d3c1c31..7226a35e46 100644 --- a/doc/source/contrib/index.rst +++ b/doc/source/contrib/index.rst @@ -10,7 +10,7 @@ Would you like to contribute to the project? Please see :ref:`contributing`. .. toctree:: :hidden: - sources - print_proxy - stats contributing + data_sources/index + print_proxy/index + stats diff --git a/doc/source/contrib/print_proxy/index.rst.mako b/doc/source/contrib/print_proxy/index.rst.mako new file mode 100644 index 0000000000..6832405611 --- /dev/null +++ b/doc/source/contrib/print_proxy/index.rst.mako @@ -0,0 +1,20 @@ +.. _contrib-print-proxy: + +Print Proxy +----------- + +Part of ``pyramid_oereb`` plugable system is also the production of PDF files of the extracts. + +It is solved via a proxy approach. The extract is passed to a service which knows how to produce a PDF +satisfying the federal specifications. + +As of now ``pyramid_oereb`` offers the following print proxies: + +* :ref:`contrib-print_proxy-mapfish-print` +* :ref:`contrib-print_proxy-xml2pdf` + +.. toctree:: + :hidden: + + mapfish-print + xml2pdf diff --git a/doc/source/contrib/print_proxy.rst.mako b/doc/source/contrib/print_proxy/mapfish-print.rst.mako similarity index 79% rename from doc/source/contrib/print_proxy.rst.mako rename to doc/source/contrib/print_proxy/mapfish-print.rst.mako index 21d052163e..d6484cfc73 100644 --- a/doc/source/contrib/print_proxy.rst.mako +++ b/doc/source/contrib/print_proxy/mapfish-print.rst.mako @@ -1,13 +1,59 @@ -.. _contrib-print_proxy: +.. _contrib-print_proxy-mapfish-print: -Print Proxy ------------ +Mapfish Print +------------- + +Configuration +^^^^^^^^^^^^^ + +Sub themes +.......... + +To enable separate pages per sub theme, enable the option `split_sub_themes` in the `print` section of your +configuration. + + +.. code-block:: yaml + + print: + split_sub_themes: true + +Sorting +....... + +You can influence the sort order for each theme separately. Per default, the sub themes are unsorted. + +Example for alphabetic sort: + +.. code-block:: yaml + + - name: plr119 + sub_themes: + sorter: + module: pyramid_oereb.contrib.print_proxy.sub_themes.sorting + class_name: AlphabeticSort + + +The list sort provides a fix, non-alphabetic order. A ordered list as parameter defines the order. The sub theme names +have to match exactly, otherwise they will be added at the end. Example configuration: + +.. code-block:: yaml + + - name: plr119 + sub_themes: + sorter: + module: pyramid_oereb.contrib.print_proxy.sub_themes.sorting + class_name: ListSort + params: + list: + - First sub theme + - Another sub theme + - Last sub theme <%! import glob, inspect, re, sys %> <% modules = [m for m in sys.modules.keys() if m.startswith('pyramid_oereb')] files = glob.glob('../../pyramid_oereb/contrib/print_proxy/mapfish_print/*.py') -files += glob.glob('../../pyramid_oereb/contrib/print_proxy/xml_2_pdf/*.py') modules = [ re.sub(r'\.__init__', '', f[6:-3].replace("/", ".")) for f in files ] @@ -53,57 +99,3 @@ ${re.sub('.', underline[0], module.split('.')[-1] + ' ' + cls)} %endfor %endfor - - -Sub themes ----------- - -To enable separate pages per sub theme, enable the option `split_sub_themes` in the `print` section of your -configuration. - - -.. code-block:: yaml - - print: - split_sub_themes: true - - -You can influence the sort order for each theme separately. Per default, the sub themes are unsorted. - -Example for alphabetic sort: - -.. code-block:: yaml - - - name: plr119 - sub_themes: - sorter: - module: pyramid_oereb.contrib.print_proxy.sub_themes.sorting - class_name: AlphabeticSort - - -The list sort provides a fix, non-alphabetic order. A ordered list as parameter defines the order. The sub theme names -have to match exactly, otherwise they will be added at the end. Example configuration: - -.. code-block:: yaml - - - name: plr119 - sub_themes: - sorter: - module: pyramid_oereb.contrib.print_proxy.sub_themes.sorting - class_name: ListSort - params: - list: - - First sub theme - - Another sub theme - - Last sub theme - -Print configuration -------------------- - -**XML2PDF** - -To properly configure the XML2PDF print service of GISDATEN AG, you need specific configuration in the section -``print`` of your ``yaml`` file. -Please see the `standard configuration file -`__ -as an example, or use the ``create_standard_yaml`` script to regenerate your configuration file with the desired options. diff --git a/doc/source/contrib/print_proxy/xml2pdf.rst.mako b/doc/source/contrib/print_proxy/xml2pdf.rst.mako new file mode 100644 index 0000000000..05df0d6378 --- /dev/null +++ b/doc/source/contrib/print_proxy/xml2pdf.rst.mako @@ -0,0 +1,64 @@ +.. _contrib-print_proxy-xml2pdf: + +XML2PDF +------- + +Configuration +............. + + +To properly configure the XML2PDF print service of GISDATEN AG, you need specific configuration in the section +``print`` of your ``yaml`` file. +Please see the `standard configuration file +`__ +as an example, or use the ``create_standard_yaml`` script to regenerate your configuration file with the desired options. + +<%! import glob, inspect, re, sys %> +<% +modules = [m for m in sys.modules.keys() if m.startswith('pyramid_oereb')] +files = glob.glob('../../pyramid_oereb/contrib/print_proxy/xml_2_pdf/*.py') +modules = [ + re.sub(r'\.__init__', '', f[6:-3].replace("/", ".")) for f in files +] + +modules.sort() +delete_modules = [] +for i, module in enumerate(modules): + try: + __import__(module) + except ImportError: + delete_modules.append(i) +delete_modules.reverse() +for i in delete_modules: + del modules[i] + +classes = {} +for module in modules: + classes[module] = [] + for name, obj in inspect.getmembers(sys.modules[module]): + if inspect.isclass(obj) and obj.__module__ == module: + classes[module].append(name) + +underline = ['^', '`', '\'', '.', '~', '*'] +%> + +%for module in modules: +.. _api-${module.replace('.', '-').lower()}: + +.. automodule:: ${module} + + +%for cls in classes[module]: +.. _api-${module.replace('.', '-').lower()}-${cls.lower()}: + +*${module.split('.')[-1].title().replace('_', ' ')} ${cls}* +${re.sub('.', underline[0], module.split('.')[-1] + ' ' + cls)} + +.. autoclass:: ${module}.${cls} + :members: + :inherited-members: + + .. automethod:: __init__ + +%endfor +%endfor diff --git a/doc/source/contrib/stats.rst.mako b/doc/source/contrib/stats.rst.mako index 666c8d8ba6..29e4aaa98d 100644 --- a/doc/source/contrib/stats.rst.mako +++ b/doc/source/contrib/stats.rst.mako @@ -1,7 +1,7 @@ .. _contrib-stats: Statistics -========== +---------- The statistics functionality allows you to gather usage information within pyramid_oereb itself. The data gathered will be persisted in user defined configured database, @@ -14,7 +14,7 @@ to define in addition standard reporting views, see :ref:`standard-reporting` fo Configuration -------------- +^^^^^^^^^^^^^ The functionality is configured via the server's ini file; see the project repository for a complete example of such an ini file. Example of a configuration suitable for usage with Gunicorn: @@ -83,7 +83,7 @@ then you should at least set 'healtcheck' explicitely and the logger will avoid .. _standard-reporting: Standard reporting ------------------- +^^^^^^^^^^^^^^^^^^ To fulfill the most common needs for statistics reporting, we recommend the usage of database views based on the raw data table. You can create these views using the script *create_stats_tables*, or @@ -170,7 +170,7 @@ by creating the following views in your database manually, and adapting them if Implementation --------------- +^^^^^^^^^^^^^^ <%! import glob, inspect, re, sys %> <% diff --git a/doc/source/index.rst b/doc/source/index.rst index 5915a2227a..4b481ced4a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -11,9 +11,10 @@ pyramid_oereb (ÖREB-Server) documentation :hidden: installation + installation-dev + makefile configuration changes - standard/index contrib/index core/index faq @@ -48,11 +49,12 @@ The server provides access to the 4 services: * GetCapabilities * GetVersions -The server is able to use ÖEREBlex, GeoAdmin API for gathering data. This needs to be configured and prepared -by the integrator of this package. In addition a small tool for loading legend symbols for each used WMS layer -is included. +The server is able to use several specific external api endpoints to fetch data at runtime (e.g. ÖEREBlex or GeoAdmin +API). These need to be configured and prepared by the integrator of this package. Please read the dedicated part +of documentation. -For the moment we provide an adapter to get the PDF static extract from mapfishprint. +For the moment we provide an adapter to get the PDF static extract from mapfishprint and +`oereb_xml_pdf_service `__. .. image:: ../images/overview.png :align: center diff --git a/doc/source/installation-dev.rst b/doc/source/installation-dev.rst new file mode 100644 index 0000000000..23a864f8d4 --- /dev/null +++ b/doc/source/installation-dev.rst @@ -0,0 +1,13 @@ +.. _installation-dev: + +Installation for DEV's +====================== + +``pyramid_oereb`` is a piece of python software following the rules of the pyramid webframework. To develop +features there are basically two ways to setup: + +# Docker/Docker-Compose +# local system python with a virtualenv + +We recommend the Docker way since ``pyramid_oereb`` has dependencies around the geos/gdal/ogr stack which +might easily conflict with versions installed in a daily used system and therefore might lead to problems.`__. @@ -26,6 +26,79 @@ In order to install and run an instance of ``pyramid_oereb``, the following requ should be able to use any spatial database, that is supported by `SQLAlchemy `__ and `GeoAlchemy 2 `__. +3. **A Service to produce PDF extracts:** + This might be a externally running instance of `oereb_xml_pdf_service `__ + (needs registration). Or you can use a self-hosted instance of `mapfish-print `__ + prepared for the ÖREB extract. + +To straighten this guide we will run them inside a docker composition. This puts aside local differences +like OS (Mac, Windows, Linux) and safes you from conflicts of maybe already running and conflicting services +from your other projects + +.. _installation-docker-docker-compose: + +Docker/Docker-Compose +--------------------- + +.. note:: We assume you have a working + `docker `__/`docker-compose `__ + and `git `__ setup on your machine. + +First we need to get the code. Clone the pyramid_oereb repository in a place of your choice on your machine: + +.. code-block:: shell + + git clone https://github.com/openoereb/pyramid_oereb.git + +CD into the created directory: + +.. code-block:: shell + + cd pyramid_oereb + +Docker separates runtimes in so called containers. What is inside a container is defined in an image. These +images are described by so called Dockerfiles. This repository contains an ``Dockerfile`` in the project root +in case you want to have a look. A container can be considered existing only at runtime. Once +it was stopped, all things inside are gone. Each service (pyramid_oereb, database, print-server) will be +run in its own container. + +As we learned above ``pyramid_oereb`` needs different services. The organisation of these services can be done +by docker-compose. The description of the composition is persisted in a ``docker-compose.yml`` file. + +Additionally a docker container can utilize so called ``volumes`` to persist data from inside the container +over restarts. This is useful especially for configuration but also for data you do not want to be gone after +containers were stopped. Think of the data you insert into you database or all the python packages you install +from the web. Wouldn't it be nice to keep them even your containers are stopped? Well... exactly this is how +this repositories docker composition is set up. + +The following steps are required to get a running setup: + +#. build docker images locally +#. setup pyramid_oereb (make build) + #. setup all necessary python packages + #. create database structure as SQL + #. create configuration (wsgi => development.ini) + #. create configuration (pyramid_oereb => pyramid_oereb.yml) + +Building the docker images locally can be achieved by: + +.. code-block:: shell + + # on Linux + docker-compose build + +Setup pyramid_oereb can be achieved by (use the version for your OS): + +.. code-block:: shell + + # on Linux + docker-compose run --rm -u $(id -u):$(id -g) oereb-make build + +.. code-block:: shell + + # on Windows + docker-compose run --rm oereb-make build + .. _installation-step: @@ -214,7 +287,7 @@ Next steps Now you should be able to set up a running ``pyramid_oereb`` server using the standard configuration. If this configuration fits your needs, you can now continue with importing your data into the created database. A detailed description of each table can be found in the documentation of the -:ref:`api-pyramid_oereb-standard-models`. +:ref:`contrib-data-sources-standard-models-theme`. If your data is already available in an existing database with a different structure or you need to use a custom data source, the possible ways to adapt the models or to extend the application are described in the diff --git a/doc/source/makefile.rst b/doc/source/makefile.rst new file mode 100644 index 0000000000..e0ce7295a1 --- /dev/null +++ b/doc/source/makefile.rst @@ -0,0 +1,168 @@ +.. _makefile: + +Makefile +======== + +``pyramid_oereb`` uses GNU-Makefile a lot to setup itself and its components. This section is a try to +describe the structure of the used +`Makefile `_. + +A Makefile is constructed of so called targets. Most often a target represents a file which should be +created. So you the `line `_ defines +the commands how to create the development.ini file which is necessary to run DEV instance of +``pyramid_oereb``. + +To stay with this line in the Makefile you can see that a mako-render command is called with several variables +from a ``virtual environment``. Thats a bit interesting. More interesting is the dependency which is defined +right on the same line of the target: ``install`` + +It refers to the ``install`` target +`some lines above `_ which has a +dependency ``requirements-timestamp`` which refers to a target +`some lines above `_ ... and so forth. + +Important to know is that GNU Make keeps track of target files. So if some change was made for instance to +your ``requirements.txt`` file to update a pypi package a simple ``make build`` is enough to setup your project +with it and provide it in your VENV. If you call ``make build`` for another reason and say the +``requirements.txt`` file was not touched by you the complete targets which depend on this file are omitted. + +This is a really powerful tool which - used correctly - can save a lot of work compared to write the same +logic in a shell scripte or in a python script. In the best case it leads to reproducible environments +independent of the machine it is issued on. + +However, because it is a bit different how it works, people often struggle with its usage and avoid to use it +at all. + +The following sections should help you to understand better what the +`Makefile `_ provides you when you call a +decent target. It shows the dependency-target-system in a graph. + +- green elements are files which are expected to be there (e.g. ``setup.py``) +- red elements are files which will be created through the target or which are meta targets ("phony" - no files are created) + +General targets +--------------- + +``make install`` +'''''''''''''''' + +Basically sets up your virtual environment based on the projects requirements. + +.. image:: ../images/make.install.png + :align: center + +``make build`` +'''''''''''''' + +Completely sets up your application to be ready for running. This includes steps like: + +- prepare ``development.ini`` file +- prepare DEV DB +- fill DEV DB +- ... + +.. image:: ../images/make.build.png + :align: center + +Run a development server +------------------------ + +``make serve-dev`` +'''''''''''''''''' + +Runs a ``pserve`` development server which reloads when changes to python source files were made. + +.. image:: ../images/make.serve-dev.png + :align: center + +``make serve`` +'''''''''''''' + +Runs a ``pserve`` development server. + +.. image:: ../images/make.serve.png + :align: center + +Testing +------- + +``make tests`` +'''''''''''''' + +Executes all python testing. This includes the module tests (they can be executed directly to save time). + +.. image:: ../images/make.tests.png + :align: center + +``make lint`` +''''''''''''' + +Does the linting to check code style conformance. + +.. image:: ../images/make.lint.png + :align: center + +``make git-attributes`` +''''''''''''''''''''''' + +Executes the gitattributes checker. + +.. image:: ../images/make.git-attributes.png + :align: center + +``make check`` +'''''''''''''' + +Collection target to execute all targets mentioned above in one single call. + +.. image:: ../images/make.check.png + :align: center + +Maintainence +------------ + +``make updates`` +'''''''''''''''' + +Provides a list of outdated python packages and the possible better target version. + +.. image:: ../images/make.updates.png + :align: center + +Documentation +------------- + +``make doc-html`` +''''''''''''''''' + +Creates the documentation as a static HTML page with sphinx. + +.. image:: ../images/make.doc-html.png + :align: center + +``make doc-latex`` +'''''''''''''''''' + +Creates the documentation as a PDF page with sphinx. + +.. image:: ../images/make.doc-latex.png + :align: center + +Cleaning up +----------- + +``make clean`` +'''''''''''''' + +Wipes test results and `development.ini` file. + +.. image:: ../images/make.clean.png + :align: center + +``make clean-all`` +'''''''''''''''''' + +Completely wipes all setup files to provide green field for a new start. + +.. image:: ../images/make.clean-all.png + :align: center diff --git a/doc/source/standard/index.rst b/doc/source/standard/index.rst deleted file mode 100644 index 7f15487de6..0000000000 --- a/doc/source/standard/index.rst +++ /dev/null @@ -1,38 +0,0 @@ - -Standard -======== - -The standard package is the part where all the database configuration is stored. It also provides really -useful functions to integrate data, as well as creation of a YAML-configuration fitting this standard -structure. In addition you will find here the hook methods which are used in several places in the -configuration and an example usage of the pyconizer package to provide legend entry icons for a dedicated -layer. - -.. toctree:: - :hidden: - - sources - models/index - -Functions for creating standard environment -------------------------------------------- - -.. _api-pyramid_oereb-standard-create_tables: - -.. automodule:: pyramid_oereb.contrib.data_sources.create_tables - :members: - create_tables_from_standard_configuration - -.. _api-pyramid_oereb-standard-load_legend_entries: - -.. automodule:: pyramid_oereb.contrib.data_sources.standard.load_legend_entries - :members: - create_legend_entries_in_standard_db - -Functions used as configurable hooks ------------------------------------- - -.. _api-pyramid_oereb-standard-hook_methods: - -.. automodule:: pyramid_oereb.contrib.data_sources.standard.hook_methods - :members: diff --git a/doc/source/standard/models/factory_models.rst.mako b/doc/source/standard/models/factory_models.rst.mako deleted file mode 100644 index 3cc9bf0d07..0000000000 --- a/doc/source/standard/models/factory_models.rst.mako +++ /dev/null @@ -1,23 +0,0 @@ -<% import re%> - -.. _api-${module_name.replace('.', '-').lower()}: - -*${module_name.split('.')[-1].title().replace('_', ' ')}* -${re.sub('.', '^', module_name.split('.')[-1].title().replace('_', ' ') + ' ')} - -TODO: improve explication of how generic classes adapt to themes - -The classes below are generated through a class builder factory and are customized for the different themes (TODO: insert link) which make up the app. - -.. autoclass:: ${module_name} - -%for cls in classes: - -.. _api-${module_name.replace('.', '-').lower()}-${cls.lower()}: - -${cls} -${re.sub('.', '~', cls)} - -.. autoclass:: ${module_name}.${cls} - -%endfor \ No newline at end of file diff --git a/doc/source/standard/models/index.rst.mako b/doc/source/standard/models/index.rst.mako deleted file mode 100644 index 8aa1021ff3..0000000000 --- a/doc/source/standard/models/index.rst.mako +++ /dev/null @@ -1,20 +0,0 @@ -.. _api-pyramid_oereb-standard-models: - -Models -====== - -.. automodule:: pyramid_oereb.contrib.data_sources.standard.models - - -.. toctree:: - :hidden: - -%for file_name in module_file_names: - ${file_name} -%endfor - -Exemplary schema of a standard database ---------------------------------------- - .. image:: ../../../images/standard_database_schema_example.png - :scale: 20 % - :align: center diff --git a/doc/source/standard/models/models.rst.mako b/doc/source/standard/models/models.rst.mako deleted file mode 100644 index 085cf093fd..0000000000 --- a/doc/source/standard/models/models.rst.mako +++ /dev/null @@ -1,23 +0,0 @@ -<% import re%> - -.. _api-${module_name.replace('.', '-').lower()}: - -*${module_name.split('.')[-1].title().replace('_', ' ')}* -${re.sub('.', '^', module_name.split('.')[-1].title().replace('_', ' ') + ' ')} - -.. automodule:: ${module_name} - -%for cls in classes: - -.. _api-${module_name.replace('.', '-').lower()}-${cls.lower()}: - -${cls} -${re.sub('.', '~', cls)} - -.. autoclass:: ${module_name}.${cls} - :members: - :inherited-members: - - .. automethod:: __init__ - -%endfor \ No newline at end of file diff --git a/pyramid_oereb/contrib/data_sources/standard/models/__init__.py b/pyramid_oereb/contrib/data_sources/standard/models/__init__.py index 20090a7e01..ea8d2b6c93 100644 --- a/pyramid_oereb/contrib/data_sources/standard/models/__init__.py +++ b/pyramid_oereb/contrib/data_sources/standard/models/__init__.py @@ -2,6 +2,16 @@ """ This Package provides all models fitting to the standard database configuration. It is separated by the 17 mandatory topics the federation asks for. + +The following functions are class factories to enable reuse and making SQL-Alchemy +classes configurable. + +The classes produced by the factory methods are shared in different contrib modules. +As of the moment of writing this includes: + +* :ref:`contrib-data-sources-standard` +* :ref:`contrib-data-sources-oereblex` + """ diff --git a/pyramid_oereb/contrib/data_sources/standard/models/main.py b/pyramid_oereb/contrib/data_sources/standard/models/main.py index 82cd536901..c16f145ed7 100644 --- a/pyramid_oereb/contrib/data_sources/standard/models/main.py +++ b/pyramid_oereb/contrib/data_sources/standard/models/main.py @@ -16,7 +16,7 @@ pyramid_oereb_main -But you can change it also via configuration. +But you can change it also via :ref:`configuration`. Note: Whenever you configure your own sqlalchemy ORM's to use them in this application you must imitate diff --git a/pyramid_oereb/contrib/print_proxy/mapfish_print/mapfish_print.py b/pyramid_oereb/contrib/print_proxy/mapfish_print/mapfish_print.py index 0527815880..06c9f31591 100644 --- a/pyramid_oereb/contrib/print_proxy/mapfish_print/mapfish_print.py +++ b/pyramid_oereb/contrib/print_proxy/mapfish_print/mapfish_print.py @@ -784,11 +784,12 @@ def sort_by_index(elem): """ Provides the sort key for the supplied hint / law / legal provision element as a tuple consisting of: - * index - Notes - - index is defined by Interlis model OeREBKRM_V2_0 as range -1000..1000 - - "Index = None" if geolink_formatter processes entry from OEREBLEX that has no index + * index + + Notes: + - index is defined by Interlis model OeREBKRM_V2_0 as range -1000..1000 + - "Index = None" if geolink_formatter processes entry from OEREBLEX that has no index Args: elem (dict): one element of the hints / laws / legal provisions list Returns: diff --git a/pyramid_oereb/core/readers/data_integration.py b/pyramid_oereb/core/readers/data_integration.py index 25f01ef98d..a754363b0f 100644 --- a/pyramid_oereb/core/readers/data_integration.py +++ b/pyramid_oereb/core/readers/data_integration.py @@ -32,7 +32,7 @@ def read(self): If you construct a subclass of this class your implementation needs to offer this method in the same signature. Means the parameters must be the same and the return must be a list of - :ref:`api-pyramid_oereb-core-records-data_integration-dataintegrationbaserecord`. + :ref:`api-pyramid_oereb-core-records-data_integration-dataintegrationrecord`. Otherwise the API like way the server works would be broken. Returns: diff --git a/pyramid_oereb/core/readers/law_status.py b/pyramid_oereb/core/readers/law_status.py index 1a8a23b562..d7e092a4c9 100644 --- a/pyramid_oereb/core/readers/law_status.py +++ b/pyramid_oereb/core/readers/law_status.py @@ -17,7 +17,7 @@ def __init__(self, dotted_source_class_path, **params): (str or pyramid_oereb.core.sources.lawstatus.LawStatusBaseSource): The path to the class which represents the source used by this reader. This class must exist and it must implement basic source behaviour of the - :ref:`api-pyramid_oereb-core-sources-lawstatus-lawstatusbasesource`. + :ref:`api-pyramid_oereb-core-sources-law_status-lawstatusbasesource`. (kwargs): kwargs, which are necessary as configuration parameter for the above by dotted name defined class. """ @@ -31,7 +31,7 @@ def read(self): Note: If you subclass this class your implementation needs to offer this method in the same signature. Means the parameters must be the same and the return must be a list of - :ref:`api-pyramid_oereb-core-records-lawstatus-lawstatusrecord`. + :ref:`api-pyramid_oereb-core-records-law_status-lawstatusrecord`. Otherwise the API like way the server works would be broken. Args: diff --git a/pyramid_oereb/core/readers/real_estate_type.py b/pyramid_oereb/core/readers/real_estate_type.py index afcba7a98a..0ce5171f4d 100644 --- a/pyramid_oereb/core/readers/real_estate_type.py +++ b/pyramid_oereb/core/readers/real_estate_type.py @@ -17,7 +17,7 @@ def __init__(self, dotted_source_class_path, **params): (str or pyramid_oereb.core.sources.realestatetype.RealEstateTypeBaseSource): The path to the class which represents the source used by this reader. This class must exist and it must implement basic source behaviour of the - :ref:`api-pyramid_oereb-core-sources-realestatetype-realestatetypebasesource`. + :ref:`api-pyramid_oereb-core-sources-real_estate_type-realestatetypebasesource`. (kwargs): kwargs, which are necessary as configuration parameter for the above by dotted name defined class. """ @@ -31,7 +31,7 @@ def read(self): Note: If you subclass this class your implementation needs to offer this method in the same signature. Means the parameters must be the same and the return must be a list of - :ref:`api-pyramid_oereb-core-records-realestatetype-realestatetyperecord`. + :ref:`api-pyramid_oereb-core-records-real_estate_type-realestatetyperecord`. Otherwise the API like way the server works would be broken. diff --git a/pyramid_oereb/core/records/view_service.py b/pyramid_oereb/core/records/view_service.py index cd98ac02d4..cd88cad012 100644 --- a/pyramid_oereb/core/records/view_service.py +++ b/pyramid_oereb/core/records/view_service.py @@ -46,7 +46,7 @@ def __init__(self, symbol, legend_text, type_code, type_code_list, theme, sub_theme (pyramid_oereb.lib.records.theme.ThemeRecord): The optional sub theme to which the legend entry belongs. identifier (str): The identifier of the legend entry which might be used for linking to - other elements. + other elements. """ if not isinstance(legend_text, dict): warnings.warn('Type of "legend_text" should be "dict"' @@ -116,9 +116,10 @@ def __init__(self, reference_wms, layer_index, layer_opacity, default_language, @staticmethod def sanitize_layer_index(layer_index): """ - Checks the validity of the layer index + Checks the validity of the layer index. + Arg: - layer_index (int): index of the layer + layer_index (int): index of the layer Returns: int: the layer index if it is an int berween -1000 and 1000. @@ -163,6 +164,7 @@ def check_min_max_attributes(min_point, min_name, max_point, max_name): Checks the validity of a min and max point: - type check - min_point < max_point + Args: min_point (shapely.geometry.point.Point): a point geometry min_name (): the name of the point diff --git a/requirements.txt b/requirements.txt index 74a7737c7a..26d00547f8 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,4 @@ -pypdf==3.16.4 +pypdf==3.17.1 filetype==1.2.0 geoalchemy2==0.14.2 pyramid==2.0.2 @@ -6,9 +6,9 @@ pyramid-debugtoolbar==4.10 qrcode==7.4.2 image==1.5.33 shapely==2.0.2 -SQLAlchemy==2.0.22 +SQLAlchemy==2.0.23 pyaml-env==1.2.1 -urllib3==2.0.7 +urllib3==2.1.0 waitress==2.1.2 pyreproj==3.0.0 mako-render==0.1.0 diff --git a/tests-requirements.txt b/tests-requirements.txt index dbee33f69c..94457834c5 100644 --- a/tests-requirements.txt +++ b/tests-requirements.txt @@ -1,9 +1,9 @@ -jsonschema==4.19.1 +jsonschema==4.20.0 lxml==4.9.3 pytest==7.4.3 pytest-cov==4.1.0 pytest-ordering==0.6 requests-mock==1.11.0 -responses==0.23.3 +responses==0.24.1 webtest==3.0.0 pillow==10.1.0