Skip to content

README.md

Latest commit

 

History

History
85 lines (57 loc) · 3.61 KB

README.md

File metadata and controls

85 lines (57 loc) · 3.61 KB

PyLua Internal Documentation

This directory contains internal documentation for PyLua v0.3 development. These documents are intended for contributors, maintainers, and anyone interested in understanding the implementation details of the PyLua interpreter.

Documents Overview

ROADMAP.md

Post-0.3 roadmap and milestones

This is the planning document for work after the 0.3 release. It outlines:

  • Planned milestones and future features
  • High-level priorities for v3.1+ (classes/modules, decorators, context managers, async, etc.)
  • Performance and footprint goals

Start here if you want to understand what's next.

LANGUAGE_IMPLEMENTATION.md

Guide on interpreter implementation

This document provides background on how programming language interpreters work, with specific focus on:

  • The standard interpreter pipeline: Lexer → Parser → AST → Compiler → VM
  • CPython's internal architecture and execution model
  • Python 3.12 syntax features and grammar changes
  • Object system design and memory management
  • Bytecode compilation and virtual machine execution
  • Practical guidance for implementing Python semantics in Luau

Essential reading for understanding the theoretical foundation and technical challenges of building a Python interpreter.

Target Audience

For Contributors

  • New contributors: Start with ROADMAP.md to understand upcoming work and priorities
  • Core developers: Use both documents as reference for implementation decisions
  • Language experts: LANGUAGE_IMPLEMENTATION.md provides the theoretical foundation

For Maintainers

  • Architecture decisions should align with the principles outlined in these documents
  • Use the sections in ROADMAP.md for milestone planning
  • Reference the compliance goals when evaluating feature requests

Key Design Principles

Based on these documents, PyLua v0.3 follows these core principles:

  1. Python 3.12 Compliance: Support Python 3.12 syntax and below for focused, manageable scope
  2. CPython-Inspired Architecture: Follow proven interpreter design patterns
  3. Lupa-Style API: Familiar interface for embedders (Python-in-Luau)
  4. Modular Design: Clean separation between lexer, parser, compiler, and VM
  5. Roblox Optimization: Designed specifically for the Roblox/Luau environment

Contributing Guidelines

When contributing to PyLua v0.3:

  1. Read both documents to understand the architecture and goals
  2. Follow the phase plan - implement features in the correct order
  3. Maintain Python compliance - reference CPython behavior for accuracy
  4. Write comprehensive tests - each component needs thorough test coverage
  5. Document design decisions - update these docs when making architectural changes

Quick Reference

Need to... Reference
See upcoming features and priorities ROADMAP.md - Post-0.3 milestones
Implement lexer/tokenizer LANGUAGE_IMPLEMENTATION.md - Lexical Analysis
Design AST nodes LANGUAGE_IMPLEMENTATION.md - Parsing and AST
Build the virtual machine LANGUAGE_IMPLEMENTATION.md - CPython Execution Model
Understand Python 3.12 features LANGUAGE_IMPLEMENTATION.md - Python 3.12 Syntax Updates

External References

These documents reference and build upon: