Skip to content

prefect.variables

Variable

Bases: BaseModel

Variables are named, mutable JSON values that can be shared across tasks and flows.

Parameters:

Name Type Description Default
name

A string identifying the variable.

 required
value

A string that is the value of the variable.

 required
tags

An optional list of strings to associate with the variable.

 required
Source code in src/prefect/variables.py 
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 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
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
class Variable(BaseModel):
    """
    Variables are named, mutable JSON values that can be shared across tasks and flows.

    Arguments:
        name: A string identifying the variable.
        value: A string that is the value of the variable.
        tags: An optional list of strings to associate with the variable.
    """

    name: str = Field(
        default=...,
        description="The name of the variable",
        examples=["my_variable"],
        max_length=MAX_VARIABLE_NAME_LENGTH,
    )
    value: StrictVariableValue = Field(
        default=...,
        description="The value of the variable",
        examples=["my-value"],
    )
    tags: Optional[List[str]] = Field(default=None)

    @classmethod
    @sync_compatible
    async def set(
        cls,
        name: str,
        value: StrictVariableValue,
        tags: Optional[List[str]] = None,
        overwrite: bool = False,
    ) -> "Variable":
        """
        Sets a new variable. If one exists with the same name, must pass `overwrite=True`

        Returns the newly set variable object.

        Args:
            - name: The name of the variable to set.
            - value: The value of the variable to set.
            - tags: An optional list of strings to associate with the variable.
            - overwrite: Whether to overwrite the variable if it already exists.

        Example:
            Set a new variable and overwrite it if it already exists.

            ```
            from prefect.variables import Variable

            @flow
            def my_flow():
                Variable.set(name="my_var",value="test_value", tags=["hi", "there"], overwrite=True)
            ```
        """
        client, _ = get_or_create_client()
        variable_exists = await client.read_variable_by_name(name)
        var_dict = {"name": name, "value": value, "tags": tags or []}

        if variable_exists:
            if not overwrite:
                raise ValueError(
                    f"Variable {name!r} already exists. Use `overwrite=True` to update it."
                )
            await client.update_variable(variable=VariableUpdate(**var_dict))
            variable = await client.read_variable_by_name(name)
            var_dict = {
                "name": variable.name,
                "value": variable.value,
                "tags": variable.tags or [],
            }
        else:
            await client.create_variable(variable=VariableCreate(**var_dict))

        return cls(**var_dict)

    @classmethod
    @sync_compatible
    async def get(
        cls,
        name: str,
        default: StrictVariableValue = None,
    ) -> StrictVariableValue:
        """
        Get a variable's value by name.

        If the variable does not exist, return the default value.

        Args:
            - name: The name of the variable value to get.
            - default: The default value to return if the variable does not exist.

        Example:
            Get a variable's value by name.
            ```python
            from prefect import flow
            from prefect.variables import Variable

            @flow
            def my_flow():
                var = Variable.get("my_var")
            ```
        """
        client, _ = get_or_create_client()
        variable = await client.read_variable_by_name(name)

        return variable.value if variable else default

    @classmethod
    @sync_compatible
    async def unset(cls, name: str) -> bool:
        """
        Unset a variable by name.

        Args:
            - name: The name of the variable to unset.

        Returns `True` if the variable was deleted, `False` if the variable did not exist.

        Example:
            Unset a variable by name.
            ```python
            from prefect import flow
            from prefect.variables import Variable

            @flow
            def my_flow():
                Variable.unset("my_var")
            ```
        """
        client, _ = get_or_create_client()
        try:
            await client.delete_variable_by_name(name=name)
            return True
        except ObjectNotFound:
            return False

get(name, default=None) async classmethod

Get a variable's value by name.

If the variable does not exist, return the default value.

Parameters:

Name Type Description Default
- name

The name of the variable value to get.

 required
- default

The default value to return if the variable does not exist.

 required
Example

Get a variable's value by name.

from prefect import flow
from prefect.variables import Variable

@flow
def my_flow():
    var = Variable.get("my_var")
Source code in src/prefect/variables.py 
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
@classmethod
@sync_compatible
async def get(
    cls,
    name: str,
    default: StrictVariableValue = None,
) -> StrictVariableValue:
    """
    Get a variable's value by name.

    If the variable does not exist, return the default value.

    Args:
        - name: The name of the variable value to get.
        - default: The default value to return if the variable does not exist.

    Example:
        Get a variable's value by name.
        ```python
        from prefect import flow
        from prefect.variables import Variable

        @flow
        def my_flow():
            var = Variable.get("my_var")
        ```
    """
    client, _ = get_or_create_client()
    variable = await client.read_variable_by_name(name)

    return variable.value if variable else default

set(name, value, tags=None, overwrite=False) async classmethod

Sets a new variable. If one exists with the same name, must pass overwrite=True

Returns the newly set variable object.

Parameters:

Name Type Description Default
- name

The name of the variable to set.

 required
- value

The value of the variable to set.

 required
- tags

An optional list of strings to associate with the variable.

 required
- overwrite

Whether to overwrite the variable if it already exists.

 required
Example

Set a new variable and overwrite it if it already exists.

from prefect.variables import Variable

@flow
def my_flow():
    Variable.set(name="my_var",value="test_value", tags=["hi", "there"], overwrite=True)
Source code in src/prefect/variables.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
@classmethod
@sync_compatible
async def set(
    cls,
    name: str,
    value: StrictVariableValue,
    tags: Optional[List[str]] = None,
    overwrite: bool = False,
) -> "Variable":
    """
    Sets a new variable. If one exists with the same name, must pass `overwrite=True`

    Returns the newly set variable object.

    Args:
        - name: The name of the variable to set.
        - value: The value of the variable to set.
        - tags: An optional list of strings to associate with the variable.
        - overwrite: Whether to overwrite the variable if it already exists.

    Example:
        Set a new variable and overwrite it if it already exists.

        ```
        from prefect.variables import Variable

        @flow
        def my_flow():
            Variable.set(name="my_var",value="test_value", tags=["hi", "there"], overwrite=True)
        ```
    """
    client, _ = get_or_create_client()
    variable_exists = await client.read_variable_by_name(name)
    var_dict = {"name": name, "value": value, "tags": tags or []}

    if variable_exists:
        if not overwrite:
            raise ValueError(
                f"Variable {name!r} already exists. Use `overwrite=True` to update it."
            )
        await client.update_variable(variable=VariableUpdate(**var_dict))
        variable = await client.read_variable_by_name(name)
        var_dict = {
            "name": variable.name,
            "value": variable.value,
            "tags": variable.tags or [],
        }
    else:
        await client.create_variable(variable=VariableCreate(**var_dict))

    return cls(**var_dict)

unset(name) async classmethod

Unset a variable by name.

Parameters:

Name Type Description Default
- name

The name of the variable to unset.

 required

Returns True if the variable was deleted, False if the variable did not exist.

Example

Unset a variable by name.

from prefect import flow
from prefect.variables import Variable

@flow
def my_flow():
    Variable.unset("my_var")
Source code in src/prefect/variables.py 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
@classmethod
@sync_compatible
async def unset(cls, name: str) -> bool:
    """
    Unset a variable by name.

    Args:
        - name: The name of the variable to unset.

    Returns `True` if the variable was deleted, `False` if the variable did not exist.

    Example:
        Unset a variable by name.
        ```python
        from prefect import flow
        from prefect.variables import Variable

        @flow
        def my_flow():
            Variable.unset("my_var")
        ```
    """
    client, _ = get_or_create_client()
    try:
        await client.delete_variable_by_name(name=name)
        return True
    except ObjectNotFound:
        return False