RandomAK 0.1.0
A Python package for enhanced randomization functions
License: MIT
Requires Python: >=3.6



# RandomAK

**RandomAK** is a Python package that provides a wide variety of randomization utilitiesâ€”from generating random numbers and strings to creating complex data structures like matrices and nested dictionaries. It is designed for developers who need quick and reliable randomization functions.

---

## Features

- **Random Numbers:** Generate random integers, floats, primes, and booleans.
- **Random Strings:** Create random words, sentences, alphanumeric strings, and strings with punctuation.
- **Data Structures:** Produce random lists, tuples, dictionaries, sets, matrices, 2D lists, and nested dictionaries.
- **Utility Functions:** Shuffle lists, sample unique elements, and more.
- **Custom Generation:** Build lists with elements generated by a custom function.

---

## Installation

Install **RandomAK** via pip:

```sh
pip install RandomAK
```

---

## Usage

Import the package:

```python
import randomak
```

Below is a detailed explanation of all available functions in **RandomAK**.

---

## Detailed Function Documentation

### 1. `randlist(NoOfElements: int, Start: int = 0, End: int = 100) -> List[int]`
Generates a list of random integers.

- **Parameters:**
  - `NoOfElements`: Number of integers.
  - `Start`: Lower bound (inclusive).
  - `End`: Upper bound (inclusive).
- **Returns:** A list of random integers.
- **Example:**
  ```python
  numbers = randomak.randlist(5, 10, 50)
  print(numbers)  # Output: [23, 12, 45, 33, 29]
  ```

---

### 2. `randtuple(NoOfElements: int, Start: int = 0, End: int = 100) -> Tuple[int, ...]`
Generates a tuple of random integers.

- **Parameters:** Same as `randlist`.
- **Returns:** A tuple of random integers.
- **Example:**
  ```python
  tup = randomak.randtuple(4, 0, 20)
  print(tup)  # Output: (3, 17, 8, 19)
  ```

---

### 3. `randdic(NoOfElements: int, Start: int = 0, End: int = 100) -> Dict[int, int]`
Creates a dictionary with random integer keys and values.

- **Parameters:**
  - `NoOfElements`: Number of key-value pairs.
  - `Start`/`End`: Range for keys and values.
- **Returns:** A dictionary with random integer keys and values.
- **Example:**
  ```python
  d = randomak.randdic(3, 1, 10)
  print(d)  # Output: {4: 7, 2: 9, 10: 1}
  ```

---

### 4. `randset(NoOfElements: int, Start: int = 0, End: int = 100) -> Set[int]`
Generates a set of unique random integers.

- **Parameters:** Same as `randlist`.
- **Returns:** A set containing unique random integers.
- **Example:**
  ```python
  s = randomak.randset(5, 0, 50)
  print(s)  # Output: {2, 14, 23, 37, 45}
  ```

---

### 5. `randstring(length: int, chars: str = string.ascii_letters) -> str`
Generates a random string from the given characters.

- **Parameters:**
  - `length`: Length of the string.
  - `chars`: String containing characters to use (default: ascii letters).
- **Returns:** A random string.
- **Example:**
  ```python
  s = randomak.randstring(8)
  print(s)  # Output: 'AbcDefGh'
  ```

---

### 6. `randfloatlist(NoOfElements: int, Start: float = 0.0, End: float = 1.0) -> List[float]`
Generates a list of random floating-point numbers.

- **Parameters:**
  - `NoOfElements`: Number of floats.
  - `Start` and `End`: Range for the floats.
- **Returns:** A list of random floats.
- **Example:**
  ```python
  floats = randomak.randfloatlist(4, 0.5, 2.5)
  print(floats)  # Output: [1.23, 2.01, 0.67, 1.89]
  ```

---

### 7. `randmatrix(rows: int, cols: int, Start: int = 0, End: int = 100) -> List[List[int]]`
Creates a matrix (list of lists) with random integers.

- **Parameters:**
  - `rows`: Number of rows.
  - `cols`: Number of columns.
  - `Start`/`End`: Range for the integers.
- **Returns:** A matrix of random integers.
- **Example:**
  ```python
  matrix = randomak.randmatrix(3, 4, 0, 10)
  for row in matrix:
      print(row)
  # Output: 
  # [1, 7, 4, 9]
  # [2, 0, 6, 3]
  # [5, 8, 1, 4]
  ```

---

### 8. `randword(length: int) -> str`
Generates a random lowercase word.

- **Parameters:** 
  - `length`: Length of the word.
- **Returns:** A string representing a random word.
- **Example:**
  ```python
  word = randomak.randword(6)
  print(word)  # Output: 'random'
  ```

---

### 9. `randsentence(wordCount: int, minWordLength: int = 3, maxWordLength: int = 8) -> str`
Generates a random sentence composed of random words.

- **Parameters:**
  - `wordCount`: Number of words.
  - `minWordLength`: Minimum length for each word.
  - `maxWordLength`: Maximum length for each word.
- **Returns:** A string representing a sentence.
- **Example:**
  ```python
  sentence = randomak.randsentence(5)
  print(sentence)  # Output: 'Lorem ipsum dolor sit amet.'
  ```

