chore(doc): document Python class methods

abn · abn · commit c9d82b19de41 · 2025-01-30T17:23:22.000+01:00
diff --git a/src/poetry/utils/env/python/manager.py b/src/poetry/utils/env/python/manager.py
@@ -85,11 +85,27 @@ def minor_version(self) -> Version:
 
     @classmethod
     def get_active_python(cls) -> Python | None:
+        """
+        Fetches the active Python interpreter from available system paths or falls
+        back to finding the first valid Python executable named "python".
+
+        An "active Python interpreter" in this context is an executable (or a symlink)
+        with the name `python`. This is done so to detect cases where pyenv or
+        alternatives are used.
+
+        This method first uses the `ShutilWhichPythonProvider` to detect Python
+        executables in the path. If no interpreter is found using, it attempts
+        to locate a Python binary named "python" via the `findpython` library.
+
+        :return: An instance representing the detected active Python,
+                 or None if no valid environment is found.
+        """
         for python in ShutilWhichPythonProvider().find_pythons():
             return cls(python=python)
 
-        # fallback to findpython
-        if python := findpython.find():
+        # fallback to findpython, restrict to finding only executables
+        # named "python" as the intention here is just that, nothing more
+        if python := findpython.find("python"):
             return cls(python=python)
 
         return None
@@ -103,6 +119,9 @@ def from_executable(cls, path: Path | str) -> Python:
 
     @classmethod
     def get_system_python(cls) -> Python:
+        """
+        Creates and returns an instance of the class representing the Poetry's Python executable.
+        """
         return cls(
             python=findpython.PythonVersion(
                 executable=Path(sys.executable),
@@ -128,6 +147,17 @@ def get_by_name(cls, python_name: str) -> Python | None:
 
     @classmethod
     def get_preferred_python(cls, config: Config, io: IO | None = None) -> Python:
+        """
+        Determine and return the "preferred" Python interpreter based on the provided
+        configuration and optional input/output stream.
+
+        This method first attempts to get the active Python interpreter if the configuration
+        does not mandate using Poetry's Python. If an active interpreter is found, it is returned.
+        Otherwise, the method defaults to retrieving the Poetry's Python interpreter (System Python).
+
+        This method **does not** attempt to sort versions or determine Python version constraint
+        compatibility.
+        """
         io = io or NullIO()
 
         if not config.get("virtualenvs.use-poetry-python") and (
@@ -142,6 +172,21 @@ def get_preferred_python(cls, config: Config, io: IO | None = None) -> Python:
 
     @classmethod
     def get_compatible_python(cls, poetry: Poetry, io: IO | None = None) -> Python:
+        """
+        Retrieve a compatible Python version based on the given poetry configuration
+        and Python constraints derived from the project.
+
+        This method iterates through all available Python candidates and checks if any
+        match the supported Python constraint as defined in the specified poetry package.
+
+        :param poetry: The poetry configuration containing package information,
+                       including Python constraints.
+        :param io: The input/output stream for error and status messages. Defaults
+                   to a null I/O if not provided.
+        :return: A Python instance representing a compatible Python version.
+        :raises NoCompatiblePythonVersionFoundError: If no Python version matches
+                the supported constraint.
+        """
         io = io or NullIO()
         supported_python = poetry.package.python_constraint
 
