pudl.scripts.check_path_permissions#

Check read, write, and delete permissions for local or remote paths.

Attributes#

NOISY_BACKEND_LOGGERS

Exceptions#

PathPermissionError

Permission check failure annotated with the stage that failed.

Classes#

`PermissionCheck`	Named permission-check stages used by the CLI and its reports.
`CheckReport`	Structured result for a single permission check.
`PathReport`	Structured result for all permission checks against one path.
`PathCheckReport`	Top-level report for a CLI invocation across one or more paths.

Functions#

`_get_ferceqr_deployment_paths`(→ list[upath.UPath])	Return resolved FERC EQR deployment targets as fully configured UPath objects.
`_build_upath`(→ upath.UPath)	Return a `UPath` with anon and any per-target options baked in.
`_suppress_backend_tracebacks`(→ Any)	Temporarily silence noisy storage-backend exception logging.
`_ensure_directory_like_path`(→ None)	Raise if the provided path points at an existing file/object.
`check_read_access`(→ None)	Raise if the given path cannot be read as a directory-like location.
`check_write_access`(→ None)	Raise if a canary file cannot be written, read back, and deleted.
`_record_check_output`(→ None)	Record a result message in the summary and optionally print it.
`_record_check_outcome`(→ None)	Set the check outcome and record the message in one step.
`_run_check`(→ None)	Run a single permission check and update the structured summary.
`_check_single_path`(→ PathReport)	Run the requested checks for one path and return a structured summary.
`main`(→ int)	Check path permissions using UPath for local filesystems and cloud buckets.

Module Contents#

pudl.scripts.check_path_permissions.NOISY_BACKEND_LOGGERS = ('fsspec', 'gcsfs', 'gcsfs.retry', 's3fs')[source]#

class pudl.scripts.check_path_permissions.PermissionCheck[source]#

Bases: enum.StrEnum

Named permission-check stages used by the CLI and its reports.

READ = 'read'[source]#

WRITE = 'write'[source]#

DELETE = 'delete'[source]#

exception pudl.scripts.check_path_permissions.PathPermissionError(message: str)[source]#

Bases: click.ClickException

Permission check failure annotated with the stage that failed.

check: PermissionCheck[source]#

message: str[source]#

__post_init__() → None[source]#: Initialize the underlying Click exception message.

class pudl.scripts.check_path_permissions.CheckReport[source]#

Structured result for a single permission check.

requested: bool[source]#

success: bool | None = None[source]#

messages: list[str] = [][source]#

errors: list[str] = [][source]#

class pudl.scripts.check_path_permissions.PathReport[source]#

Structured result for all permission checks against one path.

path: str[source]#

resolved_path: str | None[source]#

anon: bool[source]#

checks: dict[PermissionCheck, CheckReport][source]#

success: bool = False[source]#

class pudl.scripts.check_path_permissions.PathCheckReport[source]#

Top-level report for a CLI invocation across one or more paths.

paths: list[str][source]#

anon: bool[source]#

results: list[PathReport][source]#

success: bool = False[source]#

pudl.scripts.check_path_permissions._get_ferceqr_deployment_paths(anon: bool = False) → list[upath.UPath][source]#

Return resolved FERC EQR deployment targets as fully configured UPath objects.

Each target is constructed with its YAML-defined storage_options, then the global --anon flag is applied on top (so it can override per-target settings if needed).

Parameters:: anon – Whether to force anonymous access for gs:// or s3:// targets.

pudl.scripts.check_path_permissions._build_upath(path: str, anon: bool, storage_options: dict[str, Any] | None = None) → upath.UPath[source]#: Return a UPath with anon and any per-target options baked in.

pudl.scripts.check_path_permissions._suppress_backend_tracebacks() → Any[source]#: Temporarily silence noisy storage-backend exception logging.

pudl.scripts.check_path_permissions._ensure_directory_like_path(path: upath.UPath) → None[source]#: Raise if the provided path points at an existing file/object.

pudl.scripts.check_path_permissions.check_read_access(path: upath.UPath) → None[source]#: Raise if the given path cannot be read as a directory-like location.

pudl.scripts.check_path_permissions.check_write_access(path: upath.UPath) → None[source]#: Raise if a canary file cannot be written, read back, and deleted.

pudl.scripts.check_path_permissions._record_check_output(*, check_name: PermissionCheck, message: str, json_output: bool, summary: PathReport, is_error: bool = False) → None[source]#: Record a result message in the summary and optionally print it.

pudl.scripts.check_path_permissions._record_check_outcome(*, check_name: PermissionCheck, success: bool, message: str, json_output: bool, summary: PathReport) → None[source]#: Set the check outcome and record the message in one step.

pudl.scripts.check_path_permissions._run_check(*, action: PermissionCheck, resolved_path: upath.UPath, json_output: bool, summary: PathReport) → None[source]#: Run a single permission check and update the structured summary.

pudl.scripts.check_path_permissions._check_single_path(*, path: upath.UPath, read_requested: bool, write_requested: bool, json_output: bool, anon: bool) → PathReport[source]#: Run the requested checks for one path and return a structured summary.

pudl.scripts.check_path_permissions.main(ctx: click.Context, paths: tuple[str, Ellipsis], read_requested: bool, write_requested: bool, json_output: bool, anon: bool, check_ferceqr_deployment_paths: bool) → int[source]#: Check path permissions using UPath for local filesystems and cloud buckets.