arganic.arguments

Argument

Argument class.

Represents an argument with properties such as name, default value, and validation rules. Provides a method for validation.

Attributes:

• name (str) –

  The name of the argument.

• default ((Any, optional)) –

  The default value of the argument.

• read_only (bool, default=True) –

  Whether the argument is read-only.

• required (bool, default=True) –

  Whether the argument is required.

• type ((Type | tuple[Type], optional)) –

  The data type(s) of the argument value.

• validator ((Validator | tuple[Validator], optional)) –

  A Validator object or list of Validator objects used to validate the argument value.

• choices ((tuple, optional)) –

  A tuple of choices the argument value can take.

Methods:

• validate –

  Validate the argument value based on the specified rules.

Examples:

Example of a full-featured argument construction:

from arganic.arguments import Argument, class_properties, ArgumentHandler  # Import Argument class.
from arganic.validators import MinLength, MaxLength  # Import validators


# Argument example
@class_properties(
    arg1=Argument(
        type=(str, list, tuple),  # Multiple types are supported.
        required=False,  # This argument is not required.
        default='first',  # A default value.
        read_only=False,  # This Argument/property is not writeable.
        choices=('first', 'second', ['first', 'second'], ('first', 'second')),  # Available choices.
        validator=(MinLength(1), MaxLength(10))  # Validators.
    )
)
class FullFeaturedArgument(ArgumentHandler):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

    def get_arg1(self) -> str | list | tuple:
        return self.get('arg1')


# 'first' value is allowed in choices options
ffa1 = FullFeaturedArgument(arg1='first')
print(ffa1.get_arg1())

# arg1 is not required and will take de the default value 'first'
ffa2 = FullFeaturedArgument()
print(ffa2.get_arg1())

# arg1 can be a tuple
ffa3 = FullFeaturedArgument(arg1=('first', 'second'))
print(ffa3.get_arg1())

# arg1 can be a list
ffa4 = FullFeaturedArgument(arg1=['first', 'second'])
print(ffa4.get_arg1())

# arg1 can be set
ffa4 = FullFeaturedArgument(arg1=['first', 'second'])
print(ffa4.get_arg1())
ffa4.set('arg1', 'second')
print(ffa4.get_arg1())

---

choices property

choices: tuple

Optional

A list of choices limiting the values that the supplied arguments can have.

---

default property

default: Any

Optional

The default value the argument will take if no value is provided.

---

name property

name: str

The argument name.

---

read_only property

read_only: bool

Default=True

The argument is read-only, so it can no longer be modified.

---

required property

required: bool

Default=True

The argument is required if the value is missing: an Exception will occur.

---

type property

type: Type | tuple[Type]

Optional

Defines the type(s) of values accepted for this argument, if the type provided is not valid an Exception will occur.

---

validator property

validator: Validator | tuple[Validator]

Optional

One or more instances of Validators constraining the value that an argument can have.

---

validate

validate(value: Any) -> bool

Validate the argument value based on the specified rules.

Parameters:

• value (Any) –

  The value to validate.

Returns:

• bool –

  True if the value is valid, False otherwise.

Raises:

• TypeError –

  If the value is not of the specified type.

• ValueError –

  If the value is required but not provided, or if it is not among the specified choices.

ArgumentHandler

Handles arguments or properties for decorated classes, methods or functions.

Attributes

---

values: dict The provided arguments values validated and correctly formatted.

Methods:

• get –

  Retrieves the value of a specified argument or property.

• set –

  Sets the value of a specified argument or property.

values property

values: dict

The validated values.

---

get

get(key: str) -> Any

Retrieves the value of a specified argument or property.

Parameters:

• key (str) –

  The key of the argument or property to retrieve.

Returns:

• Any –

  The value of the argument or property.

set

set(key: str, value: Any) -> None

Sets the value of arguments or properties to the specified key.

Parameters:

• key (str) –

  The key of the argument to set.

• value (Any) –

  The new value for the argument.

Raises:

• ValueError –

  if the argument is not writeable.

class_properties

class_properties(**_properties: Argument) -> Callable

Decorator for class properties.

A decorator for class properties allowing you to define the data managed by the class during construction and then access these values within the class.

Parameters:

• _properties (Argument, default: {} ) –

  A dictionary of the Arguments the decorator will handle.

Returns:

• Callable –

  The decorator function.

function_arguments

function_arguments(**_arguments: Argument) -> Callable

Decorator for function arguments.

A decorator for functions allowing you to constrain the arguments provided during the call but also to find the correctly formatted values within the function.

Parameters:

• _arguments (Argument, default: {} ) –

  A dictionary of the Arguments the decorator will handle.

Returns:

• Callable –

  The decorator function.

method_arguments

method_arguments(**_arguments: Argument) -> Callable

Decorator for method arguments.

A decorator for class methods allowing you to constrain the arguments provided during the call but also to find the correctly formatted values within the method.

Parameters:

• _arguments (Argument, default: {} ) –

  A dictionary of the Arguments the decorator will handle.

Returns:

• Callable –

  The decorator function.