API¶
Configuration¶
cnxdb.config
¶
-
cnxdb.config.
discover_settings
(settings=None)[source]¶ Discover settings from environment variables
DB_URL
is required, whileDB_READONLY_URL
andDB_SUPER_URL
are not required and while default toDB_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 acloser
function. Theengines
value is asqlalchemy.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 sqlalchemyTable
objects. They can be retrieved via the registry atregistry.engines
andregistry.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_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_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_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