Metadata-Version: 2.4
Name: gabiteodoru-qython
Version: 0.1.1
Summary: Qython: Python-like syntax with q-functional constructs translator
Home-page: https://github.com/gabiteodoru/qython
Author: Gabi Teodoru
Author-email: gabiteodoru@gmail.com
Keywords: q kdb qython compiler translator functional-programming
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: parso
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Qython Programming Language

**Qython** is a hybrid programming language that combines Python's readable syntax with q/kdb+'s functional programming paradigms. It extends Python with domain-specific constructs that map directly to q's efficient operations, creating a bridge between imperative and functional programming.

## What is Qython?

Qython is designed for developers who want to:
- **Write readable code** using Python-like syntax
- **Generate efficient q code** automatically
- **Express functional concepts** declaratively
- **Bridge paradigms** between imperative and functional programming

### Language Philosophy

1. **Familiarity**: Leverage Python's intuitive syntax and structure
2. **Efficiency**: Generate optimized q/kdb+ code for high-performance computing
3. **Expressiveness**: Add domain-specific constructs for common q patterns
4. **Safety**: Automatic closure analysis and error checking

## Qython Language Features

### 1. Core Python Compatibility
Qython supports standard Python constructs:

```python
def calculate_mean(values, weights):
    if len(values) == 0:
        raise ValueError("Cannot compute mean of empty list")
    
    total = 0
    weight_sum = 0
    
    # Standard Python logic works
    for i in range(len(values)):
        total = total + values[i] * weights[i]
        weight_sum = weight_sum + weights[i]
    
    return total / weight_sum
```

### 2. Extended Constructs

#### `do` Statement - Declarative Iteration
Replace imperative loops with declarative iteration counts:

```python
def repeat_operation(n):
    counter = 0
    do n times:
        counter = counter + 1
        process_step(counter)
    return counter
```

#### `converge()` Function - Functional Convergence
Express iterative algorithms that converge to a solution:

```python
def newton_sqrt(x):
    def step(guess):
        new_guess = (guess + x / guess) / 2
        return new_guess
    
    result = converge(step, starting_from=x/2)
    return result
```

The `converge()` function:
- **Takes a step function** that defines the iteration logic
- **Detects convergence** using q's built-in convergence operator
- **Eliminates boilerplate** tolerance checking and loop management

### 3. Function-Based Convergence

Qython provides a `converge()` function for iterative algorithms:

```python
def complex_convergence(a, b, tolerance):
    def step(result):
        next_val = some_function(result, a, b)
        return next_val
    
    final_result = converge(step, starting_from=a)
    return final_result
```

Generates efficient q code:
```q
step/[a]
```

## File Types and Project Structure

### File Extensions
- **`.py`** - Pure Python files (standard Python syntax)
- **`.qy`** - Qython files (extended syntax with `do` and `converge`)

### Project Structure
```
qython-project/
├── src/
│   ├── algorithms.qy        # Qython source files
│   ├── utilities.py         # Pure Python utilities
│   └── converge_examples.qy # Convergence algorithms
├── build/
│   └── generated.q          # Compiled q code
├── translator/
│   ├── translate.py         # Qython → Q compiler
│   ├── custom_grammar.txt   # Extended grammar definition
│   └── demo.py             # Usage examples
└── README.md
```

## Qython → Q Translation

### Language Mappings

| Qython | Q | Purpose |
|--------|---|---------|
| `def func(x, y):` | `func:{[x;y] ...}` | Function definition |
| `if condition:` | `if[condition; ...]` | Conditionals |
| `while condition:` | `while[condition; ...]` | Traditional loops |
| `do n times:` | `do[n; ...]` | Fixed iteration |
| `converge(step_func, starting_from=val)` | `step_func/[val]` | Convergence iteration |
| `x = y` | `x:y` | Assignment |
| `x / y` | `x%y` | Division |
| `raise ValueError("msg")` | `` `$"msg" `` | Error handling |

### Real-World Example: Newton's Method

**Qython Source** (`newton.qy`):
```python
def sqrt_newton(x):
    """Calculate square root using Newton's method in Qython."""
    if x < 0:
        raise ValueError("Cannot compute sqrt of negative number")
    if x == 0:
        return 0
    
    def step(guess):
        new_guess = (guess + x / guess) / 2
        return new_guess
    
    result = converge(step, starting_from=x/2)
    return result
