feat: Deprecate top-level imports (#1282)

news/1282.removal.md

+Deprecate the top-level imports from `pdm` module, it will be removed in the future.

pdm/__init__.py

+import warnings
 from pkgutil import extend_path
+from typing import Any
 
 __path__ = extend_path(__path__, __name__)  # type: ignore
 # Export for plugin use
-from pdm.cli.commands.base import BaseCommand
-from pdm.core import Core
-from pdm.installers import InstallManager, Synchronizer
-from pdm.project import Config, ConfigItem, Project
+from pdm.cli.commands.base import BaseCommand as _BaseCommand
+from pdm.core import Core as _Core
+from pdm.installers import InstallManager as _InstallManager
+from pdm.installers import Synchronizer as _Synchronizer
+from pdm.project import Config as _Config
+from pdm.project import ConfigItem as _ConfigItem
+from pdm.project import Project as _Project
 
-__all__ = (
-    "Project",
-    "Config",
-    "ConfigItem",
-    "BaseCommand",
-    "InstallManager",
-    "Synchronizer",
-    "Core",
-)
+_deprecated = {
+    "Project": (_Project, "pdm.project"),
+    "Config": (_Config, "pdm.project"),
+    "ConfigItem": (_ConfigItem, "pdm.project"),
+    "BaseCommand": (_BaseCommand, "pdm.cli.commands.base"),
+    "InstallManager": (_InstallManager, "pdm.installers"),
+    "Synchronizer": (_Synchronizer, "pdm.installers"),
+    "Core": (_Core, "pdm.core"),
+}
+
+__all__ = tuple(_deprecated)
+
+
+def __getattr__(name: str) -> Any:
+    if name in _deprecated:
+        obj, module = _deprecated[name]
+        warnings.warn(
+            f"Deprecating top-level `from pdm import {name}`. "
+            f"Import it from {module} instead."
+        )
+        return obj
+    raise AttributeError(name)

pdm/cli/commands/venv/__init__.py

 import argparse
 from typing import List
 
-from pdm import Project
+from pdm.project import Project
 from pdm.cli.commands.base import BaseCommand
 from pdm.cli.commands.venv.activate import ActivateCommand
 from pdm.cli.commands.venv.create import CreateCommand

pdm/cli/commands/venv/backends.py

@@ -5,7 +5,8 @@ import sys
 from pathlib import Path
 from typing import Any, List, Mapping, Optional, Tuple, Type
 
-from pdm import Project, termui
+from pdm.project import Project
+from pdm import termui
 from pdm.cli.commands.venv.utils import get_venv_prefix
 from pdm.exceptions import PdmUsageError, ProjectError
 from pdm.models.python import PythonInfo

pdm/cli/commands/venv/create.py

 import argparse
 
-from pdm import BaseCommand, Project
+from pdm.cli.commands.base import BaseCommand
+from pdm.project import Project
 from pdm.cli.commands.venv.backends import BACKENDS
 from pdm.cli.options import verbose_option
 

pdm/cli/commands/venv/purge.py

 import argparse
 import shutil
 
-from pdm import Project, termui
+from pdm.project import Project
+from pdm import termui
 from pdm.cli.commands.base import BaseCommand
 from pdm.cli.commands.venv.utils import iter_central_venvs
 from pdm.cli.options import verbose_option

pdm/cli/commands/venv/remove.py

@@ -2,7 +2,8 @@ import argparse
 import shutil
 from pathlib import Path
 
-from pdm import Project, termui
+from pdm.project import Project
+from pdm import termui
 from pdm.cli.commands.base import BaseCommand
 from pdm.cli.commands.venv.utils import iter_venvs
 from pdm.cli.options import verbose_option