typja 0.1.0

Type checker for your Jinja2 templates

Typja

An experimental tool to check Jinja templates for type errors using Python's type hints. It parses Jinja templates, extracts variable usage, and checks them against provided type information.

Features

• Type Checking for Jinja2 Templates: Validate that variables in your Jinja2 templates match their declared types
• Python Type Hints Integration: Leverage your existing Python type annotations to catch template errors early
• Pre-commit Integration: Built-in pre-commit hook for automated checking
• Flexible Configuration: Customize checking behavior with typja.toml
• Rich Error Reports: Detailed error messages with code snippets and suggestions
• Watch Mode: Monitor templates for changes and run checks automatically

Quick Start

Installation

pip install typja

Basic Usage

# Check all templates in current directory
typja check

# Run in watch mode
typja watch

# Initialize a new typja.toml configuration
typja init

Configuration

Create a typja.toml file in your project root with typja init or manually:

[project]
root = "."
paths = ["./models/**/*.py"]
fail_on_warning = false

[environment]
template_dirs = ["./templates"]
include_patterns = ["*.html", "*.jinja", "*.jinja2"]

[linting]
strict = false
prefer_pep604_unions = true
validate_imports = true
validate_variables = true

[errors]
verbosity = "normal"
show_snippets = true
show_hints = true
color = "auto"

Type Annotations in Templates

Use special Jinja2 comments to declare variable types:

{# typja:var user: User #}
{# typja:var items: list[str] #}
{# typja:var count: int #}

<h1>{{ user.name }}</h1>
<ul>
  {% for item in items %}
    <li>{{ item }}</li>
  {% endfor %}
</ul>

Examples

See the examples/fastapi/ directory for a complete FastAPI application with Jinja2 template type checking.

Pre-commit Integration

Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/Daniel-Brai/Typja
    rev: v0.1.0
    hooks:
      - id: typja-check
        # With args
        # args: ["--strict", "--fix"]

Documentation

• Configuration Guide - Detailed configuration options
• Syntax Guide - Template syntax and type annotations

Contributing

See CONTRIBUTING.md for development instructions.

License

See LICENSE for details.