Skip to main content

CEP 4 - Implement initial conda plugin mechanism

Title Implement initial conda plugin mechanism
Status Implemented
Author(s) Bianca Henderson <bhenderson@anaconda.com>, Jannis Leidel <jleidel@anaconda.com>
Created July 5, 2022
Updated August 22, 2022
Discussion https://github.com/conda-incubator/ceps/pull/32
Implementation
  • https://github.com/conda/conda/pull/11435
  • https://github.com/conda/conda/pull/11960

Abstract​

In order to enable customization and extra features that are compatible with and discoverable by conda (but do not necessarily ship as a default part of the conda codebase), we would like to implement an official conda plugin mechanism.

A plugin mechanism in conda would provide many benefits, including (but not limited to) the coverage of underserved use cases, the added ability to extend conda internals via official APIs, as well as lowering the barrier of entry for contributions from other stakeholders in the conda community and ecosystem.

The initial proposal to add this plugin architecture has been officially approved; this current CEP will discuss the specific way that the plugin mechanism will actually be implemented.

Specification​

Plugins in conda will integrate the "hook + entry point" structure by utilizing the pluggy Python framework. This implementation can be broken down via the following two steps:

  • Define the hook(s) to be registered
  • Register the plugin under the conda entrypoint namespace

Hook​

Below is an example of a very basic plugin "hook":

my_plugin.py

import conda.plugins


@conda.plugins.register
def conda_subcommands():
    ...

Packaging via a pyproject.toml file​

Below is an example that configures setuptools using a pyproject.toml file (note that the setup.py file is optional if a pyproject.toml file is defined):

pyproject.toml

[build-system]
requires = ["setuptools", "setuptools-scm"]
build-backend = "setuptools.build_meta"

[project]
name = "my-conda-plugin"
version = "1.0.0"
description = "My conda plugin"
requires-python = ">=3.7"
dependencies = ["conda"]

[project.entry-points."conda"]
my-conda-plugin = "my_plugin"

Packaging via a setup.py file​

Below is an example of an entry point namespace for the custom plugin function, decorated with the plugin hook shown in the "Hook" section above:

setup.py

from setuptools import setup

setup(
    name="my-conda-plugin",
    install_requires="conda",
    entry_points={"conda": ["my-conda-plugin = my_plugin"]},
    py_modules=["my_plugin"],
)

Rationale​

This new conda plugin API ecosystem will bring about many benefits and possibilities, including but not limited to:

  • Custom subcommands
  • Support for packaging-related topics (e.g., virtual packages)
  • Development environment integrations (e.g., shells)
  • Alternative dependency solver backends
  • Experimental features that are not currently covered by conda

As mentioned previously, an official plugin ecosystem will also enable contributors across the conda community to develop and share new features, thus bringing about more functionality and focus on the user experience.

Backwards Compatibility​

There are no expected backwards compatibility issues for this new feature.

Alternatives​

The following lists alternative Python frameworks, libraries, and packages that were considered for use in this proposed conda plugin implementation:

Ultimately, pluggy was decided on as the ideal framework for this project due to its extensive documentation and relatively straightforward "hook + entry point" configuration.

Implementation​

The pull request for the initial conda plugin mechanism implementation includes extensive documentation as well as a tutorial on how to implement a basic custom subcommand. Please add any implementation-related suggestions directly to this pull request.

The method of how these plugins will be shared/distributed is currently undecided and will be discussed in a future CEP.

Resolution​

This was a standard, non-timed-out vote.

This vote has reached quorum (10 + 0 = 10 which is at least 60% of 16).

It has also passed since it recorded 10 "yes" votes and 0 "no" votes giving 10/10 which is greater than 60% of 15.

It should be noted that a request for change was recorded in the pull request about minor implementation details that do not invalidate the previous votes. The author made the requested change.

Reference​

All CEPs are explicitly CC0 1.0 Universal.