:orphan:

:mod:`cloup.constraints._core`
==============================

.. py:module:: cloup.constraints._core





                              
Classes
-------

.. autosummary::

   ~cloup.constraints._core.Constraint
   ~cloup.constraints._core.Operator
   ~cloup.constraints._core.And
   ~cloup.constraints._core.Or
   ~cloup.constraints._core.ErrorFmt
   ~cloup.constraints._core.Rephraser
   ~cloup.constraints._core.WrapperConstraint
   ~cloup.constraints._core.RequireAtLeast
   ~cloup.constraints._core.AcceptAtMost
   ~cloup.constraints._core.RequireExactly
   ~cloup.constraints._core.AcceptBetween


Attributes
----------

.. autoapisummary::

   cloup.constraints._core.Op
   cloup.constraints._core.HelpRephraser
   cloup.constraints._core.ErrorRephraser
   cloup.constraints._core.require_all
   cloup.constraints._core.accept_none
   cloup.constraints._core.all_or_none
   cloup.constraints._core.mutually_exclusive
   cloup.constraints._core.require_any
   cloup.constraints._core.require_one

                                           
Contents
--------
.. py:data:: Op
   

   

.. py:data:: HelpRephraser
   

   

.. py:data:: ErrorRephraser
   

   

.. py: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``).

   .. versionchanged:: 0.9.0
       calling a constraint, previously equivalent to :meth:`~Constraint.check`,
       is now equivalent to calling :func:`cloup.constrained_params` with this
       constraint as first argument.

   .. py:method:: must_check_consistency(ctx)
      :staticmethod:

      Return ``True`` if consistency checks are enabled.

      .. versionchanged:: 0.9.0
          this method now a static method and takes a ``click.Context`` in input.


   .. py:method:: __getattr__(attr)


   .. py:method:: help(ctx)
      :abstractmethod:

      A description of the constraint. 


   .. py:method:: check_consistency(params)

      Perform some sanity checks that detect inconsistencies between these
      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 (setting
        ``check_constraints_consistency=False`` in ``context_settings``)

      :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


   .. py:method:: check_values(params, ctx)
      :abstractmethod:

      Check 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`


   .. py:method:: check(params: Sequence[click.Parameter], ctx: Optional[click.Context] = None) -> None
               check(params: Sequence[str], ctx: Optional[click.Context] = None) -> None

      Raise 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 ``check_constraints_consistency=False`` as part
          of your ``context_settings``.

      :param params: an iterable of parameter names or a sequence of
                     :class:`click.Parameter`
      :param ctx: a `click.Context`; if not provided, :func:`click.get_current_context`
                  is used
      :raises:
          :exc:`~cloup.constraints.ConstraintViolated`
          :exc:`~cloup.constraints.UnsatisfiableConstraint`


   .. py:method:: rephrased(help = None, error = None)

      Override the help string and/or the error message of this constraint
      wrapping it with a :class:`Rephraser`.

      :param help:
          if provided, overrides the help string of this constraint. It can be
          a string or a function ``(ctx: click.Context, constr: Constraint) -> str``.
          If you want to hide this constraint from the help, pass ``help=""``.
      :param error:
          if provided, overrides the error message of this constraint.
          It can be:

          - a string, eventually a ``format`` string supporting the replacement
            fields described in :class:`ErrorFmt`.

          - or a function ``(err: ConstraintViolated) -> str``; note that
            a :class:`ConstraintViolated` error has fields for ``ctx``,
            ``constraint`` and ``params``, so it's a complete description
            of what happened.


   .. py:method:: hidden()

      Hide this constraint from the command help.


   .. py:method:: __call__(*param_adders)

      Equivalent to calling :func:`cloup.constrained_params` with this
      constraint as first argument.

      .. versionchanged:: 0.9.0
          this method, previously equivalent to :meth:`~Constraint.check`, is
          now equivalent to calling :func:`cloup.constrained_params` with this
          constraint as first argument.


   .. py:method:: __or__(other)


   .. py:method:: __and__(other)


   .. py:method:: __repr__()

      Return repr(self).



.. py:class:: Operator(*constraints)

   Bases: :py:obj:`Constraint`, :py:obj:`abc.ABC`

   Base class for all n-ary operators defined on constraints. 

   N-ary operator for constraints.
   :param constraints: operands

   .. py:attribute:: HELP_SEP
      :annotation: :str

      Used as separator of all constraints' help strings.


   .. py:method:: help(ctx)

      A description of the constraint. 


   .. py:method:: check_consistency(params)

      Perform some sanity checks that detect inconsistencies between these
      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 (setting
        ``check_constraints_consistency=False`` in ``context_settings``)

      :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


   .. py:method:: __repr__()

      Return repr(self).



.. py:class:: And(*constraints)

   Bases: :py:obj:`Operator`

   It's satisfied if all operands are satisfied.

   N-ary operator for constraints.
   :param constraints: operands

   .. py:attribute:: HELP_SEP
      :annotation: =  and 

      

   .. py:method:: check_values(params, ctx)

      Check 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`


   .. py:method:: __and__(other)



