Skip to content

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 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 
1
2
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[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 cached property #

A read-only dict configuration

default_source property #

Get the default source from the pypi setting

parent_workspace_project property #

Return the nearest parent project that can host a workspace.

project_config cached property #

Read-and-writable configuration dict for project settings

workspace_project property #

Return the parent workspace project if this project is a member.

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.

add_member(path, *, show_message=True, dry_run=False) #

Add a project path to the workspace members.

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, freethreaded=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.

has_member(path) #

Check if the given path is configured as a workspace member.

is_lockfile_fresh() #

Return whether the lockfile satisfies the current project inputs.

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.

iter_members() #

Iterate over resolved workspace member paths.

iter_workspace_dependencies() #

Iterate over implicit editable requirements for workspace members.

lock_inputs() #

Return the canonical project inputs that determine a lock resolution.

lock_inputs_enabled() #

Return whether canonical lock inputs should be validated and persisted.

maybe_add_to_workspace() #

Add this project to the nearest parent workspace when applicable.

pyproject_content_hash(algo='sha256') #

Return a lockfile content hash including workspace members.

remove_member(path, *, show_message=True, dry_run=False) #

Remove an exact project path from the workspace members.

resolve_interpreter() #

Get the Python interpreter path.

split_extras_groups(all_groups) #

Split the groups into extras and non-extras.

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.

with_workspace_dependencies(requirements, *, exclude=None) #

Return requirements with implicit workspace member dependencies included.

Members already declared in other dependency groups are skipped so they keep those groups in the lockfile instead of being forced into default (#3816).

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

Write the lock file to disk.

Signals#

Tip

Added in 1.12.0.

The signal definition for PDM.

Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
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 = 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 = pdm_signals.signal('post_init') module-attribute #

Called after a project is initialized. Args: project (Project): The project object

post_install = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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 = pdm_signals.signal('pre_lock') module-attribute #

Called before a project is locked. Args: project (Project): The project object requirements (list[Requirement]): The requirements to lock dry_run (bool): If true, won't perform any actions

pre_publish = 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 = 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 = 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