Metadata-Version: 2.4
Name: pyx-compiler
Version: 1.0.0
Summary: A custom Python-subset compiler and virtual machine written in Python
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# PyX Compiler

PyX is a Python-inspired programming language and custom compiler implemented in Python.

PyX is designed as an educational compiler project with its own lexer, parser and AST, semantic analyzer and type system, intermediate representation, bytecode generator, virtual machine, and command-line interface (`pyxc`).

## Architecture

```text
PyX Source
    |
    v
Lexer
    |
    v
Parser
    |
    v
AST
    |
    v
Semantic Analysis + Type System
    |
    v
Intermediate Representation (IR)
    |
    v
Bytecode
    |
    v
Virtual Machine
    |
    v
Program Output
```

## Current Features

- Variables and assignment
- `int`, `float`, `bool`, `string`, `None`
- Lists, tuples, and dictionaries
- Indexed access and indexed assignment
- Augmented assignment and augmented indexed assignment
- Arithmetic, comparison, boolean, and membership operators
- Short-circuit `and` / `or`
- `if`, `elif`, `else`
- `while`, `for`, `range`
- `break` and `continue`
- Functions, return values, and recursion
- `print()`, `input()`, `len()`
- Comments and Python-style indentation
- Semantic validation and runtime diagnostics
- Custom bytecode and virtual machine

## Requirements

- Python 3.11 or newer
- Git
- Windows, Linux, or macOS

The project is developed and tested with Python 3.11.x.

## Developer Installation

Clone using SSH:

```bash
git clone git@github.com:technomaxxa/pyx-compiler.git
cd pyx-compiler
```

Create a virtual environment:

```bash
python -m venv .venv
```

Windows PowerShell:

```powershell
.venv\Scripts\Activate.ps1
```

Windows Git Bash:

```bash
source .venv/Scripts/activate
```

Linux/macOS:

```bash
source .venv/bin/activate
```

Install in editable mode:

```bash
python -m pip install --upgrade pip
pip install -e .
```

Verify the CLI:

```bash
pyxc --help
```

Run an example:

```bash
pyxc examples/hello.pyx
```

## Testing

Run the complete test suite from the repository root:

```bash
pytest
```

## Using PyX

Create `hello.pyx`:

```pyx
print("Hello from PyX")
```

Run it:

```bash
pyxc hello.pyx
```

## Project Structure

```text
pyx-compiler/
├── .github/
├── docs/
├── examples/
├── src/
│   └── pyx/
│       ├── lexer/
│       ├── parser/
│       ├── semantic/
│       ├── ir/
│       ├── bytecode/
│       ├── vm/
│       ├── errors/
│       ├── __init__.py
│       └── main.py
├── tests/
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── SECURITY.md
├── pyproject.toml
├── requirements.txt
└── .gitignore
```

## Documentation

See the `docs/` directory for the language specification, installation guide, architecture, compiler pipeline, virtual-machine documentation, developer guide, and examples.

## End-User Installation

After the package is published to PyPI, end users can install a released version with:

```bash
pip install pyx-compiler
```

Then run:

```bash
pyxc program.pyx
```

## Developer Mode

Developers can work directly with the source repository:

```bash
git clone git@github.com:technomaxxa/pyx-compiler.git
cd pyx-compiler
pip install -e .
```

After modifying `src/pyx/`:

```bash
pytest
pyxc program.pyx
```

## Releases

PyX uses Git tags and GitHub Releases for versioned compiler releases.

Example release tags:

```text
v1.0.0
v1.0.1
v1.1.0
```

## License

PyX is distributed under the proprietary terms in `LICENSE`. The license is not an open-source license.

## Security

Never commit passwords, API keys, access tokens, private SSH keys, or other secrets. See `SECURITY.md` for security-reporting guidance.

## Project Status

PyX is a custom compiler and virtual-machine project intended for education, experimentation, and compiler engineering study.
