API Reference

pdm.core.Core

A high level object that manages all classes and configurations

add_config(name, config_item) staticmethod

Add a config item to the configuration class.

Parameters:

Name	Type	Description	Default
name	str	The name of the config item	required
config_item	pdm.project.config.ConfigItem	The config item to add	required

create_project(root_path=None, is_global=False, global_config=None)

Create a new project object

Parameters:

Name	Type	Description	Default
root_path	PathLike	The path to the project root directory	None
is_global	bool	Whether the project is a global project	False
global_config	str	The path to the global config file	None

Returns:

Type	Description
Project	The project object

get_command(args) staticmethod

Get the command name from the arguments

handle(project, options)

Called before command invocation

load_plugins()

Import and load plugins under pdm.plugin namespace A plugin is a callable that accepts the core object as the only argument.

Example

def my_plugin(core: pdm.core.Core) -> None:
    ...

main(args=None, prog_name=None, obj=None, **extra)

The main entry function

register_command(command, name=None)

Register a subcommand to the subparsers, with an optional name of the subcommand.

Parameters:

Name	Type	Description	Default
command	Type[pdm.cli.commands.base.BaseCommand]	The command class to register	required
name	str	The name of the subcommand, if not given, command.name is used	None

pdm.core.Project

Core project class.

Parameters:

Name	Type	Description	Default
core	Core	The core instance.	required
root_path	str | Path | None	The root path of the project.	required
is_global	bool	Whether the project is global.	False
global_config	str | Path | None	The path to the global config file.	None

config: Mapping[str, Any] cached property

A read-only dict configuration

default_source: RepositoryConfig property

Get the default source from the pypi setting

project_config: Config cached property

Read-and-writable configuration dict for project settings

add_dependencies(requirements, to_group='default', dev=False, show_message=True, write=True)

Add requirements to the given group, and return the requirements of that group.

env_or_setting(var, key)

Get a value from environment variable and fallback on a given setting.

Returns None if both the environment variable and the key does not exists.

find_interpreters(python_spec=None, search_venv=None)

Return an iterable of interpreter paths that matches the given specifier,

which can be

1. a version specifier like 3.7
2. an absolute path
3. a short name like python3
4. None that returns all possible interpreters

get_best_matching_cpython_version(use_minimum=False)

Returns the best matching cPython version that fits requires-python, this platform and arch. If no best match could be found, return None.

Default for best match strategy is "highest" possible interpreter version. If "minimum" shall be used, set use_minimum to True.

get_provider(strategy='all', tracked_names=None, for_install=False, ignore_compatibility=NotSet, direct_minimal_versions=False, env_spec=None, locked_repository=None)

Build a provider class for resolver.

:param strategy: the resolve strategy :param tracked_names: the names of packages that needs to update :param for_install: if the provider is for install :param ignore_compatibility: if the provider should ignore the compatibility when evaluating candidates :param direct_minimal_versions: if the provider should prefer minimal versions instead of latest :returns: The provider object

get_reporter(requirements, tracked_names=None)

Return the reporter object to construct a resolver.

:param requirements: requirements to resolve :param tracked_names: the names of packages that needs to update :param spinner: optional spinner object :returns: a reporter

get_repository(cls=None, ignore_compatibility=NotSet, env_spec=None)

Get the repository object

get_resolver(allow_uv=True)

Get the resolver class to use for the project.

get_setting(key)

Get a setting from its dotted key (without the tool.pdm prefix).

Returns None if the key does not exists.

get_synchronizer(quiet=False, allow_uv=True)

Get the synchronizer class to use for the project.

iter_interpreters(python_spec=None, search_venv=None, filter_func=None, respect_version_file=True)

Iterate over all interpreters that matches the given specifier. And optionally install the interpreter if not found.

resolve_interpreter()

Get the Python interpreter path.

use_pyproject_dependencies(group, dev=False)

Get the dependencies array and setter in the pyproject.toml Return a tuple of two elements, the first is the dependencies array, and the second value is a callable to set the dependencies array back.

write_lockfile(toml_data, show_message=True, write=True, **_kwds)

Write the lock file to disk.

Signals

Added in version 1.12.0

