get_project(url=None, username=None, password=None, token=None, scope=None, scope_id=None, env_filename=None, status='ACTIVE', check_certificates=None)[source]

Retrieve and return the KE-chain project to be used throughout an app.

This helper is made to bootstrap a pykechain enabled python script or an jupyter notebook with the correct project (technically this is a pykechain.models.Scope model).

When no parameters are passed in this function, it will try to retrieve url, token, scope (or scope_id) from the environment variables or a neatly placed ‘.env’ file.

when the environment variable KECHAIN_FORCE_ENV_USE is set to true, (or ok, on, 1, yes) then the use of environmentvariables for the retrieval of the scope are enforced. The following environment variables can be set:

KECHAIN_URL           - full url of KE-chain where to connect to eg: 'https://<some>'
KECHAIN_TOKEN         - authentication token for the KE-chain user provided from KE-chain user account control
KECHAIN_USERNAME      - the username for the credentials
KECHAIN_PASSWORD      - the password for the credentials
KECHAIN_SCOPE         - the name of the project / scope. Should be unique, otherwise use scope_id
KECHAIN_SCOPE_ID      - the UUID of the project / scope.
KECHAIN_FORCE_ENV_USE - set to 'true', '1', 'ok', or 'yes' to always use the environment variables.
KECHAIN_SCOPE_STATUS  - the status of the Scope to retrieve, defaults to None to retrieve all scopes
KECHAIN_CHECK_CERTIFICATES - if the certificates of the URL should be checked. default to True if not present.

New in version 1.12.

  • url (basestring or None) – (optional) url of KE-chain

  • username (basestring or None) – (optional) username for authentication (together with password, if not token)

  • password (basestring or None) – (optional) password for username/password authentication (together with username, if not token)

  • token (basestring or None) – (optional) token for authentication (if not username/password)

  • scope (basestring or None) – (optional) name of the scope to retrieve from KE-chain.

  • scope_id (basestring or None) – (optional) UUID of the scope to retrieve and return from KE-chain

  • env_filename (basestring or None) – (optional) name of the environment filename to bootstrap the Client

  • status (basestring or None) – (optional) status of the scope to retrieve, defaults to enums.Scopestatus.ACTIVE

  • check_certificates (bool or None) – (optional) if to check TLS/SSL Certificates. If nothing provided (None) it ensures it does check certficates.



  • NotFoundError – If the scope could not be found

  • ClientError – If the client connection to KE-chain was unsuccessful

  • APIError – If other Errors occur to retrieve the scope


An example with parameters provided

>>> from pykechain import get_project
>>> project = get_project(url='http://localhost:8000',
...     username='foo', password='bar', scope='1st!')
>>> print(

An example with a .env file on disk:

# This is an .env file on disk.
>>> project = get_project(env_filename='/path/to/.env')

An example for get_project that will extract all from the environment variables

>>> env_vars = os.environ
>>> env_vars.get('KECHAIN_TOKEN')
>>> env_vars.get('KECHAIN_URL')
>>> env_vars.get('KECHAIN_SCOPE')
Bike Project
>>> project = get_project()
Bike Project