---

### 10. `randdate(StartYear: int = 2000, EndYear: int = 2025) -> str`
Generates a random date string in the format YYYY-MM-DD.

- **Parameters:**
  - `StartYear`: Starting year.
  - `EndYear`: Ending year.
- **Returns:** A date string.
- **Example:**
  ```python
  date_str = randomak.randdate()
  print(date_str)  # Output: '2012-07-15'
  ```

---

### 11. `randboollist(NoOfElements: int) -> List[bool]`
Creates a list of random boolean values.

- **Parameters:**
  - `NoOfElements`: Number of boolean values.
- **Returns:** A list of booleans.
- **Example:**
  ```python
  bools = randomak.randboollist(4)
  print(bools)  # Output: [True, False, True, False]
  ```

---

### 12. `randcolor() -> str`
Generates a random hexadecimal color code.

- **Returns:** A hex color string (e.g., `#1A2B3C`).
- **Example:**
  ```python
  color = randomak.randcolor()
  print(color)  # Output: '#3F7A9C'
  ```

---

### 13. `randlistoflists(noOfSublists: int, sublistLength: int, Start: int = 0, End: int = 100) -> List[List[int]]`
Creates a list of lists filled with random integers.

- **Parameters:**
  - `noOfSublists`: Number of sublists.
  - `sublistLength`: Number of integers per sublist.
  - `Start`/`End`: Range for the integers.
- **Returns:** A 2D list.
- **Example:**
  ```python
  list_of_lists = randomak.randlistoflists(3, 4, 10, 20)
  print(list_of_lists)
  # Output: [[12, 15, 10, 19], [11, 17, 16, 13], [14, 18, 12, 20]]
  ```

---

### 14. `randascii(length: int) -> str`
Generates a random string composed of ASCII letters, digits, and punctuation.

- **Parameters:**
  - `length`: Length of the generated string.
- **Returns:** A string containing a mix of characters.
- **Example:**
  ```python
  ascii_str = randomak.randascii(10)
  print(ascii_str)  # Output: 'A1b!C2d@E3'
  ```

---

### 15. `randunique(NoOfElements: int, Start: int = 0, End: int = 100) -> List[int]`
Creates a list of unique random integers.

- **Parameters:** Same as `randlist`.
- **Returns:** A list with unique integers.
- **Example:**
  ```python
  unique_nums = randomak.randunique(5, 1, 20)
  print(unique_nums)  # Output: [3, 7, 12, 18, 5]
  ```

---

### 16. `randeven(NoOfElements: int, Start: int = 0, End: int = 100) -> List[int]`
Generates a list of random even integers.

- **Parameters:** Same as `randlist`.
- **Returns:** A list of even numbers.
- **Example:**
  ```python
  evens = randomak.randeven(5, 1, 50)
  print(evens)  # Output: [2, 8, 14, 22, 46]
  ```

---

### 17. `randodd(NoOfElements: int, Start: int = 0, End: int = 100) -> List[int]`
Generates a list of random odd integers.

- **Parameters:** Same as `randlist`.
- **Returns:** A list of odd numbers.
- **Example:**
  ```python
  odds = randomak.randodd(5, 1, 50)
  print(odds)  # Output: [3, 7, 15, 27, 49]
  ```

---

### 18. `is_prime(n: int) -> bool`
*Internal Helper Function* â€“ Checks whether a number is prime.

- **Parameters:**
  - `n`: The number to check.
- **Returns:** `True` if `n` is prime; otherwise, `False`.
- **Note:** This function is used by `randprime` and typically isnâ€™t called directly.

---

### 19. `randprime(NoOfElements: int, Start: int = 2, End: int = 100) -> List[int]`
Generates a list of random prime numbers.

- **Parameters:**
  - `NoOfElements`: Number of prime numbers to generate.
  - `Start`/`End`: Range for prime candidates.
- **Returns:** A list of prime numbers.
- **Example:**
  ```python
  primes = randomak.randprime(3, 2, 50)
  print(primes)  # Output: [3, 19, 37]
  ```

---

### 20. `randindex(data: Sequence[Any]) -> Any`
Returns a random valid index for a given sequence.

- **Parameters:**
  - `data`: The sequence (e.g., list, tuple).
- **Returns:** A random index from the sequence or `None` if empty.
- **Example:**
  ```python
  index = randomak.randindex([10, 20, 30, 40])
  print(index)  # Output: 2
  ```

---

### 21. `randshuffle(lst: List[Any]) -> List[Any]`
Shuffles a list and returns a new shuffled copy.

- **Parameters:**
  - `lst`: The list to shuffle.
- **Returns:** A new list with elements in random order.
- **Example:**
  ```python
  original = [1, 2, 3, 4, 5]
  shuffled = randomak.randshuffle(original)
  print(shuffled)  # Output: [4, 1, 5, 2, 3]
  ```

---

### 22. `randsample(lst: List[Any], k: int) -> List[Any]`
Selects `k` unique random elements from a list.