The signal definition for PDM.

Example

from pdm.signals import post_init, post_install

def on_post_init(project):
    project.core.ui.echo("Project initialized")
# Connect to the signal
post_init.connect(on_post_init)
# Or use as a decorator
@post_install.connect
def on_post_install(project, candidates, dry_run):
    project.core.ui.echo("Project install succeeded")

post_build: NamedSignal = pdm_signals.signal('post_build') module-attribute

Called after a project is built.

Parameters:

Name	Type	Description	Default
project	Project	The project object	required
artifacts	Sequence[str]	The locations of built artifacts	required
config_settings	dict[str, str] | None	Additional config settings passed via args	required

post_init: NamedSignal = pdm_signals.signal('post_init') module-attribute

Called after a project is initialized.

Parameters:

Name	Type	Description	Default
project	Project	The project object	required

post_install: NamedSignal = pdm_signals.signal('post_install') module-attribute

Called after a project is installed.

Parameters:

Name	Type	Description	Default
project	Project	The project object	required
packages	list[Package]	The packages installed	required
dry_run	bool	If true, won't perform any actions	required

post_lock: NamedSignal = pdm_signals.signal('post_lock') module-attribute

Called after a project is locked.

Parameters:

Name	Type	Description	Default
project	Project	The project object	required
resolution	dict[str, list[Candidate]]	The resolved candidates	required
dry_run	bool	If true, won't perform any actions	required

post_publish: NamedSignal = pdm_signals.signal('post_publish') module-attribute

Called after a project is published.

Parameters:

Name	Type	Description	Default
project	Project	The project object	required

post_run: NamedSignal = pdm_signals.signal('post_run') module-attribute

Called after any run.

Parameters:

Name	Type	Description	Default
project	Project	The project object	required
script	str	the script name	required
args	Sequence[str]	the command line provided arguments	required

post_script: NamedSignal = pdm_signals.signal('post_script') module-attribute

Called after any script.

Parameters:

Name	Type	Description	Default
project	Project	The project object	required
script	str	the script name	required
args	Sequence[str]	the command line provided arguments	required

post_use: NamedSignal = pdm_signals.signal('post_use') module-attribute

Called after use switched to a new Python version.

Parameters:

Name	Type	Description	Default
project	Project	The project object	required
python	PythonInfo	Information about the new Python interpreter	required

pre_build: NamedSignal = pdm_signals.signal('pre_build') module-attribute

Called before a project is built.

Parameters:

Name	Type	Description	Default
project	Project	The project object	required
dest	str	The destination location	required
config_settings	dict[str, str] | None	Additional config settings passed via args	required

pre_install: NamedSignal = pdm_signals.signal('pre_install') module-attribute

Called before a project is installed.

Parameters:

Name	Type	Description	Default
project	Project	The project object	required
packages	list[Package]	The packages to install	required
dry_run	bool	If true, won't perform any actions	required

pre_invoke: NamedSignal = pdm_signals.signal('pre_invoke') module-attribute

Called before any command is invoked.

Parameters:

Name	Type	Description	Default
project	Project	The project object	required
command	str | None	the command name	required
options	Namespace	the parsed arguments	required

pre_lock: NamedSignal = pdm_signals.signal('pre_lock') module-attribute

Called before a project is locked.

Parameters:

Name	Type	Description	Default
project	Project	The project object	required
requirements	list[Requirement]	The requirements to lock	required
dry_run	bool	If true, won't perform any actions	required

pre_publish: NamedSignal = pdm_signals.signal('pre_publish') module-attribute

Called before a project is published.

Parameters:

Name	Type	Description	Default
project	Project	The project object	required

pre_run: NamedSignal = pdm_signals.signal('pre_run') module-attribute

Called before any run.

Parameters:

Name	Type	Description	Default
project	Project	The project object	required
script	str	the script name	required
args	Sequence[str]	the command line provided arguments	required

pre_script: NamedSignal = pdm_signals.signal('pre_script') module-attribute

Called before any script.

Parameters:

Name	Type	Description	Default
project	Project	The project object	required
script	str	the script name	required
args	Sequence[str]	the command line provided arguments	required