📝 Add docstrings to issue-1225

Docstrings generation was requested by @fizyk.

* #1241 (comment)

The following files were modified:

* `pytest_postgresql/config.py`
* `pytest_postgresql/factories/client.py`
* `pytest_postgresql/factories/noprocess.py`
* `pytest_postgresql/factories/process.py`
* `tests/test_executor.py`

Author: coderabbitai[bot]

pytest_postgresql/config.py

@@ -28,9 +28,28 @@ class PostgreSQLConfig:
 
 
 def get_config(request: FixtureRequest) -> PostgreSQLConfig:
-    """Return a dictionary with config options."""
+    """
+    Create a PostgreSQLConfig populated from pytest configuration options.
+    
+    Reads pytest options and INI values prefixed with "postgresql_" to populate a PostgreSQLConfig dataclass. The "load" option is normalized to Paths or strings and "port_search_count" is converted to an int.
+    
+    Parameters:
+        request (FixtureRequest): pytest fixture request used to read config options and INI values.
+    
+    Returns:
+        PostgreSQLConfig: Configuration populated from the pytest settings.
+    """
 
     def get_postgresql_option(option: str) -> Any:
+        """
+        Retrieve a PostgreSQL-related pytest configuration value.
+        
+        Parameters:
+            option (str): The suffix of the configuration name (without the "postgresql_" prefix).
+        
+        Returns:
+            The value of the pytest configuration option named "postgresql_<option>", or `None` if not set.
+        """
         name = "postgresql_" + option
         return request.config.getoption(name) or request.config.getini(name)
 
@@ -56,7 +75,15 @@ def get_postgresql_option(option: str) -> Any:
 
 
 def detect_paths(load_paths: list[LocalPath | str]) -> list[Path | str]:
-    """Convert path to sql files to Path instances."""
+    """
+    Normalize a sequence of load paths so SQL file paths are Path objects and other entries are preserved.
+    
+    Parameters:
+        load_paths (list[LocalPath | str]): Iterable of paths to normalize; entries may be pytest LocalPath objects or strings.
+    
+    Returns:
+        list[Path | str]: A new list where entries that refer to files ending with ".sql" are returned as pathlib.Path objects and all other entries are returned unchanged (strings).
+    """
     converted_load_paths: list[Path | str] = []
     for path in load_paths:
         if isinstance(path, LocalPath):
@@ -65,4 +92,4 @@ def detect_paths(load_paths: list[LocalPath | str]) -> list[Path | str]:
             converted_load_paths.append(Path(path))
         else:
             converted_load_paths.append(path)
-    return converted_load_paths
+    return converted_load_paths

pytest_postgresql/factories/client.py

@@ -35,21 +35,30 @@ def postgresql(
     dbname: str | None = None,
     isolation_level: "psycopg.IsolationLevel | None" = None,
 ) -> Callable[[FixtureRequest], Iterator[Connection]]:
-    """Return connection fixture factory for PostgreSQL.
-
-    :param process_fixture_name: name of the process fixture
-    :param dbname: database name
-    :param isolation_level: optional postgresql isolation level
-                            defaults to server's default
-    :returns: function which makes a connection to postgresql
+    """
+    Create a pytest fixture factory that yields a PostgreSQL connection.
+    
+    Parameters:
+        process_fixture_name (str): Name of the pytest fixture that provides the database process executor (used to obtain host, port, user, password, template DB name, and server version).
+        dbname (str | None): Database name to connect to; if None, use the executor's database name.
+        isolation_level (psycopg.IsolationLevel | None): Optional transaction isolation level to configure the janitor; if None, use the server default.
+    
+    Returns:
+        Callable[[FixtureRequest], Iterator[psycopg.Connection]]: A pytest fixture factory function which, when used in a test, yields an open psycopg Connection to the specified database and ensures database janitor lifecycle management around the connection.
     """
 
     @pytest.fixture
     def postgresql_factory(request: FixtureRequest) -> Iterator[Connection]:
-        """Fixture factory for PostgreSQL.
-
-        :param request: fixture request object
-        :returns: postgresql client
+        """
+        Provide a pytest fixture that yields a psycopg Connection to the test PostgreSQL database.
+        
+        The fixture resolves the process executor and global config from the given request, prepares or drops the test database as configured, and manages the database janitor and connection lifecycle so the connection is open for the duration of the consuming test.
+        
+        Parameters:
+            request (FixtureRequest): Pytest fixture request used to obtain the process fixture and test configuration.
+        
+        Returns:
+            Connection: A psycopg Connection connected to the selected test database; the connection is closed after the fixture completes.
         """
         proc_fixture: PostgreSQLExecutor | NoopExecutor = request.getfixturevalue(process_fixture_name)
         config = get_config(request)
@@ -84,4 +93,4 @@ def postgresql_factory(request: FixtureRequest) -> Iterator[Connection]:
             yield db_connection
             db_connection.close()
 
-    return postgresql_factory
+    return postgresql_factory

pytest_postgresql/factories/noprocess.py

@@ -46,24 +46,36 @@ def postgresql_noproc(
     options: str = "",
     load: list[Callable | str | Path] | None = None,
 ) -> Callable[[FixtureRequest], Iterator[NoopExecutor]]:
-    """Postgresql noprocess factory.
-
-    :param host: hostname
-    :param port: exact port (e.g. '8000', 8000)
-    :param user: postgresql username
-    :param password: postgresql password
-    :param dbname: postgresql database name
-    :param options: Postgresql connection options
-    :param load: List of functions used to initialize database's template.
-    :returns: function which makes a postgresql process
+    """
+    Create a pytest session-scoped fixture that provides a NoopExecutor connected to an existing PostgreSQL server.
+    
+    The returned fixture resolves connection parameters from the explicit arguments or from the test configuration, applies xdist worker-specific adjustment to the database name, and uses a DatabaseJanitor to optionally drop the test database and load initialization elements into the template before yielding the configured NoopExecutor.
+    
+    Parameters:
+        host (str | None): Hostname to connect to; if None, taken from test configuration.
+        port (str | int | None): Port to connect to; if None, taken from configuration or defaults to 5432.
+        user (str | None): Username to authenticate as; if None, taken from configuration.
+        password (str | None): Password to authenticate with; if None, taken from configuration.
+        dbname (str | None): Base database name; if None, taken from configuration. The name is adjusted when pytest-xdist is in use.
+        options (str): Additional connection options; if empty, taken from configuration.
+        load (list[Callable | str | Path] | None): Sequence of initialization elements (callables or filesystem paths) to load into the database template; if None, taken from configuration.
+    
+    Returns:
+        Callable[[FixtureRequest], Iterator[NoopExecutor]]: A pytest fixture function which yields a configured NoopExecutor instance.
     """
 
     @pytest.fixture(scope="session")
     def postgresql_noproc_fixture(request: FixtureRequest) -> Iterator[NoopExecutor]:
-        """Noop Process fixture for PostgreSQL.
-
-        :param request: fixture request object
-        :returns: tcp executor-like object
+        """
+        Provide a pytest fixture that yields a NoopExecutor configured for an existing PostgreSQL server.
+        
+        The fixture resolves connection parameters from the fixture request and the factory's closure values, applies xdist-aware database name transformation, and uses a DatabaseJanitor context to optionally drop the test database (if configured) and load initialization elements into the database template before yielding the executor.
+        
+        Parameters:
+            request (FixtureRequest): Pytest fixture request used to obtain configuration.
+        
+        Returns:
+            noop_exec (NoopExecutor): Executor-like object configured with the resolved host, port, user, password, dbname, and options.
         """
         config = get_config(request)
         pg_host = host or config.host
@@ -98,4 +110,4 @@ def postgresql_noproc_fixture(request: FixtureRequest) -> Iterator[NoopExecutor]
                 janitor.load(load_element)
             yield noop_exec
 
-    return postgresql_noproc_fixture
+    return postgresql_noproc_fixture

pytest_postgresql/factories/process.py

