Skip to content

Expressions¤

Helpers¤

get_annotation module-attribute ¤

get_annotation = partial(get_expression, parse_strings=None)
Referenced by:

get_base_class module-attribute ¤

get_base_class = partial(
    get_expression, parse_strings=False
)
Referenced by:

get_class_keyword module-attribute ¤

get_class_keyword = partial(
    get_expression, parse_strings=False
)
Referenced by:

get_condition module-attribute ¤

get_condition = partial(get_expression, parse_strings=False)
Referenced by:

get_expression ¤

get_expression(
    node: AST | None,
    parent: Module | Class,
    *,
    member: str | None = None,
    parse_strings: bool | None = None,
) -> Expr | None

Build an expression from an AST.

Parameters:

  • node ¤

    (AST | None) –

    The annotation node.

  • parent ¤

    (Module | Class) –

    The parent used to resolve the name.

  • member ¤

    (str | None, default: None ) –

    The member name (for resolution in its scope).

  • parse_strings ¤

    (bool | None, default: None ) –

    Whether to try and parse strings as type annotations.

Returns:

  • Expr | None –

    A string or resovable name or expression.

Referenced by: Used by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
def get_expression(
    node: ast.AST | None,
    parent: Module | Class,
    *,
    member: str | None = None,
    parse_strings: bool | None = None,
) -> Expr | None:
    """Build an expression from an AST.

    Parameters:
        node: The annotation node.
        parent: The parent used to resolve the name.
        member: The member name (for resolution in its scope).
        parse_strings: Whether to try and parse strings as type annotations.

    Returns:
        A string or resovable name or expression.
    """
    if node is None:
        return None
    if parse_strings is None:
        try:
            module = parent.module
        except ValueError:
            parse_strings = False
        else:
            parse_strings = not module.imports_future_annotations
    return _build(node, parent, member=member, parse_strings=parse_strings)

safe_get_annotation module-attribute ¤

safe_get_annotation = partial(
    safe_get_expression,
    parse_strings=None,
    msg_format=_msg_format % "annotation",
)
Referenced by:

safe_get_base_class module-attribute ¤

safe_get_base_class = partial(
    safe_get_expression,
    parse_strings=False,
    msg_format=_msg_format % "base class",
)
Referenced by:

safe_get_class_keyword module-attribute ¤

safe_get_class_keyword = partial(
    safe_get_expression,
    parse_strings=False,
    msg_format=_msg_format % "class keyword",
)
Referenced by:

safe_get_condition module-attribute ¤

safe_get_condition = partial(
    safe_get_expression,
    parse_strings=False,
    msg_format=_msg_format % "condition",
)
Referenced by:

safe_get_expression ¤

safe_get_expression(
    node: AST | None,
    parent: Module | Class,
    *,
    member: str | None = None,
    parse_strings: bool | None = None,
    log_level: LogLevel | None = error,
    msg_format: str = "{path}:{lineno}: Failed to get expression from {node_class}: {error}",
) -> Expr | None

Safely (no exception) build a resolvable annotation.

Parameters:

  • node ¤

    (AST | None) –

    The annotation node.

  • parent ¤

    (Module | Class) –

    The parent used to resolve the name.

  • member ¤

    (str | None, default: None ) –

    The member name (for resolution in its scope).

  • parse_strings ¤

    (bool | None, default: None ) –

    Whether to try and parse strings as type annotations.

  • log_level ¤

    (LogLevel | None, default: error ) –

    Log level to use to log a message. None to disable logging.

  • msg_format ¤

    (str, default: '{path}:{lineno}: Failed to get expression from {node_class}: {error}' ) –

    A format string for the log message. Available placeholders: path, lineno, node, error.

Returns:

  • Expr | None –

    A string or resovable name or expression.

Referenced by: Used by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
def safe_get_expression(
    node: ast.AST | None,
    parent: Module | Class,
    *,
    member: str | None = None,
    parse_strings: bool | None = None,
    log_level: LogLevel | None = LogLevel.error,
    msg_format: str = "{path}:{lineno}: Failed to get expression from {node_class}: {error}",
) -> Expr | None:
    """Safely (no exception) build a resolvable annotation.

    Parameters:
        node: The annotation node.
        parent: The parent used to resolve the name.
        member: The member name (for resolution in its scope).
        parse_strings: Whether to try and parse strings as type annotations.
        log_level: Log level to use to log a message. None to disable logging.
        msg_format: A format string for the log message. Available placeholders:
            path, lineno, node, error.

    Returns:
        A string or resovable name or expression.
    """
    try:
        return get_expression(node, parent, member=member, parse_strings=parse_strings)
    except Exception as error:  # noqa: BLE001
        if log_level is None:
            return None
        node_class = node.__class__.__name__
        try:
            path: Path | str = parent.relative_filepath
        except ValueError:
            path = "<in-memory>"
        lineno = node.lineno  # ty:ignore[unresolved-attribute]
        error_str = f"{error.__class__.__name__}: {error}"
        message = msg_format.format(path=path, lineno=lineno, node_class=node_class, error=error_str)
        getattr(logger, log_level.value)(message)
    return None

Expression nodes¤

Expr dataclass ¤

Expr()

Base class for expressions.

Referenced by: Returned by: Subclassed by: Used by: Yielded by:

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

path property ¤

path: str