- **Parameters:**
  - `lst`: The list to sample from.
  - `k`: Number of unique elements to return.
- **Returns:** A list of sampled elements.
- **Example:**
  ```python
  sample = randomak.randsample([1, 2, 3, 4, 5], 3)
  print(sample)  # Output: [2, 4, 1]
  ```

---

### 23. `randwordlist(NoOfElements: int, wordLength: int = 5) -> List[str]`
Generates a list of random words.

- **Parameters:**
  - `NoOfElements`: Number of words.
  - `wordLength`: Length of each word.
- **Returns:** A list of words.
- **Example:**
  ```python
  words = randomak.randwordlist(4, 6)
  print(words)  # Output: ['random', 'module', 'python', 'random']
  ```

---

### 24. `randdictkeys(NoOfElements: int, Start: int = 0, End: int = 100, strLength: int = 5) -> Dict[int, str]`
Creates a dictionary with random integer keys and random string values.

- **Parameters:**
  - `NoOfElements`: Number of key-value pairs.
  - `Start`/`End`: Range for integer keys.
  - `strLength`: Length of the generated string values.
- **Returns:** A dictionary with random keys and string values.
- **Example:**
  ```python
  rand_dict = randomak.randdictkeys(3, 1, 50, 8)
  print(rand_dict)  # Output: {12: 'AbCdEfGh', 37: 'IjKlMnOp', 25: 'QrStUvWx'}
  ```

---

### 25. `randtupleofsets(NoOfElements: int, setSize: int, Start: int = 0, End: int = 100) -> Tuple[Set[int], ...]`
Generates a tuple where each element is a set of random integers.

- **Parameters:**
  - `NoOfElements`: Number of sets.
  - `setSize`: Number of integers in each set.
  - `Start`/`End`: Range for the integers.
- **Returns:** A tuple of sets.
- **Example:**
  ```python
  tuple_sets = randomak.randtupleofsets(2, 3, 0, 20)
  print(tuple_sets)  # Output: ({3, 15, 7}, {8, 12, 19})
  ```

---

### 26. `rand2dlist(NoOfElements: int, innerLength: int, Start: int = 0, End: int = 100) -> List[List[int]]`
Creates a 2D list (list of lists) with random integers.

- **Parameters:** Same as `randlistoflists`.
- **Returns:** A 2D list.
- **Example:**
  ```python
  two_d_list = randomak.rand2dlist(3, 4, 0, 30)
  print(two_d_list)
  # Output: [[5, 12, 19, 3], [7, 0, 15, 28], [9, 20, 11, 4]]
  ```

---

### 27. `randnesteddict(depth: int, breadth: int, Start: int = 0, End: int = 100) -> Dict[str, Any]`
Generates a nested dictionary with specified depth and breadth.

- **Parameters:**
  - `depth`: How many levels deep the dictionary is nested.
  - `breadth`: Number of key-value pairs at each level.
  - `Start`/`End`: Range for the integer values at the deepest level.
- **Returns:** A nested dictionary.
- **Example:**
  ```python
  nested_dict = randomak.randnesteddict(2, 2)
  print(nested_dict)
  # Output: {'Abc': {'Xyz': 45, 'Def': 12}, 'Qwe': {'Rty': 78, 'Uio': 34}}
  ```

---

### 28. `randdatetime(StartYear: int = 2000, EndYear: int = 2025) -> datetime.datetime`
Generates a random datetime object.

- **Parameters:**
  - `StartYear`: Earliest year.
  - `EndYear`: Latest year.
- **Returns:** A `datetime.datetime` object.
- **Example:**
  ```python
  dt = randomak.randdatetime(2010, 2020)
  print(dt)  # Output: 2017-05-23 14:35:12
  ```

---

### 29. `randcustomlist(NoOfElements: int, customFunc: Callable[[], Any]) -> List[Any]`
Generates a list where each element is produced by a custom function.

- **Parameters:**
  - `NoOfElements`: Number of elements.
  - `customFunc`: A function that returns a value; it is called for each element.
- **Returns:** A list of elements generated by the custom function.
- **Example:**
  ```python
  custom = randomak.randcustomlist(5, lambda: randomak.randint(0, 50))
  print(custom)  # Output: [13, 27, 6, 45, 22]
  ```

---

### 30. `randchoice(seq: Sequence[Any]) -> Any`
Selects a random element from a non-empty sequence.

- **Parameters:**
  - `seq`: A non-empty sequence (e.g., list, tuple).
- **Returns:** A randomly selected element, or `None` if the sequence is empty.
- **Example:**
  ```python
  element = randomak.randchoice(['apple', 'banana', 'cherry'])
  print(element)  # Output: 'banana'
  ```

---

## Contributing

Contributions to **RandomAK** are welcome. If you find bugs or have suggestions for improvements or new features, please open an issue or submit a pull request on our GitHub repository.

---

## License

This project is licensed under the **MIT License** â€“ see the [LICENSE](LICENSE) file for details.

---

## Contact

For questions or support, please contact:  
AnbuKumaran Arangaperumal
anbuku12345@gmail.com

--