Development Guidelines¶

Runtime Type Checking 🔍¶

mesa-frames includes optional runtime type checking using beartype for development and debugging purposes. This feature helps catch type-related errors early during development and testing.

Development Environment Setup¶

Option 1: Hatch Development Environment (Recommended)¶

The easiest way to enable runtime type checking is to use Hatch's development environment:

# Enter the development environment (auto-enables runtime type checking)
hatch shell dev

# Verify it's enabled
python -c "import os; print('Runtime type checking:', os.getenv('MESA_FRAMES_RUNTIME_TYPECHECKING'))"
# → Runtime type checking: true

Option 2: Manual Environment Variable¶

For other development setups, you can manually enable runtime type checking:

Runtime type checking can be enabled by setting the MESA_FRAMES_RUNTIME_TYPECHECKING environment variable:

export MESA_FRAMES_RUNTIME_TYPECHECKING=1
# or
export MESA_FRAMES_RUNTIME_TYPECHECKING=true
# or
export MESA_FRAMES_RUNTIME_TYPECHECKING=yes

Usage Examples¶

For Development and Testing¶

# Enable runtime type checking for testing
MESA_FRAMES_RUNTIME_TYPECHECKING=1 uv run pytest

# Enable runtime type checking for running scripts
MESA_FRAMES_RUNTIME_TYPECHECKING=1 uv run python your_script.py

In Your IDE or Development Environment¶

VS Code (Already Configured):

• Debugging: Runtime type checking is automatically enabled when using VS Code's debugger
• Testing: Automatically enabled when running tests through VS Code's testing interface

• Manual override: You can also add it manually in .vscode/settings.json:

  {
      "python.env": {
          "MESA_FRAMES_RUNTIME_TYPECHECKING": "1"
      }
  }
  

PyCharm: In your run configuration, add the environment variable:

MESA_FRAMES_RUNTIME_TYPECHECKING=1

How It Works¶

When enabled, the runtime type checking system:

1. Automatically instruments all mesa-frames packages with beartype decorators
2. Validates function arguments and return values at runtime
3. Provides detailed error messages when type mismatches occur
4. Helps catch type-related bugs during development

Requirements¶

Runtime type checking requires the optional beartype dependency:

# Install beartype for runtime type checking
uv add beartype
# or
pip install beartype

Performance Considerations¶

The overhead includes:

• Function call interception and validation
• Type checking computations at runtime
• Memory usage for type checking infrastructure

When to Use Runtime Type Checking¶

✅ Automatically enabled (recommended):

• Hatch development environment (hatch shell dev)
• VS Code debugging sessions
• VS Code test execution
• Contributing to mesa-frames development

✅ Manual activation (when needed):

• Development and debugging in other IDEs
• Writing new features outside VS Code
• Running unit tests from command line
• Troubleshooting type-related issues

❌ Not recommended for:

• Production deployments
• Performance benchmarking
• Large-scale simulations
• Final model runs

Troubleshooting¶

If you encounter issues with runtime type checking:

1. Check beartype installation:

uv run python -c "import beartype; print(beartype.__version__)"

1. Verify environment variable:

echo $MESA_FRAMES_RUNTIME_TYPECHECKING

1. For automatic configurations:
2. Hatch dev: Ensure you're in the dev environment (hatch shell dev)
3. VS Code debugging: Check that the debugger configuration in .vscode/launch.json includes the environment variable

4. VS Code testing: Verify that .env.test file exists and contains MESA_FRAMES_RUNTIME_TYPECHECKING=true

5. Check for warnings in your application logs

6. Disable temporarily if needed:

unset MESA_FRAMES_RUNTIME_TYPECHECKING