.. _bundles:

=======
Bundles
=======

An EDM environment bundle is essentially a JSON serialization of an
environment's metadata. Bundles are the most reliable way of sharing
EDM environments as they not only allow the user to replicate the set
of installed dependencies but also support persistence for constraint
modifiers, the list of manually installed packages, and the runtime
version and implementation.

.. note::

  Refer `environment bundles <https://docs.enthought.com/edm/user/cli.html?highlight=bundles#environment-bundles>`_ on how to create bundles with edm.

EDS supports bundle repositories to store and share edm bundles.

List bundles in a repository
============================

A common part of upload workflow is to interactively inspect the
contents of a repository to verify that new artifacts are present. The
format of the command to list bundles is::

    $ hatcher bundles list <organization-name> <repository-name> <platform>

For example, to list the bundles in the ``enthought/free`` repository for
the ``win-x86_64`` platform, the following command is used::

  $ hatcher bundles list enthought free win-x86_64

  Bundle Name    Bundle Version    Python Tag
  -------------  ----------------  ------------
  mayavi_demo    1.0-1             cp27
  mayavi_demo    1.0-2             cp27
  ...

.. note::

    The valid platforms can be listed with the command in
    :ref:`list-platforms`.

Upload bundle to a repository
=============================

As part of an automated build workflow, it may be required to
upload the new build artifact to a development repository in the Enthought
Deployment Server. The upload command for bundles is constructed as follows::

    $ hatcher bundles upload <organization-name> <repository-name> <platform> <filename>

For example, if a new ``mayavi_demo-2.0-2.bundle`` bundle has been built it may be uploaded to an
``internal-dev`` repository::

    $ hatcher bundles upload enthought internal-dev win-x86_64 mayavi_demo-2.0-2.bundle

Once the upload is complete, before long the bundle should be visible in
the repository::

  $ hatcher bundles list enthought internal-dev win-x86_64

  Bundle Name    Bundle Version    Python Tag
  -------------  ----------------  ------------
  mayavi_demo    2.0-2             cp27
  mayavi_demo    1.0-1             cp27
  mayavi_demo    1.0-2             cp27
  ...


.. note::

    - The valid platforms can be listed with the command in
      :ref:`list-platforms`.
    - The filename of the bundle is expected to follow the
      ``<name-with-underscores>-<version>-<build>.bundle`` template.
    - Only **metadata** bundles are supported for uploading.


Download bundle from a repository
=================================

After a bundle has been uploaded to one of the Enthought Deployment Server
repositories, you may want to download it on some machine and create a new
Python environment. The download command for bundles is constructed as follows::

    $ hatcher bundles download <organization-name> <repository-name> <platform> <python-tag> <bundle name> <bundle version> <output directory>

To create a new environment with the downloaded bundle, you can
use EDM in the same way you would for any other bundle file::

    $ edm envs import <environmnent-name> -f <download-bundle-file-path>

.. note::

   For the environment creation to work, you will need to make sure
   your `~/.edm.yaml` includes the corresponding package and runtime
   repositories that are referenced by the bundle description under
   the ``repositories`` and ``runtime_repositories`` configuration
   options.

Inspect the bundle metadata
===========================

To quickly check the contents/requirements of an uploaded bundle you
can use the ``metadata`` command which is constructed as follows::

  $ hatcher bundles metadata <organization-name> <repository-name> <platform> <python-tag> <bundle name> <bundle version>

Which will print out the bundle description as a json string.



Retrieve the bundle repository index
====================================

The bundle repository index can be also downloaded as a json string with the
``index`` command which is constructed as follows::

  $ hatcher bundles metadata <organization-name> <repository-name> <platform>

Which returns the index of available bundles as a json string grouped by python
tag and bundle name.