
.. _cloud-packages:

=====================
Working with packages
=====================

.. contents::
   :local:
   :depth: 1

.. _cloud-packages-overview:

Overview
========

All files uploaded to Anaconda Cloud are stored in packages. Each
Cloud package is visible at its own unique URL based on the 
name of the user who owns the package and the name of the package.

Users can create a Cloud package and then upload files into it.

NOTE: All packages are public if uploaded by users of free accounts.
Packages may be designated as private by 
:ref:`upgrading to a paid account <cloud-accounts-upgrade-plan>`.


For more information, see :ref:`package <cloud-glossary-package>`.

.. _cloud-packages-namespaces:

Namespaces
----------

A namespace is the part of Cloud where a user or organization 
may host packages. For example, the user namespace 
https://anaconda.org/travis contains packages that were uploaded 
and shared by a user named ``travis``.

For more information, see :ref:`cloud-glossary-namespace`.

.. _cloud-packages-labels:

Labels
------

A label is part of the URLs on Cloud where conda looks for packages.

Each file within a package may be tagged with one or more labels, or 
not tagged at all to accept the default label of ``main``.

For more information, see :ref:`cloud-glossary-label`.

.. _cloud-packages-managers:

Using package managers
======================

Cloud supports two package managers,
:ref:`conda <cloud-conda-packages>` and
:ref:`PyPI <cloud-pypi-packages>`. To work with conda or PyPI packages,
you must use their corresponding subdomains:

* To install conda packages from the user ``travis``, use the repository
  URL ``https://conda.anaconda.org/travis``

* To install PyPI packages from the user ``travis``, use the repository
  URL ``https://pypi.anaconda.org/travis``

.. _cloud-conda-packages:

Conda packages
--------------

.. _cloud-uploading-conda-packages:

Uploading conda packages
^^^^^^^^^^^^^^^^^^^^^^^^

This example shows how to build and upload a
`conda <http://conda.pydata.org/>`_ package to Cloud using 
``conda build``.

#. Before you start, install ``anaconda-client`` and ``conda-build``::

       conda install anaconda-client conda-build

#. Choose the repository for which you would like to build the 
   package. In this example, we use a simple public `conda test 
   package <https://github.com/Anaconda-Platform/anaconda-client/tree/develop/example-packages/conda>`_::

       git clone https://github.com/Anaconda-Platform/anaconda-client
       cd anaconda-client/example-packages/conda/

   In this directory, there are two required files, 
   `meta.yaml <https://github.com/Anaconda-Platform/anaconda-client/blob/develop/example-packages/conda/meta.yaml>`_ 
   and `build.sh <https://github.com/Anaconda-Platform/anaconda-client/blob/develop/example-packages/conda/build.sh>`_.
   
   macOS and Linux systems are Unix systems. Packages built for Unix systems 
   require a ``build.sh`` file, packages built for Windows require a 
   ``bld.bat`` file, and packages built for both Windows and Unix systems 
   require both a ``build.sh`` file and a ``bld.bat`` file. All packages 
   require a ``meta.yaml`` file.

#. To build the package, turn off automatic Client uploading 
   and then run the ``conda build`` command::

       conda config --set anaconda_upload no
       conda build .

   All packages built in this way are placed in a subdirectory of 
   :doc:`Anaconda's </anaconda/index>` ``conda-bld`` directory.

#. You can check where the resulting file was placed with the
   ``--output`` option::

       conda build . --output

#. You can upload the test package to Cloud with the 
   :ref:`anaconda upload <cli-upload>` command::

       anaconda login
       anaconda upload /path/to/conda-package.tar.bz2

   NOTE: Replace ``/path/to/`` with the actual path where you 
   stored the package.

For more information on conda's overall build framework, you may 
also want to read the articles `Building conda
packages <http://conda.pydata.org/docs/building/bpp.html>`_ 
and `Tutorials on conda build 
<http://conda.pydata.org/docs/build_tutorials.html>`_.


Installing conda packages
^^^^^^^^^^^^^^^^^^^^^^^^^

You can install conda packages from Cloud by adding channels to 
your conda configuration.

