.. currentmodule:: cloup.constraints .. highlight:: none Constraints =========== Overview -------- A :class:`Constraint` is essentially a validator for groups of parameters. When unsatisfied, a constraint raises a :exc:`click.UsageError` with an appropriate error message, which is handled and displayed by Click. Each constraint also has an associated description (:meth:`Constraint.help`) that can optionally be shown in the ``--help`` of a command. You can easily override both the help description and the error message if you want (see `Rephrasing constraints`_). Constraints can be combined with logical operators (see `Defining new constraints`_) and can also be applied conditionally (see `Conditional constraints`_). Implemented constraints ----------------------- Parametric constraints ~~~~~~~~~~~~~~~~~~~~~~ Parametric constraints are *subclasses* of ``Constraint`` and so they are camel-cased; .. autosummary:: RequireExactly RequireAtLeast AcceptAtMost AcceptBetween Non-parametric constraints ~~~~~~~~~~~~~~~~~~~~~~~~~~ Non-parametric constraints are *instances* of ``Constraint`` and so they are snake-cased (``like_this``). Most of these are instances of parametric constraints or (rephrased) combinations of them. =========================== ============================================================ :data:`accept_none` Requires all parameters to be unset. --------------------------- ------------------------------------------------------------ :data:`all_or_none` Satisfied if either all or none of the parameters are set. --------------------------- ------------------------------------------------------------ :data:`mutually_exclusive` A rephrased version of ``AcceptAtMost(1)``. --------------------------- ------------------------------------------------------------ :data:`require_all` Requires all parameters to be set. --------------------------- ------------------------------------------------------------ :data:`require_any` Alias for ``RequireAtLeast(1)``. --------------------------- ------------------------------------------------------------ :data:`require_one` Alias for ``RequireExactly(1)``. =========================== ============================================================ When is a parameter considered "set"? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Basically, Cloup considers a parameter to be "set" when its value differs from the one assigned by Click when the parameter is not provided neither by the CLI user nor by the developer. .. list-table:: :header-rows: 1 :widths: 10 7 10 10 :align: center * - Param type - Click default - It's set if - Note * - string - ``None`` - ``value is not None`` - even if empty * - number - ``None`` - ``value is not None`` - even if zero * - boolean non-flag - ``None`` - ``value is not None`` - even if ``False`` * - boolean flag - ``False`` - ``value is True`` - * - tuple - ``()`` - ``len(value) > 0`` - In the future, this policy may become configurable at the context and parameter level. Conditional constraints ~~~~~~~~~~~~~~~~~~~~~~~ :class:`If` allows you to define conditional constraints:: If(condition, then, [else_]) - **condition** -- can be: - a concrete instance of :class:`~conditions.Predicate` - a parameter name; this is a shortcut for ``IsSet(param_name)`` - a list/tuple of parameter names; this is a shortcut for ``AllSet(*param_names)``. - **then** -- the constraint checked when the condition is true. - **else_** -- an optional constraint checked when the condition is false. Available predicates can be imported from ``cloup.constraints`` and are: .. autosummary:: IsSet AllSet AnySet Equal For example: .. code-block:: python from cloup.constraints import ( If, RequireAtLeast, require_all, accept_none, IsSet, Equal ) # If parameter with name "param" is set, # then require all parameters, else forbid them all If('param', then=require_all, else_=accept_none) # Equivalent to: If(IsSet('param'), then=require_all, else_=accept_none) # If "arg" and "opt" are both set, then require exactly 1 param If(['arg', 'opt'], then=RequireExactly(1)) # Another example... of course the else branch is optional If(Equal('param', 'value'), then=RequireAtLeast(1)) Predicates have an associated ``description`` and can be composed with the logical operators ``&`` (and), ``|`` (or) and ``~`` (not). For example: .. code-block:: python predicate = ~IsSet('foo') & Equal('bar', 'value') # --foo is not set and --bar="value" Applying constraints -------------------- Constraints are well-integrated with option groups but decoupled from them: you can apply them to any group of parameters, eventually including positional arguments. There are three ways to apply a constraint: 1. setting the parameter ``constraint`` of ``@option_group`` (or ``OptionGroup``) 2. using the ``@constraint`` decorator and specifying parameters by name 3. using the constraint as a decorator that takes parameter decorators as arguments (similarly to ``@option_groups``, but supporting ``argument`` too); this is just convenient *syntax sugar* on top of ``@constraint`` that can be used in some circumstances. As you'll see, Cloup handles slightly differently the constraints applied to option groups, but only in relation to the ``--help`` output. Usage with @option_group ~~~~~~~~~~~~~~~~~~~~~~~~ As you have probably seen in the :doc:`option-groups` chapter, you can easily apply a constraint to an option group by setting the ``constraint`` argument of ``@option_group`` (or ``OptionGroup``): .. code-block:: python :emphasize-lines: 6 @option_group( 'Option group title', option('-o', '--one', help='an option'), option('-t', '--two', help='a second option'), option('--three', help='a third option'), constraint=RequireAtLeast(1), ) This code produces the following help section with the constraint description between square brackets on the right of the option group title:: Option group title: [at least 1 required] -o, --one TEXT an option -t, --two TEXT a second option --three TEXT a third option If the constraint description doesn't fit into the section heading line, it is printed on the next line:: Option group title: [this is a long description that doesn't fit into the title line] -o, --one TEXT an option -t, --two TEXT a second option --three TEXT a third option If the constraint is violated, the following error is shown:: Error: at least 1 of the following parameters must be set: --one (-o) --two (-t) --three You can customize both the help description and the error message of a constraint using the method :meth:`Constraint.rephrased` (see `Rephrasing constraints`_). If you simply want to hide the constraint description in the help, you can use the method :meth:`Constraint.hidden`: .. code-block:: python @option_group( ... constraint=RequireAtLeast(1).hidden(), ) The ``@constraint`` decorator ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Using the :func:`cloup.constraint` decorator, you can apply a constraint to any group of parameters (arguments and options) providing their **destination names**, i.e. the names of the function arguments they are mapped to (by Click). For example: =============================================== =================== Declaration Name =============================================== =================== ``@option('-o')`` ``o`` ``@option('-o', '--out-path')`` ``out_path`` ``@option('-o', '--out-path', 'output_path')`` ``output_path`` =============================================== =================== Here's a meaningless example just to show how to use the API: .. code-block:: python from cloup import argument, command, constraint, option from cloup.constraints import If, RequireExactly, mutually_exclusive @command('cmd', show_constraints=True) @argument('arg', required=False) @option('--one') @option('--two') @option('--three') @option('--four') @constraint( mutually_exclusive, ['arg', 'one', 'two'] ) @constraint( If('one', then=RequireExactly(1)), ['three', 'four'] ) def cmd(arg, one, two, three, four): print('ciao') .. _show-constraints: If you set the ``command`` parameter ``show_constraints`` to ``True``, the following section is shown at the bottom of the command help:: Constraints: {ARG, --one, --two} mutually exclusive {--three, --four} exactly 1 required if --one is set Even in this case, you can still hide a specific constraint by using the method :meth:`~Constraint.hidden`. Note that ``show_constraint`` can also be set in the ``context_settings`` of your root command. Of course, the context setting can be overridden by each individual command. .. _constraints-as-decorators: Constraints as decorators ~~~~~~~~~~~~~~~~~~~~~~~~~ ``@constraint`` is powerful but has some drawbacks: - it requires to replicate (once again) the name of the constrained parameters; - it doesn't visually group the involved parameters with nesting (as ``@option_group`` does with options). As an answer to these issues, Cloup introduced the possibility to use constraints themselves as decorators, with an usage similar to that of ``@option_group``. However, note that there are cases when ``@constraint`` is your only option. This feature is just a layer of syntax sugar on top of ``@constraint``. The following: .. code-block:: python @mutually_exclusive( option('--one'), option('--two'), option('--three'), ) is equivalent to: .. code-block:: python @option('--one') @option('--two') @option('--three') @constraint(mutually_exclusive, ['one', 'two', 'three']) .. admonition:: Syntax limitation in Python < 3.9 :name: attention-python-decorators :class: attention In Python < 3.9, the expression on the right of the operator ``@`` is required to be a "dotted name, optionally followed by a single call" (see `PEP 614 `_). This means that you can't instantiate a parametric constraint on the right of ``@``, because the resultant expressions would make two calls, e.g.: .. code-block:: python # This is a syntax error in Python < 3.9 @RequireExactly(2)( # 1st call to instantiate the constraint ... # 2nd call to apply the constraint ) To work around this syntax limitation you can assign your constraint to a variable before using it as a decorator: .. code-block:: python require_two = RequireExactly(2) # somewhere in the code @require_two( option('--one'), option('--two'), option('--three'), ) or, in alternative, you can use the ``@constrained_params`` decorator described below. The ``@constrained_params`` decorator may turn useful to work around the just described syntax limitation in Python < 3.9 or simply when your constraint is long/complex enough that it'd be weird to use it as a decorator: .. code-block:: python @constrained_params( RequireAtLeast(1), option('--one'), option('--two'), option('--three'), ) .. _constraint-inside-option-group: You can use constraints as decorators even inside ``@option_group`` to constrain one or multiple subgroups: .. code-block:: python :emphasize-lines: 3-6 @option_group( "Number options", RequireAtLeast(1)( option('--one'), option('--two') ), option('--three') ) # equivalent to: @option_group( "Number options", option('--one'), option('--two') option('--three') ) @constraint(RequireAtLeast(1), ['one', 'two']) Note that the syntax limitation affecting Python < 3.9 described in the :ref:`attention box ` above does not apply in this case since we are not using ``@`` here. .. _rephrasing-constraints: Rephrasing constraints ---------------------- You can override the help description and/or the error message of a constraint using the :meth:`~Constraint.rephrased` method. It takes two arguments: - **help** -- if provided, overrides the help description. It can be: - a string - a function ``(ctx: Context, constr: Constraint) -> str`` If you want to hide this constraint from the help, pass ``help=""`` or use the method :meth:`~Constraint.hidden`. - **error** -- if provided, overrides the error message. It can be: - a string, eventually a ``format`` string whose fields are stored and documented as attributes in :class:`ErrorFmt`. - a function ``(err: ConstraintViolated) -> str`` where :exc:`ConstraintViolated` is an exception object that fully describes the violation of a constraint, including fields like ``ctx``, ``constraint`` and ``params``. An example from Cloup ~~~~~~~~~~~~~~~~~~~~~ Cloup itself makes use of rephrasing a lot for defining non-parametric constraints, for example: .. code-block:: python mutually_exclusive = AcceptAtMost(1).rephrased( help='mutually exclusive', error=f'the following parameters are mutually exclusive:\n' f'{ErrorFmt.param_list}' ) Example: adding extra info to the original error ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sometimes you just want to add extra info before or after the original error message. In that case, you can either pass a function or using ``ErrorFmt.error``: .. code-block:: python # Using function (err: ConstraintViolated) -> str mutually_exclusive.rephrased( error=lambda err: f'{err}\n' f'Use --renderer, the other options are deprecated. ) # Using ErrorFmt.error from cloup.constraint import ErrorFmt mutually_exclusive.rephrased( error=f'{ErrorFmt.error}\n' f'Use --renderer, the other options are deprecated. ) Defining new constraints ------------------------ The available constraints should cover 99% of use cases but if you need it, it's very easy to define new ones. Here are your options: - you can use the **logical operators** ``&`` and ``|`` to combine existing constraints and then eventually: - use the ``rephrased`` method described in the previous section - or subclass :class:`~WrapperConstraint` if you want to define a new parametric ``Constraint`` class wrapping the result - just subclass ``Constraint``; look at existing implementations for guidance. Example 1: logical operator + rephrasing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is how Cloup defines ``all_or_none`` (this example may be out-of-date): .. code-block:: python all_or_none = (require_all | accept_none).rephrased( help='provide all or none', error=f'the following parameters must be provided all together ' f'(or none should be provided):\n' f'{ErrorFmt.param_list}', ) Example 2: defining a new parametric constraint ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *Option 1 -- Just use a function.* .. code-block:: python def accept_between(min, max): return (RequireAtLeast(min) & AcceptAtMost(max)).rephrased( help=f'at least {min} required, at most {max} accepted' ) >>> accept_between(1, 3) Rephraser(help='at least 1 required, at most 3 accepted') *Option 2 -- WrapperConstraint.* This is useful when you want to define a new constraint type. ``WrapperConstraint`` delegates all methods to the wrapped constraint so you can override only the methods you need to override. .. code-block:: python class AcceptBetween(WrapperConstraint): def __init__(self, min: int, max: int): # [...] self._min = min self._max = max # whatever you pass as **kwargs is used in the __repr__ super().__init__( RequireAtLeast(min) & AcceptAtMost(max), min=min, max=max, # <= included in the __repr__ ) def help(self, ctx: Context) -> str: return f'at least {self._min} required, ' \ f'at most {self._max} accepted' >>> AcceptBetween(1, 3) AcceptBetween(1, 3) \*Validation protocol --------------------- A constraint performs two types of checks and there's a method for each type: - :meth:`~Constraint.check_consistency` – performs sanity checks meant to detect mistakes of the developer; as such, they are performed *before* argument parsing (when possible); for example, if you try to apply a ``mutually_exclusive`` constraint to an option group containing multiple required options, this method will raise ``UnsatisfiableConstraint`` - :meth:`~Constraint.check_values` – performs user input validation and, when unsatisfied, raises a ``ConstraintViolated`` error with an appropriate message; ``ConstrainedViolated`` is a subclass of ``click.UsageError`` and, as such, is handled by Click itself by showing the command usage and the error message. Using a constraint as a function is equivalent to call the method :meth:`~Constraint.check`, which performs (by default) both kind of checks, unless consistency checks are disabled (see below). When you add constraints through ``@option_group``, ``OptionGroup`` and ``@constraint``, this is what happens: - constraints are checked for consistency *before* parsing - input is parsed and processed; all values are stored by Click in the ``Context`` object, precisely in ``ctx.params`` - constraints validate the parameter values. In all cases, constraints applied to option groups are checked before those added through ``@constraint``. If you use a constraint inside a callback, of course, consistency checks can't be performed before parsing. All checks are performed together after parsing. Disabling consistency checks ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can safely skip this section since disabling consistency checks is a micro-optimization likely to be completely irrelevant in practice. Current consistency checks should not have any relevant impact on performance, so they are enabled by default. Nonetheless, they are completely useless in production, so I added the possibility to turn them off (globally) passing ``check_constraints_consistency=False`` as part of your ``context_settings``. Just because I could. To disable them only in production, you should set an environment variable in your development machine, say ``PYTHON_ENV="dev"``; then you can put the following code at the entry-point of your program: .. code-block:: python import os from cloup import Context SETTINGS = Context.setting( check_constraints_consistency=(os.getenv('PYTHON_ENV') == 'dev') # ... other settings ... ) @group(context_settings=SETTINGS) # ... def main(...): ... Have I already mentioned that this is probably not worth the effort? \*Feature support ----------------- .. note:: If you use command classes/decorators redefined by Cloup, you can skip this section. To support constraints, a ``Command`` must inherit from :class:`ConstraintMixin`. It's worth noting that ``ConstraintMixin`` integrates with ``OptionGroupMixin`` but it **doesn't** require it to work. To use the ``@constraint`` decorator, you must currently use ``@cloup.command`` as command decorator. Using ``@click.command(..., cls=cloup.Command)`` won't work. This may change in the future though.