Metadata-Version: 2.4
Name: pyseu
Version: 0.1.3
Summary: Python Execution State Explorer — observe what Python executed and how state changed
Author: Pyseu
License: MIT
Project-URL: Repository, https://github.com/ChandanHegde07/pyseu
Keywords: debugging,tracing,education,development
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Pyseu — Python Execution State Explorer

Pyseu is a lightweight, local Python developer utility that helps you understand what Python actually executed and how program state changed during execution.

Pyseu works alongside Python's existing interpreter. It observes runtime execution and presents the execution flow and state changes in a clean terminal format.

## Install

Install Pyseu directly from PyPI:

```bash
pip install pyseu
```

Or install the project from source:

```bash
git clone <repository-url>
cd pyseu
pip install -e .
```

## Usage

Run any Python program with:

```bash
pyseu program.py
```

Show the version:

```bash
pyseu --version
```

Show help:

```bash
pyseu -h
```

## Example

Given `example.py`:

```python
x = 10
y = 20
z = x + y
print(z)
```

Run:

```bash
pyseu example.py
```

Output:

```
Pyseu — Python Execution State Explorer
[1] x = 10
    x: None → 10
[2] y = 20
    y: None → 20
[3] z = x + y
    z: None → 30
[4] print(z)
    PROGRAM OUTPUT: 30
Execution completed successfully.
```

### Class Example

Given `stock.py`:

```python
class Solution:
    def maxProfit(self, prices):
        min_price = prices[0]
        max_profit = 0
        for price in prices:
            if price < min_price:
                min_price = price
            profit = price - min_price
            if profit > max_profit:
                max_profit = profit
        return max_profit

prices = [7, 1, 5, 3, 6, 4]
solution = Solution()
result = solution.maxProfit(prices)
print(result)
```

Output:

```
Pyseu — Python Execution State Explorer
DEFINE Solution
[10] prices = [7, 1, 5, 3, 6, 4]
    prices: None → [7, 1, 5, 3, 6, 4]
[12] solution = Solution()
    solution: None → <Solution instance>
CALL maxProfit(prices=[7, 1, 5, 3, 6, 4])
  [3]         min_price = prices[0]
      min_price: None → 7
  [4]         max_profit = 0
      max_profit: None → 0
  ...
  [15]         return max_profit
RETURN maxProfit → 5
[13] result = solution.maxProfit(prices)
    result: None → 5
    PROGRAM OUTPUT: 5
Execution completed successfully.
```

## What Pyseu Does

Pyseu observes the execution of your Python program and shows:

* Which source lines were executed
* Which variables were created or changed
* Previous and current variable values
* Program output
* Function and recursive execution
* Loop and conditional execution
* Runtime exceptions and execution failures
* Changes to mutable objects such as lists and dictionaries

## Design

Pyseu is an execution observer, not a replacement Python interpreter.

The Python interpreter executes the program while Pyseu observes runtime execution:

```
Python Program
      ↓
Python Interpreter
      ↓
Runtime Trace
      ↓
Pyseu
      ↓
Execution + State Changes
      ↓
Terminal Output
```

Pyseu uses Python's runtime tracing capabilities and standard library rather than implementing its own Python interpreter.

## Features

* Runtime line-by-line execution tracing
* Runtime variable state tracking
* Variable change detection
* Program stdout capture
* Function and recursion tracing
* Loop and conditional tracing
* Mutable object state tracking
* Clear exception reporting
* Fully local execution
* No web service required
* No third-party runtime dependencies

## Requirements

* Python 3.10+
* No third-party runtime dependencies

## Development

Clone the repository and install it in editable mode:

```bash
pip install -e .
```

Run the test suite:

```bash
python -m pytest
```

Build the package:

```bash
python -m build
```

Check the package:

```bash
python -m twine check dist/*
```

## Project Status

Current release: v0.1.2

Pyseu v0.1.2 is a polish and reliability release with cleaner output formatting and improved runtime object representations.

The project intentionally keeps its scope small. Future development will be driven by real usage and practical developer needs.

## License

MIT License

Copyright (c) 2026 Pyseu Contributors
