API Reference

Settings

The Settings class is a simple container class to hold configuration parameters used throughout EDM. When used from the CLI, the settings object is built from the configuration file and the CLI options.

To create a Settings object from an existing configuration file:

from edm.api import Settings

settings = Setting.from_filename("config.yaml")
# look at the configured authentication
print(settings.auth)
class edm.api.Settings(auth=None, proxies=NOTHING, filename=None, repositories=(), runtime_repositories=(), bundle_repositories=(), store_url='https://packages.enthought.com', repository_cache=NOTHING, root_directory=NOTHING, publisher=NOTHING, log_file=None, max_retries=0, verify_ssl=True, ca_certificates=None, override_ps1=True, shell=None, application_managers=(), solver_kind=<SolverKind.sat: 1>)

Create a new Settings instance.

Any argument passed to the constructor need to be a keyword argument, and is understood as an argument to the update method, e.g.:

settings = Settings(store_url="http://acme.com")

# equivalent to
settings = Settings()
settings.update(store_url="http://acme.com")
evolve(**kw)

Returns a new Settings instance with the given arguments. Everything else will be copied from this instance.

update_from_config(config)

Merge settings from the given config.

Parameters:config (Configuration) – The configuration instance to update from.
assets_cache_directory

New name for the obsolete repository_cache

environments_directory

The directory where environments are stored

indices_cache

The directory where cached indices are stored

proxies_dict

A dictionary <scheme>:<proxy_string> that can be used as the proxies argument for requests.

packages_cache

The directory where downloaded eggs are stored

packages_indices_cache

The directory where cached packages’ indices are stored

packages_directory

The directory where cached extracted packages are stored

runtimes_cache

The directory where downloaded runtimes are stored

runtimes_indices_cache

The directory where cached runtimes’ indices are stored

runtimes_directory

The directory where cached extracted runtimes are stored

storage_directory

The directory where environments metadata are kept

Session

The Session class centralizes network I/O. It is a thin wrapper around a requests.Session, with a few helpers specific to EDM client/server protocol:

settings = Setting(auth=APITokenAuth("api token"))
with Session.authenticated_from_settings(settings) as session:
    # At this stage, the session is authenticated against the packages
    # server configured in settings
    print(session.get("https://packages.enthought.com"))

If you need to create a session without authentication (e.g. you intend to ask the user about authentication details), you would do something as follows:

settings = Settings()
with Session.from_settings(settings) as session:
    print("authentication details ?")
    # GUI or CLI prompt to request user details
    ...
    session.authenticate(auth=(username, password))
    # Or through an API token
    session.authenticate(auth=APITokenAuth("token value"))

Note

to fetch assets such as packages, runtimes, etc. you should not use Session.get directly, but use the AssetsFetcher API instead.

class edm.api.Session(authenticator, proxies=None, verify=True, max_retries=0, publisher=None, ca_certificates=None)

Simple class to handle http session management

It also ensures connection settings such as proxy, SSL CA certification, etc. are handled consistently.

The constructor is considered private, you should use one of the from_* method instead.

Parameters

authenticator : IAuthManager
An authenticator instance
proxies : dict
A proxy dict as expected by requests (and provided by Settings.proxies_dict).
verify : bool
If True, SSL CA are verified (default).
max_retries: int
The number of retries to pass down the requests library.
classmethod authenticated_from_settings(settings)

Create a new session from a settings and fail without authentication.

Parameters:settings (Settings) – The edm settings to use.
classmethod from_settings(settings)

Create a new session from a settings and authenticate if credentials are available.

Parameters:settings (Settings) – The edm settings to use.
authenticate(auth)

Try to authenticate to the configured store with the given authentication.

Existing auth, if it exists, will be discarded

auth: IAuthManager
An authentication object following the IAuthManager interface.

Note

Emit start/end events on the TOPIC_AUTHENTICATE topic.

fetch(url)

Small helper to fetch data from URLS.

Equivalent to a get, but it automatically raises for errors, and the response is streamed.

url: str
A url.
delete(url, *a, **kw)

Do a DELETE on the given url.

The API is the same as requests.Session.delete.

get(url, *a, **kw)

Do a GET on the given url.

The API is the same as requests.Session.get.

head(url, *a, **kw)

Do a HEAD on the given url.

The API is the same as requests.Session.head.

post(url, *a, **kw)

Do a POST on the given url.

The API is the same as requests.Session.post.

EnvironmentsManager

The EnvironmentsManager class defines the API to manipulate registered environments.

