Skip to content

Commit 2efc9e3

Browse files
committed
docs(readme): add Offline Mode section
1 parent d6c27fc commit 2efc9e3

1 file changed

Lines changed: 77 additions & 1 deletion

File tree

README.md

Lines changed: 77 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,12 @@
11
# TrueEntropy 🎲
22

3-
[![PyPI version](https://badge.fury.io/py/trueentropy.svg)](https://badge.fury.io/py/trueentropy)
3+
[![CI](https://github.com/medeirosdev/TrueEntropy-PyLib/actions/workflows/ci.yml/badge.svg)](https://github.com/medeirosdev/TrueEntropy-PyLib/actions/workflows/ci.yml)
4+
[![PyPI version](https://badge.fury.io/py/trueentropy.svg)](https://pypi.org/project/trueentropy/)
5+
[![PyPI downloads](https://img.shields.io/pypi/dm/trueentropy.svg)](https://pypi.org/project/trueentropy/)
46
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
57
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
68
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
9+
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
710

811
**True randomness from real-world entropy sources.**
912

@@ -75,6 +78,79 @@ for _ in range(1000):
7578
trueentropy.stop_collector()
7679
```
7780

81+
## Offline Mode
82+
83+
TrueEntropy can operate without network access using local entropy sources only.
84+
85+
### Sources by Network Requirement
86+
87+
| Source | Requires Network | Description |
88+
|--------|------------------|-------------|
89+
| **Timing Jitter** | ❌ No | CPU timing variations |
90+
| **System State** | ❌ No | RAM, processes, CPU metrics |
91+
| **Network Latency** | ✅ Yes | Ping response times |
92+
| **External APIs** | ✅ Yes | Earthquakes, crypto prices |
93+
| **Weather Data** | ✅ Yes | OpenWeatherMap / wttr.in |
94+
| **Quantum Random** | ✅ Yes | random.org / ANU QRNG |
95+
96+
### Enabling Offline Mode
97+
98+
```python
99+
import trueentropy
100+
101+
# Enable offline mode (disables all network-dependent sources)
102+
trueentropy.configure(offline_mode=True)
103+
104+
# Generate random numbers using local sources only
105+
value = trueentropy.random()
106+
number = trueentropy.randint(1, 100)
107+
108+
# Check which sources are active
109+
health = trueentropy.health()
110+
print(f"Offline mode: {health['offline_mode']}")
111+
for source, info in health['sources'].items():
112+
status = "" if info['enabled'] else ""
113+
print(f" {status} {source}")
114+
```
115+
116+
### Selective Source Configuration
117+
118+
```python
119+
import trueentropy
120+
121+
# Disable only specific sources
122+
trueentropy.configure(
123+
enable_weather=False, # Disable weather API
124+
enable_radioactive=False, # Disable quantum sources
125+
)
126+
127+
# Or enable only fast local sources
128+
trueentropy.configure(
129+
offline_mode=True, # Disable all network sources
130+
enable_timing=True, # Keep timing jitter
131+
enable_system=True, # Keep system state
132+
)
133+
134+
# Reset to defaults (all sources enabled)
135+
trueentropy.reset_config()
136+
```
137+
138+
### Health Monitoring in Offline Mode
139+
140+
```python
141+
from trueentropy import get_pool
142+
from trueentropy.health import print_health_report
143+
144+
# Configure offline mode
145+
trueentropy.configure(offline_mode=True)
146+
147+
# View detailed health report with source status
148+
print_health_report(get_pool())
149+
```
150+
151+
> **Note**: Offline mode provides reduced entropy diversity. For security-critical applications, consider using all available sources when network access is available.
152+
153+
78154
## Advanced Features
79155

80156
### Async Support

0 commit comments

Comments
 (0)