Services documentation

A Service is a module that regroups processing methods related to a same theme.

goslin_service.py

Service regrouping methods related to the PyGoslin tool.

This module contains utility functions that interact with the PyGoslin library to parse, normalize, and analyze lipid names.

The main tasks include :

  • Retrieving the list of available grammars in the tool.

  • Parsing lipid names using various grammars.

  • Standardized lipid names and retrieving relating information.

  • Building JSON responses based on parsing results according their status (successful, uncompleted, or failed.)

src.implementation.services.goslin_service.build_failed_parsing_result(name: str) → FailedParsing

Build a JSON response for failed lipid parsing results.

Parameters:

name (str) – The original lipid name attempted for parsing.

Returns:

A model object containing details of the failed parsing attempt.

Return type:

FailedParsing

src.implementation.services.goslin_service.build_successful_parsing_result(parsing_result: tuple[LipidAdduct, str], name: str) → SuccessfulParsing

Build a JSON response for successful lipid parsing results.

Parameters:

  • parsing_result (tuple[LipidAdduct, str]) –

    A tuple (lipid, grammar) returned by parse_lipid.

    • lipid : LipidAdduct object, containing detailed lipid information.

    • grammar : str, the name of the grammar used for parsing.

  • name (str) – The original lipid name successfully parsed.

Returns:

A model object containing successful parsing details.

Return type:

SuccessfulParsing

src.implementation.services.goslin_service.build_uncompleted_parsing_result(messages: dict, name: str) → UncompletedParsing

Build a JSON response for uncompleted lipid parsing results.

Parameters:

  • messages (dict) – A dictionary with error messages for each grammar, showing partially parsed results.

  • name (str) – The original lipid name attempted for parsing.

Returns:

A model object containing uncompleted parsing details.

Return type:

UncompletedParsing

src.implementation.services.goslin_service.get_list_grammars() → list[str]

Fetches the list of grammars available in the Goslin tool.

Returns:

A list with all the grammars available in the Goslin tool.

Return type:

list[str]

src.implementation.services.goslin_service.parse_one_lipid(lipid_name: str) → tuple | dict | LipidException

Parse a lipid name using all available grammars in a predefined order.

The grammars are tried sequentially : Shorthand, Goslin, FattyAcid, LipidMaps, SwissLipids, and Hmdb. The parsing stops at the first successful grammar.

Parameters:

lipid_name (str) – The name of the lipid to parse.

Returns:

  • tuple – If parsing is successful, returns a tuple (lipid, grammar) where:

    • lipid : LipidAdduct object with detailed lipid information.

    • grammar : str, the name of the grammar used.

  • dict – If parsing is uncompleted, returns a dictionary where keys are grammar names, and values are the substrings successfully parsed before failure.

  • LipidException – If parsing completely fails, returns a LipidException indicating no grammar succeeded in parsing the lipid name.

src.implementation.services.goslin_service.standardized_lipids(lipid_names: list[str]) → dict

Standardized lipid names and retrieve related information?

It builds a complete JSON response containing the parsing result for all the lipid names sent in parameter.

It also counts the number of lipids that failed to be parsed, those that were parsed incompletely, those that were parsed successfully, as well as the total of lipids that were not parsed (the sum of those that failed and those that were parsed incompletely) and the total of lipids parsed.

Parameters:

lipid_names (list[str]) – The list of lipid names to standardize.

Returns:

The complete JSON response to return.

Return type:

dict

lipidmaps_service.py

Service regrouping methods to process information from the LipidMaps Structure Database.

This module includes functions for :

  • Parsing the LipidMaps Structure Database to build a local “database”.

  • Retrieving lipid class names from the LipidMaps classification file.

  • Retrieving lipid information from the local LipidMaps database.

src.implementation.services.lipidmaps_service.create_lipidmaps_local_database(url_file: str) → None

Parse the LipidMaps Structure Database SDF file and create a local “database”.

This function extracts relevant information (LipidMaps ID, InCHI key, standardized name, and SwissLipids ID) from the LipidMaps Structure Database and updates the LIPIDMAPS_DATABASE variable with a list of dictionaries, where each dictionary contains information about one lipid entry.

Structure of the local “database” (dictionary keys):

  • LIPIDMAPS_ID : LipidMaps entry ID for the molecule.

  • INCHI_KEY : InCHI key of the molecule.

  • STANDARDIZED_NAME : Standardized name of the molecule.

  • SWISSLIPIDS_ID : SwissLipids entry ID for the molecule (or None if not known).

Parameters:

url_file (str) – URL pointing to the SDF file of the LipidMaps Structure Database.

Raises:

FileNotFoundError – If the provided URL file is not a valid LipidMaps SDF file.

src.implementation.services.lipidmaps_service.get_lipidmaps_class_name(num_line: int) → str | None

Retrieve the LipidMaps class name for a lipid from the “lipid-list.csv” file.

This function reads the CSV file provided by the PyGoslin package and extracts the class name corresponding to the given line number. The line number is determined during the parsing of the lipid using PyGoslin.

Parameters:

num_line (int) – Line number in the CSV file corresponding to the lipid’s class.

Returns:

The LipidMaps class name for the given lipid.

Return type:

str

src.implementation.services.lipidmaps_service.get_lipidmaps_info(lipid_name: str) → dict | bool

Retrieve lipid information from the local LipidMaps database.

This function checks if a lipid’s standardized name exists in the local LipidMaps database. If found, it returns detailed information, including the LipidMaps ID, InCHI key, and SwissLipids ID (if available).

Parameters:

lipid_name (str) – Standardized lipid name obtained after parsing with PyGoslin.

Returns:

  • dict – A dictionary with lipid information if the lipid is found in the database.

  • bool – False if the lipid name is not found in the database.

Raises:

ValueError – If the local database is not initialized.

metadata_service.py

Service regrouping methods related to the application metadata.

It processes and retrieves metadata about the Goslin microservice, including details such as API version, description, documentation and information about accessibility and ownership.

src.implementation.services.metadata_service.get_app_metadata() → dict

Retrieve metadata about the application.

It reads metadata from a JSON file and adds dynamic version details, such as the commit SHA-1 hash and the build timestamp, which are stored in the Vars object after being computed at the start of the application.

Returns:

A dictionary containing version metadata.

Return type:

dict

Notes

The JSON metadata file is read from the resources/goslin_about.json file.

src.implementation.services.metadata_service.get_version_metadata()

Retrieve version metadata for the Goslin microservice.

Updates the METADATA variable stored in the src.models.objects.Vars object with information about the current version of the application.

This includes:

  • The SHA-1 hash of the last commit.

  • A short version of the SHA-1 hash.

  • The timestamp of when the application was built.

Notes

This function relies on the git command-line tool to retrieve commit information.