Skip to content

Typing & Type Hints

Typing & Type HintingLink

Sierra‑SDK uses strict static typing to ensure safety, clarity, and predictability in all components. This guide helps you apply best practices using mypy, pyright, and Python’s typing system across scripts, invokers, and plugins.

✅ Type Annotations: The BasicsLink

Use fully annotated function signatures. Avoid implicit Any.

Python
1
2
def add(a: int, b: int) -> int:
    return a + b

✔️ Always declare return types ✔️ Prefer str, int, bool, float, None, list[str], dict[str, int], etc.

✅ Advanced Typing in SierraLink

sierra.Param[...]Link

Wrap input parameters using Param[T, SierraOption]. This supports type-checked command-line inputs.

Python
1
2
3
4
5
6
7
8
@invoker.entry_point
def run(
    name: sierra.Param[
        str | None,
        sierra.SierraOption(description="User name", mandatory="MANDATORY")
    ]
) -> None:
    ...

💡 Sierra type-wrappers are fully compatible with MyPy and Pyright.

✅ Callable TypesLink

When registering dependencies, use explicit function signatures.

Python
1
2
3
@invoker.dependency
def compute(value: int) -> int:
    ...

Never leave them untyped—this breaks type checking across invoker dependency graphs.

✅ Use TypedDict for JSON-like ObjectsLink

For structured dicts (e.g. plugin config or JSON schemas), use typing.TypedDict.

Python
1
2
3
4
5
6
import typing

class PluginConfig(typing.TypedDict):
    name: str
    version: str
    enabled: bool

✅ Use Literal for Constrained ValuesLink

Use typing.Literal for fixed string options like "MANDATORY", "PRIMARY", etc.

Python
1
2
def set_flag(mode: typing.Literal["MANDATORY", "OPTIONAL"]) -> None:
    ...

✅ MyPy and PyrightLink

Configure mypy.iniLink

INI
1
2
3
4
5
6
[mypy]
strict = True
ignore_missing_imports = True
disallow_untyped_defs = True
check_untyped_defs = True
warn_unused_ignores = True

Pyright config (pyrightconfig.json)Link

JSON
1
2
3
4
{
  "typeCheckingMode": "strict",
  "reportMissingTypeStubs": false
}

🧠 Best Practices SummaryLink

Rule Example or Tool
Use full type signatures def func(x: int) -> str
Use Param[T, Option] For all invoker arguments
No implicit Any Use mypy --strict
Wrap dicts with TypedDict class MyDict(TypedDict)
Validate literals Literal["A", "B", "C"]

🔒 Static = SafeLink

Static typing helps Sierra:

  • Prevent runtime errors
  • Enable smart auto-complete
  • Ensure plugin contracts are valid
  • Document APIs without ambiguity

❗️ All contributions to Sierra‑SDK must pass mypy and pyright with zero errors.