MWPath

class lsst.daf.butler.cli.utils.MWPath(exists: bool | None = None, file_okay: bool = True, dir_okay: bool = True, writable: bool = False, readable: bool = True, resolve_path: bool = False, allow_dash: bool = False, path_type: type | None = None)

Bases: Path

Overrides click.Path to implement file-does-not-exist checking.

Changes the definition of exists so that True indicates the location (file or directory) must exist, False indicates the location must not exist, and None indicates that the file may exist or not. The standard definition for the click.Path exists parameter is that for True a location must exist, but False means it is not required to exist (not that it is required to not exist).

Parameters:
existsbool or None, optional

If True, the location (file or directory) indicated by the caller must exist. If False the location must not exist. If None, the location may exist or not.

file_okaybool, optional

Allow a file as a value.

dir_okaybool, optional

Allow a directory as a value.

writablebool, optional

If True, a writable check is performed.

readable`bool, optional

If True, a readable check is performed.

resolve_pathbool, optional

Resolve the path.

allow_dashbool, optional

Allow single dash as value to mean a standard stream.

path_typetype or None, optional

Convert the incoming value to this type.

Notes

All parameters other than exists come directly from click.Path.

Attributes Summary

arity

envvar_list_splitter

if a list of this type is expected and the value is pulled from a string environment variable, this is what splits it up.

is_composite

Methods Summary

__call__(value[, param, ctx])

Call self as a function.

coerce_path_result(value)

convert(value, param, ctx)

Convert values through types.

fail(message[, param, ctx])

Helper method to fail with an invalid value message.

get_metavar(param)

Returns the metavar default for this param if it provides one.

get_missing_message(param)

Optionally might return extra information about a missing parameter.

shell_complete(ctx, param, incomplete)

Return a special completion marker that tells the completion system to use the shell to provide path completions for only directories or any paths.

split_envvar_value(rv)

Given a value from an environment variable this splits it up into small chunks depending on the defined envvar list splitter.

to_info_dict()

Gather information that could be useful for a tool generating user-facing documentation.

Attributes Documentation

arity: t.ClassVar[int] = 1
envvar_list_splitter: t.ClassVar[str] = ':'

if a list of this type is expected and the value is pulled from a string environment variable, this is what splits it up. None means any whitespace. For all parameters the general rule is that whitespace splits them up. The exception are paths and files which are split by os.path.pathsep by default (“:” on Unix and “;” on Windows).

is_composite: t.ClassVar[bool] = False

Methods Documentation

__call__(value: Any, param: Parameter | None = None, ctx: Context | None = None) Any

Call self as a function.

coerce_path_result(value: str | PathLike[str]) str | bytes | PathLike[str]
convert(value: str | PathLike[str], param: Parameter | None, ctx: Context | None) Any

Convert values through types.

Called by click.ParamType to “convert values through types”. click.Path uses this step to verify Path conditions.

Parameters:
valuestr or os.PathLike

File path.

paramclick.Parameter

Parameters provided by Click.

ctxclick.Context

Context provided by Click.

fail(message: str, param: Parameter | None = None, ctx: Context | None = None) t.NoReturn

Helper method to fail with an invalid value message.

get_metavar(param: Parameter) str | None

Returns the metavar default for this param if it provides one.

get_missing_message(param: Parameter) str | None

Optionally might return extra information about a missing parameter.

New in version 2.0.

shell_complete(ctx: Context, param: Parameter, incomplete: str) List[CompletionItem]

Return a special completion marker that tells the completion system to use the shell to provide path completions for only directories or any paths.

Parameters:
  • ctx – Invocation context for this command.

  • param – The parameter that is requesting completion.

  • incomplete – Value being completed. May be empty.

New in version 8.0.

split_envvar_value(rv: str) Sequence[str]

Given a value from an environment variable this splits it up into small chunks depending on the defined envvar list splitter.

If the splitter is set to None, which means that whitespace splits, then leading and trailing whitespace is ignored. Otherwise, leading and trailing splitters usually lead to empty items being included.

to_info_dict() Dict[str, Any]

Gather information that could be useful for a tool generating user-facing documentation.

Use click.Context.to_info_dict() to traverse the entire CLI structure.

New in version 8.0.