xorandom 0.1.0

useless random libary

xorandom

Overview

xorandom is a lightweight, fast pseudo-random number generator (PRNG) library implemented in Python, inspired by xorshift algorithms. It provides functions for generating random integers, floats, bit sequences, and other utilities compatible with Python’s random module API.

The library is designed for deterministic behavior with explicit seeding, making it suitable for simulations, procedural generation, and reproducible testing.

---

Example Usage

import xorandom

def main():
    # Seed + basic RNG calls
    xorandom.seed(0xDEADBEEF)
    print("randuint64():", xorandom.randuint64())
    print("randbits(20):", xorandom.randbits(20))
    print("getrandbits(16) alias:", xorandom.getrandbits(16))
    print("randbelow(100):", xorandom.randbelow(100))
    print("random():", xorandom.random())
    print("uniform(1,5):", xorandom.uniform(1,5))

    # Discrete random values / indices
    print("randint(1,6):", xorandom.randint(1,6))
    print("randrange(0,10,2):", xorandom.randrange(0,10,2))

    # Selection / permutation / sampling
    seq = [1, 2, 3, 4, 5]
    print("choice(seq):", xorandom.choice(seq))

    arr = [1, 2, 3, 4, 5]
    xorandom.shuffle(arr)
    print("shuffle ->", arr)

    print("sample([10,20,30,40], 2):", xorandom.sample([10,20,30,40], 2))

    # choices: unweighted (replacement) & weighted (replacement)
    print("choices unweighted k=5:", xorandom.choices(['a','b','c'], k=5))
    print("choices weighted k=5:", xorandom.choices(['a','b','c'], k=5, weights=[0.1,0.7,0.2]))

    # Gaussian / Normal distribution (Box-Muller transform)
    print("normalvariate(0,1):", xorandom.normalvariate(0,1))
    print("gauss(10,2):", xorandom.gauss(10,2))

    # Exponential distribution
    print("expovariate(0.5):", xorandom.expovariate(0.5))

    # Characters / strings / bytes
    print("randsymbol():", xorandom.randsymbol())
    print("randchar_from_charset('abc'):", xorandom.randchar_from_charset('abc'))
    print("randstr(8):", xorandom.randstr(8))
    print("random_from_spec('1sS%'):", xorandom.random_from_spec('1sS%'))
    print("randbytes(6):", xorandom.randbytes(6))

    # State save / restore -> demonstrate reproducibility
    state = xorandom.getstate()
    print("saved state:", state)
    v1 = xorandom.random()
    xorandom.setstate(state)
    v2 = xorandom.random()
    print("reproducible? ->", v1 == v2, "values:", v1, v2)

if __name__ == "__main__":
    main()

---

Features

• Fast xorshift-based random number generation.
• Compatible with Python’s random API (seed, random, randint, etc.).
• Support for integer, float, bit-level, and distribution-based generation.
• Deterministic seeding and state restoration.
• Efficient sampling, shuffling, and character/byte generation.

---

API Reference

Core Functions

• seed(value: int) — Initialize the generator with a seed.
• randuint64() -> int — Generate a 64-bit unsigned random integer.
• randbits(k: int) -> int — Return an integer with k random bits.
• getrandbits(k: int) -> int — Alias for randbits.
• randbelow(n: int) -> int — Random integer in [0, n).
• random() -> float — Random float in [0.0, 1.0).
• uniform(a: float, b: float) -> float — Random float in [a, b].

Discrete and Distribution Functions

• randint(a: int, b: int) — Random integer between a and b inclusive.
• randrange(start, stop[, step]) — Random integer from range.
• normalvariate(mu, sigma) — Normal distribution (Box–Muller transform).
• gauss(mu, sigma) — Alias for normalvariate.
• expovariate(lambd) — Exponential distribution.

Sequence and Sampling Functions

• choice(seq) — Random element from a sequence.
• shuffle(seq) — Shuffle sequence in place.
• sample(population, k) — Random sample of size k.
• choices(population, k, weights=None) — Random selection with replacement.

String and Byte Functions

• randsymbol() — Random alphanumeric symbol.
• randchar_from_charset(charset) — Random character from a given charset.
• randstr(length) — Random string of given length.
• random_from_spec(spec) — Random string matching a character specification.
• randbytes(length) — Random byte sequence.

State Management

• getstate() — Get current generator state.
• setstate(state) — Restore generator state.

---

License

This library is distributed under the MIT License.