# Generated by SnakeBridge v0.12.0 - DO NOT EDIT MANUALLY
# Regenerate with: mix compile
# Library: dspy 3.1.2
# Python module: dspy.utils.annotation

defmodule Dspy.Utils.Annotation do
  @moduledoc """
  Submodule bindings for `dspy.utils.annotation`.
  """

  def __snakebridge_python_name__, do: "dspy.utils.annotation"
  def __snakebridge_library__, do: "dspy"

  @doc """
  Decorator / decorator creator for marking APIs experimental in the docstring.



  ## Parameters

  - `f` - The function to be decorated.
  - `version` - The version in which the API was introduced as experimental. The version is used to determine whether the API should be considered as stable or not when releasing a new version of DSPy.

  Parameters:
  - `f` (term() | nil default: None)
  - `version` (term() default: None)

  Returns:
  - `term()`
  """
  @spec experimental() :: {:ok, term()} | {:error, Snakepit.Error.t()}
  @spec experimental(keyword()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  @spec experimental(term() | nil) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  @spec experimental(term() | nil, keyword()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  @spec experimental(term() | nil, term()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  @spec experimental(term() | nil, term(), keyword()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  def experimental() do
    SnakeBridge.Runtime.call(__MODULE__, :experimental, [], [])
  end

  def experimental(opts)
      when is_list(opts) and
             (opts == [] or
                (is_tuple(hd(opts)) and tuple_size(hd(opts)) == 2 and is_atom(elem(hd(opts), 0)))) do
    SnakeBridge.Runtime.call(__MODULE__, :experimental, [], opts)
  end

  def experimental(f) do
    SnakeBridge.Runtime.call(__MODULE__, :experimental, [f], [])
  end

  def experimental(f, opts)
      when is_list(opts) and
             (opts == [] or
                (is_tuple(hd(opts)) and tuple_size(hd(opts)) == 2 and is_atom(elem(hd(opts), 0)))) do
    SnakeBridge.Runtime.call(__MODULE__, :experimental, [f], opts)
  end

  def experimental(f, version) do
    SnakeBridge.Runtime.call(__MODULE__, :experimental, [f, version], [])
  end

  def experimental(f, version, opts)
      when is_list(opts) and
             (opts == [] or
                (is_tuple(hd(opts)) and tuple_size(hd(opts)) == 2 and is_atom(elem(hd(opts), 0)))) do
    SnakeBridge.Runtime.call(__MODULE__, :experimental, [f, version], opts)
  end

  @doc """
  Parameter specification variable.

  The preferred way to construct a parameter specification is via the
  dedicated syntax for generic functions, classes, and type aliases,
  where the use of '**' creates a parameter specification::

    type IntFunc[**P] = Callable[P, int]

  For compatibility with Python 3.11 and earlier, ParamSpec objects
  can also be created as follows::

    P = ParamSpec('P')

  Parameter specification variables exist primarily for the benefit of
  static type checkers.  They are used to forward the parameter types of
  one callable to another callable, a pattern commonly found in
  higher-order functions and decorators.  They are only valid when used
  in ``Concatenate``, or as the first argument to ``Callable``, or as
  parameters for user-defined Generics. See class Generic for more
  information on generic types.

  An example for annotating a decorator::

    def add_logging[**P, T](f: Callable[P, T]) -> Callable[P, T]:
        '''A type-safe decorator to add logging to a function.'''
        def inner(*args: P.args, **kwargs: P.kwargs) -> T:
            logging.info(f'{f.__name__} was called')
            return f(*args, **kwargs)
        return inner

    @add_logging
    def add_two(x: float, y: float) -> float:
        '''Add two numbers together.'''
        return x + y

  Parameter specification variables can be introspected. e.g.::

    >>> P = ParamSpec("P")
    >>> P.__name__
    'P'

  Note that only parameter specification variables defined in the global
  scope can be pickled.

  Returns:
  - `term()`
  """
  @spec p() :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def p() do
    SnakeBridge.Runtime.get_module_attr(__MODULE__, "P")
  end

  @doc """
  Type variable.

  The preferred way to construct a type variable is via the dedicated
  syntax for generic functions, classes, and type aliases::

    class Sequence[T]:  # T is a TypeVar
        ...

  This syntax can also be used to create bound and constrained type
  variables::

    # S is a TypeVar bound to str
    class StrSequence[S: str]:
        ...

    # A is a TypeVar constrained to str or bytes
    class StrOrBytesSequence[A: (str, bytes)]:
        ...

  However, if desired, reusable type variables can also be constructed
  manually, like so::

   T = TypeVar('T')  # Can be anything
   S = TypeVar('S', bound=str)  # Can be any subtype of str
   A = TypeVar('A', str, bytes)  # Must be exactly str or bytes

  Type variables exist primarily for the benefit of static type
  checkers.  They serve as the parameters for generic types as well
  as for generic function and type alias definitions.

  The variance of type variables is inferred by type checkers when they
  are created through the type parameter syntax and when
  ``infer_variance=True`` is passed. Manually created type variables may
  be explicitly marked covariant or contravariant by passing
  ``covariant=True`` or ``contravariant=True``. By default, manually
  created type variables are invariant. See PEP 484 and PEP 695 for more
  details.

  Returns:
  - `term()`
  """
  @spec r() :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def r() do
    SnakeBridge.Runtime.get_module_attr(__MODULE__, "R")
  end
end