Common utility functions

from alexandria3k import common

Functionality common to multiple modules

exception common.Alexandria3kError(message)

An exception raised by errors detected by the Alexandria3k API. These errors are caught by the CLI and displayed only through their message. API clients might want to catch these errors and report them in a friendly manner.

exception common.Alexandria3kInternalError(message)

An exception raised by internal errors detected by the Alexandria3k API. These errors are propagated to the top level and are not caught by the CLI, thus resulting in a reportable stack trace.

common.data_from_uri_provider(source)

Given a file path, a URL, or this package’s resource path return a readable source for its contents.

Parameters

source (str) – A file path, a URL, or an internal data source starting with resource:.

common.ensure_table_exists(connection, table_name)

Terminate the program with an error message if the specified table does not exist.

Parameters

  • connection (Connection) – The database connection to use for checking the table’s existence.

  • table_name (str) – The table to check for existence.

common.ensure_unlinked(file_path)

Ensure that the file at the specified path does not exist by unlinking it, if needed.

Parameters

file_path (str) – Path to the file that must not exist.

common.get_string_resource(file_path)

Return the contents of the named file relative to the package’s source code directory.

Parameters

file_path (str) – The file’s file path relative to the src/alexandria3k directory.

common.is_unittest()

Return True if the routine is executed in a unit test.

common.is_url(url)

Return true if url looks like a URL.

Parameters

url (str) – The URL to match

common.log_sql(statement)

Return the specified SQL statement. If the debug “sql” value is set, output a copy of the statement on the standard output.

Parameters

statement (str) – The statement that will be executed.

common.program_version()

Return a string identifying the program’s version.

common.query_result(cursor, query)

Return the result of executing the specified query.

Parameters

  • cursor (Cursor) – Database cursor to use for executing the query.

  • query (str) – The query to execute.

common.remove_sqlite_comments(script)

Remove SQLite comments (– and C-style) from the passed script. This cannot handle comment characters embedded in strings.

Parameters

script (str) – An SQL script, possibly multi-line, possibly containing C-style block comments (/* … */).

common.set_fast_writing(connection, name='main')

Implement very fast database inserts at the risk of possible data corruption in case of a crash. We don’t really care, because we assume the database is populated in one go from empty, and if it gets corrupted the process can be repeated. This increases speed in ORCID works population by 50: from 845291 / 2 records in 16980 s (40 ms / record) to 3225659 / 2 records in 1292 s (800 μs / record). It also reduces the time required to run the Crossref tests from 994 ms to 372 ms. See https://stackoverflow.com/a/58547438/20520 for measurements behind this approach.

Parameters

  • connection (Connection) – Connection to the database to configure.

  • name (str, optional) – Name of the database to configure.

common.table_exists(cursor, table_name)

Return True if the specified database table exists.

Parameters

  • cursor (Cursor) – Database cursor to use for executing the required query.

  • table_name (str) – The table to check for existence.

common.try_sql_execute(execution_context, statement)

Return the result of executing the specified SQL statement. The statement is logged through log_sql. If the satement’s execution fails the program terminates with the failure’s error message.

Parameters

  • execution_context – The context in which the execute method will be called to evaluate the statement.

  • statement (str) – The statement that will be executed.

common.warn(message)

Output a warning on the standard error stream with the specified message.

Parameters

message (str) – The message to output.