@@ -37,7 +37,23 @@
 
 
 def _pg_exe(executable: str | None, config: PostgreSQLConfig) -> str:
-    """If executable is set, use it. Otherwise best effort to find the executable."""
+    """
+    Resolve the filesystem path to the PostgreSQL control executable (pg_ctl).
+    
+    If `executable` is provided, it is returned as-is. Otherwise the function uses
+    `config.exec` if that path exists; if not, it attempts to locate `pg_ctl` using
+    `pg_config --bindir` and returns the `pg_ctl` path from that bindir.
+    
+    Parameters:
+        executable (str | None): Explicit path to a pg_ctl-like executable, or None to auto-resolve.
+        config (PostgreSQLConfig): Configuration providing a fallback executable path via `config.exec`.
+    
+    Returns:
+        str: Absolute path to the pg_ctl executable to use.
+    
+    Raises:
+        ExecutableMissingException: If neither an existing executable path nor `pg_config` can be found.
+    """
     postgresql_ctl = executable or config.exec
     # check if that executable exists, as it's no on systems' PATH
     # only replace it if executable isn't passed manually
@@ -51,7 +67,17 @@ def _pg_exe(executable: str | None, config: PostgreSQLConfig) -> str:
 
 
 def _pg_port(port: PortType | None, config: PostgreSQLConfig, excluded_ports: Iterable[int]) -> int:
-    """User specified port, otherwise find an unused port from config."""
+    """
+    Select the PostgreSQL port to use, preferring an explicit port and falling back to the configured port.
+    
+    Parameters:
+        port (PortType | None): Preferred port provided by the caller; may be None.
+        config (PostgreSQLConfig): Configuration containing the default port to use when `port` is not specified.
+        excluded_ports (Iterable[int]): Ports that must not be selected.
+    
+    Returns:
+        int: A port number that is not in `excluded_ports`.
+    """
     pg_port = get_port(port, excluded_ports) or get_port(config.port, excluded_ports)
     assert pg_port is not None
     return pg_port
@@ -82,37 +108,38 @@ def postgresql_proc(
     postgres_options: str | None = None,
     load: list[Callable | str | Path] | None = None,
 ) -> Callable[[FixtureRequest, TempPathFactory], Iterator[PostgreSQLExecutor]]:
-    """Postgresql process factory.
-
-    :param executable: path to postgresql_ctl
-    :param host: hostname
-    :param port:
-        exact port (e.g. '8000', 8000)
-        randomly selected port (None) - any random available port
-        -1 - command line or pytest.ini configured port
-        [(2000,3000)] or (2000,3000) - random available port from a given range
-        [{4002,4003}] or {4002,4003} - random of 4002 or 4003 ports
-        [(2000,3000), {4002,4003}] - random of given range and set
-    :param user: postgresql username
-    :param password: postgresql password
-    :param dbname: postgresql database name
-    :param options: Postgresql connection options
-    :param startparams: postgresql starting parameters
-    :param unixsocketdir: directory to create postgresql's unixsockets
-    :param postgres_options: Postgres executable options for use by pg_ctl
-    :param load: List of functions used to initialize database's template.
-    :returns: function which makes a postgresql process
+    """
+    Create a pytest fixture factory that starts a temporary PostgreSQL server process for tests.
+    
+    This factory returns a session-scoped fixture which allocates a port, initializes a data directory, starts PostgreSQL, runs initial load steps into the template database, and yields a PostgreSQLExecutor for test use. The fixture ensures the server is stopped and cleaned up when tests finish.
+    
+    Parameters:
+        executable (str | None): Path to the PostgreSQL control executable (pg_ctl). If None, the configured executable or pg_config discovery will be used.
+        port (PortType | None | int): Port selection specification. Accepts:
+            - an exact port (e.g. 8000 or "8000"),
+            - None to select any available port,
+            - -1 to use the command-line or pytest.ini configured port,
+            - a range tuple/list (e.g. (2000, 3000)) to pick a random available port from that range,
+            - a set/list of ports (e.g. {4002, 4003}) to pick a random port from the set,
+            - a list combining ranges and sets (e.g. [(2000,3000), {4002,4003}]).
+        postgres_options (str | None): Additional options for the PostgreSQL server process passed through pg_ctl.
+        load (list[Callable | str | Path] | None): Initialization steps applied to the template database before tests run; each element is either a callable or a path/SQL identifier that DatabaseJanitor.load understands.
+    
+    Returns:
+        Callable[[FixtureRequest, TempPathFactory], Iterator[PostgreSQLExecutor]]: A pytest fixture factory that yields a started PostgreSQLExecutor configured per the provided arguments and test configuration.
     """
 
     @pytest.fixture(scope="session")
     def postgresql_proc_fixture(
         request: FixtureRequest, tmp_path_factory: TempPathFactory
     ) -> Iterator[PostgreSQLExecutor]:
-        """Process fixture for PostgreSQL.
-
-        :param request: fixture request object
-        :param tmp_path_factory: temporary path object (fixture)
-        :returns: tcp executor
+        """
+        Create, start, and yield a PostgreSQL server process configured for the requesting test.
+        
+        This fixture selects an available port, prepares a data directory and logfile, starts a PostgreSQL server via PostgreSQLExecutor, applies any configured initialization/load steps, and yields the running executor to the test. The server is stopped and resources are cleaned up when the fixture context exits.
+        
+        Returns:
+            PostgreSQLExecutor: A configured and started executor connected to the test PostgreSQL instance.
         """
         config = get_config(request)
         pg_dbname = dbname or config.dbname
@@ -181,4 +208,4 @@ def postgresql_proc_fixture(
                     janitor.load(load_element)
                 yield postgresql_executor
 
-    return postgresql_proc_fixture
+    return postgresql_proc_fixture

tests/test_executor.py

@@ -49,7 +49,11 @@ def version(self) -> Any:
 
 
 def test_unsupported_version(request: FixtureRequest) -> None:
-    """Check that the error gets raised on unsupported postgres version."""
+    """
+    Verify that starting an executor with an unsupported PostgreSQL version raises PostgreSQLUnsupported.
+    
+    Creates a PatchedPostgreSQLExecutor configured to simulate an unsupported server version and asserts that invoking its start() method raises `PostgreSQLUnsupported`.
+    """
     config = get_config(request)
     port = get_port(config.port)
     assert port is not None
@@ -75,7 +79,14 @@ def test_executor_init_with_password(
     tmp_path_factory: pytest.TempPathFactory,
     locale: str,
 ) -> None:
-    """Test whether the executor initializes properly."""
+    """
+    Verify that a PostgreSQLExecutor initialized with a password and database name can start and stop successfully when running under the specified locale.
+    
+    The test sets LC_ALL to `locale`, prepares a temporary data directory and logfile, constructs a PostgreSQLExecutor using the test configuration and provided credentials, and asserts the executor can start and stop.
+    
+    Parameters:
+        locale (str): Locale string to set for the test environment (e.g., "en_US.UTF-8").
+    """
     config = get_config(request)
     monkeypatch.setenv("LC_ALL", locale)
     pg_exe = process._pg_exe(None, config)
@@ -100,7 +111,9 @@ def test_executor_init_bad_tmp_path(
     request: FixtureRequest,
     tmp_path_factory: pytest.TempPathFactory,
 ) -> None:
-    r"""Test init with \ and space chars in the path."""
+    """
+    Verifies executor initialization, startup, and shutdown succeed when the datadir path contains backslash and space characters.
+    """
     config = get_config(request)
     pg_exe = process._pg_exe(None, config)
     port = process._pg_port(-1, config, [])
@@ -171,4 +184,4 @@ def test_custom_isolation_level(postgres_isolation_level: Connection) -> None:
     """Check that a client fixture with a custom isolation level works."""
     cur = postgres_isolation_level.cursor()
     cur.execute("SELECT 1")
-    assert cur.fetchone() == (1,)
+    assert cur.fetchone() == (1,)