add doc, add tests

.coveragerc

@@ -1,5 +1,13 @@
 [run]
 source =
-    src/geolink2oereb
+    src
 omit =
     src/geolink2oereb/lib/interfaces/oerebkrmtrsfr/v2_0/classes.py
+    src/geolink2oereb/cli.py
+    setup.py
+    tests/*.py
+[report]
+skip_covered = True
+show_missing = True
+[xml]
+output = coverage.xml

Makefile

@@ -21,7 +21,7 @@ lint: .venv/requirements.timestamp
 
 .PHONY: test
 test: .venv/requirements.timestamp
-	.venv/bin/py.test -vv --cov-config .coveragerc --cov src/geolink2oereb --cov-report=xml:coverage.xml tests
+	.venv/bin/py.test -vvv --cov --cov-config .coveragerc --cov-report=xml --cov-report=term tests
 
 
 .PHONY: check

doc/source/basics.rst

@@ -0,0 +1,23 @@
+Basic info
+==========
+
+
+This is a small library, meant to be used in combination with an *OEREBlex* instance.
+It is capable of parsing a received *lexlink* response (XML) and transforming it to the
+`OeREBKRMtrsfr_V2_0 <https://models.geo.admin.ch/V_D/OeREB/OeREBKRMtrsfr_V2_0.ili>`_ structure for further
+usage.
+
+To make the configuration more easy it is using the pyramid_oereb library to reuse the
+complex ÖREBlex
+`configuration <https://github.com/openoereb/pyramid_oereb/blob/master/dev/config/pyramid_oereb.yml.mako#L185-L223>`_
+and ÖREBlex
+`parsing <https://github.com/openoereb/pyramid_oereb/blob/master/pyramid_oereb/contrib/data_sources/oereblex/sources/document.py>`_
+already developed there.
+
+For development and integration purposes geolink2oereb offers a :ref:`CLI` executable. But its
+main use case is to be utilized as a library in another python libraries context.
+
+See the mgdm2oereb implementation as an example:
+
+`mgdm2oereb => oereblex.geolink2oereb <https://github.com/openoereb/mgdm2oereb/blob/master/xsl/oereblex.geolink2oereb.py>`_
+

doc/source/cli.rst

@@ -0,0 +1,25 @@
+
+CLI
+===
+
+The command line interface of geolink2oereb.
+
+Once installed as python package geolink2oereb offers a command line
+interface to issue the transformation of one lexlink id to the
+OEREB transfer structure. To get info about the parameters the cli programm
+needs, you can issue the execution as follows:
+
+.. code-block:: shell
+
+  load_documents --help
+
+You can call the tool like this:
+
+.. code-block:: shell
+
+  load_documents -l 4304 -t ch.Planungszonen -p <absolute-path-to-your-config>/config.yaml
+
+Please keep in mind, that the binary executable is available only in the
+python path where you installed it. If you installed it with
+a VENV you might prefix it with the path to you VENV's bin directory.
+

doc/source/conf.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 #
-# OEREBlex geoLink Formatter documentation build configuration file, created by
-# sphinx-quickstart on Tue May 16 13:06:47 2017.
+# geolink2oereb documentation build configuration file, created by
+# sphinx-quickstart on Tue Oct 08 13:06:47 2023.
 #
 # This file is execfile()d with the current directory set to its
 # containing dir.
@@ -37,12 +37,14 @@
 
 
 extensions = [
+    'sphinx_rtd_theme',
     'sphinx.ext.autodoc',
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
-    'sphinx.ext.napoleon'
+    'sphinx.ext.napoleon',
+    'sphinx.ext.autosectionlabel'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -175,3 +177,6 @@
 
 # Napoleon configuration
 napoleon_numpy_docstring = False
+napoleon_google_docstring = True
+napoleon_include_init_with_doc = True
+napoleon_preprocess_types = True

doc/source/geolink2oereb.rst

@@ -1,4 +1,5 @@
-Module *geolink2oereb*
-==========================
+Module *transform*
+==================
 
-.. automodule:: geolink2oereb
+.. automodule:: geolink2oereb.transform
+   :members:

doc/source/index.rst

@@ -1,14 +1,14 @@
-
 OEREBlex geolink2oereb
 ======================
 
 .. toctree::
    :maxdepth: 2
    :hidden:
 
+   basics
+   cli
    geolink2oereb
-
-.. include:: description.rst
+   interfaces
 
 
 Indices and tables
@@ -17,6 +17,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-
-
-run with `documents = run_batch([4304,4305,4305], 'ch.Planungszonen', 'config_gr.yaml', 'pyramid_oereb')`

doc/source/interfaces.rst

@@ -0,0 +1,71 @@
+Interfaces
+==========
+
+*pyramid_oereb*
+---------------
+
+.. automodule:: geolink2oereb.lib.interfaces.pyramid_oereb
+   :members:
+
+*OeREBKRMtrsfr_V2_0 generators*
+-------------------------------
+
+.. automodule:: geolink2oereb.lib.interfaces.oerebkrmtrsfr.v2_0.generators
+   :members:
+
+*OeREBKRMtrsfr_V2_0 classes*
+-------------------------------
+
+This is a selection of classes available to adapt to ``OeREBKRMtrsfr_V2_0``. The selection shows the classes
+used in the current implementation. Please have a look in the source file to see the complete implementation.
+
+.. autoclass:: geolink2oereb.lib.interfaces.oerebkrmtrsfr.v2_0.classes.OeREBKRM_V2_0_Dokumente_Dokument
+   :members:
+   :undoc-members:
+
+.. autoclass:: geolink2oereb.lib.interfaces.oerebkrmtrsfr.v2_0.classes.OeREBKRM_V2_0_Amt_Amt
+   :members:
+   :undoc-members:
+
+.. autoclass:: geolink2oereb.lib.interfaces.oerebkrmtrsfr.v2_0.classes.ZustaendigeStelleType
+   :members:
+   :undoc-members:
+
+.. autoclass:: geolink2oereb.lib.interfaces.oerebkrmtrsfr.v2_0.classes.TitelType
+   :members:
+   :undoc-members:
+
+.. autoclass:: geolink2oereb.lib.interfaces.oerebkrmtrsfr.v2_0.classes.TextImWebType
+   :members:
+   :undoc-members:
+
+.. autoclass:: geolink2oereb.lib.interfaces.oerebkrmtrsfr.v2_0.classes.OeREBKRM_V2_0_MultilingualUri
+   :members:
+   :undoc-members:
+
+.. autoclass:: geolink2oereb.lib.interfaces.oerebkrmtrsfr.v2_0.classes.OeREBKRM_V2_0_LocalisedUri
+   :members:
+   :undoc-members:
+
+.. autoclass:: geolink2oereb.lib.interfaces.oerebkrmtrsfr.v2_0.classes.LocalisedTextType
+   :members:
+   :undoc-members:
+
+.. autoclass:: geolink2oereb.lib.interfaces.oerebkrmtrsfr.v2_0.classes.LocalisedTextType86
+   :members:
+   :undoc-members:
+
+.. autoclass:: geolink2oereb.lib.interfaces.oerebkrmtrsfr.v2_0.classes.LocalisationCH_V1_LocalisedText
+   :members:
+   :undoc-members:
+
+.. autoclass:: geolink2oereb.lib.interfaces.oerebkrmtrsfr.v2_0.classes.LocalisationCH_V1_MultilingualText
+   :members:
+   :undoc-members:
+
+``geolink2oereb.lib.interfaces.oerebkrmtrsfr.v2_0.classes.GeneratedsSuper`` is the superclass all above
+mentioned classes are inheriting from.
+
+.. autoclass:: geolink2oereb.lib.interfaces.oerebkrmtrsfr.v2_0.classes.GeneratedsSuper
+   :members:
+   :undoc-members:

setup.py

@@ -18,7 +18,7 @@
 
 tests_require = [
     'WebTest >= 1.3.1',  # py3 compat
-    'pytest',  # includes virtualenv
+    'pytest==7.4.2',  # includes virtualenv
     'pytest-cov'
 ]
 

src/geolink2oereb/cli.py

@@ -1,13 +1,14 @@
 import optparse
 import logging
-import uuid
 
+from io import StringIO
 from geolink2oereb.transform import run
 
 logging.basicConfig(level="DEBUG", format="%(asctime)s [%(levelname)s] %(message)s")
 
 log = logging.getLogger(__name__)
 
+
 def geolink2oereb():
     parser = optparse.OptionParser(
         usage="usage: %prog [options]",
@@ -18,7 +19,7 @@ def geolink2oereb():
         "--geolink_id",
         dest="geolink_id",
         metavar="GEOLINKID",
-        type="integer",
+        type="int",
         help="The the ID to load the documents for.",
     )
     parser.add_option(
@@ -65,8 +66,9 @@ def geolink2oereb():
         "-o",
         "--outfile-path",
         dest="outfile_path",
-        default=f"/tmp/{str(uuid.uuid4())}.xml",
-        help="The absolute path where the output will be written to.",
+        default=None,
+        help="The absolute path where the output will be written to."
+             "If omitted, the output will be printed as command output to the console.",
     )
 
     options, args = parser.parse_args()
@@ -78,6 +80,17 @@ def geolink2oereb():
         options.source_class_path,
         options.c2ctemplate_style,
     )
-    with open(options.outfile_path) as fh:
-        for element in oerebkrmtrsfr:
-            fh.write(str(element))
+    out_string_list = []
+
+    for lexlink_group in oerebkrmtrsfr:
+        for element in lexlink_group:
+            output = StringIO()
+            element.export(output, 0, namespacedef_=None)
+            out_string_list.append(output.getvalue())
+            output.close()
+    out_string = '\n'.join(out_string_list)
+    if options.outfile_path is None:
+        print(out_string)
+    else:
+        with open(options.outfile_path, mode="w+") as fh:
+            fh.write(out_string)

src/geolink2oereb/lib/interfaces/oerebkrmtrsfr/v2_0/generators.py

@@ -1,3 +1,8 @@
+"""
+This interface offers methods to access python classes matching the ``OeREBKRMtrsfr_V2_0`` INTERLIS model. It
+is used mainly for translation and handling between ``pyramid_oereb`` and ``OeREBKRMtrsfr_V2_0``.
+"""
+
 import logging
 from geolink2oereb.lib.interfaces.oerebkrmtrsfr.v2_0.classes import (
     OeREBKRM_V2_0_Dokumente_Dokument,
@@ -17,6 +22,16 @@
 
 
 def fix_url(url):
+    """
+    Helper method to hotfix an often occurring problem with urls not being valid in the ili sense. The URLs
+    out of ÖREBlex are missing the http/https part often. So we try to fix this on the fly.
+
+    Args:
+        url (str): The URL string which might be fixed.
+
+    Returns:
+        The maybe fixed URL.
+    """
     if not url.startswith('http'):
         new_url = 'https://{}'.format(url)
         logging.info(f"Fixing url from {url} to {new_url}")
@@ -25,6 +40,23 @@ def fix_url(url):
 
 
 def multilingual_text_from_dict(multilingual_dict):
+    """
+    Produces a MultilingualText object out of a dict in the form:
+
+    .. code-block:: python
+
+        {
+          "de": "Test",
+          "it": "Testo"
+        }
+
+    Args:
+        multilingual_dict (dict or None): The definition of the multilingual element or None.
+
+    Returns:
+        geolink2oereb.lib.interfaces.oerebkrmtrsfr.v2_0.classes.TitelType
+    """
+
     if multilingual_dict is None:
         return multilingual_dict
     localized_texts = LocalisedTextType()
@@ -36,6 +68,22 @@ def multilingual_text_from_dict(multilingual_dict):
 
 
 def multilingual_uri_from_dict(multilingual_dict):
+    """
+    Produces a MultilingualText object out of a dict in the form:
+
+    .. code-block:: python
+
+        {
+          "de": "Test",
+          "it": "Testo"
+        }
+
+    Args:
+        multilingual_dict (dict or None): The definition of the multilingual element or None.
+
+    Returns:
+        geolink2oereb.lib.interfaces.oerebkrmtrsfr.v2_0.classes.TextImWebType
+    """
     if multilingual_dict is None:
         return multilingual_dict
     localized_texts = LocalisedTextType86()
@@ -48,6 +96,7 @@ def multilingual_uri_from_dict(multilingual_dict):
 
 def office_record_to_oerebkrmtrsfr(office_record):
     """
+    Translates a ``pyramid_oereb`` office record object to an OeREBKRM_V2_0_Amt_Amt object.
 
     Args:
         office_record (pyramid_oereb.core.records.office.OfficeRecord): The office record to translate.
@@ -70,13 +119,18 @@ def office_record_to_oerebkrmtrsfr(office_record):
 
 def document_record_to_oerebkrmtrsfr(document_record):
     """
+    Translates a ``pyramid_oereb`` document record object to an OeREBKRM_V2_0_Dokumente_Dokument object.
 
     Args:
         document_record (pyramid_oereb.core.records.documents.DocumentRecord): The record to translate.
 
     Returns:
-        (geolink2oereb.lib.interfaces.oerebkrmtrsfr.v2_0.classes.OeREBKRM_V2_0_Amt_Amt,
-            geolink2oereb.lib.interfaces.oerebkrmtrsfr.v2_0.classes.OeREBKRM_V2_0_Dokumente_Dokument)
+        (tuple): tuple containing:
+
+            geolink2oereb.lib.interfaces.oerebkrmtrsfr.v2_0.classes.OeREBKRM_V2_0_Amt_Amt:
+                The office which belongs to the document (responsible office).
+            geolink2oereb.lib.interfaces.oerebkrmtrsfr.v2_0.classes.OeREBKRM_V2_0_Dokumente_Dokument:
+                The document.
     """
     amt = office_record_to_oerebkrmtrsfr(document_record.responsible_office)
     dokument = OeREBKRM_V2_0_Dokumente_Dokument(