Path of the expressed name/attribute.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:  # noqa: ARG002
    """Iterate on the expression elements.

    Parameters:
        flat: Expressions are trees.

            When flat is false, this method iterates only on the first layer of the tree.
            To iterate on all the subparts of the expression, you have to do so recursively.
            It allows to handle each subpart specifically (for example subscripts, attribute, etc.),
            without them getting rendered as strings.

            On the contrary, when flat is true, the whole tree is flattened as a sequence
            of strings and instances of [Names][griffe.ExprName].

    Yields:
        Strings and names when flat, strings and expressions otherwise.
    """
    yield from ()

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprAttribute dataclass ¤

ExprAttribute(values: list[str | Expr])

Bases: Expr


              flowchart TD
              griffe.ExprAttribute[ExprAttribute]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprAttribute
                


              click griffe.ExprAttribute href "" "griffe.ExprAttribute"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Attributes like a.b.

Returned by:

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • append –

    Append a name to this attribute.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

The canonical path of this attribute.

classname property ¤

classname: str

The expression class name.

first property ¤

first: str | Expr

The first part of this attribute (on the left).

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

last property ¤

last: ExprName

The last part of this attribute (on the right).

path property ¤

path: str

The path of this attribute.

values instance-attribute ¤

values: list[str | Expr]

The different parts of the dotted chain.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

append ¤

append(value: ExprName) -> None

Append a name to this attribute.

Parameters:

  • value ¤

    (ExprName) –

    The expression name to append.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
312
313
314
315
316
317
318
319
320
def append(self, value: ExprName) -> None:
    """Append a name to this attribute.

    Parameters:
        value: The expression name to append.
    """
    if value.parent is None:
        value.parent = self.last
    self.values.append(value)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
295
296
297
298
299
300
301
302
303
304
305
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    precedence = _get_precedence(self)
    first = self.values[0]
    if isinstance(first, str) and first.isdigit():
        # Integer literals need parentheses: `1.bit_length()` is a syntax error.
        yield f"({first})"
    else:
        yield from _yield(first, flat=flat, outer_precedence=precedence, is_left=True)
    for value in self.values[1:]:
        yield "."
        yield from _yield(value, flat=flat, outer_precedence=precedence)

modernize ¤

modernize() -> ExprName | ExprAttribute

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
307
308
309
310
def modernize(self) -> ExprName | ExprAttribute:
    if modern := _modern_types.get(self.canonical_path):
        return ExprName(modern, parent=self.last.parent)
    return self

ExprBinOp dataclass ¤

ExprBinOp(
    left: str | Expr, operator: str, right: str | Expr
)

Bases: Expr


              flowchart TD
              griffe.ExprBinOp[ExprBinOp]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprBinOp
                


              click griffe.ExprBinOp href "" "griffe.ExprBinOp"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Binary operations like a + b.

Returned by:

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

left instance-attribute ¤

left: str | Expr

Left part.

operator instance-attribute ¤

operator: str

Binary operator.

path property ¤

path: str

Path of the expressed name/attribute.

right instance-attribute ¤

right: str | Expr

Right part.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
356
357
358
359
360
361
362
363
364
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    precedence = _get_precedence(self)
    right_precedence = precedence
    if self.operator == "**" and isinstance(self.right, ExprUnaryOp):
        # Unary operators on the right have higher precedence, e.g. `a ** -b`.
        right_precedence = _OperatorPrecedence(precedence - 1)
    yield from _yield(self.left, flat=flat, outer_precedence=precedence, is_left=True)
    yield f" {self.operator} "
    yield from _yield(self.right, flat=flat, outer_precedence=right_precedence, is_left=False)

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprBoolOp dataclass ¤

ExprBoolOp(operator: str, values: Sequence[str | Expr])

Bases: Expr


              flowchart TD
              griffe.ExprBoolOp[ExprBoolOp]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprBoolOp
                


              click griffe.ExprBoolOp href "" "griffe.ExprBoolOp"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Boolean operations like a or b.

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

operator instance-attribute ¤

operator: str

Boolean operator.

path property ¤

path: str

Path of the expressed name/attribute.

values instance-attribute ¤

values: Sequence[str | Expr]

Operands.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
376
377
378
379
380
381
382
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    precedence = _get_precedence(self)
    it = iter(self.values)
    yield from _yield(next(it), flat=flat, outer_precedence=precedence, is_left=True)
    for value in it:
        yield f" {self.operator} "
        yield from _yield(value, flat=flat, outer_precedence=precedence, is_left=False)

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprCall dataclass ¤

ExprCall(function: Expr, arguments: Sequence[str | Expr])

Bases: Expr


              flowchart TD
              griffe.ExprCall[ExprCall]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprCall
                


              click griffe.ExprCall href "" "griffe.ExprCall"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Calls like f().

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

arguments instance-attribute ¤

arguments: Sequence[str | Expr]

Passed arguments.

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

The canonical path of this subscript's left part.

classname property ¤

classname: str

The expression class name.

function instance-attribute ¤

function: Expr

Function called.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

path property ¤

path: str

Path of the expressed name/attribute.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
399
400
401
402
403
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    yield from _yield(self.function, flat=flat, outer_precedence=_get_precedence(self))
    yield "("
    yield from _join(self.arguments, ", ", flat=flat)
    yield ")"

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprCompare dataclass ¤

ExprCompare(
    left: str | Expr,
    operators: Sequence[str],
    comparators: Sequence[str | Expr],
)

