API Reference

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. 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 submission form and handle save/submit actions.

On GET, renders the empty form. On POST, validates uploaded files with MDAnalysis, then either downloads form data as JSON (save) or initiates submission to BioSimDB (submit).

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.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.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()

Save uploaded files and form data to a temp directory for post-login submission.

Stores uploaded files in a new temporary directory and saves the form data and directory path in the Flask session so the submission can be resumed after OAuth login.

Side effects:

session[“pending_form_data”]: Set to the submitted form data as a dict. session[“pending_files_dir”]: Set to the path of the temporary directory.

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.