.. py:class:: Or(*constraints)

   Bases: :py:obj:`Operator`

   It's satisfied if at least one of the operands is satisfied.

   N-ary operator for constraints.
   :param constraints: operands

   .. py:attribute:: HELP_SEP
      :annotation: =  or 

      

   .. py:method:: check_values(params, ctx)

      Check 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`


   .. py:method:: __or__(other)



.. py:class:: ErrorFmt

   Bases: :py:obj:`cloup._util.FrozenSpace`

   :class:`Rephraser` allows you to pass a ``format`` string as ``error``
   argument; this class contains the "replacement fields" supported by such
   format string. You can use them as following::

       mutually_exclusive.rephrased(
           error=f"{ErrorFmt.error}\n"
                 f"Some extra information here."
       )

   .. py:attribute:: error
      :annotation: = {error}

      Replaced by the original error message. Useful if all you want is to
      append or prepend some extra info to the original error message.


   .. py:attribute:: param_list
      :annotation: = {param_list}

      Replaced by a 2-space indented list of the constrained parameters.



.. py: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.

   You'll rarely (if ever) use this class directly. In most cases, you'll use
   the method :meth:`Constraint.rephrased`. Refer to it for more info.

   .. seealso::

       - :meth:`Constraint.rephrased` -- wraps a constraint with a ``Rephraser``.
       - :class:`WrapperConstraint` -- alternative to ``Rephraser``.
       - :class:`ErrorFmt` -- describes the keyword you can use in an error
         format string.

   .. py:method:: help(ctx)

      A description of the constraint. 


   .. py:method:: check_consistency(params)

      Perform some sanity checks that detect inconsistencies between these
      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 (setting
        ``check_constraints_consistency=False`` in ``context_settings``)

      :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


   .. py:method:: check_values(params, ctx)

      Check 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`


   .. py:method:: __repr__()

      Return repr(self).



.. py: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.

   :param constraint: the constraint to wrap
   :param attrs: these are just used to generate a ``__repr__`` method

   .. py:method:: help(ctx)

      A description of the constraint. 


   .. py:method:: check_consistency(params)

      Perform some sanity checks that detect inconsistencies between these
      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 (setting
        ``check_constraints_consistency=False`` in ``context_settings``)

      :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


   .. py:method:: check_values(params, ctx)

      Check 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`


   .. py:method:: __repr__()

      Return repr(self).



.. py:class:: RequireAtLeast(n)

   Bases: :py:obj:`Constraint`

   Satisfied if the number of set parameters is >= n.

   .. py:method:: help(ctx)

      A description of the constraint. 


   .. py:method:: check_consistency(params)

      Perform some sanity checks that detect inconsistencies between these
      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 (setting
        ``check_constraints_consistency=False`` in ``context_settings``)

      :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


   .. py:method:: check_values(params, ctx)

      Check 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`


   .. py:method:: __repr__()

      Return repr(self).



.. py:class:: AcceptAtMost(n)

   Bases: :py:obj:`Constraint`

   Satisfied if the number of set parameters is <= n.

   .. py:method:: help(ctx)

      A description of the constraint. 


   .. py:method:: check_consistency(params)

      Perform some sanity checks that detect inconsistencies between these
      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 (setting
        ``check_constraints_consistency=False`` in ``context_settings``)

      :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


   .. py:method:: check_values(params, ctx)

      Check 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`


   .. py:method:: __repr__()

      Return repr(self).



.. py:class:: RequireExactly(n)

   Bases: :py:obj:`WrapperConstraint`

   Requires an exact number of parameters to be set.

   :param constraint: the constraint to wrap
   :param attrs: these are just used to generate a ``__repr__`` method

   .. py:method:: help(ctx)

      A description of the constraint. 


   .. py:method:: check_values(params, ctx)

      Check 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`


   .. py:method:: __repr__()

      Return repr(self).



.. py: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.

   Satisfied if the number of set parameters is between
   ``min`` and ``max`` (included).

   :param min: must be an integer >= 0
   :param max: must be an integer > min

   .. py:method:: help(ctx)

      A description of the constraint. 



.. py:data:: require_all
   

   Satisfied if all parameters are set.


.. py:data:: accept_none
   

   Satisfied if none of the parameters is set. Useful only in conditional constraints.


.. py:data:: all_or_none
   

   Satisfied if either all or none of the parameters are set.


.. py:data:: mutually_exclusive
   

   Satisfied if at most one of the parameters is set.


.. py:data:: require_any
   

   Alias for ``RequireAtLeast(1)``.


.. py:data:: require_one
   

   Alias for ``RequireExactly(1)``.



                                         