Code standards
============================

.. admonition:: Under progress...
   :class: hint

   *Section to be completed*

GEOP4TH's philosophy
----------------------

GEOP4TH relies on generic and format-agnostic elementary functions, called *geobricks* and defined in the geobricks.py script.

The philosophy of *geobricks* is to aim for a high level of abstraction: mandatory user's choices are to be reduced to the minimum. But 
it should still be possible for the advanced users to access advanced options. To combine these two goals, we use smart default values and smart procedures
in order to infer the parameter values when they are not passed by the user.

.. admonition:: Under progress...
   :class: hint

   *More info to come on script organization...*

File formats and extensions
-------------------------------

.. admonition:: in a nutshell

    - when referring to the file extension (for instance '.json'), ``extension`` is used, and would ideally include the '.' character
    - when referring to the file format (for instance 'GeoJSON'), ``file_format`` is used, and would ideally not include the '.' character

When developping new prep-processing steps, it is very likely that you will have to deal with file formats and extensions!
In GEOP4TH code, we make a difference between those 2. An extension refers to the suffix to the file name ('.asc', '.tif', '.json'...).
We usually need this variable to differentiate between different file types such as raster files, vector files and so on. In that case we use 
the variable name ``extension`` as in :func:`geobricks.get_filelist` or :func:`geobricks.load_any`. We also consider that the ``extension`` values
should include the '.' character. Of course this theory, in practice we add a safeguard to deal with values missing the '.':

.. code-block:: python3

    if isinstance(extension, str):
        if extension[0] != '.': extension = '.' + extension

The tricky part to have in mind is that a single extension can refers to different file formats, for example 
``.json`` can refer both to 'JSON', 'GeoJSON' or 'TopoJSON' files, ``.tif`` can refer both to 'TIFF' or 'GeoTIFF'... (see 
`wikipedia file formats <https://en.wikipedia.org/wiki/List_of_file_formats>`_). 

In the situations told before (:func:`geobricks.get_filelist`, :func:`geobricks.load_any`, ...), we do not mind if
the extension refers to one file format or another, because we try our best to handle these potential issues
in the code itself, so that users will not have to care for that. For instance in :func:`geobricks.load_any` 
we will differentiate between 'JSON' and 'GeoJSON' during the loading step:

.. code-block:: python3
    
    try: 
        data_ds = gpd.read_file(data, **kwargs)
    except: # DataSourceError
        try:
            data_ds = pd.read_json(data, **kwargs)
        except:
            data_ds = json.load(open(data, "r"))
            print("   Warning: The JSON file could not be loaded as a pandas.DataFrame and was loaded as a dict")

Anyway, in some other cases, we **want** to differentiate between different file formats with the same extension. It is typically
the case in :func:`download_fr.bnpe`. In the water withdrawal API of BNPE that this function queries, the user can explicitely
choose between 'JSON' or 'GeoJSON' formats. Of course we wanted to keep this choice available. In that type of situation, we use the variable
name `file_format` and we consider that its value should not include the '.'. Once again, we still add a nice safeguard:

.. code-block:: python3

    if file_formats[i][0] == '.': file_formats[i] = file_formats[i][1:]





.. |IDE| raw:: html

  <abbr title="Integrated development environment">IDE</abbr>

.. # define a hard line break for HTML
.. |br| raw:: html

   <br>
   

.. |nbsp| unicode:: 0xA0 
   :trim: