Type hinting

conda is an old project that was created when Python type hinting didn’t exist yet. As a result, many parts of its codebase are not annotated. That said, we strive to progressively improve the type annotation coverage with each contribution. On this page, we summarize the guiding principles that you should apply when adding type annotations in your contributions.

Main principles

We adhere to the Typing Best Practices recommended by the official Python documentation. Some additional tips can be found in Google’s Python Guide: Type Annotations (ignore the formatting concerns, those are dealt with automatically by our pre-commit hooks).

From those tips, we emphasize:

• Be abstract on inputs and concrete on outputs (tip: explore the different abstract classes in collections.abc).

• Use from __future__ import annotations in your modules to opt-in for the most recent type hinting capabilities (e.g. deferred evaluation).

• If there’s no return value, that actually means we are returning None. Annotate it!

Consider using multiple signatures

If your type hints are getting too complex (too many unions, many different return type hints), it may be time to consider whether you want to split the types in different signatures with typing.overload decorator. conda.plugins.manager.CondaPluginManager.get_hook_results is a good example for this use case.

Custom type hints

conda ships with some custom types for type hinting. They are spread around the codebase, so sometimes they are not easy to find. This is a summary:

• conda.common.path.PathType: Use it for values that represent file paths.

• conda.common.path.PathTypes: Use it for an iterable of PathType values.

Local development

Linters

We use ruff to lint and format our codebase. We have selected a few type hinting related rules, but we have not added ANN yet. That said, you can enable it temporarily in your pyproject.toml while developing locally.

Type hinting coverage

The linux-typing job in tests.yml runs MyPy and uploads the reports to codecov under the label MyPy. Its only purpose is to track type hinting coverage, not to report type hinting errors (yet).

In this codecov.io webapp report, you can find the coverage for every Python file in the codebase.