aiida.control package

User facing APIs to control AiiDA from the verdi cli, scripts or plugins

Submodules

Provides an API for postgres database maintenance tasks.

This API creates and drops postgres users and databases used by the verdi quicksetup commandline tool. It allows convenient access to this functionality from within python without knowing details about how postgres is installed by default on various systems. If the postgres setup is not the default installation, additional information needs to be provided.

class aiida.control.postgres.Postgres(port=None, interactive=False, quiet=True)[source]

Bases: object

Provides postgres database manipulation assuming no prior setup

  • Can be used to create the initial aiida db user and database.
  • Works in every reasonable environment, provided the user can sudo

Tries to use psychopg2 with a fallback to psql subcommands (using sudo su to run as postgres user).

Parameters:
  • port – (str) Assume the database server runs on this port
  • interactive – (bool) Allow prompting the user for information Will also be passed to sudo (if using psycopg2 fails) and to the callback that can be set to be called when automatic setup detection fails
  • quiet – (bool) Suppress messages

Simple Example:

postgres = Postgres()
postgres.determine_setup()
postgres.create_dbuser('username', 'password')
if not postgres.db_exists('dbname'):
    postgres.create_db('username', 'dbname')

Complex Example:

postgres = Postgres(port=5433, interactive=True)
postgres.setup_fail_callback = prompt_db_info
postgres.determine_setup()
if postgres.pg_execute:
    print('setup sucessful!')
__dict__ = dict_proxy({'__module__': 'aiida.control.postgres', 'copy_db': <function copy_db>, '__weakref__': <attribute '__weakref__' of 'Postgres' objects>, 'set_port': <function set_port>, 'determine_setup': <function determine_setup>, 'create_dbuser': <function create_dbuser>, 'drop_db': <function drop_db>, 'create_db': <function create_db>, 'set_setup_fail_callback': <function set_setup_fail_callback>, 'drop_dbuser': <function drop_dbuser>, 'dbuser_exists': <function dbuser_exists>, '__dict__': <attribute '__dict__' of 'Postgres' objects>, 'db_exists': <function db_exists>, '__doc__': "\n Provides postgres database manipulation assuming no prior setup\n\n * Can be used to create the initial aiida db user and database.\n * Works in every reasonable environment, provided the user can sudo\n\n Tries to use psychopg2 with a fallback to psql subcommands (using ``sudo su`` to run as postgres user).\n\n :param port: (str) Assume the database server runs on this port\n :param interactive: (bool) Allow prompting the user for information\n Will also be passed to ``sudo`` (if using ``psycopg2`` fails) and to\n the callback that can be set to be called when automatic setup detection fails\n :param quiet: (bool) Suppress messages\n\n Simple Example::\n\n postgres = Postgres()\n postgres.determine_setup()\n postgres.create_dbuser('username', 'password')\n if not postgres.db_exists('dbname'):\n postgres.create_db('username', 'dbname')\n\n Complex Example::\n\n postgres = Postgres(port=5433, interactive=True)\n postgres.setup_fail_callback = prompt_db_info\n postgres.determine_setup()\n if postgres.pg_execute:\n print('setup sucessful!')\n ", '__init__': <function __init__>, '_no_setup_detected': <function _no_setup_detected>})
__init__(port=None, interactive=False, quiet=True)[source]

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'aiida.control.postgres'
__weakref__

list of weak references to the object (if defined)

_no_setup_detected()[source]

Print a warning message and calls the failed setup callback

copy_db(src_db, dest_db, dbuser)[source]
create_db(dbuser, dbname)[source]

Create a database in postgres

Parameters:
  • dbuser – (str), Name of the user which should own the db.
  • dbname – (str), Name of the database.
create_dbuser(dbuser, dbpass)[source]

Create a database user in postgres

Parameters:
  • dbuser – (str), Name of the user to be created.
  • dbpass – (str), Password the user should be given.
db_exists(dbname)[source]

Check wether a postgres database with dbname exists

Parameters:dbname – Name of the database to check for
Returns:(bool), True if database exists, False otherwise
dbuser_exists(dbuser)[source]

Find out if postgres user with name dbuser exists

Parameters:dbuser – (str) database user to check for
Returns:(bool) True if user exists, False otherwise
determine_setup()[source]

Find out how postgres can be accessed.

Depending on how postgres is set up, psycopg2 can be used to create dbs and db users, otherwise a subprocess has to be used that executes psql as an os user with the right permissions.

drop_db(dbname)[source]

Drop a database in postgres

Parameters:dbname – (str), Name of the database.
drop_dbuser(dbuser)[source]

Drop a database user in postgres

Parameters:dbuser – (str), Name of the user to be dropped.
set_port(port)[source]

Set the port manually

set_setup_fail_callback(callback)[source]

Set a callback to be called when setup cannot be determined automatically

Parameters:callback – a callable with signature callback(interactive, dbinfo)
aiida.control.postgres._pg_execute_not_connected(command, **kwargs)[source]

A dummy implementation of a postgres command execution function.

Represents inability to execute postgres commands.

aiida.control.postgres._pg_execute_psyco(command, **kwargs)[source]

executes a postgres commandline through psycopg2

Parameters:
  • command – A psql command line as a str
  • kwargs – will be forwarded to psycopg2.connect
aiida.control.postgres._pg_execute_sh(command, user='postgres', **kwargs)[source]

executes a postgres command line as another system user in a subprocess.

Parameters:
  • command – A psql command line as a str
  • user – Name of a system user with postgres permissions
  • kwargs – connection details to forward to psql, signature as in psycopg2.connect

To stop sudo from asking for a password and fail if one is required, pass noninteractive=True as a kwarg.

aiida.control.postgres._try_connect(**kwargs)[source]

try to start a psycopg2 connection.

Returns:True if successful, False otherwise
aiida.control.postgres._try_subcmd(**kwargs)[source]

try to run psql in a subprocess.

Returns:True if successful, False otherwise
aiida.control.postgres.manual_setup_instructions(dbuser, dbname)[source]

Create a message with instructions for manually creating a database

aiida.control.postgres.prompt_db_info(*args)[source]

Prompt interactively for postgres database connecting details

Can be used as a setup fail callback for aiida.control.postgres.Postgres

Returns:dictionary with the following keys: host, port, database, user

Create, configure, manage users

aiida.control.user.get_or_new_user(**kwargs)[source]

find an existing user or instantiate a new one (unstored)