Skip to content

define.param.groups

group(cls=None, *, exclude=None, **kwargs)

Construct a Parameter group.

Parameters:

Name Type Description Default
cls T

The class to make into a parameter group

 None
exclude t.Sequence[str] | None

List of type to exclude from the parameter list. Useful if you assign values to the class instance at runtime, but still want to annotate them in your type hints

 None

Returns:

Name Type Description
type T | t.Callable[[T], T]

The modified class

Example: 

import arc

@arc.group
class MyGroup():
    name: str

@arc.command
def command(group: MyGroup):
    print(group.name)

command("Sean")

Source code in /home/runner/work/arc/arc/arc/define/param/groups.py 
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
def group(
    cls: T = None, *, exclude: t.Sequence[str] | None = None, **kwargs: t.Any
) -> T | t.Callable[[T], T]:
    """Construct a Parameter group.

    Args:
        cls (T, optional): The class to make into a parameter group
        exclude (t.Sequence[str] | None, optional): List of type to exclude
            from the parameter list. Useful if you assign values to the class
            instance at runtime, but still want to annotate them in your type
            hints


    Returns:
        type: The modified class

    Example:
    ```py
    import arc

    @arc.group
    class MyGroup():
        name: str

    @arc.command
    def command(group: MyGroup):
        print(group.name)

    command("Sean")
    ```
    """

    if cls:
        return modify_group_cls(cls, t.cast(dict[str, t.Any], _default_group_options))

    def inner(cls: T) -> T:
        return modify_group_cls(cls, {"exclude": exclude or [], **kwargs})

    return inner

groupoptions(cls)

Returns a dictionary representing the options passed in when a parameter group was created. Should be used in conjuction with isgroup().

Parameters:

Name Type Description Default
cls type

Parameter Group Class

 required

Raises:

Type Description
TypeError

If the passed in type is not a parameter group

Returns:

Name Type Description
ParamGroupOptions at.ParamGroupOptions

The options dictionary
Source code in /home/runner/work/arc/arc/arc/define/param/groups.py 
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
def groupoptions(cls: type) -> at.ParamGroupOptions:
    """Returns a dictionary representing the options passed
    in when a parameter group was created. Should be used
    in conjuction with [`isgroup()`][arc.define.param.groups.isgroup].

    Args:
        cls (type): Parameter Group Class

    Raises:
        TypeError: If the passed in type is not a parameter group

    Returns:
        ParamGroupOptions: The options dictionary
    """
    if not isgroup(cls):
        raise TypeError(f"{cls} is not a parameter group")

    return getattr(cls, "__arc_group__")

isgroup(cls)

Returns a boolean whether or not a given type is an arc parameter group

Source code in /home/runner/work/arc/arc/arc/define/param/groups.py 
110
111
112
113
def isgroup(cls: type) -> bool:
    """Returns a boolean whether or not
    a given type is an arc parameter group"""
    return hasattr(cls, "__arc_group__")