browsermem 0.1.0__py3-none-win_amd64.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- browsermem/__init__.py +66 -0
- browsermem/__main__.py +5 -0
- browsermem/_native.py +139 -0
- browsermem/api.py +117 -0
- browsermem/browsermem.dll +0 -0
- browsermem/cli.py +182 -0
- browsermem/errors.py +44 -0
- browsermem/forensics.py +258 -0
- browsermem/history.py +122 -0
- browsermem/models.py +190 -0
- browsermem/monitor.py +335 -0
- browsermem/py.typed +0 -0
- browsermem-0.1.0.dist-info/METADATA +219 -0
- browsermem-0.1.0.dist-info/RECORD +17 -0
- browsermem-0.1.0.dist-info/WHEEL +5 -0
- browsermem-0.1.0.dist-info/entry_points.txt +3 -0
- browsermem-0.1.0.dist-info/licenses/LICENSE +21 -0
browsermem/monitor.py
ADDED
|
@@ -0,0 +1,335 @@
|
|
|
1
|
+
"""Live, event-driven tab monitoring."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import asyncio
|
|
6
|
+
import contextlib
|
|
7
|
+
import logging
|
|
8
|
+
import queue
|
|
9
|
+
import re
|
|
10
|
+
import threading
|
|
11
|
+
import time
|
|
12
|
+
from collections import defaultdict
|
|
13
|
+
from ctypes import byref, c_void_p, sizeof
|
|
14
|
+
from typing import (
|
|
15
|
+
AsyncIterator,
|
|
16
|
+
Callable,
|
|
17
|
+
Dict,
|
|
18
|
+
Iterator,
|
|
19
|
+
List,
|
|
20
|
+
Optional,
|
|
21
|
+
Pattern,
|
|
22
|
+
Set,
|
|
23
|
+
Tuple,
|
|
24
|
+
Union,
|
|
25
|
+
)
|
|
26
|
+
|
|
27
|
+
from ._native import TAB_CALLBACK, bm_monitor_options, lib
|
|
28
|
+
from .errors import check
|
|
29
|
+
from .models import BrowserFilter, EventKind, Tab, _tab_from_native, browser_mask
|
|
30
|
+
|
|
31
|
+
log = logging.getLogger("browsermem")
|
|
32
|
+
|
|
33
|
+
Handler = Callable[[Tab], None]
|
|
34
|
+
_STOP = object()
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
class _Filtered:
|
|
38
|
+
"""A handler that only fires when ``accept(tab)`` is true."""
|
|
39
|
+
|
|
40
|
+
def __init__(self, wrapped: Handler, accept: Callable[[Tab], bool]) -> None:
|
|
41
|
+
self.wrapped = wrapped
|
|
42
|
+
self.accept = accept
|
|
43
|
+
|
|
44
|
+
def __call__(self, tab: Tab) -> None:
|
|
45
|
+
if self.accept(tab):
|
|
46
|
+
self.wrapped(tab)
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
class TabMonitor:
|
|
50
|
+
"""Watches browser windows and reports tab changes together with their URL.
|
|
51
|
+
|
|
52
|
+
Consume events in whichever style fits your program (they can be combined)::
|
|
53
|
+
|
|
54
|
+
# callback
|
|
55
|
+
TabMonitor(lambda tab: print(tab.url)).run_forever()
|
|
56
|
+
|
|
57
|
+
# decorators, per event kind
|
|
58
|
+
monitor = TabMonitor()
|
|
59
|
+
|
|
60
|
+
@monitor.on(EventKind.TAB_CHANGED)
|
|
61
|
+
def changed(tab): ...
|
|
62
|
+
|
|
63
|
+
# blocking iterator
|
|
64
|
+
with TabMonitor() as monitor:
|
|
65
|
+
for tab in monitor.events():
|
|
66
|
+
...
|
|
67
|
+
|
|
68
|
+
# asyncio
|
|
69
|
+
async with TabMonitor() as monitor:
|
|
70
|
+
async for tab in monitor.aevents():
|
|
71
|
+
...
|
|
72
|
+
|
|
73
|
+
Callbacks run on a native worker thread: keep them short, or hand work off
|
|
74
|
+
to your own thread / event loop.
|
|
75
|
+
"""
|
|
76
|
+
|
|
77
|
+
def __init__(
|
|
78
|
+
self,
|
|
79
|
+
callback: Optional[Handler] = None,
|
|
80
|
+
*,
|
|
81
|
+
browsers: BrowserFilter = None,
|
|
82
|
+
all_windows: bool = False,
|
|
83
|
+
debounce_ms: int = 600,
|
|
84
|
+
rescan_ms: int = 0,
|
|
85
|
+
cache_ttl_ms: int = 30_000,
|
|
86
|
+
emit_unresolved: bool = True,
|
|
87
|
+
queue_size: int = 1000,
|
|
88
|
+
) -> None:
|
|
89
|
+
"""
|
|
90
|
+
Args:
|
|
91
|
+
callback: Called for every event.
|
|
92
|
+
browsers: Only watch these browsers (default: all supported).
|
|
93
|
+
all_windows: Also report changes in background browser windows.
|
|
94
|
+
debounce_ms: How long a window caption must be stable before it is reported.
|
|
95
|
+
rescan_ms: Periodically rescan the focused tab to catch navigations
|
|
96
|
+
that keep the same title (0 = off; each rescan costs ~0.1-0.6 s CPU).
|
|
97
|
+
cache_ttl_ms: Reuse a result while a window's caption is unchanged.
|
|
98
|
+
emit_unresolved: Deliver events even when no URL could be resolved.
|
|
99
|
+
queue_size: Capacity of the buffer behind :meth:`events`.
|
|
100
|
+
"""
|
|
101
|
+
self._options = bm_monitor_options()
|
|
102
|
+
lib.bm_monitor_options_init(byref(self._options))
|
|
103
|
+
self._options.struct_size = sizeof(bm_monitor_options)
|
|
104
|
+
self._options.browser_mask = browser_mask(browsers)
|
|
105
|
+
self._options.all_windows = int(all_windows)
|
|
106
|
+
self._options.debounce_ms = debounce_ms
|
|
107
|
+
self._options.rescan_ms = rescan_ms
|
|
108
|
+
self._options.cache_ttl_ms = cache_ttl_ms
|
|
109
|
+
self._options.emit_unresolved = int(emit_unresolved)
|
|
110
|
+
|
|
111
|
+
self._handlers: Dict[Optional[EventKind], List[Handler]] = defaultdict(list)
|
|
112
|
+
if callback:
|
|
113
|
+
self._handlers[None].append(callback)
|
|
114
|
+
self._queue: queue.Queue = queue.Queue(maxsize=queue_size)
|
|
115
|
+
self._async_queues: Set[Tuple[asyncio.AbstractEventLoop, asyncio.Queue]] = set()
|
|
116
|
+
self._handle = c_void_p()
|
|
117
|
+
self._native_cb = TAB_CALLBACK(self._on_native) # must outlive the native monitor
|
|
118
|
+
self._callback_thread: Optional[int] = None
|
|
119
|
+
self._lock = threading.RLock()
|
|
120
|
+
|
|
121
|
+
# -- handlers ------------------------------------------------------------
|
|
122
|
+
|
|
123
|
+
def on(self, *kinds: EventKind) -> Callable[[Handler], Handler]:
|
|
124
|
+
"""Decorator registering a handler for the given event kinds (all if none)."""
|
|
125
|
+
|
|
126
|
+
def register(fn: Handler) -> Handler:
|
|
127
|
+
self.add_handler(fn, *kinds)
|
|
128
|
+
return fn
|
|
129
|
+
|
|
130
|
+
return register
|
|
131
|
+
|
|
132
|
+
def add_handler(self, fn: Handler, *kinds: EventKind) -> None:
|
|
133
|
+
with self._lock:
|
|
134
|
+
for kind in kinds or (None,):
|
|
135
|
+
self._handlers[kind].append(fn)
|
|
136
|
+
|
|
137
|
+
def on_url(self, pattern: Union[str, Pattern[str]],
|
|
138
|
+
*kinds: EventKind) -> Callable[[Handler], Handler]:
|
|
139
|
+
"""Decorator: call the handler only when the tab URL matches a regex (``re.search``)::
|
|
140
|
+
|
|
141
|
+
@monitor.on_url(r"youtube\\.com/watch")
|
|
142
|
+
def video(tab): ...
|
|
143
|
+
"""
|
|
144
|
+
regex = re.compile(pattern) if isinstance(pattern, str) else pattern
|
|
145
|
+
|
|
146
|
+
def register(fn: Handler) -> Handler:
|
|
147
|
+
self.add_handler(_Filtered(fn, lambda t: bool(t.url and regex.search(t.url))), *kinds)
|
|
148
|
+
return fn
|
|
149
|
+
|
|
150
|
+
return register
|
|
151
|
+
|
|
152
|
+
def on_domain(self, *domains: str) -> Callable[[Handler], Handler]:
|
|
153
|
+
"""Decorator: call the handler only for tabs on these domains (and subdomains)::
|
|
154
|
+
|
|
155
|
+
@monitor.on_domain("github.com", "gitlab.com")
|
|
156
|
+
def code_hosting(tab): ...
|
|
157
|
+
"""
|
|
158
|
+
|
|
159
|
+
def register(fn: Handler) -> Handler:
|
|
160
|
+
self.add_handler(_Filtered(fn, lambda t: t.matches_domain(*domains)))
|
|
161
|
+
return fn
|
|
162
|
+
|
|
163
|
+
return register
|
|
164
|
+
|
|
165
|
+
def wait_for(
|
|
166
|
+
self,
|
|
167
|
+
match: Union[str, Pattern[str], Callable[[Tab], bool], None] = None,
|
|
168
|
+
timeout: Optional[float] = None,
|
|
169
|
+
) -> Optional[Tab]:
|
|
170
|
+
"""Block until a tab event matches, then return it (``None`` on timeout).
|
|
171
|
+
|
|
172
|
+
``match`` is a URL regex, a predicate, or ``None`` for the next event with a
|
|
173
|
+
URL. Starts the monitor if needed::
|
|
174
|
+
|
|
175
|
+
tab = monitor.wait_for(r"/checkout/complete", timeout=300)
|
|
176
|
+
"""
|
|
177
|
+
if match is None:
|
|
178
|
+
predicate: Callable[[Tab], bool] = lambda t: t.resolved # noqa: E731
|
|
179
|
+
elif callable(match):
|
|
180
|
+
predicate = match
|
|
181
|
+
else:
|
|
182
|
+
regex = re.compile(match) if isinstance(match, str) else match
|
|
183
|
+
predicate = lambda t: bool(t.url and regex.search(t.url)) # noqa: E731
|
|
184
|
+
|
|
185
|
+
found: List[Tab] = []
|
|
186
|
+
done = threading.Event()
|
|
187
|
+
|
|
188
|
+
def handler(tab: Tab) -> None:
|
|
189
|
+
if not done.is_set() and tab.event != EventKind.WINDOW_CLOSED and predicate(tab):
|
|
190
|
+
found.append(tab)
|
|
191
|
+
done.set()
|
|
192
|
+
|
|
193
|
+
self.add_handler(handler)
|
|
194
|
+
try:
|
|
195
|
+
self.start()
|
|
196
|
+
deadline = None if timeout is None else time.monotonic() + timeout
|
|
197
|
+
while not done.wait(0.25): # short waits keep Ctrl+C responsive
|
|
198
|
+
if deadline is not None and time.monotonic() >= deadline:
|
|
199
|
+
return None
|
|
200
|
+
return found[0]
|
|
201
|
+
finally:
|
|
202
|
+
self.remove_handler(handler)
|
|
203
|
+
|
|
204
|
+
def remove_handler(self, fn: Handler) -> None:
|
|
205
|
+
"""Unregister a handler (including ones added with on_url / on_domain)."""
|
|
206
|
+
with self._lock:
|
|
207
|
+
for handlers in self._handlers.values():
|
|
208
|
+
handlers[:] = [h for h in handlers
|
|
209
|
+
if h != fn and getattr(h, "wrapped", None) != fn]
|
|
210
|
+
|
|
211
|
+
# -- lifecycle -----------------------------------------------------------
|
|
212
|
+
|
|
213
|
+
@property
|
|
214
|
+
def running(self) -> bool:
|
|
215
|
+
return bool(self._handle.value)
|
|
216
|
+
|
|
217
|
+
def start(self) -> TabMonitor:
|
|
218
|
+
"""Start monitoring (idempotent). The current tab is reported as a SNAPSHOT event."""
|
|
219
|
+
with self._lock:
|
|
220
|
+
if not self.running:
|
|
221
|
+
check(lib.bm_monitor_start(byref(self._options), self._native_cb, None,
|
|
222
|
+
byref(self._handle)))
|
|
223
|
+
return self
|
|
224
|
+
|
|
225
|
+
def stop(self) -> None:
|
|
226
|
+
"""Stop monitoring (idempotent). Safe to call from inside a handler."""
|
|
227
|
+
if threading.get_ident() == self._callback_thread:
|
|
228
|
+
# The native worker cannot join itself: stop from another thread.
|
|
229
|
+
threading.Thread(target=self.stop, name="browsermem-stop", daemon=True).start()
|
|
230
|
+
return
|
|
231
|
+
with self._lock:
|
|
232
|
+
if not self.running:
|
|
233
|
+
return
|
|
234
|
+
handle, self._handle = self._handle, c_void_p()
|
|
235
|
+
check(lib.bm_monitor_stop(handle))
|
|
236
|
+
async_queues = list(self._async_queues)
|
|
237
|
+
self._put(_STOP)
|
|
238
|
+
for loop, q in async_queues:
|
|
239
|
+
loop.call_soon_threadsafe(q.put_nowait, _STOP)
|
|
240
|
+
|
|
241
|
+
def __enter__(self) -> TabMonitor:
|
|
242
|
+
return self.start()
|
|
243
|
+
|
|
244
|
+
def __exit__(self, *exc: object) -> None:
|
|
245
|
+
self.stop()
|
|
246
|
+
|
|
247
|
+
async def __aenter__(self) -> TabMonitor:
|
|
248
|
+
return self.start()
|
|
249
|
+
|
|
250
|
+
async def __aexit__(self, *exc: object) -> None:
|
|
251
|
+
await asyncio.get_running_loop().run_in_executor(None, self.stop)
|
|
252
|
+
|
|
253
|
+
def __del__(self) -> None:
|
|
254
|
+
with contextlib.suppress(Exception):
|
|
255
|
+
self.stop()
|
|
256
|
+
|
|
257
|
+
# -- consumption ---------------------------------------------------------
|
|
258
|
+
|
|
259
|
+
def events(self, timeout: Optional[float] = None) -> Iterator[Tab]:
|
|
260
|
+
"""Yield events until :meth:`stop` is called, or until ``timeout`` seconds
|
|
261
|
+
pass without an event. Ctrl+C works while waiting."""
|
|
262
|
+
while True:
|
|
263
|
+
waited = 0.0
|
|
264
|
+
while True:
|
|
265
|
+
try:
|
|
266
|
+
item = self._queue.get(timeout=0.25)
|
|
267
|
+
break
|
|
268
|
+
except queue.Empty:
|
|
269
|
+
waited += 0.25
|
|
270
|
+
if timeout is not None and waited >= timeout:
|
|
271
|
+
return
|
|
272
|
+
if item is _STOP:
|
|
273
|
+
return
|
|
274
|
+
yield item
|
|
275
|
+
|
|
276
|
+
async def aevents(self) -> AsyncIterator[Tab]:
|
|
277
|
+
"""Async iterator over events, delivered on the running event loop."""
|
|
278
|
+
loop = asyncio.get_running_loop()
|
|
279
|
+
q: asyncio.Queue = asyncio.Queue()
|
|
280
|
+
entry = (loop, q)
|
|
281
|
+
with self._lock:
|
|
282
|
+
self._async_queues.add(entry)
|
|
283
|
+
try:
|
|
284
|
+
while True:
|
|
285
|
+
item = await q.get()
|
|
286
|
+
if item is _STOP:
|
|
287
|
+
return
|
|
288
|
+
yield item
|
|
289
|
+
finally:
|
|
290
|
+
with self._lock:
|
|
291
|
+
self._async_queues.discard(entry)
|
|
292
|
+
|
|
293
|
+
def run_forever(self) -> None:
|
|
294
|
+
"""Start, dispatch events to handlers until Ctrl+C, then stop."""
|
|
295
|
+
self.start()
|
|
296
|
+
try:
|
|
297
|
+
for _ in self.events():
|
|
298
|
+
pass
|
|
299
|
+
except KeyboardInterrupt:
|
|
300
|
+
pass
|
|
301
|
+
finally:
|
|
302
|
+
self.stop()
|
|
303
|
+
|
|
304
|
+
# -- native bridge -------------------------------------------------------
|
|
305
|
+
|
|
306
|
+
def _put(self, item: object) -> None:
|
|
307
|
+
try:
|
|
308
|
+
self._queue.put_nowait(item)
|
|
309
|
+
except queue.Full: # drop the oldest event rather than block the native thread
|
|
310
|
+
with contextlib.suppress(queue.Empty):
|
|
311
|
+
self._queue.get_nowait()
|
|
312
|
+
self._queue.put_nowait(item)
|
|
313
|
+
|
|
314
|
+
def _on_native(self, ptr, _user) -> None: # runs on the native worker thread
|
|
315
|
+
self._callback_thread = threading.get_ident()
|
|
316
|
+
try:
|
|
317
|
+
tab = _tab_from_native(ptr.contents)
|
|
318
|
+
except Exception:
|
|
319
|
+
log.exception("browsermem: failed to decode a native event")
|
|
320
|
+
return
|
|
321
|
+
self._dispatch(tab)
|
|
322
|
+
|
|
323
|
+
def _dispatch(self, tab: Tab) -> None:
|
|
324
|
+
self._put(tab)
|
|
325
|
+
with self._lock:
|
|
326
|
+
handlers = [*self._handlers[None], *self._handlers[tab.event]]
|
|
327
|
+
async_queues = list(self._async_queues)
|
|
328
|
+
for loop, q in async_queues:
|
|
329
|
+
with contextlib.suppress(RuntimeError): # the event loop was closed
|
|
330
|
+
loop.call_soon_threadsafe(q.put_nowait, tab)
|
|
331
|
+
for handler in handlers:
|
|
332
|
+
try:
|
|
333
|
+
handler(tab)
|
|
334
|
+
except Exception:
|
|
335
|
+
log.exception("browsermem: handler %r raised", handler)
|
browsermem/py.typed
ADDED
|
File without changes
|
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: browsermem
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Real-time browser tab URLs and titles for Python on Windows: get the active tab, react to tab changes, track browsing activity. Chrome, Edge, Brave, Opera, Vivaldi.
|
|
5
|
+
Keywords: browser,url,active-tab,current-url,tab,chrome,edge,brave,real-time,monitoring,activity-tracking,windows,automation,forensics
|
|
6
|
+
Author: BinaryBreaker
|
|
7
|
+
Maintainer: BinaryBreaker
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Classifier: Development Status :: 4 - Beta
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: Intended Audience :: Information Technology
|
|
13
|
+
Classifier: Intended Audience :: Science/Research
|
|
14
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
15
|
+
Classifier: Programming Language :: C++
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
24
|
+
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
|
|
25
|
+
Classifier: Topic :: System :: Monitoring
|
|
26
|
+
Classifier: Topic :: Utilities
|
|
27
|
+
Classifier: Topic :: Security
|
|
28
|
+
Classifier: Typing :: Typed
|
|
29
|
+
Project-URL: Homepage, https://github.com/BinaryBreaker/browsermem
|
|
30
|
+
Project-URL: Documentation, https://binarybreaker.github.io/browsermem/
|
|
31
|
+
Project-URL: Issues, https://github.com/BinaryBreaker/browsermem/issues
|
|
32
|
+
Project-URL: Changelog, https://github.com/BinaryBreaker/browsermem/blob/main/CHANGELOG.md
|
|
33
|
+
Requires-Python: >=3.9
|
|
34
|
+
Provides-Extra: test
|
|
35
|
+
Requires-Dist: pytest>=7; extra == "test"
|
|
36
|
+
Requires-Dist: pytest-timeout>=2; extra == "test"
|
|
37
|
+
Provides-Extra: docs
|
|
38
|
+
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
|
|
39
|
+
Requires-Dist: mkdocstrings[python]>=0.26; extra == "docs"
|
|
40
|
+
Provides-Extra: dev
|
|
41
|
+
Requires-Dist: browsermem[docs,test]; extra == "dev"
|
|
42
|
+
Requires-Dist: ruff>=0.6; extra == "dev"
|
|
43
|
+
Requires-Dist: build>=1; extra == "dev"
|
|
44
|
+
Description-Content-Type: text/markdown
|
|
45
|
+
|
|
46
|
+
<div align="center">
|
|
47
|
+
|
|
48
|
+
# browsermem
|
|
49
|
+
|
|
50
|
+
**Get the real-time URL of the active browser tab from Python. No extension, no WebDriver, no setup.**
|
|
51
|
+
|
|
52
|
+
[](https://pypi.org/project/browsermem/)
|
|
53
|
+
[](https://pypi.org/project/browsermem/)
|
|
54
|
+
[](https://github.com/BinaryBreaker/browsermem/actions/workflows/ci.yml)
|
|
55
|
+
[](LICENSE)
|
|
56
|
+
[](https://binarybreaker.github.io/browsermem/)
|
|
57
|
+
|
|
58
|
+
</div>
|
|
59
|
+
|
|
60
|
+
```python
|
|
61
|
+
import browsermem
|
|
62
|
+
|
|
63
|
+
browsermem.current_url()
|
|
64
|
+
# 'https://github.com/BinaryBreaker/browsermem'
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
`browsermem` reads the active tab's URL and title straight from the browser's memory, and
|
|
68
|
+
sends an event every time you switch tabs, open a tab or navigate. It works with the
|
|
69
|
+
browser you already use: the user doesn't need to install anything or restart the browser
|
|
70
|
+
with special flags.
|
|
71
|
+
|
|
72
|
+
## Features
|
|
73
|
+
|
|
74
|
+
- **Active tab:** `current_url()`, `get_active_tab()`, or the active tab of every open window.
|
|
75
|
+
- **Live events:** tab switched, new tab, navigation, browser window focused or closed.
|
|
76
|
+
- **Several ways to handle events:** callbacks, decorators, iterators or `async for`.
|
|
77
|
+
- **Filters:** `@monitor.on_domain("youtube.com")`, `@monitor.on_url(r"/checkout")`, and
|
|
78
|
+
`monitor.wait_for(...)` to block until a matching page opens.
|
|
79
|
+
- **Activity tracking:** `TabHistory` records visits and time spent per domain.
|
|
80
|
+
- **Browsers:** Chrome, Edge, Brave, Opera and Vivaldi (any Chromium-based browser).
|
|
81
|
+
Firefox is experimental.
|
|
82
|
+
- **Fast:** event-driven (no polling loop in Python); about 0.1–0.5 s per lookup, with caching.
|
|
83
|
+
- **Command line:** `browsermem active`, `browsermem watch --json` and more.
|
|
84
|
+
- **Typed and dependency-free:** one wheel covers Python 3.9–3.14. Nothing to compile.
|
|
85
|
+
- **Bonus: memory forensics.** Analyse minidumps of a browser offline.
|
|
86
|
+
|
|
87
|
+
## Install
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
pip install browsermem
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Requires Windows 10/11 (x64) and Python 3.9+.
|
|
94
|
+
|
|
95
|
+
## Quick start
|
|
96
|
+
|
|
97
|
+
### The active tab
|
|
98
|
+
|
|
99
|
+
```python
|
|
100
|
+
import browsermem
|
|
101
|
+
|
|
102
|
+
tab = browsermem.get_active_tab()
|
|
103
|
+
print(tab.browser_name) # Google Chrome
|
|
104
|
+
print(tab.title) # BinaryBreaker/browsermem
|
|
105
|
+
print(tab.url) # https://github.com/BinaryBreaker/browsermem
|
|
106
|
+
print(tab.domain) # github.com
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
### React to tab changes
|
|
110
|
+
|
|
111
|
+
```python
|
|
112
|
+
from browsermem import TabMonitor, EventKind
|
|
113
|
+
|
|
114
|
+
monitor = TabMonitor()
|
|
115
|
+
|
|
116
|
+
@monitor.on(EventKind.TAB_CHANGED, EventKind.WINDOW_ACTIVATED)
|
|
117
|
+
def changed(tab):
|
|
118
|
+
print(f"{tab.browser_name}: {tab.title} -> {tab.url}")
|
|
119
|
+
|
|
120
|
+
@monitor.on_domain("youtube.com")
|
|
121
|
+
def youtube(tab):
|
|
122
|
+
print("Watching:", tab.title)
|
|
123
|
+
|
|
124
|
+
monitor.run_forever() # Ctrl+C to stop
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
### Iterate, or use asyncio
|
|
128
|
+
|
|
129
|
+
```python
|
|
130
|
+
with TabMonitor() as monitor:
|
|
131
|
+
for tab in monitor.events():
|
|
132
|
+
print(tab.url)
|
|
133
|
+
|
|
134
|
+
async with TabMonitor() as monitor:
|
|
135
|
+
async for tab in monitor.aevents():
|
|
136
|
+
print(tab.url)
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
### Wait for a page
|
|
140
|
+
|
|
141
|
+
```python
|
|
142
|
+
with TabMonitor() as monitor:
|
|
143
|
+
tab = monitor.wait_for(r"/payment/success", timeout=300)
|
|
144
|
+
print("Done!" if tab else "Timed out")
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
### Track browsing time
|
|
148
|
+
|
|
149
|
+
```python
|
|
150
|
+
from browsermem import TabMonitor, TabHistory
|
|
151
|
+
|
|
152
|
+
monitor = TabMonitor()
|
|
153
|
+
history = TabHistory(monitor)
|
|
154
|
+
monitor.start()
|
|
155
|
+
# ... later
|
|
156
|
+
for domain, spent in history.time_by_domain().items():
|
|
157
|
+
print(f"{domain:30} {spent}")
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
### Command line
|
|
161
|
+
|
|
162
|
+
```bash
|
|
163
|
+
browsermem active # URL of the active tab
|
|
164
|
+
browsermem windows # all browser windows
|
|
165
|
+
browsermem watch # live tab events
|
|
166
|
+
browsermem watch --json # JSON lines, ready to pipe
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
## Events
|
|
170
|
+
|
|
171
|
+
| `EventKind` | When |
|
|
172
|
+
|---|---|
|
|
173
|
+
| `SNAPSHOT` | Current state when the monitor starts (also returned by one-shot queries) |
|
|
174
|
+
| `TAB_CHANGED` | Tab switch, new tab, or a navigation that changed the page title |
|
|
175
|
+
| `WINDOW_ACTIVATED` | You switched to a browser window from another app or window |
|
|
176
|
+
| `URL_CHANGED` | Same title, different URL (single-page apps). Needs `rescan_ms` |
|
|
177
|
+
| `WINDOW_CLOSED` | A browser window closed; the event holds its last tab |
|
|
178
|
+
|
|
179
|
+
## How it works
|
|
180
|
+
|
|
181
|
+
1. Windows notifies browsermem when a browser window gains focus or its title changes,
|
|
182
|
+
which happens on every tab switch and navigation.
|
|
183
|
+
2. browsermem takes a snapshot of the browser process's own memory (read-only, the same
|
|
184
|
+
access Task Manager uses).
|
|
185
|
+
3. It finds the tab's title in that memory, follows the pointers that refer to it, and
|
|
186
|
+
picks the URL stored inside the same browser objects.
|
|
187
|
+
|
|
188
|
+
See [How it works](https://binarybreaker.github.io/browsermem/how-it-works/) for details.
|
|
189
|
+
|
|
190
|
+
## Supported browsers
|
|
191
|
+
|
|
192
|
+
| Browser | Status |
|
|
193
|
+
|---|---|
|
|
194
|
+
| Google Chrome | ✅ tested |
|
|
195
|
+
| Microsoft Edge | ✅ tested |
|
|
196
|
+
| Brave, Opera, Vivaldi, Yandex | ✅ supported (same Chromium engine) |
|
|
197
|
+
| Firefox | 🧪 experimental |
|
|
198
|
+
|
|
199
|
+
## Limitations
|
|
200
|
+
|
|
201
|
+
- Windows x64 only for now.
|
|
202
|
+
- A navigation that keeps the same page title is only detected with `TabMonitor(rescan_ms=...)`.
|
|
203
|
+
- Two tabs with exactly the same title can be confused.
|
|
204
|
+
- browsermem only reads processes your user account can open (no elevation needed for
|
|
205
|
+
your own browser).
|
|
206
|
+
|
|
207
|
+
## Responsible use
|
|
208
|
+
|
|
209
|
+
browsermem reads memory of processes that belong to **your** user account. Use it for your
|
|
210
|
+
own productivity tools, automation, research and authorised investigations. Monitoring
|
|
211
|
+
other people's browsing without their knowledge and consent may be illegal where you live.
|
|
212
|
+
|
|
213
|
+
## Contributing
|
|
214
|
+
|
|
215
|
+
Bug reports and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
216
|
+
|
|
217
|
+
## License
|
|
218
|
+
|
|
219
|
+
[MIT](LICENSE) © BinaryBreaker
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
browsermem/__init__.py,sha256=kQ1JBZB0Gwf0gQyKUxYqXHgrcJqTG-B_-YHexBh2vHs,1494
|
|
2
|
+
browsermem/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
|
|
3
|
+
browsermem/_native.py,sha256=gRWr9aJL14Brqpk_FFkJZNcOo19p79S-Pxi3S5oLuJI,3941
|
|
4
|
+
browsermem/api.py,sha256=roZrhcMtkFpSj5vjjK4ZaaSLmDJDHETPvhYNWliWk7U,3426
|
|
5
|
+
browsermem/browsermem.dll,sha256=QcaV5lv46n6KJhtyirkjg6COsAFRgg1m9Jim8aCDNSA,289792
|
|
6
|
+
browsermem/cli.py,sha256=mh-CnIaFI9ABiQznpWYMjqzaRQvmpZ3V87cpS45yiOU,6438
|
|
7
|
+
browsermem/errors.py,sha256=TvLZxa_iD58ov_ZdT-Nj-Fg4eJ3t5BrAYpnU4K7Vork,1203
|
|
8
|
+
browsermem/forensics.py,sha256=UFEUk_-t5PNtlourxSmVOlpnhWpb2yVKgw9jE0fhv1A,9993
|
|
9
|
+
browsermem/history.py,sha256=xI4j4XrIBEo_0Mta6sD2RY6Kt0qxdtjjfK_7oXP07js,4347
|
|
10
|
+
browsermem/models.py,sha256=_mHX3AUXxTsEfsAzsL5Hr7JIeHRLA6izijBmS1N2kiI,5684
|
|
11
|
+
browsermem/monitor.py,sha256=Vz-brxH0A8gJSMfZy4ZhSwusdslv33yuqeSwUzIqouA,11863
|
|
12
|
+
browsermem/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
13
|
+
browsermem-0.1.0.dist-info/METADATA,sha256=reNj9j4dhIhLB8CLR0ApENmoPSFA10Bd1V1Ol26jQaA,7808
|
|
14
|
+
browsermem-0.1.0.dist-info/WHEEL,sha256=MavvTN48CE-QbhQ_kyQzVg79Yjk576_oKsIlJsE4vMI,102
|
|
15
|
+
browsermem-0.1.0.dist-info/entry_points.txt,sha256=7AxZlu314xtjmzAoOrawRCQq3oR5aF2zceUV7IoDV_g,52
|
|
16
|
+
browsermem-0.1.0.dist-info/licenses/LICENSE,sha256=wehhnCDL3DkPSjDNHripSqKDxKR_CQK68dIwwyKwIUw,1070
|
|
17
|
+
browsermem-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 BinaryBreaker
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|