1074 lines
35 KiB
Python
1074 lines
35 KiB
Python
import os
|
|
import stat
|
|
import typing as t
|
|
from datetime import datetime
|
|
from gettext import gettext as _
|
|
from gettext import ngettext
|
|
|
|
from ._compat import _get_argv_encoding
|
|
from ._compat import get_filesystem_encoding
|
|
from ._compat import open_stream
|
|
from .exceptions import BadParameter
|
|
from .utils import LazyFile
|
|
from .utils import safecall
|
|
|
|
if t.TYPE_CHECKING:
|
|
import typing_extensions as te
|
|
from .core import Context
|
|
from .core import Parameter
|
|
from .shell_completion import CompletionItem
|
|
|
|
|
|
class ParamType:
|
|
"""Represents the type of a parameter. Validates and converts values
|
|
from the command line or Python into the correct type.
|
|
|
|
To implement a custom type, subclass and implement at least the
|
|
following:
|
|
|
|
- The :attr:`name` class attribute must be set.
|
|
- Calling an instance of the type with ``None`` must return
|
|
``None``. This is already implemented by default.
|
|
- :meth:`convert` must convert string values to the correct type.
|
|
- :meth:`convert` must accept values that are already the correct
|
|
type.
|
|
- It must be able to convert a value if the ``ctx`` and ``param``
|
|
arguments are ``None``. This can occur when converting prompt
|
|
input.
|
|
"""
|
|
|
|
is_composite: t.ClassVar[bool] = False
|
|
arity: t.ClassVar[int] = 1
|
|
|
|
#: the descriptive name of this type
|
|
name: 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).
|
|
envvar_list_splitter: t.ClassVar[t.Optional[str]] = None
|
|
|
|
def to_info_dict(self) -> t.Dict[str, t.Any]:
|
|
"""Gather information that could be useful for a tool generating
|
|
user-facing documentation.
|
|
|
|
Use :meth:`click.Context.to_info_dict` to traverse the entire
|
|
CLI structure.
|
|
|
|
.. versionadded:: 8.0
|
|
"""
|
|
# The class name without the "ParamType" suffix.
|
|
param_type = type(self).__name__.partition("ParamType")[0]
|
|
param_type = param_type.partition("ParameterType")[0]
|
|
|
|
# Custom subclasses might not remember to set a name.
|
|
if hasattr(self, "name"):
|
|
name = self.name
|
|
else:
|
|
name = param_type
|
|
|
|
return {"param_type": param_type, "name": name}
|
|
|
|
def __call__(
|
|
self,
|
|
value: t.Any,
|
|
param: t.Optional["Parameter"] = None,
|
|
ctx: t.Optional["Context"] = None,
|
|
) -> t.Any:
|
|
if value is not None:
|
|
return self.convert(value, param, ctx)
|
|
|
|
def get_metavar(self, param: "Parameter") -> t.Optional[str]:
|
|
"""Returns the metavar default for this param if it provides one."""
|
|
|
|
def get_missing_message(self, param: "Parameter") -> t.Optional[str]:
|
|
"""Optionally might return extra information about a missing
|
|
parameter.
|
|
|
|
.. versionadded:: 2.0
|
|
"""
|
|
|
|
def convert(
|
|
self, value: t.Any, param: t.Optional["Parameter"], ctx: t.Optional["Context"]
|
|
) -> t.Any:
|
|
"""Convert the value to the correct type. This is not called if
|
|
the value is ``None`` (the missing value).
|
|
|
|
This must accept string values from the command line, as well as
|
|
values that are already the correct type. It may also convert
|
|
other compatible types.
|
|
|
|
The ``param`` and ``ctx`` arguments may be ``None`` in certain
|
|
situations, such as when converting prompt input.
|
|
|
|
If the value cannot be converted, call :meth:`fail` with a
|
|
descriptive message.
|
|
|
|
:param value: The value to convert.
|
|
:param param: The parameter that is using this type to convert
|
|
its value. May be ``None``.
|
|
:param ctx: The current context that arrived at this value. May
|
|
be ``None``.
|
|
"""
|
|
return value
|
|
|
|
def split_envvar_value(self, rv: str) -> t.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.
|
|
"""
|
|
return (rv or "").split(self.envvar_list_splitter)
|
|
|
|
def fail(
|
|
self,
|
|
message: str,
|
|
param: t.Optional["Parameter"] = None,
|
|
ctx: t.Optional["Context"] = None,
|
|
) -> "t.NoReturn":
|
|
"""Helper method to fail with an invalid value message."""
|
|
raise BadParameter(message, ctx=ctx, param=param)
|
|
|
|
def shell_complete(
|
|
self, ctx: "Context", param: "Parameter", incomplete: str
|
|
) -> t.List["CompletionItem"]:
|
|
"""Return a list of
|
|
:class:`~click.shell_completion.CompletionItem` objects for the
|
|
incomplete value. Most types do not provide completions, but
|
|
some do, and this allows custom types to provide custom
|
|
completions as well.
|
|
|
|
:param ctx: Invocation context for this command.
|
|
:param param: The parameter that is requesting completion.
|
|
:param incomplete: Value being completed. May be empty.
|
|
|
|
.. versionadded:: 8.0
|
|
"""
|
|
return []
|
|
|
|
|
|
class CompositeParamType(ParamType):
|
|
is_composite = True
|
|
|
|
@property
|
|
def arity(self) -> int: # type: ignore
|
|
raise NotImplementedError()
|
|
|
|
|
|
class FuncParamType(ParamType):
|
|
def __init__(self, func: t.Callable[[t.Any], t.Any]) -> None:
|
|
self.name = func.__name__
|
|
self.func = func
|
|
|
|
def to_info_dict(self) -> t.Dict[str, t.Any]:
|
|
info_dict = super().to_info_dict()
|
|
info_dict["func"] = self.func
|
|
return info_dict
|
|
|
|
def convert(
|
|
self, value: t.Any, param: t.Optional["Parameter"], ctx: t.Optional["Context"]
|
|
) -> t.Any:
|
|
try:
|
|
return self.func(value)
|
|
except ValueError:
|
|
try:
|
|
value = str(value)
|
|
except UnicodeError:
|
|
value = value.decode("utf-8", "replace")
|
|
|
|
self.fail(value, param, ctx)
|
|
|
|
|
|
class UnprocessedParamType(ParamType):
|
|
name = "text"
|
|
|
|
def convert(
|
|
self, value: t.Any, param: t.Optional["Parameter"], ctx: t.Optional["Context"]
|
|
) -> t.Any:
|
|
return value
|
|
|
|
def __repr__(self) -> str:
|
|
return "UNPROCESSED"
|
|
|
|
|
|
class StringParamType(ParamType):
|
|
name = "text"
|
|
|
|
def convert(
|
|
self, value: t.Any, param: t.Optional["Parameter"], ctx: t.Optional["Context"]
|
|
) -> t.Any:
|
|
if isinstance(value, bytes):
|
|
enc = _get_argv_encoding()
|
|
try:
|
|
value = value.decode(enc)
|
|
except UnicodeError:
|
|
fs_enc = get_filesystem_encoding()
|
|
if fs_enc != enc:
|
|
try:
|
|
value = value.decode(fs_enc)
|
|
except UnicodeError:
|
|
value = value.decode("utf-8", "replace")
|
|
else:
|
|
value = value.decode("utf-8", "replace")
|
|
return value
|
|
return str(value)
|
|
|
|
def __repr__(self) -> str:
|
|
return "STRING"
|
|
|
|
|
|
class Choice(ParamType):
|
|
"""The choice type allows a value to be checked against a fixed set
|
|
of supported values. All of these values have to be strings.
|
|
|
|
You should only pass a list or tuple of choices. Other iterables
|
|
(like generators) may lead to surprising results.
|
|
|
|
The resulting value will always be one of the originally passed choices
|
|
regardless of ``case_sensitive`` or any ``ctx.token_normalize_func``
|
|
being specified.
|
|
|
|
See :ref:`choice-opts` for an example.
|
|
|
|
:param case_sensitive: Set to false to make choices case
|
|
insensitive. Defaults to true.
|
|
"""
|
|
|
|
name = "choice"
|
|
|
|
def __init__(self, choices: t.Sequence[str], case_sensitive: bool = True) -> None:
|
|
self.choices = choices
|
|
self.case_sensitive = case_sensitive
|
|
|
|
def to_info_dict(self) -> t.Dict[str, t.Any]:
|
|
info_dict = super().to_info_dict()
|
|
info_dict["choices"] = self.choices
|
|
info_dict["case_sensitive"] = self.case_sensitive
|
|
return info_dict
|
|
|
|
def get_metavar(self, param: "Parameter") -> str:
|
|
choices_str = "|".join(self.choices)
|
|
|
|
# Use curly braces to indicate a required argument.
|
|
if param.required and param.param_type_name == "argument":
|
|
return f"{{{choices_str}}}"
|
|
|
|
# Use square braces to indicate an option or optional argument.
|
|
return f"[{choices_str}]"
|
|
|
|
def get_missing_message(self, param: "Parameter") -> str:
|
|
return _("Choose from:\n\t{choices}").format(choices=",\n\t".join(self.choices))
|
|
|
|
def convert(
|
|
self, value: t.Any, param: t.Optional["Parameter"], ctx: t.Optional["Context"]
|
|
) -> t.Any:
|
|
# Match through normalization and case sensitivity
|
|
# first do token_normalize_func, then lowercase
|
|
# preserve original `value` to produce an accurate message in
|
|
# `self.fail`
|
|
normed_value = value
|
|
normed_choices = {choice: choice for choice in self.choices}
|
|
|
|
if ctx is not None and ctx.token_normalize_func is not None:
|
|
normed_value = ctx.token_normalize_func(value)
|
|
normed_choices = {
|
|
ctx.token_normalize_func(normed_choice): original
|
|
for normed_choice, original in normed_choices.items()
|
|
}
|
|
|
|
if not self.case_sensitive:
|
|
normed_value = normed_value.casefold()
|
|
normed_choices = {
|
|
normed_choice.casefold(): original
|
|
for normed_choice, original in normed_choices.items()
|
|
}
|
|
|
|
if normed_value in normed_choices:
|
|
return normed_choices[normed_value]
|
|
|
|
choices_str = ", ".join(map(repr, self.choices))
|
|
self.fail(
|
|
ngettext(
|
|
"{value!r} is not {choice}.",
|
|
"{value!r} is not one of {choices}.",
|
|
len(self.choices),
|
|
).format(value=value, choice=choices_str, choices=choices_str),
|
|
param,
|
|
ctx,
|
|
)
|
|
|
|
def __repr__(self) -> str:
|
|
return f"Choice({list(self.choices)})"
|
|
|
|
def shell_complete(
|
|
self, ctx: "Context", param: "Parameter", incomplete: str
|
|
) -> t.List["CompletionItem"]:
|
|
"""Complete choices that start with the incomplete value.
|
|
|
|
:param ctx: Invocation context for this command.
|
|
:param param: The parameter that is requesting completion.
|
|
:param incomplete: Value being completed. May be empty.
|
|
|
|
.. versionadded:: 8.0
|
|
"""
|
|
from click.shell_completion import CompletionItem
|
|
|
|
str_choices = map(str, self.choices)
|
|
|
|
if self.case_sensitive:
|
|
matched = (c for c in str_choices if c.startswith(incomplete))
|
|
else:
|
|
incomplete = incomplete.lower()
|
|
matched = (c for c in str_choices if c.lower().startswith(incomplete))
|
|
|
|
return [CompletionItem(c) for c in matched]
|
|
|
|
|
|
class DateTime(ParamType):
|
|
"""The DateTime type converts date strings into `datetime` objects.
|
|
|
|
The format strings which are checked are configurable, but default to some
|
|
common (non-timezone aware) ISO 8601 formats.
|
|
|
|
When specifying *DateTime* formats, you should only pass a list or a tuple.
|
|
Other iterables, like generators, may lead to surprising results.
|
|
|
|
The format strings are processed using ``datetime.strptime``, and this
|
|
consequently defines the format strings which are allowed.
|
|
|
|
Parsing is tried using each format, in order, and the first format which
|
|
parses successfully is used.
|
|
|
|
:param formats: A list or tuple of date format strings, in the order in
|
|
which they should be tried. Defaults to
|
|
``'%Y-%m-%d'``, ``'%Y-%m-%dT%H:%M:%S'``,
|
|
``'%Y-%m-%d %H:%M:%S'``.
|
|
"""
|
|
|
|
name = "datetime"
|
|
|
|
def __init__(self, formats: t.Optional[t.Sequence[str]] = None):
|
|
self.formats = formats or ["%Y-%m-%d", "%Y-%m-%dT%H:%M:%S", "%Y-%m-%d %H:%M:%S"]
|
|
|
|
def to_info_dict(self) -> t.Dict[str, t.Any]:
|
|
info_dict = super().to_info_dict()
|
|
info_dict["formats"] = self.formats
|
|
return info_dict
|
|
|
|
def get_metavar(self, param: "Parameter") -> str:
|
|
return f"[{'|'.join(self.formats)}]"
|
|
|
|
def _try_to_convert_date(self, value: t.Any, format: str) -> t.Optional[datetime]:
|
|
try:
|
|
return datetime.strptime(value, format)
|
|
except ValueError:
|
|
return None
|
|
|
|
def convert(
|
|
self, value: t.Any, param: t.Optional["Parameter"], ctx: t.Optional["Context"]
|
|
) -> t.Any:
|
|
if isinstance(value, datetime):
|
|
return value
|
|
|
|
for format in self.formats:
|
|
converted = self._try_to_convert_date(value, format)
|
|
|
|
if converted is not None:
|
|
return converted
|
|
|
|
formats_str = ", ".join(map(repr, self.formats))
|
|
self.fail(
|
|
ngettext(
|
|
"{value!r} does not match the format {format}.",
|
|
"{value!r} does not match the formats {formats}.",
|
|
len(self.formats),
|
|
).format(value=value, format=formats_str, formats=formats_str),
|
|
param,
|
|
ctx,
|
|
)
|
|
|
|
def __repr__(self) -> str:
|
|
return "DateTime"
|
|
|
|
|
|
class _NumberParamTypeBase(ParamType):
|
|
_number_class: t.ClassVar[t.Type]
|
|
|
|
def convert(
|
|
self, value: t.Any, param: t.Optional["Parameter"], ctx: t.Optional["Context"]
|
|
) -> t.Any:
|
|
try:
|
|
return self._number_class(value)
|
|
except ValueError:
|
|
self.fail(
|
|
_("{value!r} is not a valid {number_type}.").format(
|
|
value=value, number_type=self.name
|
|
),
|
|
param,
|
|
ctx,
|
|
)
|
|
|
|
|
|
class _NumberRangeBase(_NumberParamTypeBase):
|
|
def __init__(
|
|
self,
|
|
min: t.Optional[float] = None,
|
|
max: t.Optional[float] = None,
|
|
min_open: bool = False,
|
|
max_open: bool = False,
|
|
clamp: bool = False,
|
|
) -> None:
|
|
self.min = min
|
|
self.max = max
|
|
self.min_open = min_open
|
|
self.max_open = max_open
|
|
self.clamp = clamp
|
|
|
|
def to_info_dict(self) -> t.Dict[str, t.Any]:
|
|
info_dict = super().to_info_dict()
|
|
info_dict.update(
|
|
min=self.min,
|
|
max=self.max,
|
|
min_open=self.min_open,
|
|
max_open=self.max_open,
|
|
clamp=self.clamp,
|
|
)
|
|
return info_dict
|
|
|
|
def convert(
|
|
self, value: t.Any, param: t.Optional["Parameter"], ctx: t.Optional["Context"]
|
|
) -> t.Any:
|
|
import operator
|
|
|
|
rv = super().convert(value, param, ctx)
|
|
lt_min: bool = self.min is not None and (
|
|
operator.le if self.min_open else operator.lt
|
|
)(rv, self.min)
|
|
gt_max: bool = self.max is not None and (
|
|
operator.ge if self.max_open else operator.gt
|
|
)(rv, self.max)
|
|
|
|
if self.clamp:
|
|
if lt_min:
|
|
return self._clamp(self.min, 1, self.min_open) # type: ignore
|
|
|
|
if gt_max:
|
|
return self._clamp(self.max, -1, self.max_open) # type: ignore
|
|
|
|
if lt_min or gt_max:
|
|
self.fail(
|
|
_("{value} is not in the range {range}.").format(
|
|
value=rv, range=self._describe_range()
|
|
),
|
|
param,
|
|
ctx,
|
|
)
|
|
|
|
return rv
|
|
|
|
def _clamp(self, bound: float, dir: "te.Literal[1, -1]", open: bool) -> float:
|
|
"""Find the valid value to clamp to bound in the given
|
|
direction.
|
|
|
|
:param bound: The boundary value.
|
|
:param dir: 1 or -1 indicating the direction to move.
|
|
:param open: If true, the range does not include the bound.
|
|
"""
|
|
raise NotImplementedError
|
|
|
|
def _describe_range(self) -> str:
|
|
"""Describe the range for use in help text."""
|
|
if self.min is None:
|
|
op = "<" if self.max_open else "<="
|
|
return f"x{op}{self.max}"
|
|
|
|
if self.max is None:
|
|
op = ">" if self.min_open else ">="
|
|
return f"x{op}{self.min}"
|
|
|
|
lop = "<" if self.min_open else "<="
|
|
rop = "<" if self.max_open else "<="
|
|
return f"{self.min}{lop}x{rop}{self.max}"
|
|
|
|
def __repr__(self) -> str:
|
|
clamp = " clamped" if self.clamp else ""
|
|
return f"<{type(self).__name__} {self._describe_range()}{clamp}>"
|
|
|
|
|
|
class IntParamType(_NumberParamTypeBase):
|
|
name = "integer"
|
|
_number_class = int
|
|
|
|
def __repr__(self) -> str:
|
|
return "INT"
|
|
|
|
|
|
class IntRange(_NumberRangeBase, IntParamType):
|
|
"""Restrict an :data:`click.INT` value to a range of accepted
|
|
values. See :ref:`ranges`.
|
|
|
|
If ``min`` or ``max`` are not passed, any value is accepted in that
|
|
direction. If ``min_open`` or ``max_open`` are enabled, the
|
|
corresponding boundary is not included in the range.
|
|
|
|
If ``clamp`` is enabled, a value outside the range is clamped to the
|
|
boundary instead of failing.
|
|
|
|
.. versionchanged:: 8.0
|
|
Added the ``min_open`` and ``max_open`` parameters.
|
|
"""
|
|
|
|
name = "integer range"
|
|
|
|
def _clamp( # type: ignore
|
|
self, bound: int, dir: "te.Literal[1, -1]", open: bool
|
|
) -> int:
|
|
if not open:
|
|
return bound
|
|
|
|
return bound + dir
|
|
|
|
|
|
class FloatParamType(_NumberParamTypeBase):
|
|
name = "float"
|
|
_number_class = float
|
|
|
|
def __repr__(self) -> str:
|
|
return "FLOAT"
|
|
|
|
|
|
class FloatRange(_NumberRangeBase, FloatParamType):
|
|
"""Restrict a :data:`click.FLOAT` value to a range of accepted
|
|
values. See :ref:`ranges`.
|
|
|
|
If ``min`` or ``max`` are not passed, any value is accepted in that
|
|
direction. If ``min_open`` or ``max_open`` are enabled, the
|
|
corresponding boundary is not included in the range.
|
|
|
|
If ``clamp`` is enabled, a value outside the range is clamped to the
|
|
boundary instead of failing. This is not supported if either
|
|
boundary is marked ``open``.
|
|
|
|
.. versionchanged:: 8.0
|
|
Added the ``min_open`` and ``max_open`` parameters.
|
|
"""
|
|
|
|
name = "float range"
|
|
|
|
def __init__(
|
|
self,
|
|
min: t.Optional[float] = None,
|
|
max: t.Optional[float] = None,
|
|
min_open: bool = False,
|
|
max_open: bool = False,
|
|
clamp: bool = False,
|
|
) -> None:
|
|
super().__init__(
|
|
min=min, max=max, min_open=min_open, max_open=max_open, clamp=clamp
|
|
)
|
|
|
|
if (min_open or max_open) and clamp:
|
|
raise TypeError("Clamping is not supported for open bounds.")
|
|
|
|
def _clamp(self, bound: float, dir: "te.Literal[1, -1]", open: bool) -> float:
|
|
if not open:
|
|
return bound
|
|
|
|
# Could use Python 3.9's math.nextafter here, but clamping an
|
|
# open float range doesn't seem to be particularly useful. It's
|
|
# left up to the user to write a callback to do it if needed.
|
|
raise RuntimeError("Clamping is not supported for open bounds.")
|
|
|
|
|
|
class BoolParamType(ParamType):
|
|
name = "boolean"
|
|
|
|
def convert(
|
|
self, value: t.Any, param: t.Optional["Parameter"], ctx: t.Optional["Context"]
|
|
) -> t.Any:
|
|
if value in {False, True}:
|
|
return bool(value)
|
|
|
|
norm = value.strip().lower()
|
|
|
|
if norm in {"1", "true", "t", "yes", "y", "on"}:
|
|
return True
|
|
|
|
if norm in {"0", "false", "f", "no", "n", "off"}:
|
|
return False
|
|
|
|
self.fail(
|
|
_("{value!r} is not a valid boolean.").format(value=value), param, ctx
|
|
)
|
|
|
|
def __repr__(self) -> str:
|
|
return "BOOL"
|
|
|
|
|
|
class UUIDParameterType(ParamType):
|
|
name = "uuid"
|
|
|
|
def convert(
|
|
self, value: t.Any, param: t.Optional["Parameter"], ctx: t.Optional["Context"]
|
|
) -> t.Any:
|
|
import uuid
|
|
|
|
if isinstance(value, uuid.UUID):
|
|
return value
|
|
|
|
value = value.strip()
|
|
|
|
try:
|
|
return uuid.UUID(value)
|
|
except ValueError:
|
|
self.fail(
|
|
_("{value!r} is not a valid UUID.").format(value=value), param, ctx
|
|
)
|
|
|
|
def __repr__(self) -> str:
|
|
return "UUID"
|
|
|
|
|
|
class File(ParamType):
|
|
"""Declares a parameter to be a file for reading or writing. The file
|
|
is automatically closed once the context tears down (after the command
|
|
finished working).
|
|
|
|
Files can be opened for reading or writing. The special value ``-``
|
|
indicates stdin or stdout depending on the mode.
|
|
|
|
By default, the file is opened for reading text data, but it can also be
|
|
opened in binary mode or for writing. The encoding parameter can be used
|
|
to force a specific encoding.
|
|
|
|
The `lazy` flag controls if the file should be opened immediately or upon
|
|
first IO. The default is to be non-lazy for standard input and output
|
|
streams as well as files opened for reading, `lazy` otherwise. When opening a
|
|
file lazily for reading, it is still opened temporarily for validation, but
|
|
will not be held open until first IO. lazy is mainly useful when opening
|
|
for writing to avoid creating the file until it is needed.
|
|
|
|
Starting with Click 2.0, files can also be opened atomically in which
|
|
case all writes go into a separate file in the same folder and upon
|
|
completion the file will be moved over to the original location. This
|
|
is useful if a file regularly read by other users is modified.
|
|
|
|
See :ref:`file-args` for more information.
|
|
"""
|
|
|
|
name = "filename"
|
|
envvar_list_splitter = os.path.pathsep
|
|
|
|
def __init__(
|
|
self,
|
|
mode: str = "r",
|
|
encoding: t.Optional[str] = None,
|
|
errors: t.Optional[str] = "strict",
|
|
lazy: t.Optional[bool] = None,
|
|
atomic: bool = False,
|
|
) -> None:
|
|
self.mode = mode
|
|
self.encoding = encoding
|
|
self.errors = errors
|
|
self.lazy = lazy
|
|
self.atomic = atomic
|
|
|
|
def to_info_dict(self) -> t.Dict[str, t.Any]:
|
|
info_dict = super().to_info_dict()
|
|
info_dict.update(mode=self.mode, encoding=self.encoding)
|
|
return info_dict
|
|
|
|
def resolve_lazy_flag(self, value: t.Any) -> bool:
|
|
if self.lazy is not None:
|
|
return self.lazy
|
|
if value == "-":
|
|
return False
|
|
elif "w" in self.mode:
|
|
return True
|
|
return False
|
|
|
|
def convert(
|
|
self, value: t.Any, param: t.Optional["Parameter"], ctx: t.Optional["Context"]
|
|
) -> t.Any:
|
|
try:
|
|
if hasattr(value, "read") or hasattr(value, "write"):
|
|
return value
|
|
|
|
lazy = self.resolve_lazy_flag(value)
|
|
|
|
if lazy:
|
|
f: t.IO = t.cast(
|
|
t.IO,
|
|
LazyFile(
|
|
value, self.mode, self.encoding, self.errors, atomic=self.atomic
|
|
),
|
|
)
|
|
|
|
if ctx is not None:
|
|
ctx.call_on_close(f.close_intelligently) # type: ignore
|
|
|
|
return f
|
|
|
|
f, should_close = open_stream(
|
|
value, self.mode, self.encoding, self.errors, atomic=self.atomic
|
|
)
|
|
|
|
# If a context is provided, we automatically close the file
|
|
# at the end of the context execution (or flush out). If a
|
|
# context does not exist, it's the caller's responsibility to
|
|
# properly close the file. This for instance happens when the
|
|
# type is used with prompts.
|
|
if ctx is not None:
|
|
if should_close:
|
|
ctx.call_on_close(safecall(f.close))
|
|
else:
|
|
ctx.call_on_close(safecall(f.flush))
|
|
|
|
return f
|
|
except OSError as e: # noqa: B014
|
|
self.fail(f"'{os.fsdecode(value)}': {e.strerror}", param, ctx)
|
|
|
|
def shell_complete(
|
|
self, ctx: "Context", param: "Parameter", incomplete: str
|
|
) -> t.List["CompletionItem"]:
|
|
"""Return a special completion marker that tells the completion
|
|
system to use the shell to provide file path completions.
|
|
|
|
:param ctx: Invocation context for this command.
|
|
:param param: The parameter that is requesting completion.
|
|
:param incomplete: Value being completed. May be empty.
|
|
|
|
.. versionadded:: 8.0
|
|
"""
|
|
from click.shell_completion import CompletionItem
|
|
|
|
return [CompletionItem(incomplete, type="file")]
|
|
|
|
|
|
class Path(ParamType):
|
|
"""The ``Path`` type is similar to the :class:`File` type, but
|
|
returns the filename instead of an open file. Various checks can be
|
|
enabled to validate the type of file and permissions.
|
|
|
|
:param exists: The file or directory needs to exist for the value to
|
|
be valid. If this is not set to ``True``, and the file does not
|
|
exist, then all further checks are silently skipped.
|
|
:param file_okay: Allow a file as a value.
|
|
:param dir_okay: Allow a directory as a value.
|
|
:param readable: if true, a readable check is performed.
|
|
:param writable: if true, a writable check is performed.
|
|
:param executable: if true, an executable check is performed.
|
|
:param resolve_path: Make the value absolute and resolve any
|
|
symlinks. A ``~`` is not expanded, as this is supposed to be
|
|
done by the shell only.
|
|
:param allow_dash: Allow a single dash as a value, which indicates
|
|
a standard stream (but does not open it). Use
|
|
:func:`~click.open_file` to handle opening this value.
|
|
:param path_type: Convert the incoming path value to this type. If
|
|
``None``, keep Python's default, which is ``str``. Useful to
|
|
convert to :class:`pathlib.Path`.
|
|
|
|
.. versionchanged:: 8.1
|
|
Added the ``executable`` parameter.
|
|
|
|
.. versionchanged:: 8.0
|
|
Allow passing ``type=pathlib.Path``.
|
|
|
|
.. versionchanged:: 6.0
|
|
Added the ``allow_dash`` parameter.
|
|
"""
|
|
|
|
envvar_list_splitter = os.path.pathsep
|
|
|
|
def __init__(
|
|
self,
|
|
exists: bool = False,
|
|
file_okay: bool = True,
|
|
dir_okay: bool = True,
|
|
writable: bool = False,
|
|
readable: bool = True,
|
|
resolve_path: bool = False,
|
|
allow_dash: bool = False,
|
|
path_type: t.Optional[t.Type] = None,
|
|
executable: bool = False,
|
|
):
|
|
self.exists = exists
|
|
self.file_okay = file_okay
|
|
self.dir_okay = dir_okay
|
|
self.readable = readable
|
|
self.writable = writable
|
|
self.executable = executable
|
|
self.resolve_path = resolve_path
|
|
self.allow_dash = allow_dash
|
|
self.type = path_type
|
|
|
|
if self.file_okay and not self.dir_okay:
|
|
self.name = _("file")
|
|
elif self.dir_okay and not self.file_okay:
|
|
self.name = _("directory")
|
|
else:
|
|
self.name = _("path")
|
|
|
|
def to_info_dict(self) -> t.Dict[str, t.Any]:
|
|
info_dict = super().to_info_dict()
|
|
info_dict.update(
|
|
exists=self.exists,
|
|
file_okay=self.file_okay,
|
|
dir_okay=self.dir_okay,
|
|
writable=self.writable,
|
|
readable=self.readable,
|
|
allow_dash=self.allow_dash,
|
|
)
|
|
return info_dict
|
|
|
|
def coerce_path_result(self, rv: t.Any) -> t.Any:
|
|
if self.type is not None and not isinstance(rv, self.type):
|
|
if self.type is str:
|
|
rv = os.fsdecode(rv)
|
|
elif self.type is bytes:
|
|
rv = os.fsencode(rv)
|
|
else:
|
|
rv = self.type(rv)
|
|
|
|
return rv
|
|
|
|
def convert(
|
|
self, value: t.Any, param: t.Optional["Parameter"], ctx: t.Optional["Context"]
|
|
) -> t.Any:
|
|
rv = value
|
|
|
|
is_dash = self.file_okay and self.allow_dash and rv in (b"-", "-")
|
|
|
|
if not is_dash:
|
|
if self.resolve_path:
|
|
# os.path.realpath doesn't resolve symlinks on Windows
|
|
# until Python 3.8. Use pathlib for now.
|
|
import pathlib
|
|
|
|
rv = os.fsdecode(pathlib.Path(rv).resolve())
|
|
|
|
try:
|
|
st = os.stat(rv)
|
|
except OSError:
|
|
if not self.exists:
|
|
return self.coerce_path_result(rv)
|
|
self.fail(
|
|
_("{name} {filename!r} does not exist.").format(
|
|
name=self.name.title(), filename=os.fsdecode(value)
|
|
),
|
|
param,
|
|
ctx,
|
|
)
|
|
|
|
if not self.file_okay and stat.S_ISREG(st.st_mode):
|
|
self.fail(
|
|
_("{name} {filename!r} is a file.").format(
|
|
name=self.name.title(), filename=os.fsdecode(value)
|
|
),
|
|
param,
|
|
ctx,
|
|
)
|
|
if not self.dir_okay and stat.S_ISDIR(st.st_mode):
|
|
self.fail(
|
|
_("{name} '{filename}' is a directory.").format(
|
|
name=self.name.title(), filename=os.fsdecode(value)
|
|
),
|
|
param,
|
|
ctx,
|
|
)
|
|
|
|
if self.readable and not os.access(rv, os.R_OK):
|
|
self.fail(
|
|
_("{name} {filename!r} is not readable.").format(
|
|
name=self.name.title(), filename=os.fsdecode(value)
|
|
),
|
|
param,
|
|
ctx,
|
|
)
|
|
|
|
if self.writable and not os.access(rv, os.W_OK):
|
|
self.fail(
|
|
_("{name} {filename!r} is not writable.").format(
|
|
name=self.name.title(), filename=os.fsdecode(value)
|
|
),
|
|
param,
|
|
ctx,
|
|
)
|
|
|
|
if self.executable and not os.access(value, os.X_OK):
|
|
self.fail(
|
|
_("{name} {filename!r} is not executable.").format(
|
|
name=self.name.title(), filename=os.fsdecode(value)
|
|
),
|
|
param,
|
|
ctx,
|
|
)
|
|
|
|
return self.coerce_path_result(rv)
|
|
|
|
def shell_complete(
|
|
self, ctx: "Context", param: "Parameter", incomplete: str
|
|
) -> t.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.
|
|
|
|
:param ctx: Invocation context for this command.
|
|
:param param: The parameter that is requesting completion.
|
|
:param incomplete: Value being completed. May be empty.
|
|
|
|
.. versionadded:: 8.0
|
|
"""
|
|
from click.shell_completion import CompletionItem
|
|
|
|
type = "dir" if self.dir_okay and not self.file_okay else "file"
|
|
return [CompletionItem(incomplete, type=type)]
|
|
|
|
|
|
class Tuple(CompositeParamType):
|
|
"""The default behavior of Click is to apply a type on a value directly.
|
|
This works well in most cases, except for when `nargs` is set to a fixed
|
|
count and different types should be used for different items. In this
|
|
case the :class:`Tuple` type can be used. This type can only be used
|
|
if `nargs` is set to a fixed number.
|
|
|
|
For more information see :ref:`tuple-type`.
|
|
|
|
This can be selected by using a Python tuple literal as a type.
|
|
|
|
:param types: a list of types that should be used for the tuple items.
|
|
"""
|
|
|
|
def __init__(self, types: t.Sequence[t.Union[t.Type, ParamType]]) -> None:
|
|
self.types = [convert_type(ty) for ty in types]
|
|
|
|
def to_info_dict(self) -> t.Dict[str, t.Any]:
|
|
info_dict = super().to_info_dict()
|
|
info_dict["types"] = [t.to_info_dict() for t in self.types]
|
|
return info_dict
|
|
|
|
@property
|
|
def name(self) -> str: # type: ignore
|
|
return f"<{' '.join(ty.name for ty in self.types)}>"
|
|
|
|
@property
|
|
def arity(self) -> int: # type: ignore
|
|
return len(self.types)
|
|
|
|
def convert(
|
|
self, value: t.Any, param: t.Optional["Parameter"], ctx: t.Optional["Context"]
|
|
) -> t.Any:
|
|
len_type = len(self.types)
|
|
len_value = len(value)
|
|
|
|
if len_value != len_type:
|
|
self.fail(
|
|
ngettext(
|
|
"{len_type} values are required, but {len_value} was given.",
|
|
"{len_type} values are required, but {len_value} were given.",
|
|
len_value,
|
|
).format(len_type=len_type, len_value=len_value),
|
|
param=param,
|
|
ctx=ctx,
|
|
)
|
|
|
|
return tuple(ty(x, param, ctx) for ty, x in zip(self.types, value))
|
|
|
|
|
|
def convert_type(ty: t.Optional[t.Any], default: t.Optional[t.Any] = None) -> ParamType:
|
|
"""Find the most appropriate :class:`ParamType` for the given Python
|
|
type. If the type isn't provided, it can be inferred from a default
|
|
value.
|
|
"""
|
|
guessed_type = False
|
|
|
|
if ty is None and default is not None:
|
|
if isinstance(default, (tuple, list)):
|
|
# If the default is empty, ty will remain None and will
|
|
# return STRING.
|
|
if default:
|
|
item = default[0]
|
|
|
|
# A tuple of tuples needs to detect the inner types.
|
|
# Can't call convert recursively because that would
|
|
# incorrectly unwind the tuple to a single type.
|
|
if isinstance(item, (tuple, list)):
|
|
ty = tuple(map(type, item))
|
|
else:
|
|
ty = type(item)
|
|
else:
|
|
ty = type(default)
|
|
|
|
guessed_type = True
|
|
|
|
if isinstance(ty, tuple):
|
|
return Tuple(ty)
|
|
|
|
if isinstance(ty, ParamType):
|
|
return ty
|
|
|
|
if ty is str or ty is None:
|
|
return STRING
|
|
|
|
if ty is int:
|
|
return INT
|
|
|
|
if ty is float:
|
|
return FLOAT
|
|
|
|
if ty is bool:
|
|
return BOOL
|
|
|
|
if guessed_type:
|
|
return STRING
|
|
|
|
if __debug__:
|
|
try:
|
|
if issubclass(ty, ParamType):
|
|
raise AssertionError(
|
|
f"Attempted to use an uninstantiated parameter type ({ty})."
|
|
)
|
|
except TypeError:
|
|
# ty is an instance (correct), so issubclass fails.
|
|
pass
|
|
|
|
return FuncParamType(ty)
|
|
|
|
|
|
#: A dummy parameter type that just does nothing. From a user's
|
|
#: perspective this appears to just be the same as `STRING` but
|
|
#: internally no string conversion takes place if the input was bytes.
|
|
#: This is usually useful when working with file paths as they can
|
|
#: appear in bytes and unicode.
|
|
#:
|
|
#: For path related uses the :class:`Path` type is a better choice but
|
|
#: there are situations where an unprocessed type is useful which is why
|
|
#: it is is provided.
|
|
#:
|
|
#: .. versionadded:: 4.0
|
|
UNPROCESSED = UnprocessedParamType()
|
|
|
|
#: A unicode string parameter type which is the implicit default. This
|
|
#: can also be selected by using ``str`` as type.
|
|
STRING = StringParamType()
|
|
|
|
#: An integer parameter. This can also be selected by using ``int`` as
|
|
#: type.
|
|
INT = IntParamType()
|
|
|
|
#: A floating point value parameter. This can also be selected by using
|
|
#: ``float`` as type.
|
|
FLOAT = FloatParamType()
|
|
|
|
#: A boolean parameter. This is the default for boolean flags. This can
|
|
#: also be selected by using ``bool`` as a type.
|
|
BOOL = BoolParamType()
|
|
|
|
#: A UUID parameter.
|
|
UUID = UUIDParameterType()
|