Web Application¶

Core web application modules for the Flask-based HED Web Tools.

Application factory¶

The application factory pattern for creating Flask instances.

This module contains the factory for creating the HEDTools application.

class hedweb.app_factory.AppFactory[source]¶

Bases: object

A factory for creating the HEDTools application.

This factory is used to create a Flask application with the given configuration. It also sets up CSRF protection for the application.

static create_app(config_class) → flask.Flask[source]¶

Creates the Flask app and registers the blueprints.

Parameters:: config_class (str or class) – A string path to config class or the actual config class.
Returns:: The initialized Flask app.
Return type:: Flask

static get_static_url_path(config_class) → str[source]¶

Gets the static URL path from the config class.

Parameters:: config_class (str) – A string path to the config class.
Returns:: The static URL path.
Return type:: str

Routes¶

Web interface routes and HTTP endpoint handlers.

Handles the routes for the HED web application.

hedweb.routes.columns_info_results() → str¶: Process columns info request and return results as a JSON string. :returns: A serialized JSON string containing the columns information. :rtype: str

hedweb.routes.events_results() → flask.Response¶

Process events form submission and return results.

Returns:: The response appropriate to the request.
Return type:: Response

Notes

The response depends on the request: - validation: text file with validation errors - assemble: an assembled events file containing assembled events. - generate: a JSON sidecar generated from the events file.

hedweb.routes.schemas_results() → flask.Response¶

Process schema form submission and return results.

Returns:: The response appropriate to the request.
Return type:: Response

Notes

The response depends on the request: - validation: text file with validation errors - convert: text file with converted schema.

hedweb.routes.schema_version_results() → str¶

Return the version of the schema as a JSON string.

Returns:: A serialized JSON string containing the version of the schema.
Return type:: str

hedweb.routes.schema_versions_results() → str¶

Return serialized JSON string with HED versions.

Returns:: A serialized JSON string containing a list of the HED versions.
Return type:: str

hedweb.routes.services_results() → str¶

Perform the requested web service and return the results in JSON.

Returns:: A serialized JSON string containing processed information.
Return type:: str

hedweb.routes.sidecars_results() → flask.Response¶

Process sidecar form submission and return results.

Returns:: The response appropriate to the request.
Return type:: Response

Notes

The response depends on the request: - validation: text file with validation errors - convert: converted sidecar. - extract: 4-column spreadsheets. - merge: a merged sidecar.

hedweb.routes.spreadsheets_results() → flask.Response¶

Process the spreadsheets in the form and return results.

Returns:: The response appropriate to the request.
Return type:: Response

Notes

The response depends on the request: - validation: text file with validation errors - convert: converted spreadsheets.

hedweb.routes.strings_results() → str¶

Process string entered in a form text box.

Returns:: The response appropriate to the request.
Return type:: Response

Notes

The response depends on the request, but appears in text box. - validation: validation errors - convert: converted string.

hedweb.routes.render_events_form() → str¶

Form for BIDS event file (with JSON sidecar) processing.

Returns:: A rendered template for the events form.
Return type:: str

hedweb.routes.render_home_page() → str¶

The home page.

Returns:: A rendered template for the home page.
Return type:: str

hedweb.routes.render_schemas_form() → str¶

The schema processing form.

Returns:: A rendered template for the schema processing form.
Return type:: str

hedweb.routes.render_services_form() → str¶

Landing page for HED hedweb services.

Returns:: A dummy rendered template so that the service can get a csrf token.
Return type:: str

hedweb.routes.render_sidecars_form() → str¶

The sidecar form.

Returns:: A rendered template for the sidecar form.
Return type:: str

hedweb.routes.render_spreadsheets_form() → str¶

The spreadsheets form.

Returns:: A rendered template for the spreadsheets form.
Return type:: str

hedweb.routes.render_strings_form() → str¶

The HED string form.

Returns:: A rendered template for the HED string form.
Return type:: str

Process form¶

Form data extraction and validation for web requests.

Handles processing of web form posts in a standardized way.

class hedweb.process_form.ProcessForm[source]¶

Bases: object

static get_input_from_form(request) → dict[source]¶

Get a dictionary of input from a service request.

Parameters:: request (Request) – A Request object containing user data for the service request.
Returns:: A dictionary containing input arguments for calling the service request.
Return type:: dict

