't Es simpel, 't es plansen, 't es Vlaams!

Home / Docs / Magic Mode

Magic Mode

Run .plats files directly with Python — no compilation step needed.

It just works.

What is Magic Mode?

Magic Mode lets you execute .plats files directly with Python's standard interpreter, just like a .py file. No need to use plats run or compile your code first.

Direct execution

Run .plats files like .py files

No compilation

Skip the build step entirely

Zero config

Just add one line to your file

Seamless integration

Works with all Python tools

How it works

Magic Mode uses Python's PEP 263 encoding declaration and the site-packages .pth mechanism to automatically transpile and execute Platskript code.

  1. Python detects # coding: vlaamsplats (PEP 263) and requests the corresponding codec
  2. During startup, Python's site module processes .pth files in site-packages
  3. VlaamsCodex installs vlaamscodex_autoload.pth which registers the custom codec
  4. The codec decodes UTF-8 bytes, strips the encoding declaration, and transpiles Platskript to Python
  5. Python executes the generated Python code transparently

Getting started

Step 1: Install Vlaams Codex

pip install vlaamscodex

Step 2: Create a .plats file

# coding: vlaamsplats
plan doe
  klap tekst gdag aan weeireld amen
gedaan

Step 3: Run it directly

python hello.plats

That's it. No need for plats run or any build step — Python handles it automatically.

Advanced usage

Using with shebang

You can also use Magic Mode with a shebang for executable .plats files:

#!/usr/bin/env python
# coding: vlaamsplats

plan doe
  klap tekst gdag aan weeireld amen
gedaan
chmod +x hello.plats
./hello.plats

Integration with Python tools

Magic Mode works with:

  • Python debugger (pdb): python -m pdb script.plats
  • Profiling: python -m cProfile script.plats
  • Code coverage: python -m coverage run script.plats
  • Any tool that accepts a .py file

Limitations

Important: Python flags

Magic Mode does not work with these flags because they disable the site module:

  • -S / --no-site — disables the site module
  • -I / --isolated — isolated mode restricts site-packages

Fallback

If Magic Mode is unavailable, use the standard command:

plats run script.plats

This compiles and executes your Platskript code normally.

Troubleshooting

Codec not found

If you get codec not found: vlaamscodex, make sure vlaamscodex is installed correctly:

pip install --force-reinstall vlaamscodex

Common issues

  • ImportError: reinstall with pip install --force-reinstall vlaamscodex
  • Using the -S flag: remove -S from your Python command
  • Virtual environments: install vlaamscodex inside your venv

Examples

Simple hello world

# coding: vlaamsplats
plan doe
  klap tekst gdag aan weeireld amen
gedaan

Using functions

# coding: vlaamsplats
plan doe
  maak funksie groet met naam doe
    klap tekst gdag plakt spatie plakt da naam amen
  gedaan

  roep groet met tekst Piet amen
gedaan

Need help?

If you run into issues with Magic Mode:

Try in Playground →