Command State

arc.State is arc's primary way for sharing global data all throughout your application.

State is a dictionary of key-value pairs that you pass when executing you application. A command can then request access to the state object by annotating a argument with State

examples/state.py

import arc


@arc.command()
def command(state: arc.State):
    # arc.State is a dict-like object, so it can be accessed
    # like a dictionary, or it can be accessed via attributes
    arc.print(state.value)
    arc.print(state["value"])


command(state={"value": 1})

$ python state.py 
1
1

Note that because the State type has a special meaning it will not be exposed to the external interface

$ python state.py --help
USAGE
    state.py [-h]

OPTIONS
    --help (-h)  Displays this help message

Subclassing State

State may also be sub-classed, and still maintain the same unique behavior. This is useful for providing additional functionality via attached methods, or provide type hinting support for static analyzers like mypy.

examples/state_inherit.py

import arc


class MyState(arc.State):
    name: str

    def punch(self):
        arc.print(f"ORA ORA, {self.name}")


@arc.command()
def punch(state: MyState):
    state.punch()


punch(state={"name": "DIO"})

$ python state_inherit.py 
ORA ORA, DIO