Deploying your plugin#

This guide explains some of the techniques you can use to deploy your plugin.

This guide covers:#

Overview of PyPI and Anaconda
Building your package
Deploying plugins to PyPI
- Manually via twine
- Automatically via GitHub actions
Deploying to Anaconda

Overview of PyPI and Anaconda#

PyPI and Anaconda are two options for how you distribute your package and allow your users to more easily find and install it. Try to deploy to both! But for now, try to at least use PyPI. You can always also provide your users with manual installation instructions (e.g. if you want them to use conda or have specific dependencies).

Building your package#

sdist means source distribution. An sdist includes all of the files that are required to build your package. An sdist may require specific additional software (e.g. compilers) to actually build.

wheel is a prebuilt package, ready to drop into your site-packages directory. It includes compiled OS-specific extensions (if applicable).

You are strongly encouraged to ship both! If the wheel is not present, pip will try to build it from the sdist before installation, and that may fail depending on the package. To see if a given package ships a wheel, check here: https://pypi.org/project/napari/#files

Note: This goes for dependencies too! Check all your dependencies for wheel availability.

build is the recommended package builder that bundles your source code into sdist or wheel distributions. Install build into your local environment and then run it at the root of your package to build your package, as shown below:

   pip install build
   python -m build .

Deploying plugins to PyPI#

Manually via twine.#

twine is a command line client you can use to upload your distribution to PyPI. Note that you will need to set up a PyPI account and authenticate yourself when uploading. See this great guide for a detailed tutorial to building and sharing your first Python packages.

    # twine is a PyPI Client
    # build is a PEP 517 package builder
    $ pip install twine build

    # create a wheel and an sdist
    $ python -m build

    # (Optional) upload to test PyPI
    $ twine upload -r testpypi dist/*

    # Upload to PyPI
    $ twine upload dist/*

Note: python -m build is the modern alternative to setuptools’ python setup.py sdist bdist_wheel. It calls setuptools behind the scenes.

Automatically via GitHub actions#

This requires either:

Running twine as above in a workflow after setting up Python and installing it or
Using a pre-made GitHub action

Here is an example workflow that manually deploys using twine when tests pass and you push a tagged commit.

#your-repo/.github/workflows/deploy.yaml
jobs:
    deploy:
      name: Deploy
      runs on: ubuntu-latest
      if: “success() && startsWith(github.ref, ‘refs/tags/’)”
      steps:
    - uses: actions/checkout@v2

    -     name: Set up Python
           uses: actions/setup-python@v2
     -     with:
           python-version “3.x”

     -     name: install
           run:
               pip install -U pip
               pip install -U build twine
               python -m build

    -     name: Build and publish
          run:  twine upload dist/*
          env:
             TWINE_USERNAME: __token__
             TWINE_PASSWORD: ${{ secrets.TWINE_API_KEY }}

Note: Gate this action on some criterion, e.g. a git tag as above, or some other criterion.

Deploying to Anaconda#

This is only a brief guide to deploying to conda-forge. More information can be found in the conda-forge docs.

Fork https://github.com/conda-forge/staged-recipes
Create a new branch
Create a new folder in recipes directory (copy the existing example)
Update the meta.yaml file to include your package’s build and run requirements
Commit and open a PR to https://github.com/conda-forge/staged-recipes

Once your recipe is approved and merged, the rest happens automagically, and your package will appear on the anaconda cloud.

This is far easier if you already have an sdist published to PyPI.