templates

Provide semantic-facing template metadata for compile-time specialization without requiring parser-level syntax support.

Classes:

• TemplateParam –
• TemplateTypeVar –
• UnionType –

Functions:

• add_generated_template_node –
• clear_generated_template_nodes –
• generated_template_nodes –
• get_template_args –
• get_template_params –
• is_template_node –
• is_template_specialization –
• mark_template_specialization –
• set_template_args –
• set_template_params –
• template_specialization_name –

TemplateParam dataclass

TemplateParam(
    name: str,
    bound: DataType,
    loc: SourceLocation = NO_SOURCE_LOCATION,
)

Describe one bounded template variable attached to a function or method declaration. attributes: name: type: str bound: type: astx.DataType loc: type: astx.SourceLocation

TemplateTypeVar

TemplateTypeVar(name: str, *, bound: DataType)

Bases: AnyType

Represent one unresolved template type parameter inside function signatures or local declared types before specialization. attributes: name: type: str bound: type: astx.DataType

Methods:

• get_struct –
• to_json –
• to_yaml –

Source code in packages/astx/src/astx/types/generic.py

def __init__(self, name: str, *, bound: astx.DataType) -> None:
    """
    title: Initialize one template type variable.
    parameters:
      name:
        type: str
      bound:
        type: astx.DataType
    """
    super().__init__()
    self.name = name
    self.bound = bound

get_struct

get_struct(simplified: bool = False) -> ReprStruct

Source code in packages/astx/src/astx/types/generic.py

def get_struct(self, simplified: bool = False) -> astx.base.ReprStruct:
    """
    title: Build one repr structure for a template type variable.
    parameters:
      simplified:
        type: bool
    returns:
      type: astx.base.ReprStruct
    """
    key = f"TEMPLATE_TYPE_VAR[{self.name}]"
    value = cast(
        astx.base.DataTypesStruct,
        {
            "name": self.name,
            "bound": self.bound.get_struct(simplified),
        },
    )
    return self._prepare_struct(key, value, simplified)

to_json

to_json(simplified: bool = False) -> str

Source code in packages/astx/src/astx/base.py

def to_json(self, simplified: bool = False) -> str:
    """
    title: Return an json string that represents the object.
    parameters:
      simplified:
        type: bool
    returns:
      type: str
    """
    return json.dumps(self.get_struct(simplified=simplified), indent=2)

to_yaml

to_yaml(simplified: bool = False) -> str

Source code in packages/astx/src/astx/base.py

def to_yaml(self, simplified: bool = False) -> str:
    """
    title: Return an yaml string that represents the object.
    parameters:
      simplified:
        type: bool
    returns:
      type: str
    """
    return str(
        yaml.dump(self.get_struct(simplified=simplified), sort_keys=False)
    )

UnionType

UnionType(
    members: Iterable[DataType],
    *,
    alias_name: str | None = None,
)

Bases: AnyType

Represent one union of concrete type references that semantic analysis may enumerate as a finite type domain. attributes: members: type: tuple[astx.DataType, Ellipsis] alias_name: type: str | None

Methods:

• get_struct –
• to_json –
• to_yaml –

Source code in packages/astx/src/astx/types/generic.py

def __init__(
    self,
    members: Iterable[astx.DataType],
    *,
    alias_name: str | None = None,
) -> None:
    """
    title: Initialize one finite union type.
    parameters:
      members:
        type: Iterable[astx.DataType]
      alias_name:
        type: str | None
    """
    super().__init__()
    self.members = tuple(members)
    self.alias_name = alias_name

get_struct

get_struct(simplified: bool = False) -> ReprStruct

Source code in packages/astx/src/astx/types/generic.py

def get_struct(self, simplified: bool = False) -> astx.base.ReprStruct:
    """
    title: Build one repr structure for a finite union type.
    parameters:
      simplified:
        type: bool
    returns:
      type: astx.base.ReprStruct
    """
    key = f"UNION[{self.alias_name or id(self)}]"
    value = cast(
        astx.base.DataTypesStruct,
        [member.get_struct(simplified) for member in self.members],
    )
    return self._prepare_struct(key, value, simplified)

to_json

to_json(simplified: bool = False) -> str

Source code in packages/astx/src/astx/base.py

def to_json(self, simplified: bool = False) -> str:
    """
    title: Return an json string that represents the object.
    parameters:
      simplified:
        type: bool
    returns:
      type: str
    """
    return json.dumps(self.get_struct(simplified=simplified), indent=2)

to_yaml

to_yaml(simplified: bool = False) -> str

Source code in packages/astx/src/astx/base.py

def to_yaml(self, simplified: bool = False) -> str:
    """
    title: Return an yaml string that represents the object.
    parameters:
      simplified:
        type: bool
    returns:
      type: str
    """
    return str(
        yaml.dump(self.get_struct(simplified=simplified), sort_keys=False)
    )

add_generated_template_node

add_generated_template_node(
    module: Module, node: AST
) -> None

Source code in packages/astx/src/astx/templates.py

