helu 0.2.0

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

Helu

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)

pip install helu

From Source

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

Development Installation

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

Quick Start

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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

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

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

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

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

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

# 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

# Run all tests
pytest

# Run tests with coverage
pytest --cov=helu

# Run tests with verbose output
pytest -v

Code Quality

# 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.

# 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 style guide
• Use 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 file for details.

Support

If you encounter any issues or have questions:

1. Check the GitHub Issues
2. Create a new issue with a clear description
3. Include Python version and relevant code snippets

Changelog

See 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