mitchallen-coin 0.1.5

A simple coin flip random number generator

mitchallen.coin

A simple, lightweight Python package that provides a random number generator perfect for simulations, games, and probabilistic applications.

Installation

pip install mitchallen-coin

Quick Start

from mitchallen.coin import flip, heads, tails

# Get a random number between 0.0 and 1.0
result = flip()
print(result)  # e.g., 0.7234567890123456

# Get a boolean coin flip result
is_heads = heads()
print(is_heads)  # True or False

# Get the opposite boolean coin flip result
is_tails = tails()
print(is_tails)  # True or False

Usage Examples

Simulate a Coin Flip

from mitchallen.coin import heads, tails

# Using heads()
if heads():
    print("Heads")
else:
    print("Tails")

# Or using tails()
if tails():
    print("Tails")
else:
    print("Heads")

Random Probability Events

from mitchallen.coin import flip

# 30% chance of rain
if flip() < 0.3:
    print("Bring an umbrella!")
else:
    print("No rain expected")

Monte Carlo Simulation

from mitchallen.coin import flip

# Estimate pi using Monte Carlo method
inside_circle = 0
total_points = 100000

for _ in range(total_points):
    x = flip()
    y = flip()
    if x*x + y*y <= 1:
        inside_circle += 1

pi_estimate = 4 * inside_circle / total_points
print(f"Pi estimate: {pi_estimate}")

Random Selection with Weighted Probabilities

from mitchallen.coin import flip

def choose_outcome(probabilities):
    """Choose an outcome based on probability distribution."""
    value = flip()
    cumulative = 0
    for outcome, prob in probabilities.items():
        cumulative += prob
        if value < cumulative:
            return outcome
    return list(probabilities.keys())[-1]

# Game loot drop system
loot = {
    "common": 0.5,
    "rare": 0.3,
    "epic": 0.15,
    "legendary": 0.05
}

result = choose_outcome(loot)
print(f"You got: {result}")

API Reference

flip()

Returns a random floating-point number in the range [0.0, 1.0).

Returns:

• float: A random decimal number from 0.0 (inclusive) to 1.0 (exclusive)

Example:

from mitchallen.coin import flip

value = flip()
assert 0.0 <= value < 1.0

heads()

Returns True if flip() > 0.5, False otherwise. Useful for simple boolean coin flip simulations.

Returns:

• bool: True if the coin flip result is greater than 0.5, False otherwise

Example:

from mitchallen.coin import heads

result = heads()
if result:
    print("Heads!")
else:
    print("Tails!")

tails()

Returns the opposite boolean value of heads(). Returns True if heads() would return False, and False if heads() would return True.

Returns:

• bool: The opposite of what heads() would return

Example:

from mitchallen.coin import tails

result = tails()
if result:
    print("Tails!")
else:
    print("Heads!")

Why mitchallen.coin?

• Simple: Clean API with intuitive functions
• Lightweight: No dependencies
• Type-safe: Full type annotations with mypy type checking
• Quality: Enforced code quality with Ruff linting and formatting
• Tested: Comprehensive test suite ensuring quality and reliability
• Namespace package: Works alongside other mitchallen packages

Contributing

Contributions are welcome! See CONTRIBUTING.md for development setup and guidelines.

License

MIT License - see LICENSE for details.