@typechecked
def add_generated_template_node(
    module: astx.Module,
    node: astx.AST,
) -> None:
    """
    title: Attach one generated template node to a module.
    parameters:
      module:
        type: astx.Module
      node:
        type: astx.AST
    """
    nodes = list(getattr(module, _GENERATED_TEMPLATE_NODES_ATTR, ()))
    nodes.append(node)
    setattr(module, _GENERATED_TEMPLATE_NODES_ATTR, tuple(nodes))

clear_generated_template_nodes

clear_generated_template_nodes(module: Module) -> None

Source code in packages/astx/src/astx/templates.py

@typechecked
def clear_generated_template_nodes(module: astx.Module) -> None:
    """
    title: Remove generated template nodes attached to one module.
    parameters:
      module:
        type: astx.Module
    """
    setattr(module, _GENERATED_TEMPLATE_NODES_ATTR, ())

generated_template_nodes

generated_template_nodes(module: Module) -> tuple[AST, ...]

Source code in packages/astx/src/astx/templates.py

@typechecked
def generated_template_nodes(module: astx.Module) -> tuple[astx.AST, ...]:
    """
    title: Return the generated template nodes attached to a module.
    parameters:
      module:
        type: astx.Module
    returns:
      type: tuple[astx.AST, Ellipsis]
    """
    value = getattr(module, _GENERATED_TEMPLATE_NODES_ATTR, ())
    return tuple(value)

get_template_args

get_template_args(node: AST) -> tuple[DataType, ...] | None

Source code in packages/astx/src/astx/templates.py

@typechecked
def get_template_args(node: astx.AST) -> tuple[astx.DataType, ...] | None:
    """
    title: Return the explicit template arguments attached to one AST node.
    parameters:
      node:
        type: astx.AST
    returns:
      type: tuple[astx.DataType, Ellipsis] | None
    """
    value = getattr(node, _TEMPLATE_ARGS_ATTR, None)
    if value is None:
        return None
    return tuple(value)

get_template_params

get_template_params(node: AST) -> tuple[TemplateParam, ...]

Source code in packages/astx/src/astx/templates.py

@typechecked
def get_template_params(node: astx.AST) -> tuple[TemplateParam, ...]:
    """
    title: Return the template parameters attached to one AST node.
    parameters:
      node:
        type: astx.AST
    returns:
      type: tuple[TemplateParam, Ellipsis]
    """
    value = getattr(node, _TEMPLATE_PARAMS_ATTR, ())
    return tuple(value)

is_template_node

is_template_node(node: AST) -> bool

Source code in packages/astx/src/astx/templates.py

@typechecked
def is_template_node(node: astx.AST) -> bool:
    """
    title: Return whether one AST node carries template parameters.
    parameters:
      node:
        type: astx.AST
    returns:
      type: bool
    """
    return bool(get_template_params(node))

is_template_specialization

is_template_specialization(node: AST) -> bool

Source code in packages/astx/src/astx/templates.py

@typechecked
def is_template_specialization(node: astx.AST) -> bool:
    """
    title: Return whether one AST node is a generated specialization.
    parameters:
      node:
        type: astx.AST
    returns:
      type: bool
    """
    return template_specialization_name(node) is not None

mark_template_specialization

mark_template_specialization(
    node: AST, specialization_name: str
) -> None

Source code in packages/astx/src/astx/templates.py

@typechecked
def mark_template_specialization(
    node: astx.AST,
    specialization_name: str,
) -> None:
    """
    title: Mark one AST node as a generated template specialization.
    parameters:
      node:
        type: astx.AST
      specialization_name:
        type: str
    """
    setattr(node, _TEMPLATE_SPECIALIZATION_ATTR, specialization_name)

set_template_args

set_template_args(
    node: AST, args: Iterable[DataType] | None
) -> None

Source code in packages/astx/src/astx/templates.py

@typechecked
def set_template_args(
    node: astx.AST,
    args: Iterable[astx.DataType] | None,
) -> None:
    """
    title: Attach explicit template arguments to one call-like AST node.
    parameters:
      node:
        type: astx.AST
      args:
        type: Iterable[astx.DataType] | None
    """
    if args is None:
        setattr(node, _TEMPLATE_ARGS_ATTR, None)
        return
    setattr(node, _TEMPLATE_ARGS_ATTR, tuple(args))

set_template_params

set_template_params(
    node: AST, params: Iterable[TemplateParam]
) -> None

Source code in packages/astx/src/astx/templates.py

@typechecked
def set_template_params(
    node: astx.AST,
    params: Iterable[TemplateParam],
) -> None:
    """
    title: Attach template parameters to one AST node.
    parameters:
      node:
        type: astx.AST
      params:
        type: Iterable[TemplateParam]
    """
    setattr(node, _TEMPLATE_PARAMS_ATTR, tuple(params))

template_specialization_name

template_specialization_name(node: AST) -> str | None

Source code in packages/astx/src/astx/templates.py

@typechecked
def template_specialization_name(node: astx.AST) -> str | None:
    """
    title: Return the generated specialization name for one AST node.
    parameters:
      node:
        type: astx.AST
    returns:
      type: str | None
    """
    value = getattr(node, _TEMPLATE_SPECIALIZATION_ATTR, None)
    return value if isinstance(value, str) else None