xorandom 0.1.0
useless random libary
License: MIT

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