create_full_molecule

specatalog.helpers.full_entry.create_full_molecule(data, molecular_formula_path, fmt, progress=None)[source]

Create a complete molecule entry with atomic database and file operations.

Performs all molecule creation steps in a transaction-safe manner:

  1. Creates the database entry.

  2. Sets up a temporary directory.

  3. Creates the temporary molecule directory.

  4. Determines the structural formula files to copy.

  5. Copies the molecular structure files into the temporary archive.

  6. Copies the completed molecule to the final archive location.

  7. Commits the database transaction.

Parameters:

  • data (cr.molecule_model_pyd) – Molecule metadata used to create the database entry.

  • molecular_formula_path (list[str]) –

    List of paths to structural formula files.

    If fmt is a specific format, the corresponding suffix is applied to each path. If fmt is "all", all supported formats are searched for and copied if they exist.

  • fmt (str) – File format suffix, for example ".pdf", or "all" to process all supported formats.

  • progress (ProgressCallback, optional) –

    Optional callback used to report the progress of the operation. The callback is called with two arguments:

    • fractionfloat

      Progress value between 0.0 and 1.0.

    • messagestr

      Human-readable description of the current processing step.

    The callback is independent of the GUI and may, for example, be connected to a graphical progress bar by the caller.

Returns:

Result object containing the status of the operation.

If the operation succeeds, success is True and molecular_id contains the ID of the created molecule.

If the operation fails, success is False and error contains the exception that caused the failure.

Return type:

CreateMoleculeResult

Notes

A temporary directory is used to ensure that incomplete files are not written directly to the final archive location.

If fmt is "all", the following file formats are searched for:

  • .pdf

  • .cdxml

  • .png

  • .jpeg

  • .jpg

  • .svg

If an error occurs, database and file operations are rolled back where possible, and partially created archive data is removed.

The progress callback is optional. If it is None, no progress information is reported.

The function does not depend on Qt or any other GUI framework.