Bases: Expr


              flowchart TD
              griffe.ExprCompare[ExprCompare]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprCompare
                


              click griffe.ExprCompare href "" "griffe.ExprCompare"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Comparisons like a > b.

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

comparators instance-attribute ¤

comparators: Sequence[str | Expr]

Things compared.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

left instance-attribute ¤

left: str | Expr

Left part.

operators instance-attribute ¤

operators: Sequence[str]

Comparison operators.

path property ¤

path: str

Path of the expressed name/attribute.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
417
418
419
420
421
422
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    precedence = _get_precedence(self)
    yield from _yield(self.left, flat=flat, outer_precedence=precedence, is_left=True)
    for op, comp in zip(self.operators, self.comparators, strict=False):
        yield f" {op} "
        yield from _yield(comp, flat=flat, outer_precedence=precedence)

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprComprehension dataclass ¤

ExprComprehension(
    target: str | Expr,
    iterable: str | Expr,
    conditions: Sequence[str | Expr],
    is_async: bool = False,
)

Bases: Expr


              flowchart TD
              griffe.ExprComprehension[ExprComprehension]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprComprehension
                


              click griffe.ExprComprehension href "" "griffe.ExprComprehension"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Comprehensions like a for b in c if d.

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

conditions instance-attribute ¤

conditions: Sequence[str | Expr]

Conditions to include the target in the result.

is_async class-attribute instance-attribute ¤

is_async: bool = False

Async comprehension or not.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

iterable instance-attribute ¤

iterable: str | Expr

Value iterated on.

path property ¤

path: str

Path of the expressed name/attribute.

target instance-attribute ¤

target: str | Expr

Comprehension target (value added to the result).

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
438
439
440
441
442
443
444
445
446
447
448
449
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    if self.is_async:
        yield "async "
    yield "for "
    yield from _yield(self.target, flat=flat, outer_precedence=_OperatorPrecedence.NONE)
    yield " in "
    # The iterable and conditions are disjunctions in the grammar:
    # lambdas, conditionals and walrus assignments need parentheses there.
    yield from _yield(self.iterable, flat=flat, outer_precedence=_OperatorPrecedence.OR, is_left=True)
    for condition in self.conditions:
        yield " if "
        yield from _yield(condition, flat=flat, outer_precedence=_OperatorPrecedence.OR, is_left=True)

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprConstant dataclass ¤

ExprConstant(value: str)

Bases: Expr


              flowchart TD
              griffe.ExprConstant[ExprConstant]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprConstant
                


              click griffe.ExprConstant href "" "griffe.ExprConstant"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Constants like "a" or 1.

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

path property ¤

path: str

Path of the expressed name/attribute.

value instance-attribute ¤

value: str

Constant value.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
463
464
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:  # noqa: ARG002
    yield self.value

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprDict dataclass ¤

ExprDict(
    keys: Sequence[str | Expr | None],
    values: Sequence[str | Expr],
)

Bases: Expr


              flowchart TD
              griffe.ExprDict[ExprDict]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprDict
                


              click griffe.ExprDict href "" "griffe.ExprDict"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Dictionaries like {"a": 0}.

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

keys instance-attribute ¤

keys: Sequence[str | Expr | None]

Dict keys.

path property ¤

path: str

Path of the expressed name/attribute.

values instance-attribute ¤

values: Sequence[str | Expr]

Dict values.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
476
477
478
479
480
481
482
483
484
485
486
487
488
489
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    yield "{"
    # Walrus assignments and yields need parentheses in keys and values,
    # e.g. `{1: (x := 2)}`.
    yield from _join(
        (
            ("**", value) if key is None else (key, ": ", value)
            for key, value in zip(self.keys, self.values, strict=False)
        ),
        ", ",
        flat=flat,
        outer_precedence=_OperatorPrecedence.STARRED,
    )
    yield "}"

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprDictComp dataclass ¤

ExprDictComp(
    key: str | Expr,
    value: str | Expr | None,
    generators: Sequence[Expr],
)

Bases: Expr


              flowchart TD
              griffe.ExprDictComp[ExprDictComp]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprDictComp
                


              click griffe.ExprDictComp href "" "griffe.ExprDictComp"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Dict comprehensions like {k: v for k, v in a}.

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

generators instance-attribute ¤

generators: Sequence[Expr]

Generators iterated on.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

key instance-attribute ¤

key: str | Expr

Target key.

path property ¤

path: str

Path of the expressed name/attribute.

value instance-attribute ¤

value: str | Expr | None

Target value.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
503
504
505
506
507
508
509
510
511
512
513
514
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    yield "{"
    if self.value:
        yield from _yield(self.key, flat=flat, outer_precedence=_OperatorPrecedence.NONE)
        yield ": "
        yield from _yield(self.value, flat=flat, outer_precedence=_OperatorPrecedence.NONE)
    else:
        yield "**"
        yield from _yield(self.key, flat=flat, outer_precedence=_OperatorPrecedence.NONE)
    yield " "
    yield from _join(self.generators, " ", flat=flat)
    yield "}"

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprExtSlice dataclass ¤

ExprExtSlice(dims: Sequence[str | Expr])

Bases: Expr


              flowchart TD
              griffe.ExprExtSlice[ExprExtSlice]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprExtSlice
                


              click griffe.ExprExtSlice href "" "griffe.ExprExtSlice"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Extended slice like a[x:y, z].

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