static set_input_objects(arguments, request)[source]¶

Extract and set input objects from the request form data.

This method processes uploaded files and form data to create appropriate input objects (TabularInput, HedString, SpreadsheetInput) and adds them to the arguments dictionary.

Parameters:

arguments (dict) – Dictionary to store the extracted input objects.
request (Request) – A Request object containing form data and uploaded files.

static set_json_files(arguments, request)[source]¶

Extract and set JSON files from the request form data.

This method processes uploaded JSON files (sidecars, remodel files, definition files) and creates appropriate objects from them, adding them to the arguments dictionary.

Parameters:

arguments (dict) – Dictionary to store the extracted JSON file objects.
request (Request) – A Request object containing form data and uploaded files.

static set_queries(arguments, request)[source]¶

Update arguments with lists of string queries

Parameters:

arguments (dict) – A dictionary with the extracted parameters that are to be processed.
request (Request) – A Request object containing form data.

static set_schema_from_request(arguments, request)[source]¶

Create a HedSchema object from form pull-down box and set schema in arguments.

Parameters:

arguments (dict) – Dictionary of parameters to which the schema will be added.
request (Request) – A Request object containing form data.

static set_tsv_schema(arguments, request, files_key, schema_key)[source]¶

Set the schema in arguments from a folder of TSV files.

This method handles uploaded TSV schema files that are uploaded as a folder structure, saves them to a temporary directory, and loads the schema from the appropriate file.

Parameters:

arguments (dict) – Dictionary of parameters to which the schema will be added.
request (Request) – A Request object containing form data.
files_key (str) – The key in the request.files dictionary that contains the TSV files.
schema_key (str) – The key in the arguments dictionary where the schema will be stored.

static set_schema_from_version(arguments, request)[source]¶

Set the schema field in arguments from a version string or uploaded file.

This method handles schema selection from a version dropdown or from an uploaded schema file when “other” version is selected.

Parameters:

arguments (dict) – Dictionary of parameters to which the schema will be added.
request (Request) – A Request object containing form data.

static get_schema(schema_input=None, version=None, as_xml_string=None) → HedSchema[source]¶

Return a HedSchema object from the given parameters.

Parameters:

schema_input (str or FileStorage or None) – Input url or file.
version (str or None) – A schema version string to load, e.g. “8.2.0” or “score_1.1.0”.
as_xml_string (str or None) – A schema in xml string format.

Returns:

A HedSchema object loaded from the input.

Return type:

HedSchema

Raises:

HedFileError – The schema can’t be loaded for some reason.

Process service¶

Core orchestration and business logic for REST services.

Handles processing of service requests in a standardized way.

class hedweb.process_service.ProcessServices[source]¶

Bases: object

A class to process service requests and return results in a standard format.

__init__()[source]¶

static set_input_from_request(request) → dict[source]¶

Get a dictionary of input from a service request.

Parameters:: request (Request) – A Request object containing user data for the service request.
Returns:: A dictionary containing input arguments for calling the service request.
Return type:: dict

static set_parameters(arguments, params)[source]¶

Update arguments with the columns that requested for the service.

Parameters:

arguments (dict) – A dictionary with the extracted parameters that are to be processed.
params (dict) – The service request dictionary extracted from the Request object.

static get_list(name, params) → list[source]¶

Return value in params associated with name as a list.

Parameters:

name (str) – The name of the parameter to extract from the params dictionary.
params (dict) – A dictionary of the service request values.

Returns:

A list of values associated with the name in the params dictionary.

Return type:

list

static set_queries(arguments, params)[source]¶

Update arguments with lists of string queries and query names.

Parameters:

arguments (dict) – A dictionary with the extracted parameters that are to be processed.
params (dict) – The service request dictionary extracted from the Request object.

static set_sidecar(arguments, params)[source]¶

Update arguments with the sidecars if there are any.

Parameters:

arguments (dict) – A dictionary with the extracted parameters that are to be processed.
params (dict) – The service request dictionary extracted from the Request object.

static set_definitions(arguments, params)[source]¶

Update arguments with the definitions if there are any.

Parameters:

arguments (dict) – A dictionary with the extracted parameters that are to be processed.
params (dict) – The service request dictionary extracted from the Request object.

