Skip to content

Commit e538bdb

Browse files
committed
docs(en): update english version of readme
1 parent da97d7a commit e538bdb

1 file changed

Lines changed: 20 additions & 16 deletions

File tree

‎README.en.md‎

Lines changed: 20 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -22,15 +22,14 @@
2222
**PyCustomRand** is a self‑written Python library for generating **pseudo-random numbers**, based on an algorithm that utilizes system time with nanosecond precision.
2323

2424
This author's project was created to study algorithms and alternative approaches to random number generation and rounding.
25-
I was not satisfied with the fact that Python's standard `random` module generates insufficiently random numbers ( *especially during multiple sequential generations* ), and the built-in `round` module rounds
26-
numbers rather "roughly" ( *`round(1.5)` = 2 and at the same time `round(2.5)` = 2* ). Therefore, I decided to write *my own* library for pseudo-random number generation — simpler, with higher entropy and proper mathematical rounding.
25+
I was not satisfied with the fact that Python's standard `random` module generates insufficiently high-entropy numbers ( *especially during multiple sequential generations* ), and the built-in `round` module rounds numbers rather "roughly" ( *`round(1.5)` = 2 and at the same time `round(2.5)` = 2* ), therefore I decided to write *my own* library — simpler, with higher entropy and mathematical rounding.
2726