#. Because conda knows how to interact with Cloud, specifying 
   the channel ``sean`` translates to https://anaconda.org/sean::

       conda config --add channels sean

#. You can now install public conda packages from Sean's Cloud
   account. Try installing the ``testci`` package at 
   https://anaconda.org/sean/testci::

       conda install testci

.. _cloud-pypi-packages:

PyPI packages
-------------

.. _uploading-pypi-packages:

Uploading PyPI packages
^^^^^^^^^^^^^^^^^^^^^^^

We can test PyPI package uploading with a small public example 
package saved in the `anaconda-client repository 
<https://github.com/Anaconda-Platform/anaconda-client/tree/develop/example-packages/pypi>`_.

#. Begin by cloning the repository from the command line::

       git clone git@github.com:Anaconda-Platform/anaconda-client.git
       cd anaconda-client/example-packages/pypi/

#. You can now create your PyPI package with the ``setup.py`` script::

       python setup.py sdist

#. The package has now been built as a source tarball and is ready 
   to be uploaded::

       anaconda upload dist/*.tar.gz

   Your package is now available at 
   ``http://anaconda.org/USERNAME/PACKAGE``.

   NOTE: Replace ``USERNAME`` with your username, and ``PACKAGE`` 
   with the package name.

Installing PyPI packages
^^^^^^^^^^^^^^^^^^^^^^^^

The best way to install a PyPI package is using ``pip``. For the 
following command, we use the package we authored in the 
examples above::

    pip install --extra-index-url https://pypi.anaconda.org/USERNAME/simple pypi-test-package

Installing private PyPI packages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The best way to manage access or make PyPI and other packages 
private is to create :ref:`organizations <creating-orgs>` 
or :ref:`groups <org-groups>`, which allow you to set separate 
permissions per package, notebook or environment.

You can also control access with the token system. All Cloud URLs 
can be prefixed with ``/t/$TOKEN`` to access private packages::

    TOKEN=$(anaconda auth --create --name YOUR-TOKEN-NAME)
    pip install --index-url https://pypi.anaconda.org/t/$TOKEN/USERNAME/simple test-package

NOTE: Replace ``YOUR-TOKEN-NAME`` with the name of the token you 
created, ``USERNAME`` with your username and 
``simple test-package`` with the actual test-package name.

Uploading packages
==================

#. To upload package files to Cloud, use the Client command line 
   interface and the :ref:`upload <cli-upload>` command::

       anaconda login
       anaconda upload PACKAGENAME

   NOTE: Replace ``PACKAGENAME`` with the actual package name.

   Cloud automatically detects packages and notebooks, package 
   or notebook types, and their versions.

#. Your package is now available at::

       https://anaconda.org/<USERNAME>/<PACKAGENAME>

   NOTE: Replace ``<USERNAME>`` with your username, and 
   ``<PACKAGENAME>`` with the package name.

#. Your package also can be downloaded by anyone using Client::

       anaconda download USERNAME/PACKAGENAME

   NOTE: Replace ``<USERNAME>`` with your username, and 
   ``<PACKAGENAME>`` with the package name.

.. _cloud-private-packages:

Using private packages
======================

By default, all packages, notebooks and environments uploaded to 
Cloud are accessible to anyone who has access to the repository. 

Packages uploaded to your user channel on Cloud can be marked as 
private using the Web UI:

#. Select the desired package.

#. Select the **Settings** tab.

#. Select Admin in the sidebar.

#. Alternatively, you can reach this page with the following URL::

       https://anaconda.org/<username>/<package>/settings/admin

   NOTE: Replace ``<username>`` with your username, and 
   ``<package>`` with the package name.

NOTE: Jupyter notebooks and conda environments can also be marked 
private using this procedure and URL.

NOTE: Other Cloud users may access your private packages either with 
tokens or by logging in.


Private packages with tokens
----------------------------

To make your private packages available to be accessed with tokens:

#. First create an access :ref:`token <cloud-glossary-token>` 
   that includes the following scope for Client::

       conda:download

   Or, in the Web UI with::

       Allow private downloads from conda repositories

   The token is a random alphanumeric string and this is used to 
   install a package or add a channel from which you want to 
   install private packages.

#. Using the provided token, a user channel can be added to 
   ``config`` with::

       conda config --add channels https://conda.anaconda.org/t/<token>/<channel>

   NOTE: Replace ``<token>`` with the provided token, and 
   ``<channel>`` with a user channel.

#. The token can also be used to install packages without first 
   adding the channel::

       conda install -c https://conda.anaconda.org/t/<token>/<channel> <package>

   NOTE: Replace ``<token>`` with the provided token, 
   ``<channel>`` with a user channel and ``<package>`` with a 
   package name.

#. Private PyPI packages can also be installed using::

       https://pypi.anaconda.org/t/<token>/<channel>

   NOTE: Replace ``<token>`` with the provided token, and 
   ``<channel>`` with a user channel.

Private packages with login
---------------------------

To make your private packages available to users who have logged in: 

#. Create an :ref:`organization <cloud-organizations>`.

#. Create a group in that organization, which may be a read-only 
   group. 

#. Add to the group the users that you want to grant access to.

#. Upload the package to the organization, or transfer an existing 
   package to the organization.

After you grant them access, other users can download and install 
your package using the Web UI or Client.

To download a package:

#. In a browser, navigate to the desired channel.

#. If the organization name is ``OrgName`` and the package name is 
   ``conda-package``, use these commands::

       conda install anaconda-client
       anaconda login
       conda install -c OrgName conda-package

Or instead::

       conda install anaconda-client
       anaconda login
       conda install -c https://conda.anaconda.org/OrgName conda-package

Removing a previous version of a package
========================================

To remove a previous version of one of your packages from Cloud:

#. Select the package name.

#. Select the **Files** tab.

#. Select the checkbox to the left of the version you want to remove.

#. In the **Actions** menu, select Remove.

You may instead use the Client command line interface:

#. Run::

       anaconda remove jsmith/testpack/0.2

   NOTE: Replace ``jsmith`` with your username, ``testpack`` with 
   the package name and ``0.2`` with the desired version.

#. You can now see the change on your profile page::

       https://anaconda.org/<USERNAME>/<PACKAGE>

   NOTE: Replace ``<USERNAME>`` with your username, and 
   ``<PACKAGE>`` with the package name.

Adding a collaborator to a package
==================================

You can add other users that are not part of an organization to 
collaborate on your packages. You will need the usernames of the other users.

#. From your dashboard, select the package by clicking on its name.

#. To display the package settings, select the Settings option.

#. To display the current collaborators, select the Collaborators 
   option.

#. Type the username of the person you want to add as a collaborator,
   and then click the Add button.

NOTE: All collaborators are given full read/write permissions to 
the package, even private packages.

Removing a collaborator from a package
======================================

To revoke package access previously granted to a collaborator:

#. From your dashboard select the package by clicking on its name.

#. To display the package settings, select the Settings option.

#. To display the current collaborators, select the Collaborators 
   option.

#. Click the red X button next to a collaborator to revoke their access.

Transferring a package to a new owner
=====================================

By default, when you create or add packages, they are attached to 
your individual profile. You can transfer ownership to another 
owner account you control, such as an organization profile you 
manage.

To transfer a package to a new owner:

#. From your dashboard--or the dashboard of an organization you
   administer--select the package for which you want to transfer
   ownership.

   The system displays options for that package.

#. To display the package settings, select the Settings option.

#. Select the Admin option.

#. Under Transfer this package to a new owner, click the Transfer
   button.

#. Select the organization name for the new owner.

#. Click the Transfer Ownership button.

Deleting a package
==================

To delete a package from Cloud, including all of its versions:

#. Select the package name.

#. Select the Settings option.

#. In the left sidebar, select Admin.

#. Click Delete.

You may instead use the Client command line interface:

#. Run::

       anaconda remove jsmith/testpak

   NOTE: Replace ``jsmith`` with your user name, and ``testpak`` 
   with the package name.

#. You can now see the change on your profile page::

       https://anaconda.org/<USERNAME>

   NOTE: Replace ``<USERNAME>`` with your username.
