Clients

class ploomber.clients.Client

Abstract class for all clients

Clients are classes that communicate with another system (usually a database), they provide a thin wrapper around libraries that implement clients to avoid managing connections directly. The most common use case by far is for a Task/Product to submit some code to a system, a client just provides a way of doing so without dealing with connection details.

A Client is reponsible for making sure an open connection is available at any point (open a connection if none is available).

However, clients are not strictly necessary, a Task/Product could manage their own client connections. For example the NotebookRunner task does have a Client since it only calls an external library to run.

Notes

Method’s names were chosen to resemble the ones in the Python DB API Spec 2.0 (PEP 249)

abstract close()

Close connection if there is one active

abstract property connection

Return a connection, open one if there isn’t any

abstract execute(code)

Execute code

class ploomber.clients.DBAPIClient(connect_fn, connect_kwargs, split_source=None)

A client for a PEP 249 compliant client library

Parameters
  • connect_fn (callable) – The function to use to open the connection

  • connect_kwargs (dict) – Keyword arguments to pass to connect_fn

  • split_source (str, optional) – Some database drivers do not support multiple commands in a single execute statement. Use this optiion to split commands by a given character (e.g. ‘;’) and send them one at a time. Defaults to None (no spltting)

close()

Close connection if there is an active one

property connection

Return a connection, open one if there isn’t any

execute(code)

Execute code with the existing connection

class ploomber.clients.RemoteShellClient(connect_kwargs, path_to_directory, run_template='bash {{path_to_code}}')

EXPERIMENTAL: Client to run commands in a remote shell

close()

Close connection if there is one active

property connection

Return a connection, open one if there isn’t any

execute(code)

Run code

class ploomber.clients.SQLAlchemyClient(uri, split_source='default')

Client for connecting with any SQLAlchemy supported database

Parameters
  • uri (str) – URI to pass to sqlalchemy.create_engine

  • split_source (str, optional) – Some database drivers do not support multiple commands in a single execute statement. Use this optiion to split commands by a given character (e.g. ‘;’) and send them one at a time. Defaults to ‘default’, which splits by ‘;’ if using SQLite database, but does not perform any splitting with other databases. If None, it will never split, a string value is interpreted as the token to use for splitting statements regardless of the database type

Notes

SQLite client does not support sending more than one command at a time, if using such backend code will be split and several calls to the db will be performed.

close()

Closes all connections

property connection

Return a connection from the pool

property engine

Returns a SQLAlchemy engine

execute(code)

Execute code

class ploomber.clients.ShellClient(run_template='bash {{path_to_code}}', subprocess_run_kwargs={'shell': False, 'stderr': - 1, 'stdout': - 1})

Client to run command in the local shell

Parameters
  • run_template (str) – Template for executing commands, must include the {{path_to_code}} placeholder which will point to the rendered code. Defaults to ‘bash {{path_to_code}}’

  • subprocess_run_kwargs (dict) – Keyword arguments to pass to the subprocess.run when running run_template

close()

Close connection if there is one active

property connection

Return a connection, open one if there isn’t any

execute(code)

Run code