dims instance-attribute ¤

dims: Sequence[str | Expr]

Dims.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

path property ¤

path: str

Path of the expressed name/attribute.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
524
525
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    yield from _join(self.dims, ", ", flat=flat)

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprFormatted dataclass ¤

ExprFormatted(
    value: str | Expr,
    conversion: str | None = None,
    format_spec: Sequence[str | Expr] | None = None,
)

Bases: Expr


              flowchart TD
              griffe.ExprFormatted[ExprFormatted]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprFormatted
                


              click griffe.ExprFormatted href "" "griffe.ExprFormatted"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Formatted string like {1 + 1}.

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

conversion class-attribute instance-attribute ¤

conversion: str | None = None

Conversion flag (s, r or a), without the leading exclamation mark.

format_spec class-attribute instance-attribute ¤

format_spec: Sequence[str | Expr] | None = None

Format specifier parts: literal strings and interpolated expressions.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

path property ¤

path: str

Path of the expressed name/attribute.

value instance-attribute ¤

value: str | Expr

Formatted value.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
567
568
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    yield from _iterate_format_parts(self.value, self.conversion, self.format_spec, flat=flat)

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprGeneratorExp dataclass ¤

ExprGeneratorExp(
    element: str | Expr,
    generators: Sequence[Expr],
    implicit: bool = False,
)

Bases: Expr


              flowchart TD
              griffe.ExprGeneratorExp[ExprGeneratorExp]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprGeneratorExp
                


              click griffe.ExprGeneratorExp href "" "griffe.ExprGeneratorExp"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Generator expressions like (a for b in c for d in e).

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

element instance-attribute ¤

element: str | Expr

Yielded element.

generators instance-attribute ¤

generators: Sequence[Expr]

Generators iterated on.

implicit class-attribute instance-attribute ¤

implicit: bool = False

Whether the generator's parentheses are implicit (as the sole argument of a call).

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

path property ¤

path: str

Path of the expressed name/attribute.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
582
583
584
585
586
587
588
589
590
591
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    # Generator expressions require parentheses everywhere
    # except as the sole argument of a call, e.g. `f(a for a in b)`.
    if not self.implicit:
        yield "("
    yield from _yield(self.element, flat=flat, outer_precedence=_OperatorPrecedence.NONE)
    yield " "
    yield from _join(self.generators, " ", flat=flat)
    if not self.implicit:
        yield ")"

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprIfExp dataclass ¤

ExprIfExp(
    body: str | Expr, test: str | Expr, orelse: str | Expr
)

Bases: Expr


              flowchart TD
              griffe.ExprIfExp[ExprIfExp]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprIfExp
                


              click griffe.ExprIfExp href "" "griffe.ExprIfExp"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Conditions like a if b else c.

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

body instance-attribute ¤

body: str | Expr

Value if test.

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

orelse instance-attribute ¤

orelse: str | Expr

Other expression.

path property ¤

path: str

Path of the expressed name/attribute.

test instance-attribute ¤

test: str | Expr

Condition.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    precedence = _get_precedence(self)
    yield from _yield(self.body, flat=flat, outer_precedence=precedence, is_left=True)
    yield " if "
    # If the test itself is another if/else, its precedence is the same, which will not give
    # a parenthesis: force it.
    test_outer_precedence = _OperatorPrecedence(precedence + 1)
    yield from _yield(self.test, flat=flat, outer_precedence=test_outer_precedence)
    yield " else "
    # If/else is right associative. For example, a nested if/else
    # `a if b else c if d else e` is effectively `a if b else (c if d else e)`, so produce a
    # flattened version without parentheses.
    if isinstance(self.orelse, ExprIfExp):
        yield from self.orelse.iterate(flat=flat)
    else:
        yield from _yield(self.orelse, flat=flat, outer_precedence=precedence, is_left=False)

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprInterpolation dataclass ¤

ExprInterpolation(
    value: str | Expr,
    conversion: str | None = None,
    format_spec: Sequence[str | Expr] | None = None,
)

Bases: Expr


              flowchart TD
              griffe.ExprInterpolation[ExprInterpolation]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprInterpolation
                


              click griffe.ExprInterpolation href "" "griffe.ExprInterpolation"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Template string interpolation like {name}.

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

conversion class-attribute instance-attribute ¤

conversion: str | None = None

Conversion flag (s, r or a), without the leading exclamation mark.

format_spec class-attribute instance-attribute ¤

format_spec: Sequence[str | Expr] | None = None

Format specifier parts: literal strings and interpolated expressions.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

path property ¤

path: str

Path of the expressed name/attribute.

value instance-attribute ¤

value: str | Expr

Interpolated value.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
634
635
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    yield from _iterate_format_parts(self.value, self.conversion, self.format_spec, flat=flat)

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprJoinedStr dataclass ¤

ExprJoinedStr(values: Sequence[str | Expr])

Bases: Expr


              flowchart TD
              griffe.ExprJoinedStr[ExprJoinedStr]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprJoinedStr
                


              click griffe.ExprJoinedStr href "" "griffe.ExprJoinedStr"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Joined strings like f"a {b} c".

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

path property ¤

path: str

Path of the expressed name/attribute.

values instance-attribute ¤

values: Sequence[str | Expr]