2827
> [!WARNING]
2928
> PyCustomRand is *currently* **not** a cryptographically secure library and is **not intended** for use in security systems!
3029
> Use the [secrets](https://docs.python.org/3/library/secrets.html#module-secrets) module for such purposes.
3130
3231
## 📌 Why use this library when Python has its own `random` and `round`?
33-
PyCustomRand was written as an alternative to these two built-in modules. Here are the main features and capabilities of the library:
32+
PyCustomRand was written as an alternative to these two built-in modules. Here are the main features and capabilities of the library, compared to them:
3433

3534
* The library is **simpler** to understand — the entire code is commented, lightweight, and clear. The PRNG (Pseudo-Random Number Generator) implementation is based on a *simple* algorithm using system time, making the library easy to customize, extend, or adapt to your needs.
3635
* In most cases, PyCustomRand produces a more *"entropic"* result during sequential generations compared to the built-in `random` module.
@@ -68,17 +67,17 @@ PyCustomRand was written as an alternative to these two built-in modules. Here a
6867
* <details>
6968
<summary>📑 List of functions</summary>
7069
71-
* Integer generation (`gen_random_number`, `randrange`, `random_integer`).
72-
* Float generation (`random`, `random_float`).
73-
* Statistical distributions: Normal (Gauss), Triangular, Exponential, Binomial.
74-
* Sequence tools: random element selection (`choice`), weighted selection (`choices`), shuffling (`shuffle`), and unique element selection (`sample`).
70+
* Integer generation (`gen_random_number`, `randrange`, `random_integer`);
71+
* Float generation (`random`, `random_float`);
72+
* Statistical distribution functions (`triangular`, `gauss`, `expovariate`, `binomialvariate`);
73+
* Sequence tools: random element selection (`choice`), weighted selection (`choices`), shuffling (`shuffle`), and unique element selection (`sample`);
7574
* PRNG sequence initialization ("seeding") (`set_seed`, `_get_next_seed_state`).
7675
</details>
7776
* The library also includes additional utilities useful for web/game development: generation of UUID v4, random HEX colors (e.g., `#ff05a1`), random bytes, random boolean values (`True`/`False`) with customizable probability.
78-
* It features a custom rounding module — `true_round`. This function rounds numbers using the standard mathematical method (0.5 is always rounded up by magnitude) and also fixes floating-point errors (e.g., the "2.675 problem").
79-
* The code is covered by unit tests (as indicated by the badge at the beginning of the README), and it has a built-in diagnostics module (`check_distribution`) allowing you to check the uniformity of the generator's distribution at any time.
77+
* A custom rounding module, `true_round`, rounds numbers using the standard mathematical method (0.5 is always rounded up by magnitude) and also fixes floating-point errors (e.g., the "2.675 problem").
78+
* The code is fully covered by unit tests (as indicated by the badge at the beginning of the README), and it has a built-in diagnostics module (`check_distribution`) allowing you to check the uniformity of the generator's distribution at any time.
8079

81-
However, the project does have some downsides:
80+
It is worth noting that the project still has some minor drawbacks:
8281
* Time-based randomness requires a small wait time (`time.sleep()` for 0.1 microseconds), so for massive iterations, PyCustomRand will be slightly slower than the built-in `random` module.
8382
* Some functions in PyCustomRand (selection, distributions) are written so simply that they might not be fully optimized for massive samples (plus the accumulating micro-wait mentioned above).
8483

@@ -100,9 +99,12 @@ pip install pycustomrand
10099
* Download the package **directly** from the *Releases* section:
101100
https://github.com/n1xsi/PyCustomRand/releases
102101

103-
* Clone the repository:
102+
* Clone the repository and install:
104103
```bash
105104
git clone https://github.com/n1xsi/PyCustomRand.git
105+
cd PyCustomRand
106+
pip install .
107+
# or for development: pip install -e .
106108
```
107109
</details>
108110

@@ -188,7 +190,9 @@ from pycustomrand import random, random_float
188190
print(random()) # Random number in [0, 1), e.g., 0.2260351121787103
189191

190192
print(random_float(0, 10)) # Random float in [0, 10), e.g., 4.014874483651235
191-
print(random_float(0, 10, digits=3)) # Same, but rounded to 3 decimals, e.g., 6.722
193+
print(random_float(0, 10, 3)) # Same, but rounded to 3 decimals, e.g., 6.722
194+
195+
print(random_float(1.2, 9.3)) # Example with float numbers in the range [1.2, 9.3), e.g., 5.899369498086576
192196
```
193197

194198
</details>
@@ -227,7 +231,7 @@ print(array) # e.g., ['cherry', 'banana', 'apple', 'orange']
227231

228232
print(sample(array, k=2)) # List of k unique elements, e.g., ['cherry', 'apple']
229233
print(sample(array, k=2, counts=[1, 2, 3, 4])) # Unique selection with counts, e.g., ['banana', 'orange']
230-
# "orange" (with the number in the array of 4) will produce four times more than "apple" (the number in the array of 1)
234+
# The probability of getting "orange" (with count 4 in the array) is four times higher than "apple" (count 1 in the array)
231235
```
232236

233237
</details>
@@ -245,12 +249,12 @@ These functions are used to model real-world processes (physics, economics, game
245249

246250
* `expovariate(lambd=1.0)` — Exponential distribution.
247251
Describes the time between events in a Poisson process. Small values appear often, large ones rarely (long tail).
248-
Used in timers. *Examples*: Time between bus arrivals, monster spawn times (they usually come up often, but sometimes there are long lulls ).
252+
Used in timers. *Examples*: Time between bus arrivals. Monster spawning (usually they come frequently, but sometimes there are long lulls).
249253
* `lambd`: Event intensity (must be > 0).
250254

251255
* `binomialvariate(n=1, p=0.5)` — Binomial distribution (alias: `binomial`).
252256
Number of successes in a sequence of `n` independent trials with success probability `p`.
253-
*Example*: Number of heads in 10 coin flips — `binomialvariate(n=10, p=0.5)`.
257+
Used in mathematics and financial modeling. *Example*: Number of heads in 10 coin flips — `binomialvariate(n=10, p=0.5)`.
254258

255259
<details>
256260
<summary>🧩 Examples 5</summary>
@@ -337,7 +341,7 @@ python -m unittest tests/test_round.py
337341
```
338342

339343
### 1.2. Running a specific test case
340-
If you are modifying the library, and you constantly fail to check any one specific test, then you don't have to waste time running all the tests - you just need to run one specific test of a specific module, for example:
344+
341345
```python
342346
from tests.test_round import TestTrueRound
343347
import unittest

0 commit comments

Comments
 (0)