static set_input_objects(arguments, params)[source]¶

Update arguments with the information in the params dictionary.

Parameters:

arguments (dict) – A dictionary with the extracted parameters that are to be processed.
params (dict) – A dictionary of the service request values.

Updates the arguments dictionary with the input objects including events, spreadsheets, schemas or strings.

static set_remodel_parameters(arguments, params)[source]¶

Update arguments with the remodeler information if any.

Parameters:

arguments (dict) – A dictionary with the extracted parameters that are to be processed.
params (dict) – The service request dictionary extracted from the Request object.

Updates the arguments dictionary with the sidecars.

static get_service_info(params) → dict[source]¶

Get a dictionary with the service request command information filled in.

Parameters:: params (dict) – A dictionary of the service request values.
Returns:: A dictionary with the command, command target and options resolved from the service request.
Return type:: dict

static get_input_schema(parameters)[source]¶

Get a HedSchema or HedSchemaGroup object from the parameters.

Parameters:: parameters (dict) – A dictionary of parameters extracted from the service request.

static process(arguments) → dict[source]¶

Call the desired service processing function and return the results in a standard format.

Parameters:: arguments (dict) – A dictionary of arguments for the processing resolved from the request.
Returns:: A dictionary of results in standard response format to be JSONified.
Return type:: dict

static get_process(target) → BaseOperations[source]¶

Return the BaseProcess object specific to the target string.

Parameters:: target (str) – Indicates what type of BaseProcess is needed.
Returns:: A processing object of a subclass of BaseOperations.
Return type:: BaseOperations

static package_spreadsheet(results) → dict[source]¶

Get the transformed results dictionary where spreadsheets are converted to strings.

Parameters:: results (dict) – The dictionary of results in standardized form returned from processing.
Returns:: The results transformed so that all entries are strings.
Return type:: dict

static get_services_list() → dict[source]¶

Get a formatted string describing services using the resources/services.json file

Returns:: dictionary in standard form with data as formatted string of services.
Return type:: dict

static get_parameter_string(params) → str[source]¶

Get a formatted string describing the parameters for a service. :param params: A list of parameters for the service. :type params: list

Returns:: A formatted string describing the parameters.
Return type:: str

Web utilities¶

Common web application helper functions.

Utilities for handling web requests and responses in the HED web application.

hedweb.web_util.convert_hed_versions(hed_info) → list[source]¶

Convert a hed_info dictionary to a list of HED version strings.

Parameters:: hed_info (dict) – A dictionary with HED version strings, where keys are prefixes and values are lists of HED versions.
Returns:: A list of HED versions with prefixes applied.
Return type:: list

hedweb.web_util.file_extension_is_valid(filename, accepted_extensions=None) → bool[source]¶

Return True if the file extension is an accepted one.

Parameters:

filename (str) – The name of the file to be checked.
accepted_extensions (list) – A list of accepted extensions.

Returns:

True if the file has an accepted extension.

Return type:

bool

hedweb.web_util.filter_issues(issues, check_for_warnings)[source]¶: Filter an issues list by severity level to allow warnings.

hedweb.web_util.form_has_file(files, file_field, valid_extensions=None) → bool[source]¶

Return True if a file with valid extension is in the request.

Parameters:

files (Request.files) – A Request object files dictionary containing request information about files.
file_field (str) – Name of the form field containing the file name.
valid_extensions (list) – A list of valid extensions.

Returns:

True if a file is present in a request object.

Return type:

bool

hedweb.web_util.form_has_option(form, option_name, target_value=None) → bool[source]¶

Return True if given option has a specific value.

Parameters:

form (Request.form) – A Request.form dictionary containing the request.
option_name (str) – The name of the radio button group in the hedweb form.
target_value (str) – The name of the selected radio button option.

Returns:

True if the target radio button has been set and false otherwise.

Return type:

bool

Notes

This is used for radio buttons and check boxes.

hedweb.web_util.form_has_url(form, url_field, valid_extensions=None) → bool[source]¶

Return True if the url_field has a valid extension.

Parameters:

form (Request.form) – A Request object form data.
url_field (str) – The name of the form field with the URL to be parsed.
valid_extensions (list) – A list of valid extensions.

Returns:

True if a URL is present in request object.

Return type:

bool

hedweb.web_util.generate_download_file_from_text(results, file_header=None) → flask.Response[source]¶

Generate a download file from text output.

Parameters:

results (dict) – Text with newlines for iterating.
file_header (str) – Optional header for download file blob.

Returns:

A Response object containing the downloaded file.

Return type:

Response

hedweb.web_util.generate_download_spreadsheet(results) → flask.Response[source]¶

Generate a download Excel file.

Parameters:: results (dict) – Dictionary with the results to be downloaded.
Returns:: A Response object containing the downloaded file.
Return type:: Response

hedweb.web_util.generate_filename(base_name, name_prefix=None, name_suffix=None, extension=None, append_datetime=False) → str[source]¶

Generate a filename for the attachment.

Parameters:

base_name (str or None) – Name of the base, usually the name of the file that the issues were generated from.
name_prefix (str or None) – Prefix prepended to the front of the base name.
name_suffix (str or None) – Suffix appended to the end of the base name.
extension (str or None) – Extension to use.
append_datetime (bool) – If True, append the current date-time to the base output filename.

Returns:

Name of the attachment other containing the issues.

Return type:

str

Notes

The form prefix_basename_suffix + extension.

hedweb.web_util.generate_text_response(results) → flask.Response[source]¶

Generate a download response.

Parameters:: results (dict) – Dictionary containing the results of the data.
Returns:: A Response object containing the downloaded file.
Return type:: Response

hedweb.web_util.generate_download_zip_file(results) → flask.Response[source]¶

Generate a download response.

Parameters:: results (dict) – Dictionary of results to use in constructing response.
Returns:: A Response object containing the downloaded file.
Return type:: Response

hedweb.web_util.get_hed_schema_from_pull_down(request) → HedSchema[source]¶

Create a HedSchema object from form pull-down box.

Parameters:: request (Request) – A Request object containing form data.
Returns:: The HED schema to use.
Return type:: HedSchema

hedweb.web_util.get_option(options, option_name, default_value) → str[source]¶

Get an option value from a dictionary of options.

Parameters:

options (dict) – A dictionary of options.
option_name (str) – The name of the option to retrieve.
default_value (str) – The default value to return if the option is not found.

Returns:

The value of the option if found, otherwise the default value.

Return type:

str

hedweb.web_util.get_parsed_name(filename, is_url=False) → tuple[str, str][source]¶

Parse a filename or URL to extract the display name and file type. :param filename: The name of the file or URL to be parsed. :type filename: str :param is_url: If True, treat the filename as a URL. :type is_url: bool

Returns:: A tuple containing the display name and file type.
Return type:: tuple[str, str]

hedweb.web_util.get_schema_versions(hed_schema) → str[source]¶

Get the formatted version of a HedSchema or HedSchemaGroup.

Parameters:: hed_schema (HedSchema or HedSchemaGroup or None) – The schema or schema group to get the version from.
Returns:: The formatted version of the schema for display purposes.
Return type:: str
Raises:: ValueError – If the provided hed_schema is not a HedSchema or HedSchemaGroup.

hedweb.web_util.handle_error(ex, hed_info=None, title=None, return_as_str=True) → str | dict[source]¶

Handle an error by returning a dictionary or simple string.

Parameters:

ex (Exception) – The exception raised.
hed_info (dict) – A dictionary of information describing the error.
title (str) – A title to be included with the message.
return_as_str (bool) – If true return as string otherwise as dictionary.

Returns:

Contains error information.

Return type:

Union[str, dict]

hedweb.web_util.handle_http_error(ex) → flask.Response[source]¶

Handle http error.

Parameters:: ex (Exception) – A class that extends python Exception class.
Returns:: A response object indicating the field_type of error.
Return type:: Response

hedweb.web_util.get_exception_message(ex) → dict[source]¶

Extract a suitable message for exception as a dictionary

Parameters:: ex (Exception) – A class that extends python Exception class.
Returns:: A dict indicating the field_type of error.
Return type:: dict

hedweb.web_util.package_results(results) → flask.Response[source]¶

Package a results dictionary into a standard form.

Parameters:: results (dict) – A dictionary with the results.
Returns:: A Response object containing the results in a standard format.
Return type:: Response