Joined values.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
682
683
684
685
686
687
688
689
690
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    quote, escaped_parts = _fstring_choose_quote(self.values)
    yield f"f{quote}"
    for value, escaped in zip(self.values, escaped_parts, strict=True):
        if isinstance(value, str):
            yield escaped
        else:
            yield from _yield(value, flat=flat, outer_precedence=_OperatorPrecedence.NONE)
    yield quote

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprKeyword dataclass ¤

ExprKeyword(
    name: str,
    value: str | Expr,
    function: Expr | None = None,
)

Bases: Expr


              flowchart TD
              griffe.ExprKeyword[ExprKeyword]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprKeyword
                


              click griffe.ExprKeyword href "" "griffe.ExprKeyword"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Keyword arguments like a=b.

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed keyword.

classname property ¤

classname: str

The expression class name.

function class-attribute instance-attribute ¤

function: Expr | None = None

Expression referencing the function called with this parameter.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

name instance-attribute ¤

name: str

Name.

path property ¤

path: str

Path of the expressed name/attribute.

value instance-attribute ¤

value: str | Expr

Value.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
727
728
729
730
731
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    yield self.name
    yield "="
    # Walrus assignments and yields need parentheses, e.g. `f(a=(b := c))`.
    yield from _yield(self.value, flat=flat, outer_precedence=_OperatorPrecedence.STARRED)

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprVarPositional dataclass ¤

ExprVarPositional(value: Expr)

Bases: Expr


              flowchart TD
              griffe.ExprVarPositional[ExprVarPositional]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprVarPositional
                


              click griffe.ExprVarPositional href "" "griffe.ExprVarPositional"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Variadic positional parameters like *args.

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

path property ¤

path: str

Path of the expressed name/attribute.

value instance-attribute ¤

value: Expr

Starred value.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
741
742
743
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    yield "*"
    yield from _yield(self.value, flat=flat, outer_precedence=_OperatorPrecedence.BIT_OR, is_left=True)

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprVarKeyword dataclass ¤

ExprVarKeyword(value: Expr)

Bases: Expr


              flowchart TD
              griffe.ExprVarKeyword[ExprVarKeyword]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprVarKeyword
                


              click griffe.ExprVarKeyword href "" "griffe.ExprVarKeyword"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Variadic keyword parameters like **kwargs.

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

path property ¤

path: str

Path of the expressed name/attribute.

value instance-attribute ¤

value: Expr

Double-starred value.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
753
754
755
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    yield "**"
    yield from _yield(self.value, flat=flat, outer_precedence=_OperatorPrecedence.BIT_OR, is_left=True)

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprLambda dataclass ¤

ExprLambda(
    parameters: Sequence[ExprParameter], body: str | Expr
)

Bases: Expr


              flowchart TD
              griffe.ExprLambda[ExprLambda]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprLambda
                


              click griffe.ExprLambda href "" "griffe.ExprLambda"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Lambda expressions like lambda a: a.b.

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

body instance-attribute ¤

body: str | Expr

Lambda's body.

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

parameters instance-attribute ¤

parameters: Sequence[ExprParameter]

Lambda's parameters.

path property ¤

path: str

Path of the expressed name/attribute.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    pos_only = False
    star = False
    yield "lambda"
    if self.parameters:
        yield " "
    for index, parameter in enumerate(self.parameters):
        if index:
            yield ", "
        if parameter.kind is ParameterKind.positional_only:
            pos_only = True
        elif pos_only:
            # End of the positional-only section.
            pos_only = False
            yield "/, "
        if parameter.kind is ParameterKind.var_positional:
            star = True
            yield "*"
        elif parameter.kind is ParameterKind.var_keyword:
            yield "**"
        elif parameter.kind is ParameterKind.keyword_only and not star:
            # `*args` also starts the keyword-only section.
            star = True
            yield "*, "
        yield parameter.name
        if parameter.default and parameter.kind not in (ParameterKind.var_positional, ParameterKind.var_keyword):
            yield "="
            yield from _yield(parameter.default, flat=flat, outer_precedence=_OperatorPrecedence.STARRED)
    if pos_only:
        # All parameters are positional-only.
        yield ", /"
    yield ": "
    # Body of lambda should not have parentheses, avoiding `lambda: a.b`
    yield from _yield(self.body, flat=flat, outer_precedence=_OperatorPrecedence.NONE)

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprList dataclass ¤

ExprList(elements: Sequence[Expr])

Bases: Expr


              flowchart TD
              griffe.ExprList[ExprList]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprList
                


              click griffe.ExprList href "" "griffe.ExprList"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Lists like [0, 1, 2].

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

elements instance-attribute ¤

elements: Sequence[Expr]

List elements.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

path property ¤

path: str

Path of the expressed name/attribute.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
810
811
812
813
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    yield "["
    yield from _join(self.elements, ", ", flat=flat)
    yield "]"

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprListComp dataclass ¤

ExprListComp(
    element: str | Expr, generators: Sequence[Expr]
)

Bases: Expr


              flowchart TD
              griffe.ExprListComp[ExprListComp]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprListComp
                


              click griffe.ExprListComp href "" "griffe.ExprListComp"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

List comprehensions like [a for b in c].

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

element instance-attribute ¤

element: str | Expr

Target value.

generators instance-attribute ¤

generators: Sequence[Expr]

Generators iterated on.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

path property ¤

path: str

