helu
Advanced tools
A lightweight Python package for generating random numbers and sequences with a clean, intuitive API.
A lightweight, zero-dependency Python package for generating random numbers and sequences with a clean, intuitive API.
pip install helu
git clone https://github.com/yourusername/helu.git
cd helu
pip install .
git clone https://github.com/yourusername/helu.git
cd helu
pip install -e ".[dev]"
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
random_int(min_val: int, max_val: int) -> intGenerate 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) -> floatGenerate a random float between min_val and max_val.
Parameters:
min_val (float): Minimum valuemax_val (float): Maximum valueReturns: 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 generatemin_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]) -> NoneSet 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]) -> AnySelect 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 sequencek (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]) -> NoneShuffle 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 sequenceReturns: 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 = ...) -> strGenerate 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) -> strGenerate 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]) -> AnySelect a random item based on relative weights (probability).
Parameters:
items: Sequence of items to choose fromweights: Sequence of weights (probabilities) for each itemReturns: 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 generatemin_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 generatemin_val (float): Minimum valuemax_val (float): Maximum valueReturns: 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
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])
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)]
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)]
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)
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)
# 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]"
# Run all tests
pytest
# Run tests with coverage
pytest --cov=helu
# Run tests with verbose output
pytest -v
# 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/
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
Helu is lightweight and performant:
random moduleContributions are welcome! Please feel free to submit a Pull Request.
git checkout -b feature/AmazingFeature)git commit -m 'Add some AmazingFeature')git push origin feature/AmazingFeature)This project is licensed under the MIT License - see the LICENSE file for details.
If you encounter any issues or have questions:
See RELEASES for version history and changes.
Made with ❤️ by the Helu Team
FAQs
A lightweight Python package for generating random numbers and sequences with a clean, intuitive API.
We found that helu demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
TrapDoor crypto stealer hits 36 malicious packages across npm, PyPI, and Crates.io, targeting crypto, DeFi, AI, and security developers.
Research
/Security News
Laravel Lang packages were compromised with an RCE backdoor across hundreds of versions, exposing cloud, CI/CD, and developer secrets.
Security News
Socket found a malicious postinstall hook across 700+ GitHub repos, including PHP packages on Packagist and Node.js project repositories.