Metadata-Version: 2.4
Name: flexibleloop
Version: 0.1.0
Summary: A flexible, customizable while loop for Python with timeout, iteration limits, and pre-iteration hooks.
Author-email: "Dr. Tolga Kaan Kanatlı" <tolgakanatli@hotmail.com>
License: MIT License
        
        Copyright (c) 2026 tolgakanatli
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/tolgakanatli/flexibleloop
Keywords: loop,while,timeout,iteration,utility
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# flexibleloop

A Python utility that extends the standard `while` loop with built-in timeout control, iteration limits, pre-iteration hooks, and dynamic condition functions — all through a clean `for`-loop interface.

---

## Why

Python's `while` loop is simple but limited. Adding a timeout, counting iterations, or updating variables before checking a condition requires boilerplate every time. `FlexibleWhile` packages all of that into a reusable, configurable object.

---

## Features

- **Timeout** — Stop the loop automatically after a set number of seconds
- **Max iterations** — Cap the number of iterations without a counter variable
- **Before function** — Run a function before each iteration; its return value becomes the loop variable
- **Condition function** — Define the loop condition as a callable instead of inline logic
- **Callbacks** — Execute custom functions when timeout or max iterations are hit
- **Clean interface** — Used as a standard `for` loop; no new syntax to learn

---

## Installation

Clone the repository and import directly:

```bash
git clone https://github.com/tolgakanatli/flexiblewhile.git
```

```python
from FlexibleLoop import FlexibleWhile
```

---

## Usage

### Basic loop with timeout

```python
from FlexibleLoop import FlexibleWhile

loop = FlexibleWhile(timeout=5.0)

for _ in loop:
    # Runs until 5 seconds have elapsed
    do_something()
```

### Loop with a condition function

```python
def condition(value):
    return value < 100

def update(value):
    return value + 7

loop = FlexibleWhile(
    before_func=update,
    cond_func=condition,
    start_vals=(0,)
)

for value in loop:
    print(value)
# Prints: 7, 14, 21, ... up to 98
```

### Loop with max iterations and a callback

```python
def on_limit():
    print("Max iterations reached")

loop = FlexibleWhile(
    max_iterations=10,
    on_max_iterations=on_limit
)

for _ in loop:
    do_something()
```

### Accessing loop metadata

```python
loop = FlexibleWhile(timeout=3.0)
for _ in loop:
    pass

print(f"Completed {loop.iterations} iterations in {loop.time_elapsed:.2f}s")
```

---

## API Reference

### `FlexibleWhile(before_func, cond_func, start_vals, timeout, max_iterations, on_timeout, on_max_iterations)`

| Parameter | Type | Default | Description |
|---|---|---|---|
| `before_func` | callable | None | Called before each iteration. Return value updates loop variable(s). |
| `cond_func` | callable | None | Loop continues while this returns `True`. `None` is equivalent to `while True`. |
| `start_vals` | tuple | `(None,)` | Initial values passed to `before_func` and `cond_func` on first iteration. |
| `timeout` | float | None | Maximum loop duration in seconds. |
| `max_iterations` | int | None | Maximum number of iterations. |
| `on_timeout` | callable | None | Called when timeout is reached. |
| `on_max_iterations` | callable | None | Called when max iterations is reached. |

### Instance attributes (after iteration)

| Attribute | Description |
|---|---|
| `loop.iterations` | Number of completed iterations |
| `loop.time_elapsed` | Total elapsed time in seconds |
| `loop.values` | Current value(s) of the loop variable |

---

## License

MIT License — free to use, modify, and distribute, including commercially.  
Attribution required: please credit **Dr. Tolga Kaan Kanatlı** in any derivative work or product.

---

## Author

**Dr. Tolga Kaan Kanatlı**  
PhD in Chemical Engineering — PEM Fuel Cells & Hydrogen Production  
[GitHub](https://github.com/tolgakanatli) · [LinkedIn](https://www.linkedin.com/in/tolgakanatli) · tolgakanatli@hotmail.com