Path of the expressed name/attribute.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
825
826
827
828
829
830
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    yield "["
    yield from _yield(self.element, flat=flat, outer_precedence=_OperatorPrecedence.NONE)
    yield " "
    yield from _join(self.generators, " ", flat=flat)
    yield "]"

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprName dataclass ¤

ExprName(
    name: str,
    parent: str
    | ExprName
    | Module
    | Class
    | Function
    | None = None,
    member: str | None = None,
)

Bases: Expr


              flowchart TD
              griffe.ExprName[ExprName]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprName
                


              click griffe.ExprName href "" "griffe.ExprName"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

This class represents a Python object identified by a name in a given scope.

Referenced by: Returned by: Used by:

Methods:

  • __eq__ –

    Two name expressions are equal if they have the same name value (parent is ignored).

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

The canonical name (resolved one, not alias name).

classname property ¤

classname: str

The expression class name.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_enum_class property ¤

is_enum_class: bool

Whether this name resolves to an enumeration class.

is_enum_instance property ¤

is_enum_instance: bool

Whether this name resolves to an enumeration instance.

is_enum_value property ¤

is_enum_value: bool

Whether this name resolves to an enumeration value.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

is_type_parameter property ¤

is_type_parameter: bool

Whether this name resolves to a type parameter.

member class-attribute instance-attribute ¤

member: str | None = None

Member name (for resolution in its scope).

name instance-attribute ¤

name: str

Actual name.

parent class-attribute instance-attribute ¤

parent: (
    str | ExprName | Module | Class | Function | None
) = None

Parent (for resolution in its scope).

path property ¤

path: str

The full, resolved name.

If it was given when creating the name, return that. If a callable was given, call it and return its result. It the name cannot be resolved, return the source.

resolved property ¤

resolved: Module | Class | None

The resolved object this name refers to.

__eq__ ¤

__eq__(other: object) -> bool

Two name expressions are equal if they have the same name value (parent is ignored).

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
844
845
846
847
848
def __eq__(self, other: object) -> bool:
    """Two name expressions are equal if they have the same `name` value (`parent` is ignored)."""
    if isinstance(other, ExprName):
        return self.name == other.name
    return NotImplemented

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[ExprName]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
850
851
def iterate(self, *, flat: bool = True) -> Iterator[ExprName]:  # noqa: ARG002
    yield self

modernize ¤

modernize() -> ExprName

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
853
854
855
856
def modernize(self) -> ExprName:
    if modern := _modern_types.get(self.canonical_path):
        return ExprName(modern, parent=self.parent)
    return self

ExprNamedExpr dataclass ¤

ExprNamedExpr(target: Expr, value: str | Expr)

Bases: Expr


              flowchart TD
              griffe.ExprNamedExpr[ExprNamedExpr]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprNamedExpr
                


              click griffe.ExprNamedExpr href "" "griffe.ExprNamedExpr"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Named/assignment expressions like a := b.

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

path property ¤

path: str

Path of the expressed name/attribute.

target instance-attribute ¤

target: Expr

Target name.

value instance-attribute ¤

value: str | Expr

Value.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
936
937
938
939
940
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    yield from _yield(self.target, flat=flat, outer_precedence=_OperatorPrecedence.NONE)
    yield " := "
    # Nested walrus assignments and yields need parentheses, e.g. `a := (b := c)`.
    yield from _yield(self.value, flat=flat, outer_precedence=_OperatorPrecedence.STARRED)

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprParameter dataclass ¤

ExprParameter(
    name: str,
    kind: ParameterKind = positional_or_keyword,
    annotation: Expr | None = None,
    default: str | Expr | None = None,
)

Bases: Expr


              flowchart TD
              griffe.ExprParameter[ExprParameter]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprParameter
                


              click griffe.ExprParameter href "" "griffe.ExprParameter"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Parameters in function signatures like a: int = 0.

Returned by: Used by:

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

annotation class-attribute instance-attribute ¤

annotation: Expr | None = None

Parameter type.

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

default class-attribute instance-attribute ¤

default: str | Expr | None = None

Parameter default.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

kind class-attribute instance-attribute ¤

kind: ParameterKind = ParameterKind.positional_or_keyword

Parameter kind.

name instance-attribute ¤

name: str

Parameter name.

path property ¤

path: str

Path of the expressed name/attribute.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:  # noqa: ARG002
    """Iterate on the expression elements.

    Parameters:
        flat: Expressions are trees.

            When flat is false, this method iterates only on the first layer of the tree.
            To iterate on all the subparts of the expression, you have to do so recursively.
            It allows to handle each subpart specifically (for example subscripts, attribute, etc.),
            without them getting rendered as strings.

            On the contrary, when flat is true, the whole tree is flattened as a sequence
            of strings and instances of [Names][griffe.ExprName].

    Yields:
        Strings and names when flat, strings and expressions otherwise.
    """
    yield from ()

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprSet dataclass ¤

ExprSet(elements: Sequence[str | Expr])

Bases: Expr


              flowchart TD
              griffe.ExprSet[ExprSet]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprSet
                


              click griffe.ExprSet href "" "griffe.ExprSet"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Sets like {0, 1, 2}.

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

elements instance-attribute ¤

elements: Sequence[str | Expr]

Set elements.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

path property ¤

path: str

