Typhon-Language 0.2.0

Typhon programming language

Typhon

Typhon is a Python-compatible language with modern syntax: brace-based blocks, static type checking, and expression-oriented features.

• GitHub repository: Typhon
• PyPI package: Typhon-Language
• VSCode extension: Typhon Language Support from GitHub Repository

Getting Started

Install Typhon via pip:

pip install typhon-language

Run Typhon from the command line:

typhon --help

Create a simple Typhon program in hello.typh:

def main() {
    print("Hello, Typhon!")
}
main()

Run the program:

typhon run hello.typh

Or run directly using uvx:

uvx --from typhon-language typhon run hello.typh

Design Concepts

Typhon is built on three core pillars:

1. Safety: As expected in modern programming languages, Typhon enforces safety through static typing, lexical scopes, immutable-by-default variables (let), and null safety features (?., ??, ?(), ?[]).
2. Expressiveness: Expression-oriented design with functional programming features. Control comprehension forms for if, match, try, and so on enable concise, value-returning expressions. Function literals, placeholders and pipe operators facilitate clean and readable code.
3. Python Interoperability: Typhon compiles directly to Python, allowing you to use the vast ecosystem of Python libraries seamlessly while enjoying a modern syntax.

Sample code

See more examples in Typhon Tests.

Documentation

For a complete guide to the language, please visit the Typhon Reference Manual.

Quick Links

• Lexical Structure (Comments, Keywords, Delimiters)
• Types
• Variables
• Expressions
• Statements
• Definitions (Functions, Classes, Modules)
• Removed Features

Syntax Changes from Python

Typhon keeps Python semantics where possible, but changes syntax and some safety rules.

Main Changes

• Brace Scoping: Typhon uses { ... } for blocks instead of indentation. Both ; and line breaks can terminate statements. See Lexical Structure.
• Static Typing: Type checking is enforced at compile time. Currently powered by basedpyright type checker.
• Declarations: Variables must be declared with let (immutable) or var (mutable). See Variables.

Syntax Extensions

• Null Safety: ?., ??, ?(), ?[] operators. See Null Safety.
• Function literals: Arrow functions such as (x) => { return x + 1 } have the same capability as regular functions. See Function literals.
• Pipe Operator: x |> f for function chaining. See Pipe Operator.
• Placeholders: _ for concise anonymous functions (e.g., _ + 1). See Placeholders.
• Control Comprehensions: Control forms as expressions (for example, (if (c) x else y)). if/while/for/let/try/with/match are supported. See Comprehensions.
• Pattern Matching: Enhanced match, if-let, and let-else statements. See Control Flow.
• self Keyword: In non-static methods, self is implicit and explicit self parameters are forbidden (including __init__). See Classes.
• Data Records: Anonymous immutable records such as {|x = 1|}. See Types.
• Block Comments: #( ... )# allows nested comments.

Detailed Design Changes

• Logical Operators: &&, ||, ! replace and, or, not (though Python keywords are still reserved).
• Operator Notes: ?? is weaker than ||; |>/?|> are weaker than ?? and left-associative; ?-family operators short-circuit.
• Const Parameters: Function parameters are immutable by default.
• Header Parentheses Convention: This rule is general: forms that introduce a braced inner scope use parenthesized headers, while forms that declare into the current scope omit them.
• Assignment Restriction: Reassignment is only to single variable names; pattern reassignment is forbidden.
• if-let Rule: Single-variable target means None check; non-single target means pattern-success check.
• Line Breaks: Stricter rules for line continuations. See Lexical Structure.

Syntax Restrictions

Some Python features are removed to enforce safety and clarity. See Removed Features.

• No del, global, nonlocal.
• No wildcard imports.
• No chained assignments (a = b = c).
• No control statements inside class bodies.

Usage

Typhon can be run directly or translated to Python.

.typh files are Typhon source files. In directory mode, Typhon processes all .typh files.

Typhon uses a .typhon directory under source paths for translated Python and caches. At the same time, .typhon-server is used for language server temporal data.

Run

Run a Typhon source file or directory.

typhon run <source> [args...]

Translate

Translate Typhon code to Python.

typhon translate <source> [-o output_dir]

Type Check

Run type checking on Typhon code.

typhon type_check <source>

Format

Format Typhon source. By default, prints formatted code to stdout. Use -i or --inplace to edit files in place. Abort formatting on syntax error.

typhon format <source> [-i]

Future Plans

See Future Plans for planned features like compile-time controls (static if) and known limitations.

Influenced By

Typhon draws inspiration from several modern programming languages:

• Python
• TypeScript
• Swift
• Rust
• Scala
• F#

Agent Configuration (Copilot / Claude Code)

This repository contains shared agent configuration files:

• AGENTS.md: repository rules and policies.
• SKILLS.md: minimal operational workflow and script usage.

Tool-specific entry files refers the shared files:

• .github/copilot-instructions.md
• CLAUDE.md

Repository policy highlights:

• Use uv run -m ... as the default script execution style.
• Keep documentation concise, practical, and example-focused rather than long or decorative.