The simplest way to create a new instance is to use the from_settings class method:

from edm.api import EnvironmentsManager, Settings

settings = Setting.from_filename("config.yaml")

environments_manager = EnvironmentsManager.from_settings(settings)
for env in environments_manager:
    print("{} installed in {}".format(env.name, env.prefix))

environments_manager.install(
    "python-cpython-2.7.10+1-win_x86.runtime", "test-runtime"
)
class edm.api.EnvironmentsManager(root_directory, environments_directory, storage_directory, runtimes_cache, publisher=None)

A class to manipulate and query the registered environments in a given root directory.

can_create_environment(name)

” Returns True if the given environment can be created

An environment is considered “creatable” iff no environment with the same name has been registered, and when the prefix does not exist

export_bundle(name, settings, bundle_format='2.0')

Return an EnvironmentBundle* class representation of the given environment.

name: str
The environment name.
settings : Settings
This is only used to get the packages and runtimes repositories
format_version : str or MetadataVersion
Which bundle format to use.
install_bundle(bundle, name, settings, asset_fetcher, force=False, install_retries=0)

Create an environment from an EDM bundle specification.

bundle: EnvironmentBundle* class
The EDM bundle to create an environment from.
name: str
The environment name.
install_retries: int
Number of times to retry individual runtime and package install operations. None means no retry.
has_environment(name)

Returns True if the given environment is already registered.

name: str
The environment name
is_environment_consistent(name)

Returns True if the given environment is consistent from a dependency POV.

name: str
The name used to register the environment
install(path, name, sha256=None, force=False, is_upgrade=False, repository_name=None, install_retries=0)

Install a runtime from its file location and its registered name.

Parameters:
  • path (str) – The path to the runtime
  • name (str) – The name used to register the environment
  • sha256 (str) – SHA256 checksum of the runtime archive.
  • force (bool) – If True, remove existing environment, if applicable, and any residual files in target environment directory.
  • install_retries (int) – Number of times to retry runtime installation. None means no retry.
Returns:

environment_root (str) – The environment’s prefix (absolute path)

unpetrified(**kwds)

If environment_name is petrified, unpetrify it for the lifetime of the context, otherwise, do nothing.

iter_environments()

Iterate (name: entry) pairs where each entry is the corresponding IRuntimeInfo metadata.

query_metadata(name)

Returns the IRuntimeInfo for the corresponding environment.

purge(name)

Purge the given environment.

Purging remove every file in the given environment’s prefix, not just files installed by EDM.

name: str
The environment name
remove(name, is_upgrade=False)

Unregister and remove every installed file of the given environment.

name: str
The environment name
upgrade(path, name)

Upgrade the environment name with the given runtime.

path: str
The path to the runtime to upgrade to
name: str
The environment name

PackagesManager

class edm.api.PackagesManager(settings, repositories, environment_info, install_retries=0)

An environment-specific packages manager. This is the main API to manipulate packages in a given environment.

classmethod from_asset_fetcher_and_environment_name(settings, asset_fetcher, name, install_retries=0)

Ctor to create a packages manager from an asset_fetcher and environment name.

This ctor is especially useful when using “non standard” asset fetchers

classmethod from_session_and_environment_name(settings, session, name, install_retries=0)

Helper to create a packages manager from a session and environment name.

It will raise an error if the environment does not exist.

It will also do multiple network IO to populate the packages repository. If you need more control (using concurrent network IO), use the default constructor.

This is often the simplest method to create a PackagesManager instance.

fix_broken(assets_fetcher)

Attempt to automatically fix broken dependencies, conflicts, etc….

fix_broken_command()

Like fix_broken, but returns a CommandContext object instead for delayed execution.

install(*a, **kw)

Install the given requirements.

Parameters:
  • assets_fetcher (AssetsFetcher) –
  • requirement_string (seq) – Sequence of strings, representing requirements.
install_command(*a, **kw)

Like install, but returns an CommandContext object instead for delayed execution.

install_from_requirements(assets_fetcher, requirements)

Install the given requirements, given as (name, EnpkgVersion) pairs, in the same order as given.

Note: no dependency checking is done, each package is installed as is.

ordered_install_from_requirements(assets_fetcher, requirements, modifiers=None)

Install the given requirements, given as (name, EnpkgVersion) pairs.

Before installation, the underlying packages will be installed in the right order (according to topological sort).

Note: this will raise an exception in the solver if the requirements are not consistent (taking into account the passed constraint modifiers).

remove(*a, **kw)

Remove the package with the given names.

