API

Configuration

cnxdb.config

cnxdb.config.discover_settings(settings=None)[source]

Discover settings from environment variables

DB_URL is required, while DB_READONLY_URL and DB_SUPER_URL are not required and while default to DB_URL. However, be aware that some parts of the application may not function correctly without these optional values set.

Parameters:settings (dict) – An existing settings value
Returns:dictionary of settings
Return type:dict

See also

See also Configuration for environment variables, defaults and required settings.

Scripting

cnxdb.scripting

cnxdb.scripting.prepare(settings=None)[source]

This function prepares an application/script for use with this codebase.

Returns:an environment dictionary containing the newly created engines, settings and a closer function. The engines value is a sqlalchemy.engine.Engine instance that can be used to connect to the database.
Return type:dict

See also

For instructions on how to use this function see: Scripting Usage

Initialization

cnxdb.init

cnxdb.init.init_db(engine, as_venv_importable=False)[source]

Initialize the database schema, including tables, functions and triggers.

Parameters:
  • engine (sqlalchemy.engine.Engine) – The database connection engine
  • as_venv_importable (bool) – Flag to trigger the use of init_venv() from this function
Returns:

None

cnxdb.init.init_venv(engine)[source]

Sets up the database’s plpython environment for use with a python virtual environment (aka venv). This function can only be run on the same system as the database or on a system with an identical path to a compatible python venv.

The results of this is that plpythonu interpreters will execute with the contents of the venv’s site-packages available for use rather than use the default system python environment only.

Parameters:engine (sqlalchemy.engine.Engine) – The database connection engine
Returns:None

cnxdb.init.manifest

Manifest marker files (manifest.json) are placed in a schema’s directory to properly order the schema files into a linear format that can be loaded into the database.

Contributions

Testing (cnxdb.contrib.testing)

These are functions that are useful in testing. They deal with testing configuration discovery, setting defaults, and inspect the environment.

cnxdb.contrib.testing.get_settings()[source]

Lookup database connection settings. This provides similar results to that of cnxdb.config.discover_settings().

Returns:A dictionary of settings
Return type:dict
cnxdb.contrib.testing.is_py3()[source]

Returns a boolean value if running under python3.x

Return type:bool
cnxdb.contrib.testing.is_venv()[source]

Tells whether the application is running within a virtualenv (aka venv).

Return type:bool
cnxdb.contrib.testing.is_venv_importable()[source]

Determines whether the tests should be run with virtualenv (aka venv) database import features enabled.

By default this will be true if the process is running within a venv. This can be overridden by setting the AS_VENV_IMPORTABLE environment variable to anything other than the string ‘true’.

Returns:enable venv features
Return type:bool

Pyramid (cnxdb.contrib.pyramid)

When used in conjunction with the Pyramid Web Framework this module will setup the cnx-db library within the Pyramid application.

For usage examples, see Pyramid Application Usage

cnxdb.contrib.pyramid.includeme(config)[source]

Used by pyramid to include this package.

This sets up a dictionary of engines for use and the a tables object containing the defined database tables as sqlalchemy Table objects. They can be retrieved via the registry at registry.engines and registry.tables.

Pytest (cnxdb.contrib.pytest)

These are shared pytest fixtures used by this library’s test suite, but also made available to packages using this library. For more information on how pytest fixtures work, look at the pytest fixtures documentation.

cnxdb.contrib.pytest.db_cursor(db_engines)[source]

Creates a database connection and cursor

cnxdb.contrib.pytest.db_cursor_without_db_init(db_engines)[source]

Creates a database connection and cursor

cnxdb.contrib.pytest.db_dict_cursor(db_engines, db_settings)[source]

Creates a database connection and cursor that outputs a dict

cnxdb.contrib.pytest.db_engines(db_settings)[source]

Returns a dictionary of database engine values. These are similar to the format used in cnxdb.scripting.prepare.

cnxdb.contrib.pytest.db_env_vars(mocker, db_settings)[source]

Sets the environment variables used by this project

cnxdb.contrib.pytest.db_init(db_engines)[source]

Initializes the database

cnxdb.contrib.pytest.db_init_and_wipe(db_wipe, db_init)[source]

Combination of the initialization and wiping procedures.

cnxdb.contrib.pytest.db_init_and_wipe_module_scope(db_wipe_module_scope, db_init_module_scope)[source]

Combination of the initialization and wiping procedures.

cnxdb.contrib.pytest.db_init_module_scope(db_engines)[source]

Initializes the database

cnxdb.contrib.pytest.db_settings()[source]

Returns database connection settings. These settings are provided in a similar format to that of cnxdb.config.discover_settings.

cnxdb.contrib.pytest.db_tables_fixture(db_engines)[source]

Provides access to sqlalchemy table objects

cnxdb.contrib.pytest.db_tables_module_scope(db_engines)[source]

Provides access to sqlalchemy table objects

cnxdb.contrib.pytest.db_wipe(db_engines, request)[source]

Cleans up the database after a test run

cnxdb.contrib.pytest.db_wipe_module_scope(db_engines, request)[source]

Cleans up the database after a test run