Developer's guide ================= This API-REST was developed with python 3.10.12 with the version |Pygoslin_version| of pygoslin_, the Python implementation of the Goslin_ tool. .. _pygoslin: https://github.com/lifs-tools/pygoslin .. _Goslin: https://pubs.acs.org/doi/10.1021/acs.analchem.1c05430 !!!! Dependencies ------------ *Last modified on : 14th Apr. 2025* This API relies on several dependencies which must be installed in the application environment (venv, Docker, ...) for the application to work. .. note:: All theses dependencies are listed in the ``requirements.txt`` file and can be install at once with the command : .. code-block:: console $ pip install -r requirements.txt Dependencies required to use the application ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. |Pygoslin_version| replace:: ``2.1.5`` .. |FastAPI_version| replace:: ``0.115.12`` .. |Loguru_version| replace:: ``0.7.3`` .. |OpenAPIGeneratorCLI_version| replace:: ``7.12.0`` .. |Pandas_version| replace:: ``2.2.3`` .. |PythonDotenv_version| replace:: ``1.1.0`` .. |PyYAML_version| replace:: ``2.8.1`` .. |Requests_version| replace:: ``2.32.3`` .. list-table:: :header-rows: 1 :widths: 30 15 55 * - Name - Version - Description * - `Pygoslin`_ - |Pygoslin_version| - | The Python implementation of the Goslin_ Tool. * - `Loguru`_ - |Loguru_version| - | Package for implementing logging. * - `OpenAPI Generator CLI`_ - |OpenAPIGeneratorCLI_version| - | Tool to generates API client libraries and server source code | (such as model objects) automatically, from an OpenAPI | Specification. * - `Pandas`_ - |Pandas_version| - | Package that provides fast, flexible, and expressive data | structures designed. * - `Python Dotenv`_ - |PythonDotenv_version| - | Package to read key-value pairs from a .env file and can set | them as environment variables. * - `PyYAML`_ - |PyYAML_version| - | YAML parser and emitter for Python. * - `Requests`_ - |Requests_version| - | Package for sending HTTP requests. .. _Loguru: https://loguru.readthedocs.io/en/stable/ .. _OpenAPI Generator CLI: https://github.com/OpenAPITools/openapi-generator#3---usage .. _Pandas: https://pandas.pydata.org/docs/user_guide/index.html .. _Python Dotenv: https://github.com/theskumar/python-dotenv?tab=readme-ov-file#getting-started .. _PyYAML: https://pyyaml.org/wiki/PyYAMLDocumentation .. _Requests: https://fr.python-requests.org/en/latest/ Dependencies required to test the application ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. |Pytest_version| replace:: ``8.3.5`` .. list-table:: :header-rows: 1 :widths: 30 15 55 * - Name - Version - Description * - `Pytest`_ - |Pytest_version| - | Test framework for Python. .. _Pytest: https://docs.pytest.org/en/stable/ Dependencies required to build the documentation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. |Sphinx_version| replace:: ``8.2.3`` .. |SphinxReadTheDocsTheme_version| replace:: ``3.0.2`` .. |SphinxTabs_version| replace:: ``3.4.7`` .. list-table:: :header-rows: 1 :widths: 30 15 55 * - Name - Version - Description * - `Sphinx`_ - |Sphinx_version| - | Tool to generate rich, well-structured, easy-to-read | documentation. * - `Sphinx ReadTheDocs Theme`_ - |SphinxReadTheDocsTheme_version| - | A Sphinx documentation theme. * - `Sphinx Tabs`_ - |SphinxTabs_version| - | A Sphinx extension to create tabbed content in | Sphinx documentation when building HTML. .. _Sphinx: https://www.sphinx-doc.org/en/master/ .. _Sphinx ReadTheDocs Theme: https://sphinx-rtd-theme.readthedocs.io/en/stable/ .. _Sphinx Tabs: https://sphinx-tabs.readthedocs.io/en/latest/ !!!! Tests ----- Tests on the application code can be found in the ``tests`` directory. All the tests were implemented with `pytest` framework. To run them, you can run the `pytest` command : .. code-block:: console $ pytest !!!! Code organisation ----------------- .. code-block:: . ├── build_docker_image.sh ├── CHANGELOG.md ├── doc │ ├── conf.py │ ├── developers_guide.rst │ ├── functions.rst │ ├── index.rst │ ├── overview.rst │ ├── query_rest_api.rst │ └── vars.rst ├── Dockerfile ├── LICENSE ├── Makefile ├── README.md ├── requirements.txt ├── resources │ ├── env │ │ ├── mesocentre.env │ │ └── pfem.env │ ├── goslin_about.json │ ├── lipid-list.csv │ └── metabocloud-goslin.yaml ├── sphinx-requirements.txt ├── src │ ├── config.py │ ├── controllers │ │ ├── about_controller.py │ │ ├── grammars_controller.py │ │ ├── __init__.py │ │ ├── root_controller.py │ │ └── validate_controller.py │ ├── implementation │ │ ├── __init__.py │ │ └── services │ │ ├── goslin_service.py │ │ ├── __init__.py │ │ ├── lipidmaps_service.py │ │ └── metadata_service.py │ ├── __init__.py │ ├── main.py │ └── models │ ├── enums │ │ ├── __init__.py │ │ ├── Messages.py │ │ └── Paths.py │ ├── __init__.py │ └── objects │ ├── __init__.py │ ├── LipidMapsEntry.py │ └── Vars.py └── tests ├── data │ ├── expected_failed_result.json │ ├── expected_mixed_result.json │ ├── expected_successful_not_all_info_result.json │ ├── expected_successful_result.json │ └── expected_uncompleted_result.json ├── __init__.py ├── test_about_service.py ├── test_controllers.py ├── test_goslin_service.py └── test_lipidmaps_service.py **build_docker_image.sh** * Script to build the Docker image in local* **CHANGELOG.md** * File to track the different updates carried out over the course of different versions. ``doc`` * Directory containing the source of the documentation **Dockerfile** * File containing all instructions to build the application Docker image. **LICENCE** * File containing the licence associated to the application. **Makefile** * Configuration file to automate the execution of a set of actions. **README.md** * File describing the project. It includes information on the purpose of the project, how it can be installed and used, where to find the documentation, etc... **requirements.txt** * File listing all dependencies necessary for the application to work. It is also use to facilitate the installation of these dependencies. ``resources`` : Directory containing the resources files * **env/mesocentre.env** : Environment file containing environment variables needed to run the application on the production server (host by the Mesocentre). * **env/pfem.env** : Environment file containing environment variables needed to run the application on the dev server (host by the PFEM). * **goslin_about.json** : JSON file with the metadata on the microservice and the tool. * **metabocloud-goslin.yaml** : YAML file configuring the OpenAPI specifications. * **lipid-list.csv** : CSV file containing the lipid class supported by the Pygoslin tool (retrieved from the ``pygoslin`` GitHub). **sphinx-requirements.txt** * File listing all dependencies necessary to build the Sphinx application. It is also use in the GitLab CI/CD to only install the necessary dependencies during the job where the Sphinx documentation is built. ``src`` : Directory containing the source code of the application * **config.py** : Module to configure the application. * **main.py** : Main application. * ``controllers`` : Package containing controllers * **about_controller.py** : Controller for the "/about" endpoint to retrieve the metadata associated to the REST API. * **grammars_controller.py** : Controller for the "/grammars" endpoint to retrieve the grammars available in Goslin tool. * **root_controller.py** : Controller for the "/" root endpoint. * **validate_controller.py** : Controller for the "/validate" endpoint to standardized lipid names. * ``implementation/services`` : Package containing services * **goslin_services.py** : Service regrouping methods related to the PyGoslin tool. * **lipidmaps_service.py** : Service regrouping methods to process information from the LipidMaps Structure Database. * **metadata_service.py** : Service regrouping methods related to the application metadata. * ``models`` : Package containing models * ``enums`` : Package containing enumeration models * **Messages.py** : Module regrouping enumerations containing messages. * **Paths.py** : Module regrouping enumerations containing paths. * ``objects`` : Package containing object models * **LipidmapsEntry.py** : An Object model to store LipidMaps Structure Database entry. * **Vars.py** : Variables used in the application. ``tests`` : Directory containing the tests * ``data`` : Directory containing expected response data. * **expected_failed_result.json** : Response data expected when a lipid failed to be parsed. * **expected_mixed_result.json** : Expected response data with all possible types of result parsing. * **expected_successful_not_all_info_result.json** : Response data expected when a lipid was parsed successfully but with some information missing. * **expected_successful_result.json** : Response data expected when a lipid was parsed successfully. * **expected_uncompleted_result.json** : Response data expected when a lipid was parsed incompletely. * **test_about_service.py** : Tests for the service managing the application metadata. * **test_controllers.py** : Tests for all controllers of the application. * **test_goslin_service.py** : Tests for the service managing the methods related to the Pygoslin tool. * **test_lipidmaps_service.py** : Tests for the services managing the methods related to the LipidMaps Structure Database. !!!! .. _code_documentation: Code documentation ------------------ .. toctree:: :maxdepth: 4 :glob: code/app_config code/controllers code/services code/models