It is an error to remove a non installed package.

remove_all(*a, **kw)

Remove every package in the current environment.

It does so in the right order.

remove_command(*a, **kw)

Remove the package with the give names.

It is an error to remove a non installed package.

update(*a, **kw)

Update the given requirements to the latest version.

update_all(*a, **kw)

Update all the packages to the latest version.

upgrade_all(*a, **kw)

Upgrade the environment, that is update every installed package to the latest available version.

Raises:SatisfiabilityError – If there is no consistent solution. Environment is left unchanged.
whats_new()

Return a list of package metadata pairs (installed, latest available).

Command contexts

class edm.api.PackagesContext(callback, pypi_requirements, installed, removed, updated, up_to_dates, constraints, fix_aborted_operation=None)

A simple wrapper class to allow delayed execution of a package request.

It contains all the required information that a UI may require before actual execution.

pypi_requirements = None

List of Requirement instances containing pypi packages.

installed = None

List of packages to be installed.

removed = None

List of packages to be removed.

updated = None

List of packages to be removed.

up_to_dates = None

Requirement: None | PackageMetadata mapping.

up_do_dates[requirement] is None if that requirement is up to date, else is the highest available package.

constraints = None

simplesat.constraints.ConstraintsModifiers Object representing the constraints on this context.

fix_aborted_operation = None

(“fix-aborted-install”, PackageMetadata) or (“fix-aborted-remove”, _DummyPackageInfo), if any previously aborted command will be retried.

has_changes

True if executing this context will change any packages.

Messaging

See the messaging section for an overview of the messaging system.

Publishers

Publishers receive events and dispatch them to registered handlers. Publishers are independent of one another. Consequently, messages sent through one publisher are not visible to other publishers. Within a publisher instance, each event is sent to a specific topic, and each handler is registered to listen to one or more topic.

Note

edm.messaging was primarly designed to handle progress management. While it may be appropriate for other uses, only progress management will be supported.

Note

by design, the messaging subsystem uses no singleton, and there is no implicitly shared state.

class edm.api.Publisher

A simple IPublisher implementation.

topic->Listeners mappings are kept track through a simple dictionary, and the listeners are stored as weak references.

send_message(topic, event)

Send the given event to the given topic.

Parameters:
  • topic (str) – The topic to send to.
  • event (Event) – An event object.
subscribe(func, topic)

Register the given function to listent to the given topic.

Parameters:
  • func (callable) – A function with the signature def f(event)
  • topic (str) – The topic to register the function to.
class edm.api.NullPublisher
send_message(topic, *a, **kw)

Send a message on the given topic.

subscribe(func, topic)

Register the given callable on the given topic.

Handler interfaces

class edm.api.IStartEndSequenceHandler

Generic interface definition for Start/End handlers.

A Start/End handler knows how to handle sequence of the type:

1. StartEvent
2. EndEvent
class edm.api.IProgressHandler

Generic interface definition for progress handlers.

A progress handler knows how to handle sequence of the type:

1. MultiStepsStartEvent
2. MultiStepsStepEvent
...
N+1. MultiStepsStepEvent
N+2. MultiStepsEndEvent

(for N steps)

Handler factories

Pre-canned handler implementations for common cases.

class edm.api.PrintDotHandler(start_message, end_message)

A simple handler that prints a message before the first message, a . for each progress event, and one message at the end.

class edm.api.StartEndHandler(start_message, end_message)

A simple handler that prints a message before the start message, and one message at the end.

Emitters

edm.api.progress_emitter(*args, **kwds)

Context manager to emit events before / during / after some long operation.

It is designed to mimic the click.progressbar API, e.g.:

iterator = iter([1, 2, 3, 4, 5])
with progress_emitter("some.topic", publisher, iterator) as progress:
    for item in progress:
        do_something_slow(item)

You can then follow the progress with an object following the IProgressHandler interface.

topic: string
The topic (e.g. “some.topic”)
publisher: IPublisher
The publisher to use
iterator: iterator
Iterator to iterate over. May be none, in which case the context manager will simply iterate N times, with N = length (see next argument).
length: int
Number of steps to iterate over. If iterator is specified and not None, the length will be guessed. If it cannot be guessed, then the number of iterations is undefined.
start_info: arbitrary object
Arbitrary object, that will be available as the info attribute of the start event.
edm.api.start_end_emitter(*args, **kwds)

Context manager to emit events before / after the yield point.

topic: string
The topic (e.g. “some.topic”)
publisher: IPublisher
The publisher to use