Path of the expressed name/attribute.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
964
965
966
967
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    yield "{"
    yield from _join(self.elements, ", ", flat=flat)
    yield "}"

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprSetComp dataclass ¤

ExprSetComp(
    element: str | Expr, generators: Sequence[Expr]
)

Bases: Expr


              flowchart TD
              griffe.ExprSetComp[ExprSetComp]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprSetComp
                


              click griffe.ExprSetComp href "" "griffe.ExprSetComp"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Set comprehensions like {a for b in c}.

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

element instance-attribute ¤

element: str | Expr

Target value.

generators instance-attribute ¤

generators: Sequence[Expr]

Generators iterated on.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

path property ¤

path: str

Path of the expressed name/attribute.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
979
980
981
982
983
984
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    yield "{"
    yield from _yield(self.element, flat=flat, outer_precedence=_OperatorPrecedence.NONE)
    yield " "
    yield from _join(self.generators, " ", flat=flat)
    yield "}"

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprSlice dataclass ¤

ExprSlice(
    lower: str | Expr | None = None,
    upper: str | Expr | None = None,
    step: str | Expr | None = None,
)

Bases: Expr


              flowchart TD
              griffe.ExprSlice[ExprSlice]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprSlice
                


              click griffe.ExprSlice href "" "griffe.ExprSlice"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Slices like [a:b:c].

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

lower class-attribute instance-attribute ¤

lower: str | Expr | None = None

Lower bound.

path property ¤

path: str

Path of the expressed name/attribute.

step class-attribute instance-attribute ¤

step: str | Expr | None = None

Iteration step.

upper class-attribute instance-attribute ¤

upper: str | Expr | None = None

Upper bound.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    # Walrus assignments need parentheses in slice bounds, e.g. `a[(b := c):]`.
    if self.lower is not None:
        yield from _yield(self.lower, flat=flat, outer_precedence=_OperatorPrecedence.STARRED)
    yield ":"
    if self.upper is not None:
        yield from _yield(self.upper, flat=flat, outer_precedence=_OperatorPrecedence.STARRED)
    if self.step is not None:
        yield ":"
        yield from _yield(self.step, flat=flat, outer_precedence=_OperatorPrecedence.STARRED)

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprSubscript dataclass ¤

ExprSubscript(left: str | Expr, slice: str | Expr)

Bases: Expr


              flowchart TD
              griffe.ExprSubscript[ExprSubscript]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprSubscript
                


              click griffe.ExprSubscript href "" "griffe.ExprSubscript"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Subscripts like a[b].

Returned by:

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

The canonical path of this subscript's left part.

classname property ¤

classname: str

The expression class name.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

left instance-attribute ¤

left: str | Expr

Left part.

path property ¤

path: str

The path of this subscript's left part.

slice instance-attribute ¤

slice: str | Expr

Slice part.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
1019
1020
1021
1022
1023
1024
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    yield from _yield(self.left, flat=flat, outer_precedence=_get_precedence(self))
    yield "["
    # Prevent parentheses from being added, avoiding `a[(b)]`
    yield from _yield(self.slice, flat=flat, outer_precedence=_OperatorPrecedence.NONE)
    yield "]"

modernize ¤

modernize() -> ExprBinOp | ExprSubscript

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
def modernize(self) -> ExprBinOp | ExprSubscript:
    if self.canonical_path == "typing.Union":
        return self._to_binop(self.slice.elements, op="|")  # ty:ignore[unresolved-attribute]
    if self.canonical_path == "typing.Optional":
        left = self.slice if isinstance(self.slice, str) else self.slice.modernize()
        return ExprBinOp(left=left, operator="|", right="None")
    return ExprSubscript(
        left=self.left if isinstance(self.left, str) else self.left.modernize(),
        slice=self.slice if isinstance(self.slice, str) else self.slice.modernize(),
    )

ExprTemplateStr dataclass ¤

ExprTemplateStr(values: Sequence[str | Expr])

Bases: Expr


              flowchart TD
              griffe.ExprTemplateStr[ExprTemplateStr]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprTemplateStr
                


              click griffe.ExprTemplateStr href "" "griffe.ExprTemplateStr"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Template strings like t"a {name}".

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

path property ¤

path: str

Path of the expressed name/attribute.

values instance-attribute ¤

values: Sequence[str | Expr]

Joined values.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
1059
1060
1061
1062
1063
1064
1065
1066
1067
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    quote, escaped_parts = _fstring_choose_quote(self.values)
    yield f"t{quote}"
    for value, escaped in zip(self.values, escaped_parts, strict=True):
        if isinstance(value, str):
            yield escaped
        else:
            yield from _yield(value, flat=flat, outer_precedence=_OperatorPrecedence.NONE)
    yield quote

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprTuple dataclass ¤

ExprTuple(
    elements: Sequence[str | Expr], implicit: bool = False
)

Bases: Expr


              flowchart TD
              griffe.ExprTuple[ExprTuple]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprTuple
                


              click griffe.ExprTuple href "" "griffe.ExprTuple"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Tuples like (0, 1, 2).

Returned by:

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

elements instance-attribute ¤

elements: Sequence[str | Expr]

Tuple elements.

implicit class-attribute instance-attribute ¤

implicit: bool = False

