From Python to Sifr

Sifr uses Python-shaped syntax, but it is not Python with a faster runtime. It is a compiled language with static types, ownership, and typed errors. The syntax should feel familiar; the contract is stricter.

Same Shape, Different Contract

If you know Python, start by keeping the surface model and changing the failure model. Sifr tries to make illegal states visible before a binary is built: missing values are typed, fallible calls return Result, and values crossing ownership or task boundaries must be explicit.

Python concept	Sifr shape	Difference
Type hints	Type annotations	Enforced by the compiler, not optional metadata
Exceptions	`Result[T, E]` plus `try`/`except`	Recoverable errors are values, not stack unwinds
Missing values	`T \| None`	You must check `None` before using the inner value
Imports	`sifr.*` modules and packages	Bare CPython stdlib names are not aliases
Integers	Exact `int` plus explicit fixed-width types	Ordinary arithmetic stays simple; representation-sensitive widths are explicit
Bytes	First-class `bytes`	Encode and decode at typed boundaries; do not rely on platform-default text behavior
Async	`async def`, `await`, `sifr.task`	Structured scopes, typed cancellation evidence, no global event loop
Function calls	Borrow by default	Heap values are not moved unless `own` is used
Mutation	`mut` and `own mut`	Parameter mutation is explicit
`assert`	Assertion	Programmer invariant, not recoverable control flow

What Carries Over

You still write def, class, if, for, list and dict literals, comprehensions, f-strings, match, async def, and await. The goal is not to make you learn a new surface grammar before you can write useful programs.

def describe(value: int | str) -> str:
    if isinstance(value, int):
        return f"number: {value}"
    return f"text: {value}"

The difference is that annotations are part of the program. If describe promises str, every path must return str.

What Changes At Compile Time

Sifr turns several Python runtime surprises into compile-time obligations:

a dictionary lookup that might miss returns V | None;
a fallible function returns Result[T, E];
a parameter is immutable unless marked mut;
a value is borrowed by default unless a function asks for own;
a spawned task can only capture values that are owned and sendable.

users: dict[str, int] = {"alice": 30}
age: int | None = users["bob"]

if age is not None:
    print(age + 1)
else:
    print("user not found")

Sifr docs are the source of truth for Sifr semantics. Python references are useful for syntax vocabulary, but they do not define Sifr’s type, ownership, error, or package model.

Common Surprises

Type hints are not hints

Sifr annotations are checked before the program runs. Treat them as part of the language, not as documentation for a separate runtime.

Exceptions do not unwind normal errors

raise inside a Result-returning function produces an error value. try/except handles that value explicitly.

Imports use the Sifr namespace

Use from sifr.collections import Counter, not import collections. Supported stdlib-style modules live under sifr.*; see the collections import example.

Calling installed Python packages is explicit

Use sifr.python when you intentionally embed CPython and call packages from a uv-created environment. Configure the root package’s [python] and [trust] tables first; see Embedded Python Interop.

Mutation is explicit

Use mut when a function should mutate a borrowed parameter, and own mut when it should take ownership and mutate the value.

Where To Go Next

Mental Model Shift

Follow the practical path from Python habits to Sifr’s compile-time model.

Ownership and Mutability

Learn mut, own, and borrow-by-default rules.

Error Handling

See how Result and try/except replace recoverable exceptions.

Embedded Python Interop

Call installed Python packages through explicit environment and trust boundaries.

Get Started

Learn Sifr

CLI

Package Management

Standard Library

Concurrency

Error Codes

From Python to Sifr

Same Shape, Different Contract

What Carries Over

What Changes At Compile Time

Common Surprises

Where To Go Next

Mental Model Shift

Ownership and Mutability

Error Handling

Embedded Python Interop

​Same Shape, Different Contract

​What Carries Over

​What Changes At Compile Time

​Common Surprises

​Where To Go Next

Mental Model Shift

Ownership and Mutability

Error Handling

Embedded Python Interop

Same Shape, Different Contract

What Carries Over

What Changes At Compile Time

Common Surprises

Where To Go Next