:mod:`cloup.constraints` ======================== .. py:module:: cloup.constraints .. autoapi-nested-parse:: Constraints for parameter groups. .. versionadded:: v0.5.0 Submodules ---------- .. toctree:: :titlesonly: :maxdepth: 1 common/index.rst conditions/index.rst exceptions/index.rst Classes ------- .. autosummary:: ~cloup.constraints.If ~cloup.constraints.AcceptAtMost ~cloup.constraints.AcceptBetween ~cloup.constraints.And ~cloup.constraints.Constraint ~cloup.constraints.Operator ~cloup.constraints.Or ~cloup.constraints.Rephraser ~cloup.constraints.RequireAtLeast ~cloup.constraints.RequireExactly ~cloup.constraints.WrapperConstraint ~cloup.constraints.ConstraintMixin ~cloup.constraints.BoundConstraintSpec ~cloup.constraints.AllSet ~cloup.constraints.AnySet ~cloup.constraints.Equal ~cloup.constraints.IsSet ~cloup.constraints.Not Functions --------- .. autosummary:: ~cloup.constraints.constraint Attributes ---------- .. autoapisummary:: cloup.constraints.accept_none cloup.constraints.all_or_none cloup.constraints.mutually_exclusive cloup.constraints.require_all Contents -------- .. class:: If(condition, then, else_ = None) Bases: :py:obj:`cloup.constraints._core.Constraint` A constraint that can be checked against an arbitrary collection of CLI parameters with respect to a specific :class:`click.Context` (which contains the values assigned to the parameters in ``ctx.params``). .. method:: help(self, ctx) A description of the constraint. .. method:: check_consistency(self, params) Performs some sanity checks that detect inconsistencies between this constraints and the properties of the input parameters (e.g. required). For example, a constraint that requires the parameters to be mutually exclusive is not consistent with a group of parameters with multiple required options. These sanity checks are meant to catch developer's mistakes and don't depend on the values assigned to the parameters; therefore: - they can be performed before any parameter parsing - they can be disabled in production (see :meth:`toggle_consistency_checks`) :param params: list of :class:`click.Parameter` instances :raises: :exc:`~cloup.constraints.errors.UnsatisfiableConstraint` if the constraint cannot be satisfied independently from the values provided by the user .. method:: check_values(self, params, ctx) Checks that the constraint is satisfied by the input parameters in the given context, which (among other things) contains the values assigned to the parameters in ``ctx.params``. You probably don't want to call this method directly. Use :meth:`check` instead. :param params: list of :class:`click.Parameter` instances :param ctx: :class:`click.Context` :raises: :exc:`~cloup.constraints.ConstraintViolated` .. method:: __repr__(self) Return repr(self). .. class:: AcceptAtMost(n) Bases: :py:obj:`Constraint` Satisfied if the number of set parameters is <= n. .. method:: help(self, ctx) A description of the constraint. .. method:: check_consistency(self, params) Performs some sanity checks that detect inconsistencies between this constraints and the properties of the input parameters (e.g. required). For example, a constraint that requires the parameters to be mutually exclusive is not consistent with a group of parameters with multiple required options. These sanity checks are meant to catch developer's mistakes and don't depend on the values assigned to the parameters; therefore: - they can be performed before any parameter parsing - they can be disabled in production (see :meth:`toggle_consistency_checks`) :param params: list of :class:`click.Parameter` instances :raises: :exc:`~cloup.constraints.errors.UnsatisfiableConstraint` if the constraint cannot be satisfied independently from the values provided by the user .. method:: check_values(self, params, ctx) Checks that the constraint is satisfied by the input parameters in the given context, which (among other things) contains the values assigned to the parameters in ``ctx.params``. You probably don't want to call this method directly. Use :meth:`check` instead. :param params: list of :class:`click.Parameter` instances :param ctx: :class:`click.Context` :raises: :exc:`~cloup.constraints.ConstraintViolated` .. method:: __repr__(self) Return repr(self). .. class:: AcceptBetween(min, max) Bases: :py:obj:`WrapperConstraint` Abstract class that wraps another constraint and delegates all methods to it. Useful when you want to define a parametric constraint combining other existing constraints minimizing the boilerplate. This is an alternative to defining a function and using :class:`Rephraser`. Feel free to do that in your code, but cloup will stick to the convention that parametric constraints are defined as classes and written in camel-case. .. method:: help(self, ctx) A description of the constraint. .. class:: And(*constraints) Bases: :py:obj:`Operator` It's satisfied if all operands are satisfied. .. attribute:: HELP_SEP :annotation: = and .. method:: check_values(self, params, ctx) Checks that the constraint is satisfied by the input parameters in the given context, which (among other things) contains the values assigned to the parameters in ``ctx.params``. You probably don't want to call this method directly. Use :meth:`check` instead. :param params: list of :class:`click.Parameter` instances :param ctx: :class:`click.Context` :raises: :exc:`~cloup.constraints.ConstraintViolated` .. method:: __and__(self, other) .. class:: Constraint Bases: :py:obj:`abc.ABC` A constraint that can be checked against an arbitrary collection of CLI parameters with respect to a specific :class:`click.Context` (which contains the values assigned to the parameters in ``ctx.params``). .. method:: must_check_consistency(cls) :classmethod: Returns True if consistency checks are enabled. .. method:: toggle_consistency_checks(cls, value) :classmethod: Enables/disables consistency checks. Enabling means that: - :meth:`check` will call :meth:`check_consistency` - :class:`~cloup.ConstraintMixin` will call `check_consistency` on constraints it is responsible for before parsing CLI arguments. .. method:: consistency_checks_toggled(cls, value) :classmethod: .. method:: help(self, ctx) :abstractmethod: A description of the constraint. .. method:: check_consistency(self, params) Performs some sanity checks that detect inconsistencies between this constraints and the properties of the input parameters (e.g. required). For example, a constraint that requires the parameters to be mutually exclusive is not consistent with a group of parameters with multiple required options. These sanity checks are meant to catch developer's mistakes and don't depend on the values assigned to the parameters; therefore: - they can be performed before any parameter parsing - they can be disabled in production (see :meth:`toggle_consistency_checks`) :param params: list of :class:`click.Parameter` instances :raises: :exc:`~cloup.constraints.errors.UnsatisfiableConstraint` if the constraint cannot be satisfied independently from the values provided by the user .. method:: check_values(self, params, ctx) :abstractmethod: Checks that the constraint is satisfied by the input parameters in the given context, which (among other things) contains the values assigned to the parameters in ``ctx.params``. You probably don't want to call this method directly. Use :meth:`check` instead. :param params: list of :class:`click.Parameter` instances :param ctx: :class:`click.Context` :raises: :exc:`~cloup.constraints.ConstraintViolated` .. method:: check(self, params: Sequence[click.Parameter], ctx: Optional[click.Context] = None) -> None check(self, params: Iterable[str], ctx: Optional[click.Context] = None) -> None Raises an exception if the constraint is not satisfied by the input parameters in the given (or current) context. This method calls both :meth:`check_consistency` (if enabled) and :meth:`check_values`. .. tip:: By default :meth:`check_consistency` is called since it shouldn't have any performance impact. Nonetheless, you can disable it in production passing ``False`` to :meth:`toggle_consistency_checks`. :param params: an iterable of parameter names or a sequence of :class:`click.Parameter` :param ctx: a `Context`; if not provided, :func:`click.get_current_context` is used :raises: :exc:`~cloup.constraints.ConstraintViolated` :exc:`~cloup.constraints.UnsatisfiableConstraint` .. method:: rephrased(self, help = None, error = None) .. method:: hidden(self) Hides this constraint from the command help. .. method:: __call__(self, param_names, ctx = None) .. method:: __or__(self, other) .. method:: __and__(self, other) .. method:: __repr__(self) Return repr(self). .. class:: Operator(*constraints) Bases: :py:obj:`Constraint`, :py:obj:`abc.ABC` Base class for all n-ary operators defined on constraints. .. attribute:: HELP_SEP :annotation: :str Used as separator of all constraints' help strings. .. method:: help(self, ctx) A description of the constraint. .. method:: check_consistency(self, params) Performs some sanity checks that detect inconsistencies between this constraints and the properties of the input parameters (e.g. required). For example, a constraint that requires the parameters to be mutually exclusive is not consistent with a group of parameters with multiple required options. These sanity checks are meant to catch developer's mistakes and don't depend on the values assigned to the parameters; therefore: - they can be performed before any parameter parsing - they can be disabled in production (see :meth:`toggle_consistency_checks`) :param params: list of :class:`click.Parameter` instances :raises: :exc:`~cloup.constraints.errors.UnsatisfiableConstraint` if the constraint cannot be satisfied independently from the values provided by the user .. method:: __repr__(self) Return repr(self). .. class:: Or(*constraints) Bases: :py:obj:`Operator` It's satisfied if at least one of the operands is satisfied. .. attribute:: HELP_SEP :annotation: = or .. method:: check_values(self, params, ctx) Checks that the constraint is satisfied by the input parameters in the given context, which (among other things) contains the values assigned to the parameters in ``ctx.params``. You probably don't want to call this method directly. Use :meth:`check` instead. :param params: list of :class:`click.Parameter` instances :param ctx: :class:`click.Context` :raises: :exc:`~cloup.constraints.ConstraintViolated` .. method:: __or__(self, other) .. class:: Rephraser(constraint, help = None, error = None) Bases: :py:obj:`Constraint` A Constraint decorator that can override the help and/or the error message of the wrapped constraint. This is useful also for defining new constraints. See also :class:`WrapperConstraint`. .. method:: help(self, ctx) A description of the constraint. .. method:: check_consistency(self, params) Performs some sanity checks that detect inconsistencies between this constraints and the properties of the input parameters (e.g. required). For example, a constraint that requires the parameters to be mutually exclusive is not consistent with a group of parameters with multiple required options. These sanity checks are meant to catch developer's mistakes and don't depend on the values assigned to the parameters; therefore: - they can be performed before any parameter parsing - they can be disabled in production (see :meth:`toggle_consistency_checks`) :param params: list of :class:`click.Parameter` instances :raises: :exc:`~cloup.constraints.errors.UnsatisfiableConstraint` if the constraint cannot be satisfied independently from the values provided by the user .. method:: check_values(self, params, ctx) Checks that the constraint is satisfied by the input parameters in the given context, which (among other things) contains the values assigned to the parameters in ``ctx.params``. You probably don't want to call this method directly. Use :meth:`check` instead. :param params: list of :class:`click.Parameter` instances :param ctx: :class:`click.Context` :raises: :exc:`~cloup.constraints.ConstraintViolated` .. method:: __repr__(self) Return repr(self). .. class:: RequireAtLeast(n) Bases: :py:obj:`Constraint` Satisfied if the number of set parameters is >= n. .. method:: help(self, ctx) A description of the constraint. .. method:: check_consistency(self, params) Performs some sanity checks that detect inconsistencies between this constraints and the properties of the input parameters (e.g. required). For example, a constraint that requires the parameters to be mutually exclusive is not consistent with a group of parameters with multiple required options. These sanity checks are meant to catch developer's mistakes and don't depend on the values assigned to the parameters; therefore: - they can be performed before any parameter parsing - they can be disabled in production (see :meth:`toggle_consistency_checks`) :param params: list of :class:`click.Parameter` instances :raises: :exc:`~cloup.constraints.errors.UnsatisfiableConstraint` if the constraint cannot be satisfied independently from the values provided by the user .. method:: check_values(self, params, ctx) Checks that the constraint is satisfied by the input parameters in the given context, which (among other things) contains the values assigned to the parameters in ``ctx.params``. You probably don't want to call this method directly. Use :meth:`check` instead. :param params: list of :class:`click.Parameter` instances :param ctx: :class:`click.Context` :raises: :exc:`~cloup.constraints.ConstraintViolated` .. method:: __repr__(self) Return repr(self). .. class:: RequireExactly(n) Bases: :py:obj:`WrapperConstraint` Requires an exact number of parameters to be set. .. method:: help(self, ctx) A description of the constraint. .. method:: check_values(self, params, ctx) Checks that the constraint is satisfied by the input parameters in the given context, which (among other things) contains the values assigned to the parameters in ``ctx.params``. You probably don't want to call this method directly. Use :meth:`check` instead. :param params: list of :class:`click.Parameter` instances :param ctx: :class:`click.Context` :raises: :exc:`~cloup.constraints.ConstraintViolated` .. class:: WrapperConstraint(constraint, **attrs) Bases: :py:obj:`Constraint` Abstract class that wraps another constraint and delegates all methods to it. Useful when you want to define a parametric constraint combining other existing constraints minimizing the boilerplate. This is an alternative to defining a function and using :class:`Rephraser`. Feel free to do that in your code, but cloup will stick to the convention that parametric constraints are defined as classes and written in camel-case. .. method:: help(self, ctx) A description of the constraint. .. method:: check_consistency(self, params) Performs some sanity checks that detect inconsistencies between this constraints and the properties of the input parameters (e.g. required). For example, a constraint that requires the parameters to be mutually exclusive is not consistent with a group of parameters with multiple required options. These sanity checks are meant to catch developer's mistakes and don't depend on the values assigned to the parameters; therefore: - they can be performed before any parameter parsing - they can be disabled in production (see :meth:`toggle_consistency_checks`) :param params: list of :class:`click.Parameter` instances :raises: :exc:`~cloup.constraints.errors.UnsatisfiableConstraint` if the constraint cannot be satisfied independently from the values provided by the user .. method:: check_values(self, params, ctx) Checks that the constraint is satisfied by the input parameters in the given context, which (among other things) contains the values assigned to the parameters in ``ctx.params``. You probably don't want to call this method directly. Use :meth:`check` instead. :param params: list of :class:`click.Parameter` instances :param ctx: :class:`click.Context` :raises: :exc:`~cloup.constraints.ConstraintViolated` .. method:: __repr__(self) Return repr(self). .. data:: accept_none Satisfied if none of the parameters is set. Useful only in conditional constraints. .. data:: all_or_none Satisfied if either all or none of the parameters are set. .. data:: mutually_exclusive Satisfied if at most one of the parameters is set. .. data:: require_all Satisfied if all parameters are set. .. class:: ConstraintMixin(*args, constraints = (), show_constraints = None, **kwargs) Provides support to constraints. .. method:: parse_args(self, ctx, args) .. method:: get_param_by_name(self, name) .. method:: get_params_by_name(self, names) .. method:: format_constraints(self, ctx, formatter) .. method:: format_help(self, ctx, formatter) .. function:: constraint(constr, params) Registers a constraint. .. class:: BoundConstraintSpec Bases: :py:obj:`NamedTuple` A NamedTuple storing a ``Constraint`` and the **names of the parameters** if has check. .. attribute:: constraint :annotation: :cloup.constraints._core.Constraint .. attribute:: params :annotation: :Sequence[str] .. class:: AllSet(*param_names) Bases: :py:obj:`Predicate` True if all listed parameters are set. .. versionadded:: 0.8.0 .. method:: negated_description(self, ctx) Succint description of the negation of this predicate (alias: `neg_desc`). .. method:: description(self, ctx) Succint description of the predicate (alias: `desc`). .. method:: __call__(self, ctx) Evaluate the predicate on the given context. .. method:: __and__(self, other) .. class:: AnySet(*param_names) Bases: :py:obj:`Predicate` True if any of the listed parameters is set. .. versionadded:: 0.8.0 .. method:: negated_description(self, ctx) Succint description of the negation of this predicate (alias: `neg_desc`). .. method:: description(self, ctx) Succint description of the predicate (alias: `desc`). .. method:: __call__(self, ctx) Evaluate the predicate on the given context. .. method:: __or__(self, other) .. class:: Equal(param_name, value) Bases: :py:obj:`Predicate` True if the parameter value equals ``value``. .. method:: description(self, ctx) Succint description of the predicate (alias: `desc`). .. method:: negated_description(self, ctx) Succint description of the negation of this predicate (alias: `neg_desc`). .. method:: __call__(self, ctx) Evaluate the predicate on the given context. .. class:: IsSet(param_name) Bases: :py:obj:`Predicate` True if the parameter is set. .. method:: description(self, ctx) Succint description of the predicate (alias: `desc`). .. method:: negated_description(self, ctx) Succint description of the negation of this predicate (alias: `neg_desc`). .. method:: __call__(self, ctx) Evaluate the predicate on the given context. .. method:: __and__(self, other) .. method:: __or__(self, other) .. class:: Not(predicate) Bases: :py:obj:`Predicate`, :py:obj:`Generic`\ [\ :py:obj:`P`\ ] Logical NOT of a predicate. .. method:: description(self, ctx) Succint description of the predicate (alias: `desc`). .. method:: negated_description(self, ctx) Succint description of the negation of this predicate (alias: `neg_desc`). .. method:: __call__(self, ctx) Evaluate the predicate on the given context. .. method:: __invert__(self) .. method:: __repr__(self) Return repr(self). .. exception:: ConstraintViolated(message, ctx = None) Bases: :py:obj:`click.UsageError` An internal exception that signals a usage error. This typically aborts any further handling. :param message: the error message to display. :param ctx: optionally the context that caused this error. Click will fill in the context automatically in some situations. .. method:: default(cls, params, desc, ctx = None) :classmethod: .. exception:: UnsatisfiableConstraint(constraint, params, reason) Bases: :py:obj:`Exception` Raised if a constraint cannot be satisfied by a group of parameters independently from their values at runtime; e.g. mutually_exclusive cannot be satisfied if multiple of the parameters are required.