Whether the tuple is implicit (e.g. without parentheses in a subscript's slice).

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

path property ¤

path: str

Path of the expressed name/attribute.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    # We fixed `_build_tuple` to make sure we never build
    # implicit tuples with no elements, but since users might load
    # data built with previous Griffe versions, we must be defensive here.
    if not self.elements:
        yield "()"
        return
    if not self.implicit:
        yield "("
    yield from _join(self.elements, ", ", flat=flat)
    if len(self.elements) == 1:
        yield ","
    if not self.implicit:
        yield ")"

modernize ¤

modernize() -> ExprTuple

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
1094
1095
1096
1097
1098
def modernize(self) -> ExprTuple:
    return ExprTuple(
        elements=[el if isinstance(el, str) else el.modernize() for el in self.elements],
        implicit=self.implicit,
    )

ExprUnaryOp dataclass ¤

ExprUnaryOp(operator: str, value: str | Expr)

Bases: Expr


              flowchart TD
              griffe.ExprUnaryOp[ExprUnaryOp]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprUnaryOp
                


              click griffe.ExprUnaryOp href "" "griffe.ExprUnaryOp"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Unary operations like -1.

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

operator instance-attribute ¤

operator: str

Unary operator.

path property ¤

path: str

Path of the expressed name/attribute.

value instance-attribute ¤

value: str | Expr

Value.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
1110
1111
1112
1113
1114
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    yield self.operator
    if self.operator == "not":
        yield " "
    yield from _yield(self.value, flat=flat, outer_precedence=_get_precedence(self))

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprYield dataclass ¤

ExprYield(value: str | Expr | None = None)

Bases: Expr


              flowchart TD
              griffe.ExprYield[ExprYield]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprYield
                


              click griffe.ExprYield href "" "griffe.ExprYield"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Yield statements like yield a.

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

path property ¤

path: str

Path of the expressed name/attribute.

value class-attribute instance-attribute ¤

value: str | Expr | None = None

Yielded value.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
1136
1137
1138
1139
1140
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    yield "yield"
    if self.value is not None:
        yield " "
        yield from _yield(self.value, flat=flat, outer_precedence=_OperatorPrecedence.STARRED)

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self

ExprYieldFrom dataclass ¤

ExprYieldFrom(value: str | Expr)

Bases: Expr


              flowchart TD
              griffe.ExprYieldFrom[ExprYieldFrom]
              griffe._internal.expressions.Expr[Expr]

                              griffe._internal.expressions.Expr --> griffe.ExprYieldFrom
                


              click griffe.ExprYieldFrom href "" "griffe.ExprYieldFrom"
              click griffe._internal.expressions.Expr href "" "griffe._internal.expressions.Expr"

Yield statements like yield from a.

Methods:

  • __iter__ –

    Iterate on the expression syntax and elements.

  • as_dict –

    Return the expression as a dictionary.

  • iterate –

    Iterate on the expression elements.

  • modernize –

    Modernize the expression.

Attributes:

canonical_name property ¤

canonical_name: str

Name of the expressed name/attribute/parameter.

canonical_path property ¤

canonical_path: str

Path of the expressed name/attribute.

classname property ¤

classname: str

The expression class name.

is_classvar property ¤

is_classvar: bool

Whether this attribute is annotated with ClassVar.

is_generator property ¤

is_generator: bool

Whether this expression is a generator.

is_iterator property ¤

is_iterator: bool

Whether this expression is an iterator.

is_tuple property ¤

is_tuple: bool

Whether this expression is a tuple.

path property ¤

path: str

Path of the expressed name/attribute.

value instance-attribute ¤

value: str | Expr

Yielded-from value.

__iter__ ¤

__iter__() -> Iterator[str | Expr]

Iterate on the expression syntax and elements.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
185
186
187
def __iter__(self) -> Iterator[str | Expr]:
    """Iterate on the expression syntax and elements."""
    yield from self.iterate(flat=False)

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return the expression as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Configuration options (none available yet).

Returns:

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
218
219
220
221
222
223
224
225
226
227
228
def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return the expression as a dictionary.

    Parameters:
        **kwargs: Configuration options (none available yet).


    Returns:
        A dictionary.
    """
    return _expr_as_dict(self, **kwargs)

iterate ¤

iterate(*, flat: bool = True) -> Iterator[str | Expr]

Iterate on the expression elements.

Parameters:

  • flat ¤

    (bool, default: True ) –

    Expressions are trees.

    When flat is false, this method iterates only on the first layer of the tree. To iterate on all the subparts of the expression, you have to do so recursively. It allows to handle each subpart specifically (for example subscripts, attribute, etc.), without them getting rendered as strings.

    On the contrary, when flat is true, the whole tree is flattened as a sequence of strings and instances of Names.

Yields:

  • str | Expr –

    Strings and names when flat, strings and expressions otherwise.

Source code in packages/griffelib/src/griffe/_internal/expressions.py 
1150
1151
1152
def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
    yield "yield from "
    yield from _yield(self.value, flat=flat, outer_precedence=_OperatorPrecedence.STARRED)

modernize ¤

modernize() -> Expr

Modernize the expression.

For example, use PEP 604 type unions | instead of typing.Union.

Returns:

  • Expr –

    A modernized expression.

Referenced by:
Source code in packages/griffelib/src/griffe/_internal/expressions.py 
208
209
210
211
212
213
214
215
216
def modernize(self) -> Expr:
    """Modernize the expression.

    For example, use PEP 604 type unions `|` instead of `typing.Union`.

    Returns:
        A modernized expression.
    """
    return self