tu 0.0.5
Utils to work with iterables
License: apache-2.0

# tu
Utils to work with iterables

To install:	```pip install tu```

## Overview
The `tu` package provides a collection of utility functions designed to simplify and enhance the manipulation and analysis of iterables in Python. It includes tools for handling operations such as running means, chunking, sliding windows, and various methods for iterating with specific conditions. This package is especially useful for data processing tasks where complex iterable manipulations are required.

## Features
- **Running Mean Calculation**: Compute running or moving averages over an iterable, useful for smoothing out time series data.
- **Chunking and Sliding Windows**: Generate chunks or sliding windows from an iterable, which is useful for batch processing or moving window analyses.
- **Unique Elements**: Extract unique elements from an iterable while preserving order.
- **Sampling**: Functions for sampling elements from an iterable based on various criteria.
- **Iterative Tools**: A variety of functions to extend Python's built-in `itertools`, including capabilities to handle padding, repeating, and more complex iteration patterns.

## Usage Examples

### Running Mean
Calculate the running mean of a sequence with a specified window size:
```python
from tu import running_mean

# Calculate running mean with a window size of 2
result = list(running_mean([1, 3, 5, 7, 9], 2))
print(result)  # Output: [2.0, 4.0, 6.0, 8.0]
```

### Chunking
Divide a list into chunks of a specified size:
```python
from tu import fast_chunker

# Chunk a range of numbers into chunks of size 3
result = list(fast_chunker(range(1, 10), 3))
print(result)  # Output: [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
```

### Unique Elements
Retrieve unique elements from an iterable:
```python
from tu import unique_everseen

# Get unique letters, preserving order
result = list(unique_everseen('AAAABBBCCDAABBB'))
print(result)  # Output: ['A', 'B', 'C', 'D']
```

### Sampling
Randomly sample elements from an iterator:
```python
from tu import random_subset

# Randomly sample 3 elements from a range
result = random_subset(range(100), 3)
print(result)  # Output: [23, 42, 76] (example output, actual may vary)
```

## Detailed Function/Class Documentation

### `running_mean`
Calculates the running mean over an iterable. It can handle arbitrary iterables including lists and generators. This function is particularly useful for signal processing and time series analysis.

### `fast_chunker`
Efficiently chunks an iterable into specified sizes. This is useful for dividing data into manageable pieces, for instance, when processing large datasets that do not fit into memory.

### `unique_everseen`
Extracts unique elements from an iterable, remembering all elements that have been seen. This function is useful for deduplication tasks while maintaining the order of elements.

### `random_subset`
Implements reservoir sampling to obtain a subset of elements from an iterator. This method is useful when the size of the data is unknown or too large to fit into memory.

For more detailed examples and a complete list of all available functions, please refer to the module's documentation strings embedded within the code.