Metadata-Version: 2.4
Name: helu
Version: 0.2.0
Summary: A lightweight Python package for generating random numbers and sequences with a clean, intuitive API.
Author-email: Your Name <xolara2518@gzeos.com>
Maintainer-email: Your Name <xolara2518@gzeos.com>
License: MIT
License-File: LICENSE
Keywords: lightweight,number-generation,random,utility
Classifier: Development Status :: 3 - Alpha
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 :: Libraries :: Python Modules
Requires-Python: >=3.8
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: flake8>=6.0.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Helu

[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

A lightweight, zero-dependency Python package for generating random numbers and sequences with a clean, intuitive API.

## Features

- 🎲 **Easy Random Number Generation** - Generate random integers and floats with simple function calls
- 🔢 **Unique Number Sequences** - Generate lists of unique random numbers within a range
- 📊 **Number Ranges** - Create sequences of numbers with custom steps
- 🔐 **Deterministic Results** - Set seeds for reproducible random number generation
- 🚀 **Zero Dependencies** - Pure Python implementation with no external requirements
- 💡 **Type Hints** - Full type annotations for better IDE support and type checking
- 📦 **Lightweight** - Minimal package size and memory footprint

## Installation

### Via pip (from PyPI)

```bash
pip install helu
```

### From Source

```bash
git clone https://github.com/yourusername/helu.git
cd helu
pip install .
```

### Development Installation

```bash
git clone https://github.com/yourusername/helu.git
cd helu
pip install -e ".[dev]"
```

## Quick Start

```python
from helu import random_int, random_float, number_range, unique_numbers, set_seed

# Generate a random integer between 1 and 100 (inclusive)
print(random_int(1, 100))  # Output: 42 (example)

# Generate a random float between 0 and 1
print(random_float(0.0, 1.0))  # Output: 0.8739... (example)

# Generate a list of 5 unique numbers between 1 and 50
print(unique_numbers(5, 1, 50))  # Output: [3, 15, 42, 28, 7] (example)

# Generate a sequence of numbers from 1 to 10 with step 2
print(number_range(1, 11, 2))  # Output: [1, 3, 5, 7, 9]

# Set a seed for deterministic/reproducible results
set_seed(42)
print(random_int(1, 100))  # Always outputs the same number
set_seed(42)
print(random_int(1, 100))  # Outputs the same number again
```

## API Reference

### `random_int(min_val: int, max_val: int) -> int`

Generate a random integer between `min_val` and `max_val` (inclusive).

**Parameters:**
- `min_val` (int): Minimum value (inclusive)
- `max_val` (int): Maximum value (inclusive)

**Returns:** int - A random integer within the specified range

**Raises:** ValueError - If min_val > max_val

**Example:**
```python
from helu import random_int

die_roll = random_int(1, 6)  # Simulates rolling a die
```

### `random_float(min_val: float, max_val: float) -> float`

Generate a random float between `min_val` and `max_val`.

**Parameters:**
- `min_val` (float): Minimum value
- `max_val` (float): Maximum value

**Returns:** float - A random float within the specified range

**Raises:** ValueError - If min_val > max_val

**Example:**
```python
from helu import random_float

temperature = random_float(20.0, 25.0)  # Random temperature
```

### `number_range(start: int, stop: int, step: int = 1) -> List[int]`

Generate a list of numbers from `start` to `stop` (exclusive) with a given `step`.

**Parameters:**
- `start` (int): Starting value (inclusive)
- `stop` (int): Ending value (exclusive)
- `step` (int): Step between values (default: 1)

**Returns:** List[int] - A list of integers in the specified range

**Example:**
```python
from helu import number_range

evens = number_range(0, 10, 2)  # [0, 2, 4, 6, 8]
odds = number_range(1, 10, 2)   # [1, 3, 5, 7, 9]
```

### `unique_numbers(count: int, min_val: int, max_val: int) -> List[int]`

Generate a list of `count` unique random integers within the range `[min_val, max_val]`.

**Parameters:**
- `count` (int): Number of unique integers to generate
- `min_val` (int): Minimum value (inclusive)
- `max_val` (int): Maximum value (inclusive)

**Returns:** List[int] - A list of unique random integers

**Raises:** ValueError - If count > (max_val - min_val + 1)

**Example:**
```python
from helu import unique_numbers

lottery_numbers = unique_numbers(6, 1, 49)  # Pick 6 unique numbers from 1 to 49
```

### `set_seed(seed: Union[int, float, str, bytes, bytearray]) -> None`

Set the seed for the random number generator to produce deterministic/reproducible results.

**Parameters:**
- `seed`: A seed value (int, float, str, bytes, or bytearray)

**Returns:** None

**Example:**
```python
from helu import set_seed, random_int

set_seed(42)
first_run = random_int(1, 1000)

set_seed(42)
second_run = random_int(1, 1000)

assert first_run == second_run  # Always True
```

### `random_choice(sequence: Sequence[Any]) -> Any`

Select a random element from a non-empty sequence.

**Parameters:**
- `sequence`: Any sequence (list, tuple, string, etc.)

**Returns:** Any - A random element from the sequence

**Raises:** ValueError - If sequence is empty

**Example:**
```python
from helu import random_choice

card = random_choice(['Hearts', 'Diamonds', 'Clubs', 'Spades'])
element = random_choice([1, 2, 3, 4, 5])
```

### `random_choices(sequence: Sequence[Any], k: int = 1) -> List[Any]`

Select k random elements from a sequence with replacement (allows duplicates).

**Parameters:**
- `sequence`: Any sequence
- `k` (int): Number of elements to select (default: 1)

**Returns:** List[Any] - A list of k random elements

**Raises:** ValueError - If sequence is empty or k is negative

**Example:**
```python
from helu import random_choices

# Rolling a die 10 times
rolls = random_choices([1, 2, 3, 4, 5, 6], k=10)

# Random colors with replacement
colors = random_choices(['red', 'blue', 'green'], k=5)
```

### `shuffle(sequence: List[Any]) -> None`

Shuffle a list in-place using the Fisher-Yates algorithm (modifies original list).

**Parameters:**
- `sequence`: A list to shuffle (must be a list, not tuple or other sequences)

**Returns:** None (modifies list in-place)

**Raises:** TypeError - If sequence is not a list

**Example:**
```python
from helu import shuffle

deck = [1, 2, 3, 4, 5]
shuffle(deck)
print(deck)  # [3, 1, 5, 2, 4] (shuffled in-place)
```

### `shuffled(sequence: Sequence[Any]) -> List[Any]`

Return a shuffled copy of a sequence without modifying the original.

**Parameters:**
- `sequence`: Any sequence

**Returns:** List[Any] - A shuffled copy of the sequence

**Example:**
```python
from helu import shuffled

original = [1, 2, 3, 4, 5]
shuffled_copy = shuffled(original)
print(original)      # [1, 2, 3, 4, 5] (unchanged)
print(shuffled_copy) # [3, 1, 5, 2, 4] (shuffled)
```

### `random_string(length: int = 10, charset: str = ...) -> str`

Generate a random string of specified length using alphanumeric characters (or custom charset).

**Parameters:**
- `length` (int): Length of the string (default: 10)
- `charset` (str): Characters to use for generation (default: letters + digits)

**Returns:** str - A random string

**Raises:** ValueError - If length is negative or charset is empty

**Example:**
```python
from helu import random_string

code = random_string(8)           # 'aBc3DeF2'
token = random_string(32)         # Random 32-char token
custom = random_string(5, 'ABCD') # Random 5-char from ABCD
```

### `random_password(length: int = 16, use_special: bool = True) -> str`

Generate a secure random password with mixed character types.

**Parameters:**
- `length` (int): Password length (default: 16, minimum: 4)
- `use_special` (bool): Include special characters (default: True)

**Returns:** str - A secure random password

**Raises:** ValueError - If length < 4

**Example:**
```python
from helu import random_password

# Generate a strong password
password = random_password(20)  # 'xK#9mL$pQ@2bF!vRnT8J'

# Generate alphanumeric-only password
simple_password = random_password(12, use_special=False)  # 'xK9mLpQ2bFvRn'
```

### `weighted_choice(items: Sequence[Any], weights: Sequence[float]) -> Any`

Select a random item based on relative weights (probability).

**Parameters:**
- `items`: Sequence of items to choose from
- `weights`: Sequence of weights (probabilities) for each item

**Returns:** Any - A randomly selected item

**Raises:** ValueError - If items/weights empty, mismatched lengths, or sum of weights ≤ 0

**Example:**
```python
from helu import weighted_choice

# Weighted dice (biased toward higher numbers)
roll = weighted_choice([1, 2, 3, 4, 5, 6], [1, 1, 1, 2, 2, 3])

# Weighted selection
loot = weighted_choice(
    ['common', 'rare', 'legendary'],
    [0.7, 0.25, 0.05]
)
```

### `random_ints(count: int, min_val: int, max_val: int) -> List[int]`

Generate a list of random integers (batch operation).

**Parameters:**
- `count` (int): Number of integers to generate
- `min_val` (int): Minimum value (inclusive)
- `max_val` (int): Maximum value (inclusive)

**Returns:** List[int] - List of random integers

**Raises:** ValueError - If count is negative or invalid range

**Example:**
```python
from helu import random_ints

# Generate 10 random test values
test_data = random_ints(10, 1, 100)

# Simulate 100 coin flips (1 = heads, 0 = tails)
flips = random_ints(100, 0, 1)
```

### `random_floats(count: int, min_val: float, max_val: float) -> List[float]`

Generate a list of random floats (batch operation).

**Parameters:**
- `count` (int): Number of floats to generate
- `min_val` (float): Minimum value
- `max_val` (float): Maximum value

**Returns:** List[float] - List of random floats

**Raises:** ValueError - If count is negative or invalid range

**Example:**
```python
from helu import random_floats

# Generate 100 random coordinates
x_coords = random_floats(100, 0.0, 100.0)
y_coords = random_floats(100, 0.0, 100.0)

# Generate random temperatures
temps = random_floats(30, 15.0, 35.0)  # 30 days of temperature
```

## Use Cases

### Games & Simulations
```python
from helu import random_int, unique_numbers, random_choice, shuffled, weighted_choice

# Dice roll
roll = random_int(1, 6)

# Card shuffling (picking 5 unique cards from 52)
cards = unique_numbers(5, 1, 52)

# Random card suit
suit = random_choice(['♠', '♥', '♦', '♣'])

# Shuffle a deck of cards
deck = list(range(1, 53))
shuffled_deck = shuffled(deck)

# Weighted loot drop (rarer items less likely)
loot = weighted_choice(['common', 'rare', 'epic', 'legendary'], [0.6, 0.25, 0.12, 0.03])
```

### Testing & Quality Assurance
```python
from helu import set_seed, random_int, random_ints, random_password

# Reproducible test scenarios
set_seed("test_scenario_001")
test_data = random_ints(10, 1, 100)  # Batch generation

# Generate test user passwords
test_passwords = [random_password(12) for _ in range(5)]
```

### Data Generation
```python
from helu import random_float, random_floats, number_range, random_string

# Generate sample coordinates efficiently
x_coords = random_floats(100, 0, 100)
y_coords = random_floats(100, 0, 100)
coordinates = list(zip(x_coords, y_coords))

# Generate batch IDs
batch_ids = number_range(1000, 1100)  # 1000 sequential IDs

# Generate random test tokens
tokens = [random_string(32) for _ in range(10)]
```

### Security & Authentication
```python
from helu import random_password, random_string

# Generate secure passwords for users
user_password = random_password(20, use_special=True)

# Generate secure API tokens
api_token = random_string(64, 'abcdef0123456789')  # Hex string

# Generate secure session IDs
session_id = random_string(32)
```

### Shuffling & Randomization
```python
from helu import shuffle, shuffled, random_choice, random_choices

# Shuffle survey questions to avoid bias
questions = ['Q1', 'Q2', 'Q3', 'Q4', 'Q5']
shuffled_questions = shuffled(questions)

# Random playlist order
playlist = ['song1', 'song2', 'song3', 'song4', 'song5']
shuffle(playlist)
print(f"Playing: {random_choice(playlist)}")

# Batch sampling with replacement
samples = random_choices(range(1, 100), k=50)
```

## Development

### Prerequisites

- Python 3.8 or higher
- pip or poetry

### Setup Development Environment

```bash
# Clone the repository
git clone https://github.com/yourusername/helu.git
cd helu

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\\Scripts\\activate

# Install development dependencies
pip install -e ".[dev]"
```

### Running Tests

```bash
# Run all tests
pytest

# Run tests with coverage
pytest --cov=helu

# Run tests with verbose output
pytest -v
```

### Code Quality

```bash
# Format code with Black
black src/ tests/

# Sort imports with isort
isort src/ tests/

# Lint with flake8
flake8 src/ tests/

# Type checking with mypy
mypy src/
```

## Testing

The project uses pytest for testing. All functions are covered with comprehensive unit tests.

```bash
# Run tests
pytest

# Run specific test file
pytest tests/test_generator.py

# Run specific test function
pytest tests/test_generator.py::test_random_int

# Run with coverage report
pytest --cov=helu --cov-report=html
```

## Performance

Helu is lightweight and performant:

- **No external dependencies** - Pure Python with standard library only
- **Minimal overhead** - Simple wrapper around Python's built-in `random` module
- **Small memory footprint** - Minimal package size

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

### Guidelines

- Follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guide
- Use [Black](https://github.com/psf/black) for code formatting
- Add tests for any new functionality
- Update documentation as needed

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

If you encounter any issues or have questions:

1. Check the [GitHub Issues](https://github.com/yourusername/helu/issues)
2. Create a new issue with a clear description
3. Include Python version and relevant code snippets

## Changelog

See [RELEASES](https://github.com/yourusername/helu/releases) for version history and changes.

## Acknowledgments

- Built with Python's standard library
- Inspired by the need for a simple, lightweight random number generation utility

---

**Made with ❤️ by the Helu Team**
