`types`#

Definition of specific return types for use when defining a conda plugin hook.

Each type corresponds to the plugin hook for which it is used.

Classes#

`CondaPlugin`	Base class for all conda plugins.
`CondaSubcommand`	Return type to use when defining a conda subcommand plugin hook.
`CondaVirtualPackage`	Return type to use when defining a conda virtual package plugin hook.
`CondaSolver`	Return type to use when defining a conda solver plugin hook.
`CondaPreCommand`	Return type to use when defining a conda pre-command plugin hook.
`CondaPostCommand`	Return type to use when defining a conda post-command plugin hook.
`ChannelNameMixin`	Class mixin to make all plugin implementations compatible, e.g. when they
`ChannelAuthBase`	Base class that we require all plugin implementations to use to be compatible.
`CondaAuthHandler`	Return type to use when the defining the conda auth handlers hook.
`CondaHealthCheck`	Return type to use when defining conda health checks plugin hook.
`CondaPreSolve`	Return type to use when defining a conda pre-solve plugin hook.
`CondaPostSolve`	Return type to use when defining a conda post-solve plugin hook.
`CondaSetting`	Return type to use when defining a conda setting plugin hook.
`ProgressBarBase`	Helper class that provides a standard way to create an ABC using
`SpinnerBase`	Helper class that provides a standard way to create an ABC using
`ReporterRendererBase`	Base class for all reporter renderers.
`CondaReporterBackend`	Return type to use when defining a conda reporter backend plugin hook.
`CondaRequestHeader`	Define vendor specific headers to include HTTP requests
`CondaPreTransactionAction`	Return type to use when defining a pre-transaction action hook.
`CondaPostTransactionAction`	Return type to use when defining a post-transaction action hook.
`CondaPrefixDataLoader`	Define new loaders to expose non-conda packages in a given prefix
`EnvironmentSpecBase`	EXPERIMENTAL
`EnvironmentFormat`	Represents supported environment formats.
`CondaEnvironmentSpecifier`	EXPERIMENTAL
`CondaEnvironmentExporter`	EXPERIMENTAL
`CondaPackageExtractor`	Return type to use when defining a conda package extractor plugin hook.
`CondaExceptionEvent`	Structured exception event passed to exception observer plugin callbacks.
`CondaExceptionObserver`	Return type to use when defining a conda exception observer plugin hook.

Attributes#

CondaPrefixDataLoaderCallable

type CondaPrefixDataLoaderCallable = Callable[[PathType, dict[str, PrefixRecord]], dict[str, PrefixRecord]]#

class CondaPlugin#

Base class for all conda plugins.

name: str#: User-facing name of the plugin used for selecting & filtering plugins and error messages.

__post_init__()#

class CondaSubcommand(*, name: str, summary: str, action: collections.abc.Callable[[argparse.Namespace], int | None], configure_parser: collections.abc.Callable[[argparse.ArgumentParser], None])#

class CondaSubcommand(*, name: str, summary: str, action: collections.abc.Callable[[tuple[str, Ellipsis]], int | None], configure_parser: None = None)

Bases: CondaPlugin

Return type to use when defining a conda subcommand plugin hook.

For details on how this is used, see conda_subcommands().

Subcommands support two shapes, distinguished by configure_parser:

If configure_parser is set, action receives the parsed argparse.Namespace.
If configure_parser is omitted, action receives the remaining argv as tuple[str, ...].

Parameters:

name -- Subcommand name (e.g., conda my-subcommand-name).
summary -- Subcommand summary, will be shown in conda --help.
action -- Callable that will be run when the subcommand is invoked.
configure_parser -- Callable that will be run when the subcommand parser is initialized.

summary: str#

action: collections.abc.Callable[[argparse.Namespace], int | None] | collections.abc.Callable[[tuple[str, Ellipsis]], int | None]#

configure_parser: collections.abc.Callable[[argparse.ArgumentParser], None] | None = None#

class CondaVirtualPackage#

Bases: CondaPlugin

Return type to use when defining a conda virtual package plugin hook.

For details on how this is used, see conda_virtual_packages().

Note

The version and build parameters can be provided in two ways:

Direct values: a string or None (where None translates to 0)
Deferred callables: functions that return either a string, None (translates to 0), or NULL (indicates the virtual package should not be exported)

Parameters:

name -- Virtual package name (e.g., my_custom_os).
version -- Virtual package version (e.g., 1.2.3).
build -- Virtual package build string (e.g., x86_64).
override_entity -- Can be set to either to "version" or "build", the corresponding value will be overridden if the environment variable CONDA_OVERRIDE_<name> is set.
empty_override -- Value to use for version or build if the override environment variable is set to an empty string. By default, this is NULL.
version_validation -- Optional version validation function to ensure that the override version follows a certain pattern.

name: str#: User-facing name of the plugin used for selecting & filtering plugins and error messages.

version: str | None | collections.abc.Callable[[], str | None | conda.auxlib._Null]#

build: str | None | collections.abc.Callable[[], str | None | conda.auxlib._Null]#

override_entity: Literal['version', 'build'] | None = None#

empty_override: None | conda.auxlib._Null#

version_validation: collections.abc.Callable[[str], str | None] | None = None#

to_virtual_package() → conda.models.records.PackageRecord | conda.auxlib._Null#

class CondaSolver#

Bases: CondaPlugin

Return type to use when defining a conda solver plugin hook.

For details on how this is used, see conda_solvers().

Parameters:

name -- Solver name (e.g., custom-solver).
backend -- Type that will be instantiated as the solver backend.

name: str#: User-facing name of the plugin used for selecting & filtering plugins and error messages.

backend: type[conda.core.solve.Solver]#

class CondaPreCommand#

Bases: CondaPlugin

Return type to use when defining a conda pre-command plugin hook.

For details on how this is used, see conda_pre_commands().

Parameters:

name -- Pre-command name (e.g., custom_plugin_pre_commands).
action -- Callable which contains the code to be run.
run_for -- Represents the command(s) this will be run on (e.g. install or create).

name: str#: User-facing name of the plugin used for selecting & filtering plugins and error messages.

action: collections.abc.Callable[[str], None]#

run_for: set[str]#

class CondaPostCommand#

Bases: CondaPlugin

Return type to use when defining a conda post-command plugin hook.

For details on how this is used, see conda_post_commands().

Parameters:

name -- Post-command name (e.g., custom_plugin_post_commands).
action -- Callable which contains the code to be run.
run_for -- Represents the command(s) this will be run on (e.g. install or create).

name: str#: User-facing name of the plugin used for selecting & filtering plugins and error messages.

action: collections.abc.Callable[[str], None]#

run_for: set[str]#

class ChannelNameMixin(channel_name: str, *args, **kwargs)#

Class mixin to make all plugin implementations compatible, e.g. when they use an existing (e.g. 3rd party) requests authentication handler.

Please use the concrete ChannelAuthBase in case you're creating an own implementation.

channel_name#

class ChannelAuthBase(channel_name: str, *args, **kwargs)#

Bases: ChannelNameMixin, requests.auth.AuthBase

Base class that we require all plugin implementations to use to be compatible.

Authentication is tightly coupled with individual channels. Therefore, an additional channel_name property must be set on the requests.auth.AuthBase based class.

class CondaAuthHandler#

Bases: CondaPlugin

Return type to use when the defining the conda auth handlers hook.

Parameters:

name -- Name (e.g., basic-auth). This name should be unique and only one may be registered at a time.
handler -- Type that will be used as the authentication handler during network requests.

name: str#: User-facing name of the plugin used for selecting & filtering plugins and error messages.

handler: type[ChannelAuthBase]#

class CondaHealthCheck#

Bases: CondaPlugin

Return type to use when defining conda health checks plugin hook.

Health checks are diagnostic actions that report on the state of a conda environment. They are invoked via conda doctor.

Health checks can optionally provide a fix capability, which is invoked via conda doctor --fix or conda doctor --fix <name>.

Fixer guidelines:

Fixers receive a confirm function that handles user confirmation and dry-run mode automatically. Simply call it with your message:

In normal mode: Prompts the user for confirmation (default: no).
In dry-run mode: Raises DryRunExit (handled by the framework).
If user declines: Raises CondaSystemExit (handled by the framework).

Example:

from conda.plugins.types import ConfirmCallback

def my_fixer(prefix: str, args: Namespace, confirm: ConfirmCallback) -> int:
    issues = find_issues(prefix)
    if not issues:
        print("No issues found.")
        return 0

    print(f"Found {len(issues)} issues")
    confirm("Fix these issues?")
    # ... perform fix ...
    return 0

For details on how this is used, see conda_health_checks().

Parameters:

name -- Health check identifier (e.g., missing-files).
action -- Callable that performs the check: action(prefix, verbose) -> None.
fixer -- Optional callable that fixes issues: fixer(prefix, args, confirm) -> int. The confirm parameter is a function to call for user confirmation. It raises an exception if the user declines or in dry-run mode.
summary -- Short description of what the check detects (shown in --list).
fix -- Short description of what the fix does (shown in --list).

name: str#: User-facing name of the plugin used for selecting & filtering plugins and error messages.

action: collections.abc.Callable[[str, bool], None]#

fixer: collections.abc.Callable[[str, argparse.Namespace, ConfirmCallback], int] | None = None#

summary: str | None = None#

fix: str | None = None#

class CondaPreSolve#

Bases: CondaPlugin

Return type to use when defining a conda pre-solve plugin hook.

For details on how this is used, see conda_pre_solves().

Parameters:

name -- Pre-solve name (e.g., custom_plugin_pre_solve).
action -- Callable which contains the code to be run.

name: str#: User-facing name of the plugin used for selecting & filtering plugins and error messages.

action: collections.abc.Callable[[frozenset[conda.models.match_spec.MatchSpec], frozenset[conda.models.match_spec.MatchSpec]], None]#

class CondaPostSolve#

Bases: CondaPlugin

Return type to use when defining a conda post-solve plugin hook.

For details on how this is used, see conda_post_solves().

Parameters:

name -- Post-solve name (e.g., custom_plugin_post_solve).
action -- Callable which contains the code to be run.

name: str#: User-facing name of the plugin used for selecting & filtering plugins and error messages.

action: collections.abc.Callable[[str, tuple[conda.models.records.PackageRecord, Ellipsis], tuple[conda.models.records.PackageRecord, Ellipsis]], None]#

class CondaSetting#

Bases: CondaPlugin

Return type to use when defining a conda setting plugin hook.

For details on how this is used, see conda_settings().

Parameters:

name -- name of the setting (e.g., config_param)
description -- description of the setting that should be targeted towards users of the plugin
parameter -- Parameter instance containing the setting definition
aliases -- alternative names of the setting

name: str#: User-facing name of the plugin used for selecting & filtering plugins and error messages.

description: str#

parameter: conda.common.configuration.Parameter#

aliases: tuple[str, Ellipsis] = ()#

class ProgressBarBase(description: str, **kwargs)#

Bases: abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

description#

abstractmethod update_to(fraction) → None#

abstractmethod refresh() → None#

abstractmethod close() → None#

finish()#

classmethod get_lock()#

class SpinnerBase(message: str, fail_message: str = 'failed\n')#

Bases: abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

message#

fail_message = Multiline-String#

Show Value

"""failed
"""

abstractmethod __enter__()#

abstractmethod __exit__(exc_type, exc_val, exc_tb)#

class ReporterRendererBase#

Bases: abc.ABC

Base class for all reporter renderers.

render(data: Any, **kwargs) → str#

abstractmethod detail_view(data: dict[str, str | int | bool], **kwargs) → str#: Render the output in a "tabular" format.

abstractmethod envs_list(data: collections.abc.Iterable[str] | dict[str, dict[str, str | bool | None]], **kwargs) → str#: Render a list of environments

abstractmethod progress_bar(description: str, **kwargs) → ProgressBarBase#: Return a ProgressBarBase~ object to use as a progress bar

classmethod progress_bar_context_manager() → contextlib.AbstractContextManager#: Returns a null context by default but allows plugins to define their own if necessary

abstractmethod spinner(message, failed_message) → SpinnerBase#: Return a SpinnerBase~ object to use as a spinner (i.e. loading dialog)

abstractmethod prompt(message: str = 'Proceed', choices=('yes', 'no'), default: str = 'yes') → str#: Allows for defining an implementation of a "yes/no" confirmation function

class CondaReporterBackend#

Bases: CondaPlugin

Return type to use when defining a conda reporter backend plugin hook.

For details on how this is used, see: conda_reporter_backends().

Parameters:

name -- name of the reporter backend (e.g., email_reporter) This is how the reporter backend with be references in configuration files.
description -- short description of what the reporter handler does
renderer -- implementation of ReporterRendererBase that will be used as the reporter renderer

name: str#: User-facing name of the plugin used for selecting & filtering plugins and error messages.

description: str#

renderer: type[ReporterRendererBase]#

class CondaRequestHeader#

Bases: CondaPlugin

Define vendor specific headers to include HTTP requests

For details on how this is used, see conda_request_headers() and conda_session_headers().

Parameters:

name -- name of the header used in the HTTP request
value -- value of the header used in the HTTP request

name: str#: User-facing name of the plugin used for selecting & filtering plugins and error messages.

value: str#

class CondaPreTransactionAction#

Bases: CondaPlugin

Return type to use when defining a pre-transaction action hook.

For details on how this is used, see conda_pre_transaction_actions().

Parameters:

name -- Pre transaction name (this is just a label)
action -- Action class which implements plugin behavior. See Action for implementation details

name: str#: User-facing name of the plugin used for selecting & filtering plugins and error messages.

action: type[conda.core.path_actions.Action]#

class CondaPostTransactionAction#

Bases: CondaPlugin

Return type to use when defining a post-transaction action hook.

For details on how this is used, see conda_post_transaction_actions().

Parameters:

name -- Post transaction name (this is just a label)
action -- Action class which implements plugin behavior. See Action for implementation details

name: str#: User-facing name of the plugin used for selecting & filtering plugins and error messages.

action: type[conda.core.path_actions.Action]#

class CondaPrefixDataLoader#

Bases: CondaPlugin

Define new loaders to expose non-conda packages in a given prefix as PrefixRecord objects.

Parameters:

name -- name of the loader
loader -- a function that takes a prefix and a dictionary that maps package names to PrefixRecord objects. The newly loaded packages must be inserted in the passed dictionary accordingly, and also returned as a separate dictionary.

name: str#: User-facing name of the plugin used for selecting & filtering plugins and error messages.

loader: CondaPrefixDataLoaderCallable#

class EnvironmentSpecBase#

Bases: abc.ABC

EXPERIMENTAL

Base class for all environment specifications.

Environment specs parse different types of environment definition files (environment.yml, requirements.txt, pyproject.toml, etc.) into a common Environment object model.

detection_supported: ClassVar[bool] = True#

abstractmethod can_handle() → bool#

Determines if the EnvSpec plugin can read and operate on the environment described by the filename.

Returns bool:: returns True, if the plugin can interpret the file.
Raises:: raises an exception if it can not handle the file. The exception should describe why the file can not be handled.

property env: conda.models.environment.Environment#

Abstractmethod:

Express the provided environment file as a conda environment object.

Returns Environment:: the conda environment represented by the file.

property available_platforms: tuple[str, Ellipsis]#

Platforms this spec can produce an Environment for.

Defaults to (context.subdir,). Multi-platform specs (conda-lock.yml, pixi.lock) override to return every platform declared in the input file.

env_for(platform: str) → conda.models.environment.Environment#

Return the Environment for a specific platform.

Defaults to returning env when platform matches context.subdir, and raising ValueError otherwise. Multi-platform specs override this method to build the Environment directly from the parsed input file without constructing one per platform.

To iterate every platform a spec covers:

envs = (spec.env_for(p) for p in spec.available_platforms)

class EnvironmentFormat#

Bases: enum.Enum

Represents supported environment formats.

FUTURE: Python 3.11+, use enum.StrEnum

lockfile = 'lockfile'#

environment = 'environment'#

__str__() → str#

property label: str#

class CondaEnvironmentSpecifier#

Bases: CondaPlugin

EXPERIMENTAL

Return type to use when defining a conda env spec plugin hook.

For details on how this is used, see conda_environment_specifiers().

Parameters:

name -- name of the spec (e.g., environment_yaml)
aliases -- user-friendly format aliases (e.g., ("yaml",)). Defaults to an empty list.
environment_spec -- EnvironmentSpecBase subclass handler
default_filenames -- default filename patterns this specifier handles (e.g., ("environment.yml", "*.conda-lock.yml"))
description -- user-friendly description of what the format does. Defaults to the name if not provided.
environment_format -- EnvironmentFormat category. Defaults to EnvironmentFormat.environment.

name: str#: User-facing name of the plugin used for selecting & filtering plugins and error messages.

environment_spec: type[EnvironmentSpecBase]#

default_filenames: tuple[str, Ellipsis] = ()#

aliases: tuple[str, Ellipsis] = ()#

description: str | None = None#

environment_format: EnvironmentFormat#

__post_init__()#

class CondaEnvironmentExporter#

Bases: CondaPlugin

EXPERIMENTAL

Return type to use when defining a conda environment exporter plugin hook supporting a single platform.

Parameters:

name -- name of the exporter (e.g., environment-yaml)
aliases -- user-friendly format aliases (e.g., ("yaml",))
default_filenames -- default filenames this exporter handles (e.g., ("environment.yml", "environment.yaml"))
export -- callable that exports an Environment to string format for a single platform
multiplatform_export -- callable that exports an Environment to string format for multiple platforms
description -- user-friendly description of what the format does. Defaults to the name if not provided.
environment_format -- EnvironmentFormat category. Defaults to EnvironmentFormat.environment.

name: str#: User-facing name of the plugin used for selecting & filtering plugins and error messages.

aliases: tuple[str, Ellipsis]#

default_filenames: tuple[str, Ellipsis]#

export: SinglePlatformEnvironmentExport | None = None#

multiplatform_export: MultiPlatformEnvironmentExport | None = None#

description: str | None = None#

environment_format: EnvironmentFormat#

__post_init__()#

class CondaPackageExtractor#

Bases: CondaPlugin

Return type to use when defining a conda package extractor plugin hook.

Package extractors handle the extraction of different package archive formats. Each extractor specifies which file extensions it supports and provides an extraction function to unpack the archive.

For details on how this is used, see conda_package_extractors().

Parameters:

name -- Extractor name (e.g., conda-package, wheel-package).
extensions -- List of file extensions this extractor handles (e.g., [".conda", ".tar.bz2"] or [".whl"]).
extract -- Callable that extracts the package archive. Takes the source archive path and the destination directory where the package contents should be extracted.

name: str#: User-facing name of the plugin used for selecting & filtering plugins and error messages.

extensions: list[str]#

extract: PackageExtract#

class CondaExceptionEvent#

Structured exception event passed to exception observer plugin callbacks.

Frozen to prevent plugins from mutating exception state. Structured args follow the threading.ExceptHookArgs / sys.UnraisableHookArgs pattern for forward compatibility.

The exception triple (exc_type, exc_value, exc_traceback) is always populated. The remaining fields describe the conda runtime state and default to None when the runtime isn't initialized (e.g. MemoryError during early startup). Runtime fields are populated all-or-nothing: if conda_version is not None, the runtime was available and all other fields are populated (active_prefix may still be None when no environment is active).

Warning

Do not store references to exc_value or exc_traceback beyond the lifetime of the callback. This can create reference cycles and prevent garbage collection.

Parameters:

exc_type -- The exception class.
exc_value -- The exception instance.
exc_traceback -- The traceback object.
argv -- The command-line arguments at the time of error (frozen copy of sys.argv). None if unavailable.
conda_version -- The conda version string. None if unavailable.
return_code -- The exit code conda will return for this error. None if unavailable.
active_prefix -- The currently active conda environment prefix, or None if no environment is active (also None when the runtime is unavailable).
target_prefix -- The prefix the command was operating on.
channels -- The configured channel names at the time of error (canonical names, e.g. defaults, conda-forge).
subdir -- The platform subdirectory (e.g., linux-64, osx-arm64).
offline -- Whether conda is running in offline mode (--offline).
dry_run -- Whether conda is running in dry-run mode (--dry-run).
quiet -- Whether conda is running in quiet mode (--quiet).
json -- Whether conda is running in JSON output mode (--json).

exc_type: type[BaseException]#

exc_value: BaseException#

exc_traceback: types.TracebackType#

argv: tuple[str, Ellipsis] | None = None#

conda_version: str | None = None#

return_code: int | None = None#

active_prefix: str | None = None#

target_prefix: str | None = None#

channels: tuple[str, Ellipsis] | None = None#

subdir: str | None = None#

offline: bool | None = None#

dry_run: bool | None = None#

quiet: bool | None = None#

json: bool | None = None#

class CondaExceptionObserver#

Bases: CondaPlugin

Return type to use when defining a conda exception observer plugin hook.

Exception observers are purely observational, modelled after CPython's sys.excepthook. They cannot suppress, modify, or redirect the exception. Their return value is ignored.

For details on how this is used, see conda_exception_observers().

Warning

Do not store references to exc_value or exc_traceback beyond the lifetime of the callback. This can create reference cycles and prevent garbage collection.

Parameters:

name -- Observer name (e.g., missing-package-reporter).
hook -- Callable invoked with a CondaExceptionEvent instance. Must not raise; any exception is caught and logged.
watch_for --
Set of exception class names this observer watches for. Matches against the full MRO. Examples:
- {"BaseException"} — fires for every exception.
- {"Exception"} — all standard exceptions (excludes KeyboardInterrupt, SystemExit).
- {"CondaError"} — all conda errors and subclasses.
- {"PackagesNotFoundError"} — a specific error and its subclasses (e.g. PackagesNotFoundInChannelsError).
- {"MemoryError"}, {"KeyboardInterrupt"}, {"SystemExit"} — specific non-conda exceptions.
- {"CondaError", "MemoryError"} — combine scopes.
For non-CondaError exceptions the conda-specific fields on CondaExceptionEvent may be None.

name: str#: User-facing name of the plugin used for selecting & filtering plugins and error messages.

hook: collections.abc.Callable[[CondaExceptionEvent], None]#

watch_for: set[str]#

types#

Classes#

Attributes#

`types`#