API Reference

Reference to the biosimdb-interface python API.

Form

biosimdb_interface.form.webform.do_submit()

Execute the deferred Invenio upload using session-stored form data. Called automatically by the loading page after login. Automatically invite user to Invenio instance community, then submit. Clears pending session data after upload and renders the success page with the record URL.

biosimdb_interface.form.webform.resume_submit()

Resume a pending submission after successful login.

Redirects to login if unauthenticated, or to the webform if no pending submission is found in the session.

biosimdb_interface.form.webform.webform()

Render the metadata form and handle save/submit actions.

On POST, validates uploaded files, converts submitted metadata to standard units, removes empty fields, and validates the result against the BioSim schema. save returns the validated JSON to the browser. submit saves uploaded files plus the validated JSON for deferred Invenio upload, then starts login if needed.

Metadata extraction endpoint.

Receives uploaded topology and trajectory files, extracts simulation metadata using biosim_extractor.metadata.populatemetadata.MetadataPopulator, and optionally validates the result against the BioSim schema.

biosimdb_interface.form.extract.extract_files_validate(top_file, traj_file)

Extract metadata from simulation files and validate against the schema.

Args:

top_file (str): Path to the topology file. traj_file (str or list[str]): Path or list of paths to the trajectory file(s).

Returns:

tuple: A tuple containing:

• result (dict): The extracted and populated metadata dictionary.

• validation_errors (list[str]): A list of validation error messages, empty if validation succeeded.

biosimdb_interface.form.extract.extract_metadata()

Extract simulation metadata from uploaded topology and trajectory files.

Expects a multipart POST with:

• topology: a single topology file.

• trajectory[]: one or more trajectory files.

Files are saved to temporary paths, passed to MetadataPopulator, and the result is validated against the schema at BIOSIM_SCHEMA_PATH.

Returns:

JSON response with one of: - {"simulation_metadata": ..., "message": "..."} on success. - {"simulation_metadata": ..., "validation_errors": [...]} if schema validation fails. - {"error": "..."} with status 400 if files are missing, or 500 on unexpected error.

biosimdb_interface.form.invenio.create_files_dict(all_files: Iterable[Path | str]) → dict[str, Path]

Save file paths into a dictionary to a format e.g.

Parameters:

all_files (Iterable[Path | str]) – Files to load into dict.

Returns:

Dictionary of file names and file paths.

Return type:

dict[str, Path]

Examples

files_dict = create_files_dict(["my_dir/*.file", "my_dir/example/*.cif"])
# files_dict = {
#    "name1.file": "my_dir/name1.file",
#    "name2.file": "my_dir/name2.file",
#    "name1.cif": "my_dir/example/name1.cif",
# }

biosimdb_interface.form.invenio.run_record_upload(api_url: str, api_key: str, metadata_path: Path, metadata_format: Literal['json', 'yaml', 'ruamel', 'pyyaml'], files: Iterable[Path | str], community: str) → None

Run the uploading of metadata and associated files to an Invenio repository.

Parameters:

• api_url (str) – URL of repository.

• api_key (str) – Repository API key.

• metadata_path (Path) – Path to metadata file.

• metadata_format (Formats) – Format of metadata file (json or yaml).

• files (list[Path | str]) – Files to upload.

• community (str) – Community to which files will be uploaded.

biosimdb_interface.form.validation.validate_with_mdanalysis()

Validate uploaded topology and trajectory files using MDAnalysis.

Saves uploaded files to a temporary directory, attempts to load them with MDAnalysis, then resets file streams for downstream processing. Skips validation if no topology file is uploaded.

Returns:

None if the files are valid or no files were uploaded. str: Error message if MDAnalysis cannot read the files.

biosimdb_interface.form.upload.extract_uploaded_file_metadata()

Extract file metadata from the current request’s uploaded files.

biosimdb_interface.form.upload.prepare_for_invenio(form_data, tmpdir)

Convert form data and upload files from tmpdir to Invenio. Cleans up tmpdir.

Args:

form_data: Flat form data (ImmutableMultiDict or similar) from the webform submission. tmpdir: Path to temporary directory containing uploaded simulation files.

Returns:

draft_id: The Invenio draft record ID of the created upload.

biosimdb_interface.form.upload.save_pending_submission(json_form=None)

Save uploaded files and form data for deferred post-login submission.

Writes uploaded request files to a new temporary directory, computes file metadata from those saved files, and stores pending submission state in the Flask session so submission can resume after OAuth login.

If json_form is provided, this function attaches the computed file metadata under json_form["files"] and writes the result to simulation_metadata.json in the temporary directory.

Args:

json_form: Optional converted/validated BioSim metadata dictionary to persist alongside uploaded files. When provided, file metadata is added before writing.

Side effects:

session[“pending_form_data”]: Set to submitted form data (dict of lists). session[“pending_files_dir”]: Set to temporary directory path containing uploaded files and optional simulation_metadata.json.

biosimdb_interface.form.utils.fill_invenio_metadata(form_data)

Populate a blank Invenio record with form data.

Args:

form_data: Dictionary of parsed form values from form_to_json().

Returns:

dict: Invenio-compatible record dictionary with custom_fields populated.

biosimdb_interface.form.utils.form_to_json(form)

Convert flat HTML form data into a nested dictionary.

Parses bracket-notation field names (e.g. section[field][1][subfield]) into nested dicts and lists. Skips submit/save keys and TEMPLATE entries. Splits vector_value fields from comma-separated strings into float lists.

Args:

form: Flat form data (ImmutableMultiDict or dict) from a POST request.

Returns:

dict: Nested dictionary of form values.

biosimdb_interface.form.utils.remove_empty_fields(d)

Recursively remove empty strings, None, empty dicts, and empty lists from a nested dict.

Args:

d: Nested dictionary to clean.

Returns:

dict: Cleaned dictionary with empty values removed.

Login

OAuth2 authorization code flow for BioSimDB login.

biosimdb_interface.login.login.authz_url() → str

Build the OAuth2 authorization URL with a secure random state parameter.

Stores the state in the session for later verification in the callback.

Returns:

str: The full authorization URL to redirect the user to.

biosimdb_interface.login.login.callback()

Handle the OAuth2 callback from the authorization server.

Verifies the state parameter, exchanges the authorization code for an access token, and redirects to the post-login URL or the webform.

Returns:

Response: Redirect to the next URL on success, or the webform on failure.

biosimdb_interface.login.login.is_logged_in()

Check whether the user has an active access token in the session.

Returns:

bool: True if the user is logged in, False otherwise.

biosimdb_interface.login.login.login()

Redirect the user to the OAuth2 authorization endpoint.

Clears any previous error from the session before initiating the flow.

biosimdb_interface.login.login.logout()

Clear the access token from the session and redirect to the webform.

Returns:

Response: Redirect to the webform.

Schema

Webform schema definition for the BioSim metadata submission form.

Loads the simulation metadata schema from WEBFORM_SCHEMA_PATH (set via environment variable) and exposes it as part of WEBFORM_SCHEMA, which drives the rendered HTML form fields.

The schema is cached in memory and reloaded automatically when the source file changes (detected via modification time), so server restarts are not required after schema updates.

biosimdb_interface.schema.webform.get_simulation_metadata()

Return the simulation metadata schema, reloading from disk if the file has changed.

Compares the current modification time of WEBFORM_SCHEMA_PATH against the cached value. If the file has been modified since the last load, the schema is re-read before returning.

Returns:

dict: Parsed simulation metadata schema.

Read in schema for webform fields and save to python object.

class biosimdb_interface.schema.helpers.SchemaPopulator(schema_path=None)

Loads a webform schema from a local JSON file.

load_schema()

Load the schema JSON file into self.schema.

Returns:

dict: Parsed JSON schema.

biosimdb_interface.schema.helpers.main()

Entry point: load a schema JSON file and print or write the result.

biosimdb_interface.schema.helpers.parse_args()

Parse command-line arguments.

Returns:

argparse.Namespace: Parsed arguments with schema (str) and optional output (str).