Cli

Helper functions for implementing a command line interface.

Functions in this file named 'require_' check preconditions which, if violated, indicate user error (some variation on the theme of having mistyped a command). They either silently succeed, or print a human-readable error message and exit the program.

Functions in this file named 'fatal_' report various kinds of fatal errors. They always exit the program.

fatal_oserror

fatal_oserror(e: OSError, operation: str = '') -> NoReturn

Report an OSError which prevents the command from continuing any further. Does not return.

The message printed takes one of several traditional forms depending on the contents of 'e' and whether 'operation' is nonempty.

fatal_yaml_error

fatal_yaml_error(e: YAMLError, yaml_file: Path) -> NoReturn

Report a YAML parser error which prevents the command from continuing any further. Does not return.

parse_src_url_arg

parse_src_url_arg(arg: Path | str) -> tuple[Literal[None], Path] | tuple[Bucket, str]

If ARG is a path, or a string that looks like a local pathname, check that it's a directory that exists, then return (None, Path(arg)). Otherwise, if it's a string that looks like 's3://[/]', refers to a bucket that exists, then return (bucket, prefix) where bucket is a hostess.aws.s3.Bucket object referring to the bucket, and prefix is the specified prefix, if any.

More URL schemes may be added in the future, in which case the return value will turn into a more structured object. To leave space for this possibility, it is an error if 'arg' is a string that starts with any sequence of ASCII alphanumerics followed by '://'.

require_bucket

require_bucket(bucket: Bucket) -> None

Command line validation: require 'bucket' to be an existing S3 bucket.

require_directory

require_directory(dir: Path) -> None

Command line validation: require 'dir' to be an existing directory.

require_no_label_errors

require_no_label_errors(label: Label, label_file: Path) -> None

Require 'label' to have no errors. If it does have errors, report them and exit.