pglift-cli 1.4.0__tar.gz → 1.6.0__tar.gz

{pglift_cli-1.4.0 → pglift_cli-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pglift_cli
-Version: 1.4.0
+Version: 1.6.0
 Summary: Command-line interface for pglift
 Project-URL: Documentation, https://pglift.readthedocs.io/
 Project-URL: Source, https://gitlab.com/dalibo/pglift/
@@ -30,7 +30,15 @@ Requires-Dist: pydantic>=2.5.0
 Requires-Dist: pyyaml>=6.0.1
 Requires-Dist: rich>=11.0.0
 Provides-Extra: dev
-Requires-Dist: pglift-cli[test,typing]; extra == 'dev'
+Requires-Dist: anyio; extra == 'dev'
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: patroni[etcd]>=2.1.5; extra == 'dev'
+Requires-Dist: port-for; extra == 'dev'
+Requires-Dist: prysk[pytest-plugin]>=0.14.0; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: trustme; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.12.10; extra == 'dev'
 Provides-Extra: test
 Requires-Dist: anyio; extra == 'test'
 Requires-Dist: patroni[etcd]>=2.1.5; extra == 'test'
@@ -40,7 +48,7 @@ Requires-Dist: pytest; extra == 'test'
 Requires-Dist: pytest-cov; extra == 'test'
 Requires-Dist: trustme; extra == 'test'
 Provides-Extra: typing
-Requires-Dist: mypy>=1.8.0; extra == 'typing'
+Requires-Dist: mypy>=1.10.0; extra == 'typing'
 Requires-Dist: types-pyyaml>=6.0.12.10; extra == 'typing'
 Description-Content-Type: text/markdown
 

{pglift_cli-1.4.0 → pglift_cli-1.6.0}/pyproject.toml

@@ -57,7 +57,7 @@ test = [
     "trustme",
 ]
 typing = [
-    "mypy >= 1.8.0",
+    "mypy >= 1.10.0",
     "types-PyYAML >= 6.0.12.10",
 ]
 dev = [

pglift_cli-1.6.0/src/pglift_cli/__init__.py

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: 2024 Dalibo
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import logging
+import os
+
+import pluggy
+
+logger = logging.getLogger(__name__)
+try:
+    loggers = list(os.environ["PGLIFT_LOGGERS"].split(","))
+except KeyError:
+    loggers = [__name__, "pglift"]
+hookimpl = pluggy.HookimplMarker(__name__)

pglift_cli-1.6.0/src/pglift_cli/_settings.py

@@ -0,0 +1,75 @@
+# SPDX-FileCopyrightText: 2021 Dalibo
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import warnings
+from pathlib import Path
+from typing import Annotated, Any, Optional
+
+from pydantic import AfterValidator, Field, ValidationInfo
+
+from pglift.settings import Settings as BaseSettings
+from pglift.settings import SiteSettings as BaseSiteSettings
+from pglift.settings.base import BaseModel, LogPath, RunPath
+
+
+def deprecated(value: Any, info: ValidationInfo) -> Any:
+    if value is not None:
+        warnings.warn(
+            f"{info.field_name!r} setting is deprecated", FutureWarning, stacklevel=2
+        )
+    return value
+
+
+class AuditSettings(BaseModel):
+    """Settings for change operations auditing."""
+
+    path: Annotated[
+        Annotated[Path, LogPath],
+        Field(description="Log file path"),
+    ]
+    log_format: Annotated[
+        str,
+        Field(description="Format for log messages"),
+    ] = "%(levelname)-8s - %(asctime)s - %(name)s - %(message)s"
+    date_format: Annotated[
+        str,
+        Field(description="Date format in log messages"),
+    ] = "%Y-%m-%d %H:%M:%S"
+
+
+class CLISettings(BaseModel):
+    """Settings for pglift's command-line interface."""
+
+    logpath: Annotated[
+        Annotated[Optional[Path], LogPath],
+        Field(
+            description="Directory where temporary debug files from command executions will be stored (DEPRECATED).",
+        ),
+        AfterValidator(deprecated),
+    ] = None
+
+    log_format: Annotated[
+        str, Field(description="Format for log messages when written to a file")
+    ] = "%(asctime)s %(levelname)-8s %(name)s - %(message)s"
+
+    date_format: Annotated[
+        str, Field(description="Date format in log messages when written to a file")
+    ] = "%Y-%m-%d %H:%M:%S"
+
+    lock_file: Annotated[
+        Path, RunPath, Field(description="Path to lock file dedicated to pglift")
+    ] = Path(".pglift.lock")
+
+    audit: Annotated[
+        Optional[AuditSettings],
+        Field(description="Settings for change operations auditing"),
+    ] = None
+
+
+class Settings(BaseSettings):
+    cli: Annotated[CLISettings, Field(default_factory=CLISettings)]
+
+
+class SiteSettings(Settings, BaseSiteSettings):
+    pass

{pglift_cli-1.4.0 → pglift_cli-1.6.0}/src/pglift_cli/database.py

@@ -11,6 +11,7 @@ from typing import Any
 
 import click
 import psycopg
+from attrs import asdict
 from pydantic.v1.utils import deep_update
 
 from pglift import databases, postgresql, privileges, task
@@ -23,6 +24,7 @@ from .util import (
     Obj,
     OutputFormat,
     async_command,
+    audit,
     dry_run_option,
     instance_identifier_option,
     manifest_option,
@@ -68,7 +70,7 @@ async def create(
     obj: Obj, instance: system.Instance, database: interface.Database
 ) -> None:
     """Create a database in a PostgreSQL instance"""
-    with obj.lock:
+    with obj.lock, audit():
         async with postgresql.running(instance):
             if await databases.exists(instance, database.name):
                 raise click.ClickException("database already exists")
@@ -86,7 +88,7 @@ async def alter(
     obj: Obj, instance: system.Instance, dbname: str, **changes: Any
 ) -> None:
     """Alter a database in a PostgreSQL instance"""
-    with obj.lock:
+    with obj.lock, audit():
         async with postgresql.running(instance):
             values = (await databases.get(instance, dbname)).model_dump(by_alias=True)
             values = deep_update(values, changes)
@@ -113,7 +115,7 @@ async def apply(
     if dry_run:
         ret = interface.ApplyResult(change_state=None)
     else:
-        with obj.lock:
+        with obj.lock, audit():
             async with postgresql.running(instance):
                 ret = await databases.apply(instance, database)
     if output_format == OutputFormat.json:
@@ -171,7 +173,7 @@ async def drop(
     obj: Obj, instance: system.Instance, databasedropped: interface.DatabaseDropped
 ) -> None:
     """Drop a database"""
-    with obj.lock:
+    with obj.lock, audit():
         async with postgresql.running(instance):
             await databases.drop(instance, databasedropped)
 
@@ -251,7 +253,7 @@ async def run(
     "--output",
     metavar="DIRECTORY",
     type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
-    help="Write dump file(s) to DIRECTORY instead of configured 'dumps_directory'.",
+    help="Write dump file(s) to DIRECTORY instead of default dumps directory.",
 )
 @click.argument("dbname")
 @pass_instance
@@ -260,3 +262,46 @@ async def dump(instance: system.Instance, dbname: str, output: Path | None) -> N
     """Dump a database"""
     async with postgresql.running(instance):
         await databases.dump(instance, dbname, output)
+
+
+@cli.command("dumps")
+@click.argument("dbname", nargs=-1)
+@output_format_option
+@pass_instance
+@async_command
+async def dumps(
+    instance: system.Instance, dbname: Sequence[str], output_format: OutputFormat
+) -> None:
+    """List the database dumps
+
+    Only dumps created in the default dumps directory are listed.
+    """
+    values = [asdict(dump) async for dump in databases.dumps(instance, dbnames=dbname)]
+    if output_format == OutputFormat.json:
+        print_json_for(values)
+    else:
+        dbnames = ", ".join(dbname) if dbname else "all databases"
+        print_table_for(values, lambda d: d, title=f"Dumps for {dbnames}")
+
+
+@cli.command("restore")
+@click.argument("dump_id")
+@click.argument("targetdbname", required=False)
+@pass_instance
+@async_command
+async def restore(
+    instance: system.Instance, dump_id: str, targetdbname: str | None
+) -> None:
+    """Restore a database dump
+
+    DUMP_ID identifies the dump id.
+
+    TARGETDBNAME identifies the (optional) name of the database in which the
+    dump is reloaded. If provided, the database needs to be created beforehand.
+
+    If TARGETDBNAME is not provided, the dump is reloaded using the database
+    name that appears in the dump. In this case, the restore command will
+    create the database so it needs to be dropped before running the command.
+    """
+    async with postgresql.running(instance):
+        await databases.restore(instance, dump_id, targetdbname)

{pglift_cli-1.4.0 → pglift_cli-1.6.0}/src/pglift_cli/instance.py

@@ -22,8 +22,9 @@ from pglift import (
     task,
 )
 from pglift.models import interface, system
+from pglift.settings import default_postgresql_version
 from pglift.settings._postgresql import PostgreSQLVersion
-from pglift.types import Status, validation_context
+from pglift.types import Operation, Status, validation_context
 
 from . import _site
 from . import hookspecs as h
@@ -34,6 +35,7 @@ from .util import (
     OutputFormat,
     PluggableCommandGroup,
     async_command,
+    audit,
     dry_run_option,
     foreground_option,
     instance_identifier,
@@ -104,7 +106,7 @@ def cli() -> None:
 @async_command
 async def create(obj: Obj, instance: interface.Instance, drop_on_error: bool) -> None:
     """Initialize a PostgreSQL instance"""
-    with obj.lock:
+    with obj.lock, audit():
         if instances.exists(instance.name, instance.version, _site.SETTINGS):
             raise click.ClickException("instance already exists")
         async with task.async_transaction(drop_on_error):
@@ -118,12 +120,14 @@ async def create(obj: Obj, instance: interface.Instance, drop_on_error: bool) ->
 @async_command
 async def alter(obj: Obj, instance: system.Instance, **changes: Any) -> None:
     """Alter PostgreSQL INSTANCE"""
-    with obj.lock:
+    with obj.lock, audit():
         status = await postgresql.status(instance)
         manifest = await instances._get(instance, status)
         values = manifest.model_dump(by_alias=True, exclude={"settings"})
         values = deep_update(values, changes)
-        with validation_context({"operation": "update"}):
+        # No need for 'settings' in validation_context() as a 'version' key
+        # must be present in 'values' when altering.
+        with validation_context(operation="update"):
             altered = _site.INSTANCE_MODEL.model_validate(values)
         await instances.apply(
             _site.SETTINGS, altered, _is_running=status == Status.running
@@ -141,14 +145,19 @@ async def apply(
 ) -> None:
     """Apply manifest as a PostgreSQL instance"""
     name, version = data["name"], data.get("version")
-    assert isinstance(version, (str, type(None)))
-    op = "update" if instances.exists(name, version, _site.SETTINGS) else "create"
-    with validation_context({"operation": op}):
+    if version is None:
+        version = default_postgresql_version(_site.SETTINGS.postgresql)
+    elif not isinstance(version, str):
+        version = str(version)
+    op: Operation = (
+        "update" if instances.exists(name, version, _site.SETTINGS) else "create"
+    )
+    with validation_context(operation=op, settings=_site.SETTINGS):
         instance = _site.INSTANCE_MODEL.model_validate(data)
     if dry_run:
         ret = interface.InstanceApplyResult(change_state=None)
     else:
-        with obj.lock:
+        with obj.lock, audit():
             ret = await instances.apply(_site.SETTINGS, instance)
     if output_format == OutputFormat.json:
         print_json_for(ret)
@@ -160,7 +169,7 @@ async def apply(
 @async_command
 async def promote(obj: Obj, instance: system.Instance) -> None:
     """Promote standby PostgreSQL INSTANCE"""
-    with obj.lock:
+    with obj.lock, audit():
         await instances.promote(instance)
 
 
@@ -213,7 +222,7 @@ async def ls(version: PostgreSQLVersion | None, output_format: OutputFormat) ->
 @async_command
 async def drop(obj: Obj, instance: tuple[system.Instance, ...]) -> None:
     """Drop PostgreSQL INSTANCE"""
-    with obj.lock:
+    with obj.lock, audit():
         for i in instance:
             await instances.drop(i)
 
@@ -261,7 +270,7 @@ async def start(
         raise click.UsageError(
             "only one INSTANCE argument may be given with --foreground"
         )
-    with obj.lock:
+    with obj.lock, audit():
         for i in instance:
             await instances.start(i, foreground=foreground)
 
@@ -275,7 +284,7 @@ async def stop(
     obj: Obj, instance: tuple[system.Instance, ...], all_instances: bool
 ) -> None:
     """Stop PostgreSQL INSTANCE"""
-    with obj.lock:
+    with obj.lock, audit():
         for i in instance:
             await instances.stop(i)
 
@@ -289,7 +298,7 @@ async def reload(
     obj: Obj, instance: tuple[system.Instance, ...], all_instances: bool
 ) -> None:
     """Reload PostgreSQL INSTANCE"""
-    with obj.lock:
+    with obj.lock, audit():
         for i in instance:
             await instances.reload(i)
 
@@ -303,7 +312,7 @@ async def restart(
     obj: Obj, instance: tuple[system.Instance, ...], all_instances: bool
 ) -> None:
     """Restart PostgreSQL INSTANCE"""
-    with obj.lock:
+    with obj.lock, audit():
         for i in instance:
             await instances.restart(i)
 
@@ -459,7 +468,7 @@ async def upgrade(
     jobs: int | None,
 ) -> None:
     """Upgrade INSTANCE using pg_upgrade"""
-    with obj.lock:
+    with obj.lock, audit():
         await postgresql.check_status(instance, Status.not_running)
         async with task.async_transaction():
             new_instance = await instances.upgrade(

{pglift_cli-1.4.0 → pglift_cli-1.6.0}/src/pglift_cli/main.py

@@ -26,16 +26,16 @@ from pglift import install, ui
 from pglift._compat import assert_never
 
 from . import __name__ as pkgname
-from . import _site
+from . import _site, loggers
 from ._settings import Settings
 from .base import CLIGroup
 from .console import console as console
 from .util import (
     InteractiveUserInterface,
-    LogDisplayer,
     Obj,
     OutputFormat,
     async_command,
+    audit,
     output_format_option,
 )
 
@@ -145,10 +145,7 @@ def cli(
             stacklevel=1,
         )
     if not context.obj:
-        context.obj = Obj(
-            displayer=None if log_file else LogDisplayer(),
-            debug=debug,
-        )
+        context.obj = Obj(debug=debug)
     else:
         assert isinstance(context.obj, Obj), context.obj
 
@@ -156,12 +153,9 @@ def cli(
     if interactive:
         ui_token = ui.set(InteractiveUserInterface())
 
-    loggers = [logging.getLogger(n) for n in ("pglift", "dotenv", "filelock")]
-    for logger in loggers:
-        logger.setLevel(logging.DEBUG)
+    handler: logging.Handler | rich.logging.RichHandler
     if debug:
         log_level = logging.DEBUG
-    handler: logging.Handler | rich.logging.RichHandler
     if log_file or not sys.stderr.isatty():
         if log_file:
             handler = logging.FileHandler(log_file)
@@ -182,11 +176,15 @@ def cli(
             show_path=False,
             highlighter=NullHighlighter(),
         )
-    for logger in loggers:
+
+    for name in loggers:
+        logger = logging.getLogger(name)
+        logger.setLevel(logging.DEBUG)
         logger.addHandler(handler)
-    # Remove rich handler on close since this would pollute all tests stderr
-    # otherwise.
-    context.call_on_close(partial(logger.removeHandler, handler))
+        # Remove rich handler on close since this would pollute all tests
+        # stderr otherwise.
+        context.call_on_close(partial(logger.removeHandler, handler))
+
     # Reset contextvars
     if ui_token is not None:
         context.call_on_close(partial(ui.reset, ui_token))
@@ -264,7 +262,7 @@ async def site_configure(
 
     This is an INTERNAL command.
     """
-    with obj.lock:
+    with obj.lock, audit():
         if action == "install":
             env = {"SETTINGS": f"@{settings_file}"} if settings_file else {}
             await install.do(_site.SETTINGS, env=env)

{pglift_cli-1.4.0 → pglift_cli-1.6.0}/src/pglift_cli/model.py

@@ -7,7 +7,6 @@ from __future__ import annotations
 import enum
 import functools
 import inspect
-import logging
 import typing
 from abc import ABC, abstractmethod
 from collections.abc import Callable, Iterator, Sequence
@@ -30,7 +29,7 @@ from pglift.types import (
     validation_context,
 )
 
-logger = logging.getLogger(__name__)
+from . import _site, logger
 
 ModelType = type[pydantic.BaseModel]
 T = TypeVar("T", bound=pydantic.BaseModel)
@@ -101,7 +100,7 @@ def as_parameters(
                 args = params_to_modelargs(kwargs)
                 with (
                     catch_validationerror(*paramspecs),
-                    validation_context({"operation": operation}),
+                    validation_context(operation=operation, settings=_site.SETTINGS),
                 ):
                     model = parse_params_as(model_type, args)
                 kwargs[model_argname] = model
@@ -110,7 +109,7 @@ def as_parameters(
         else:
 
             @functools.wraps(f)
-            def callback(**kwargs: Any) -> Any:
+            def callback(**kwargs: Any) -> Any:  # type: ignore[misc]
                 args = params_to_modelargs(kwargs)
                 values = unnest(model_type, args)
                 kwargs.update(values)
@@ -164,6 +163,7 @@ class ParamSpec(ABC):
     """Intermediate representation for a future click.Parameter."""
 
     param_decls: Sequence[str]
+    field_info: FieldInfo
     attrs: dict[str, Any]
     loc: tuple[str, ...]
 
@@ -208,7 +208,15 @@ class OptionSpec(ParamSpec):
 
     @property
     def decorator(self) -> ClickDecorator:
-        return click.option(*self.param_decls, **self.attrs)
+        return click.option(*self.param_decls, help=self._help(), **self.attrs)
+
+    def _help(self) -> str | None:
+        if description := self.field_info.description:
+            description = description[0].upper() + description[1:]
+            if description[-1] not in ".?":
+                description += "."
+            return description
+        return None
 
 
 @dataclass(frozen=True)
@@ -255,10 +263,31 @@ def _paramspecs_from_model(
             assert ftype is not None
         nested = lenient_issubclass(origin_type or ftype, pydantic.BaseModel)
         required = field.is_required()
-        if not nested and not _parents and required:
-            yield (modelname, argname), ArgumentSpec(
-                (argname.replace("_", "-"),), {"type": ftype}, loc=(modelname,)
+        attrs: dict[str, Any]
+
+        if nested:
+            yield from _paramspecs_from_model(
+                ftype, operation, _parents=_parents + (_Parent(argname, required),)
             )
+
+        elif not _parents and required:
+            attrs = {}
+            if origin_type is typing.Literal:
+                choices = list(typing.get_args(ftype))
+                if config is not None and config.choices is not None:
+                    choices = config.choices
+                attrs["type"] = click.Choice(choices)
+            if config is not None and config.as_option:
+                attrs["required"] = True
+                yield (modelname, argname), OptionSpec(
+                    (f"--{argname.replace('_', '-')}",), field, attrs, loc=(modelname,)
+                )
+
+            else:
+                yield (modelname, argname), ArgumentSpec(
+                    (argname.replace("_", "-"),), field, attrs, loc=(modelname,)
+                )
+
         else:
             metavar: str | None
             if config and config.metavar is not None:
@@ -268,12 +297,15 @@ def _paramspecs_from_model(
             if metavar is not None:
                 metavar = metavar.upper()
             argparts = tuple(p.argname for p in _parents) + tuple(argname.split("_"))
+            argname = "_".join(argparts)
+            loc = tuple(p.argname for p in _parents) + (modelname,)
+            modelname = "_".join(loc)
             fname = f"--{'-'.join(argparts)}"
-            description = None
-            if field.description:
-                description = field.description
-                description = description[0].upper() + description[1:]
-            attrs: dict[str, Any] = {}
+
+            attrs = {}
+            if required and all(p.required for p in _parents):
+                attrs["required"] = True
+
             if origin_type is typing.Literal:
                 choices = list(typing.get_args(ftype))
                 if len(choices) == 1:  # const
@@ -282,17 +314,14 @@ def _paramspecs_from_model(
                     choices = config.choices
                 attrs["type"] = click.Choice(choices)
                 metavar = None
+
             elif lenient_issubclass(ftype, enum.Enum):
                 if config and config.choices is not None:
                     choices = config.choices
                 else:
                     choices = choices_from_enum(ftype)
                 attrs["type"] = click.Choice(choices)
-            elif nested:
-                yield from _paramspecs_from_model(
-                    ftype, operation, _parents=_parents + (_Parent(argname, required),)
-                )
-                continue
+
             elif lenient_issubclass(origin_type or ftype, list):
                 if operation != "create":
                     continue
@@ -306,30 +335,27 @@ def _paramspecs_from_model(
                         attrs["type"] = click.Choice(choices_from_enum(itemtype))
                     else:
                         attrs["metavar"] = metavar
+
             elif lenient_issubclass(ftype, pydantic.SecretStr):
                 attrs["prompt"] = (
-                    description.rstrip(".") if description is not None else True
+                    field.description.rstrip(".")
+                    if field.description is not None
+                    else True
                 )
                 attrs["prompt_required"] = False
                 attrs["confirmation_prompt"] = True
                 attrs["hide_input"] = True
+
             elif lenient_issubclass(ftype, bool):
                 fname = f"{fname}/--no-{fname[2:]}"
                 # Use None to distinguish unspecified option from the default value.
                 attrs["default"] = None
+
             else:
                 attrs["metavar"] = metavar
-            if description is not None:
-                if description[-1] not in ".?":
-                    description += "."
-                attrs["help"] = description
-            if field.is_required() and all(p.required for p in _parents):
-                attrs["required"] = True
-            argname = "_".join(argparts)
-            loc = tuple(p.argname for p in _parents) + (modelname,)
-            modelname = "_".join(loc)
+
             yield (modelname, argname), OptionSpec(
-                (fname,), {"callback": default, **attrs}, loc=loc
+                (fname,), field, {"callback": default, **attrs}, loc=loc
             )
 
 

{pglift_cli-1.4.0 → pglift_cli-1.6.0}/src/pglift_cli/pgbackrest/__init__.py

@@ -22,6 +22,7 @@ from ..util import (
     Obj,
     OutputFormat,
     async_command,
+    audit,
     instance_identifier,
     instance_identifier_option,
     model_dump,
@@ -69,7 +70,7 @@ async def instance_restore(
             "--label and --date arguments are mutually exclusive"
         ) from None
     settings = pgbackrest.get_settings(_site.SETTINGS)
-    with obj.lock:
+    with obj.lock, audit():
         await base.restore(instance, settings, label=label, date=date)
 
 

{pglift_cli-1.4.0 → pglift_cli-1.6.0}/src/pglift_cli/pgbackrest/repo_path.py

@@ -12,7 +12,7 @@ from pglift.pgbackrest import repo_path
 from pglift.pgbackrest.repo_path import register_if as register_if  # noqa: F401
 
 from .. import _site, hookimpl
-from ..util import Command, Obj, async_command, instance_identifier
+from ..util import Command, Obj, async_command, audit, instance_identifier
 
 
 @click.command("backup", cls=Command)
@@ -31,7 +31,7 @@ async def instance_backup(
 ) -> None:
     """Back up PostgreSQL INSTANCE"""
     settings = pgbackrest.get_settings(_site.SETTINGS)
-    with obj.lock:
+    with obj.lock, audit():
         await repo_path.backup(instance, settings, type=backup_type)
 
 

{pglift_cli-1.4.0 → pglift_cli-1.6.0}/src/pglift_cli/pgconf.py

@@ -14,7 +14,14 @@ from pglift import h, hook, instances, postgresql
 from pglift.models import system
 from pglift.types import ConfigChanges, Status
 
-from .util import Group, Obj, async_command, instance_identifier_option, pass_instance
+from .util import (
+    Group,
+    Obj,
+    async_command,
+    audit,
+    instance_identifier_option,
+    pass_instance,
+)
 
 
 @click.group(cls=Group)
@@ -92,7 +99,7 @@ def validate_configuration_parameters(
 @async_command
 async def set_(obj: Obj, instance: system.Instance, parameters: dict[str, Any]) -> None:
     """Set configuration items."""
-    with obj.lock:
+    with obj.lock, audit():
         status = await postgresql.status(instance)
         manifest = await instances._get(instance, status)
         manifest.settings.update(parameters)
@@ -109,7 +116,7 @@ async def set_(obj: Obj, instance: system.Instance, parameters: dict[str, Any])
 @async_command
 async def remove(obj: Obj, instance: system.Instance, parameters: tuple[str]) -> None:
     """Remove configuration items."""
-    with obj.lock:
+    with obj.lock, audit():
         status = await postgresql.status(instance)
         manifest = await instances._get(instance, status)
         for p in parameters:
@@ -131,7 +138,7 @@ async def remove(obj: Obj, instance: system.Instance, parameters: tuple[str]) ->
 @async_command
 async def edit(obj: Obj, instance: system.Instance) -> None:
     """Edit managed configuration."""
-    with obj.lock:
+    with obj.lock, audit():
         actual_config = hook(
             instance._settings, h.postgresql_editable_conf, instance=instance
         )

{pglift_cli-1.4.0 → pglift_cli-1.6.0}/src/pglift_cli/prometheus.py

@@ -21,6 +21,7 @@ from .util import (
     Obj,
     OutputFormat,
     async_command,
+    audit,
     dry_run_option,
     foreground_option,
     manifest_option,
@@ -65,13 +66,13 @@ async def apply(
     """Apply manifest as a Prometheus postgres_exporter."""
     settings = prometheus.get_settings(_site.SETTINGS)
     name = data["name"]
-    op = "update" if impl.exists(name, settings) else "create"
-    with types.validation_context({"operation": op}):
+    op: types.Operation = "update" if impl.exists(name, settings) else "create"
+    with types.validation_context(operation=op):
         exporter = PostgresExporter.model_validate(data)
     if dry_run:
         ret = interface.ApplyResult(change_state=None)
     else:
-        with obj.lock:
+        with obj.lock, audit():
             ret = await impl.apply(exporter, _site.SETTINGS, settings)
     if output_format == OutputFormat.json:
         print_json_for(ret)
@@ -84,7 +85,7 @@ async def apply(
 async def install(obj: Obj, postgresexporter: PostgresExporter) -> None:
     """Install the service for a (non-local) instance."""
     settings = prometheus.get_settings(_site.SETTINGS)
-    with obj.lock:
+    with obj.lock, audit():
         async with task.async_transaction():
             await impl.apply(postgresexporter, _site.SETTINGS, settings)
 
@@ -95,7 +96,7 @@ async def install(obj: Obj, postgresexporter: PostgresExporter) -> None:
 @async_command
 async def uninstall(obj: Obj, name: str) -> None:
     """Uninstall the service."""
-    with obj.lock:
+    with obj.lock, audit():
         await impl.drop(_site.SETTINGS, name)
 
 
@@ -112,7 +113,7 @@ async def start(obj: Obj, name: str, foreground: bool) -> None:
     <version>-<name>.
     """
     settings = prometheus.get_settings(_site.SETTINGS)
-    with obj.lock:
+    with obj.lock, audit():
         service = impl.system_lookup(name, settings)
         if service is None:
             raise exceptions.InstanceNotFound(name)
@@ -131,7 +132,7 @@ async def stop(obj: Obj, name: str) -> None:
     <version>-<name>.
     """
     settings = prometheus.get_settings(_site.SETTINGS)
-    with obj.lock:
+    with obj.lock, audit():
         service = impl.system_lookup(name, settings)
         if service is None:
             raise exceptions.InstanceNotFound(name)

{pglift_cli-1.4.0 → pglift_cli-1.6.0}/src/pglift_cli/role.py

@@ -21,6 +21,7 @@ from .util import (
     Obj,
     OutputFormat,
     async_command,
+    audit,
     dry_run_option,
     instance_identifier_option,
     manifest_option,
@@ -76,7 +77,7 @@ def cli(**kwargs: Any) -> None:
 @async_command
 async def create(obj: Obj, instance: system.Instance, role: interface.Role) -> None:
     """Create a role in a PostgreSQL instance"""
-    with obj.lock:
+    with obj.lock, audit():
         async with postgresql.running(instance):
             if await roles.exists(instance, role.name):
                 raise click.ClickException("role already exists")
@@ -93,7 +94,7 @@ async def alter(
     obj: Obj, instance: system.Instance, rolname: str, **changes: Any
 ) -> None:
     """Alter a role in a PostgreSQL instance"""
-    with obj.lock:
+    with obj.lock, audit():
         async with postgresql.running(instance):
             values = (await roles.get(instance, rolname)).model_dump(by_alias=True)
             values = deep_update(values, changes)
@@ -120,7 +121,7 @@ async def apply(
     if dry_run:
         ret = interface.ApplyResult(change_state=None)
     else:
-        with obj.lock:
+        with obj.lock, audit():
             async with postgresql.running(instance):
                 ret = await roles.apply(instance, role)
     if output_format == OutputFormat.json:

{pglift_cli-1.4.0 → pglift_cli-1.6.0}/src/pglift_cli/util.py

@@ -9,18 +9,23 @@ import asyncio
 import enum
 import json
 import logging
+import logging.handlers
 import os
 import pathlib
+import shlex
+import sys
 import tempfile
 import time
 import typing
 from collections.abc import Coroutine, Iterable, Iterator, Sequence
 from contextlib import contextmanager
+from datetime import timedelta
 from functools import cache, cached_property, singledispatch, wraps
 from typing import IO, Any, Callable, TypedDict, TypeVar
 
 import click
 import filelock
+import humanize
 import psycopg
 import pydantic
 import pydantic_core
@@ -31,19 +36,18 @@ from click.shell_completion import CompletionItem
 from rich.console import Console
 from rich.table import Table
 
-from pglift import exceptions, install, instances, task
+from pglift import exceptions, install, instances
 from pglift._compat import ParamSpec
 from pglift.models import helpers, system
 from pglift.settings import Settings
 from pglift.settings._postgresql import PostgreSQLVersion
-from pglift.task import Displayer
 from pglift.types import AutoStrEnum, ByteSizeType
 
-from . import _site, model
+from . import __name__ as pkgname
+from . import _site, logger, loggers, model
+from ._settings import CLISettings
 from .console import console
 
-logger = logging.getLogger("pglift")
-
 
 def model_dump(
     m: pydantic.BaseModel, by_alias: bool = True, **kwargs: Any
@@ -429,18 +433,92 @@ foreground_option = click.option(
 
 
 @contextmanager
-def command_logging(logdir: pathlib.Path) -> Iterator[None]:
+def audit(
+    command: Sequence[str] = sys.argv, settings: CLISettings | None = None
+) -> Iterator[None]:
+    """Context manager handling log messages to the audit file, if configured
+    in site settings.
+    """
+    if settings is None:
+        settings = _site.SETTINGS.cli
+    if (audit_settings := settings.audit) is None:
+        yield None
+        return
+
+    audit_file = audit_settings.path
+    if not audit_file.parent.exists():
+        logger.debug("creating audit file parent directory")
+        audit_file.parent.mkdir(parents=True, exist_ok=True)
+    logger.debug("using audit file %s", audit_file)
+
+    handler = logging.handlers.WatchedFileHandler(audit_file)
+    handler.setLevel(logging.DEBUG)
+    formatter = logging.Formatter(
+        fmt=audit_settings.log_format, datefmt=audit_settings.date_format
+    )
+    handler.setFormatter(formatter)
+
+    loggrs = [logging.getLogger(n) for n in loggers]
+    for loggr in loggrs:
+        loggr.addHandler(handler)
+
+    # The audit logger, as defined here, is only meant to emit start/end
+    # messages below; and we avoid them to get propagated to higher logger.
+    audit_logger = logging.getLogger(pkgname).getChild("audit")
+    audit_logger.propagate = False
+    audit_logger.addHandler(handler)
+    audit_logger.setLevel(logging.DEBUG)
+
+    audit_logger.info("command: %s", shlex.join(command))
+    started_at = time.monotonic()
+
+    try:
+        yield None
+    except Exception as exc:
+        if isinstance(exc, exceptions.Cancelled):
+            msg, level = "command cancelled (%s)", logging.WARNING
+        else:
+            msg, level = "command failed (%s)", logging.ERROR
+        raise
+    else:
+        msg, level = "command completed (%s)", logging.INFO
+    finally:
+        # Note: by removing the audit handler from loggers managed above, we
+        # avoid termination messages (typically those emitted in
+        # Command.invoke()) to be emitted in this handler.
+        # If this appears to be a bad idea, removeHandler() should be invoked
+        # through context.call_on_close().
+        for loggr in loggrs:
+            loggr.removeHandler(handler)
+        elapsed = humanize.precisedelta(
+            timedelta(seconds=time.monotonic() - started_at)
+        )
+        audit_logger.log(level, msg, elapsed)
+        audit_logger.removeHandler(handler)
+        handler.close()
+
+
+@contextmanager
+def command_logging(logdir: pathlib.Path | None) -> Iterator[None]:
     logdir_created = False
     logfilename = f"{time.time()}.log"
-    logfile = logdir / logfilename
-    try:
-        if not logdir.exists():
-            logdir.mkdir(parents=True)
-            logdir_created = True
-    except OSError:
-        # Might be, e.g. PermissionError, if log file path is not writable.
+    if logdir is not None:  # pragma: nocover (DEPRECATED)
+        logdir_created = False
+        logfile = logdir / logfilename
+        try:
+            if not logdir.exists():
+                logdir.mkdir(parents=True)
+                logdir_created = True
+        except OSError:
+            # Might be, e.g. PermissionError, if log file path is not writable.
+            logfile = pathlib.Path(
+                tempfile.NamedTemporaryFile(
+                    prefix="pglift-", suffix="-" + logfilename
+                ).name
+            )
+    else:
         logfile = pathlib.Path(
-            tempfile.NamedTemporaryFile(prefix="pglift", suffix=logfilename).name
+            tempfile.NamedTemporaryFile(prefix="pglift-", suffix="-" + logfilename).name
         )
     handler = logging.FileHandler(logfile)
     formatter = logging.Formatter(
@@ -449,9 +527,9 @@ def command_logging(logdir: pathlib.Path) -> Iterator[None]:
     )
     handler.setFormatter(formatter)
     logger.addHandler(handler)
-    if logdir_created:
+    if logdir is not None and logdir_created:  # pragma: nocover (DEPRECATED)
         logger.debug("created log directory %s", logdir)
-    logger.debug("logging command at %s", logfile)
+    logger.debug("debug logging at %s", logfile)
     keep_logfile = False
     try:
         yield None
@@ -467,16 +545,15 @@ def command_logging(logdir: pathlib.Path) -> Iterator[None]:
     finally:
         if not keep_logfile:
             os.unlink(logfile)
-            if logdir_created and next(logdir.iterdir(), None) is None:
+            if (
+                logdir is not None
+                and logdir_created
+                and next(logdir.iterdir(), None) is None
+            ):  # pragma: nocover (DEPRECATED)
                 logger.debug("removing log directory %s", logdir)
                 logdir.rmdir()
 
 
-class LogDisplayer:
-    def handle(self, msg: str) -> None:
-        logger.info(msg)
-
-
 class InteractiveUserInterface:
     """An interactive UI that prompts for confirmation."""
 
@@ -499,13 +576,7 @@ class Obj:
     # instance_identifier_option decorator's callback.
     _instance: str | system.Instance
 
-    def __init__(
-        self,
-        *,
-        displayer: Displayer | None = None,
-        debug: bool = False,
-    ) -> None:
-        self.displayer = displayer
+    def __init__(self, *, debug: bool = False) -> None:
         self.debug = debug
 
     @cached_property
@@ -537,17 +608,16 @@ def async_command(
 class Command(click.Command):
     def invoke(self, context: click.Context) -> Any:
         obj: Obj = context.obj
-        displayer = obj.displayer
         with command_logging(_site.SETTINGS.cli.logpath):
             try:
-                with task.displayer_installed(displayer):
-                    return super().invoke(context)
+                return super().invoke(context)
             except filelock.Timeout:
                 raise click.ClickException("another operation is in progress") from None
             except exceptions.Cancelled as e:
                 logger.warning(str(e))
                 raise click.Abort from None
             except pydantic.ValidationError as e:
+                logger.debug("a validation error occurred", exc_info=obj.debug)
                 raise click.ClickException(str(e)) from None
             except exceptions.Error as e:
                 logger.debug("an internal error occurred", exc_info=obj.debug)

pglift_cli-1.4.0/src/pglift_cli/__init__.py

@@ -1,7 +0,0 @@
-# SPDX-FileCopyrightText: 2024 Dalibo
-#
-# SPDX-License-Identifier: GPL-3.0-or-later
-
-import pluggy
-
-hookimpl = pluggy.HookimplMarker(__name__)

pglift_cli-1.4.0/src/pglift_cli/_settings.py

@@ -1,44 +0,0 @@
-# SPDX-FileCopyrightText: 2021 Dalibo
-#
-# SPDX-License-Identifier: GPL-3.0-or-later
-
-from pathlib import Path
-from typing import Annotated
-
-from pydantic import Field
-
-from pglift.settings import Settings as BaseSettings
-from pglift.settings import SiteSettings as BaseSiteSettings
-from pglift.settings.base import BaseModel, LogPath, RunPath
-
-
-class CLISettings(BaseModel):
-    """Settings for pglift's command-line interface."""
-
-    logpath: Annotated[
-        Annotated[Path, LogPath],
-        Field(
-            description="Directory where temporary log files from command executions will be stored",
-            title="CLI log directory",
-        ),
-    ] = Path()
-
-    log_format: Annotated[
-        str, Field(description="Format for log messages when written to a file")
-    ] = "%(asctime)s %(levelname)-8s %(name)s - %(message)s"
-
-    date_format: Annotated[
-        str, Field(description="Date format in log messages when written to a file")
-    ] = "%Y-%m-%d %H:%M:%S"
-
-    lock_file: Annotated[
-        Path, RunPath, Field(description="Path to lock file dedicated to pglift")
-    ] = Path(".pglift.lock")
-
-
-class Settings(BaseSettings):
-    cli: Annotated[CLISettings, Field(default_factory=CLISettings)]
-
-
-class SiteSettings(Settings, BaseSiteSettings):
-    pass