```

**Generated Q Code**:
```q
sqrt_newton:{[x]
    if[x<0; `$"Error"];
    if[x=0; :0];
    step:{[guess]
        new_guess:(guess+x%guess)%2;
        :new_guess
    };
    result:step/[x%2];
    :result
}
```

**Performance**:
```q
q)sqrt_newton[16]
4f
q)sqrt_newton[10]  
3.162278f
q)\t:10000 sqrt_newton[100]
2  // 2 milliseconds for 10,000 iterations
```

## Qython Compiler

### Installation and Usage

```python
from translate import translate_file

# Compile Qython to Q
q_code = translate_file('myproject.qy')

# Execute in q environment
q(q_code)
```

### Advanced Features

#### Closure Analysis
The compiler automatically:
- **Detects** variables referenced from outer scope
- **Generates** proper parameter lists and function calls
- **Validates** q's 8-parameter limit
- **Optimizes** parameter ordering for performance

#### Error Handling
```python
# Qython enforces safety constraints
def too_many_vars():
    converge on result starting from 0:
        # Error: More than 8 variables would be captured
        complex_expression(a, b, c, d, e, f, g, h, i)
    return result
# Compiler error: "too many variables (9), q supports max 8 parameters"
```

## Language Design Principles

### 1. **Readability First**
Qython maintains Python's philosophy that code is read more often than written:

```python
# Clear intent and flow
def step(solution):
    return improve_solution(solution, data, parameters)

final_solution = converge(step, starting_from=initial_guess)
```

### 2. **Performance Through Translation**
Generate optimized q code while maintaining high-level abstractions:

```python
# High-level Qython
do 1000000 times:
    process_data()

# Efficient q translation
do[1000000; process_data[]]
```

### 3. **Functional-Imperative Bridge**
Combine the best of both paradigms:

- **Imperative clarity** for business logic
- **Functional efficiency** for mathematical operations
- **Automatic translation** between paradigms

### 4. **Safety and Correctness**
Compile-time guarantees for common q pitfalls:

- **Closure capture** prevents undefined variable errors
- **Parameter limits** enforced at compile time
- **Type-aware** translation for q-specific constructs

## Future Qython Extensions

### Planned Language Features
- **List comprehensions** → q's `each`, `over` operators
- **Pattern matching** → q's conditional expressions
- **Async/await** → q's deferred execution model
- **Classes** → q's namespace system
- **Type annotations** → q's type system integration

### Example Future Syntax
```python
# List comprehensions
result = [x * 2 for x in data if x > threshold]
# → {x*2} each data where data>threshold

# Pattern matching  
match algorithm:
    case "newton": converge on x starting from initial: ...
    case "bisection": while abs(high - low) > tolerance: ...
    case _: raise ValueError("Unknown algorithm")

# Async operations
async def parallel_compute(datasets):
    results = await [process(d) for d in datasets]
    return combine(results)
```

## Why Qython?

### For Python Developers
- **Familiar syntax** with powerful new constructs
- **Automatic optimization** to high-performance q code
- **Functional programming** concepts without the learning curve

### For Q/KDB+ Developers  
- **Higher-level abstractions** for complex algorithms
- **Readable code** for team collaboration
- **Faster development** with automatic closure management

### For Data Scientists
- **Expressive algorithms** for mathematical computing
- **High performance** execution on large datasets
- **Seamless integration** with existing Python workflows

### For Financial Technologists
- **Domain-specific** constructs for iterative algorithms
- **Real-time performance** through q compilation
- **Risk management** through compile-time safety checks

---

**Qython** represents the next evolution in domain-specific languages, combining the readability of Python with the performance of q/kdb+ to create a powerful tool for mathematical computing, financial modeling, and high-performance data analysis.
