snooper-pkg 0.0.1__py3-none-any.whl

snooper_pkg/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

snooper_pkg/_modidx.py

@@ -0,0 +1,102 @@
+# Autogenerated by nbdev
+
+d = { 'settings': { 'branch': 'main',
+                'doc_baseurl': '/snooper_pkg',
+                'doc_host': 'https://sayanbanerjee32.github.io',
+                'git_url': 'https://github.com/sayanbanerjee32/snooper_pkg',
+                'lib_path': 'snooper_pkg'},
+  'syms': { 'snooper_pkg.config': {},
+            'snooper_pkg.db': { 'snooper_pkg.db.ForegroundEvent': ('db.html#foregroundevent', 'snooper_pkg/db.py'),
+                                'snooper_pkg.db.ProcessEvent': ('db.html#processevent', 'snooper_pkg/db.py'),
+                                'snooper_pkg.db.Session': ('db.html#session', 'snooper_pkg/db.py'),
+                                'snooper_pkg.db._db_timestamp': ('db.html#_db_timestamp', 'snooper_pkg/db.py'),
+                                'snooper_pkg.db.close_stale_open_sessions': ('db.html#close_stale_open_sessions', 'snooper_pkg/db.py'),
+                                'snooper_pkg.db.delete_old_data': ('db.html#delete_old_data', 'snooper_pkg/db.py'),
+                                'snooper_pkg.db.end_session': ('db.html#end_session', 'snooper_pkg/db.py'),
+                                'snooper_pkg.db.get_foreground_events': ('db.html#get_foreground_events', 'snooper_pkg/db.py'),
+                                'snooper_pkg.db.get_last_completed_session': ('db.html#get_last_completed_session', 'snooper_pkg/db.py'),
+                                'snooper_pkg.db.get_processes': ('db.html#get_processes', 'snooper_pkg/db.py'),
+                                'snooper_pkg.db.get_session_by_session_id': ('db.html#get_session_by_session_id', 'snooper_pkg/db.py'),
+                                'snooper_pkg.db.init_db': ('db.html#init_db', 'snooper_pkg/db.py'),
+                                'snooper_pkg.db.log_fg_app_events': ('db.html#log_fg_app_events', 'snooper_pkg/db.py'),
+                                'snooper_pkg.db.log_process_event': ('db.html#log_process_event', 'snooper_pkg/db.py'),
+                                'snooper_pkg.db.start_session': ('db.html#start_session', 'snooper_pkg/db.py')},
+            'snooper_pkg.foreground_tracker': { 'snooper_pkg.foreground_tracker._require_windows': ( 'foreground_tracker.html#_require_windows',
+                                                                                                     'snooper_pkg/foreground_tracker.py'),
+                                                'snooper_pkg.foreground_tracker.get_foreground_window_info': ( 'foreground_tracker.html#get_foreground_window_info',
+                                                                                                               'snooper_pkg/foreground_tracker.py'),
+                                                'snooper_pkg.foreground_tracker.is_streaming_app': ( 'foreground_tracker.html#is_streaming_app',
+                                                                                                     'snooper_pkg/foreground_tracker.py'),
+                                                'snooper_pkg.foreground_tracker.start_foreground_app_monitoring': ( 'foreground_tracker.html#start_foreground_app_monitoring',
+                                                                                                                    'snooper_pkg/foreground_tracker.py')},
+            'snooper_pkg.idle_detector': { 'snooper_pkg.idle_detector.LASTINPUTINFO': ( 'idle_detector.html#lastinputinfo',
+                                                                                        'snooper_pkg/idle_detector.py'),
+                                           'snooper_pkg.idle_detector._require_windows': ( 'idle_detector.html#_require_windows',
+                                                                                           'snooper_pkg/idle_detector.py'),
+                                           'snooper_pkg.idle_detector.get_idle_seconds': ( 'idle_detector.html#get_idle_seconds',
+                                                                                           'snooper_pkg/idle_detector.py'),
+                                           'snooper_pkg.idle_detector.get_last_input_tick': ( 'idle_detector.html#get_last_input_tick',
+                                                                                              'snooper_pkg/idle_detector.py')},
+            'snooper_pkg.main': { 'snooper_pkg.main._acquire_single_instance': ( 'main.html#_acquire_single_instance',
+                                                                                 'snooper_pkg/main.py'),
+                                  'snooper_pkg.main.configure_logging': ('main.html#configure_logging', 'snooper_pkg/main.py'),
+                                  'snooper_pkg.main.main': ('main.html#main', 'snooper_pkg/main.py')},
+            'snooper_pkg.monitoring_controller': { 'snooper_pkg.monitoring_controller.MonitorController': ( 'monitoring_controller.html#monitorcontroller',
+                                                                                                            'snooper_pkg/monitoring_controller.py'),
+                                                   'snooper_pkg.monitoring_controller.MonitorController.__init__': ( 'monitoring_controller.html#monitorcontroller.__init__',
+                                                                                                                     'snooper_pkg/monitoring_controller.py'),
+                                                   'snooper_pkg.monitoring_controller.MonitorController._auto_resume': ( 'monitoring_controller.html#monitorcontroller._auto_resume',
+                                                                                                                         'snooper_pkg/monitoring_controller.py'),
+                                                   'snooper_pkg.monitoring_controller.MonitorController._midnight_rollover': ( 'monitoring_controller.html#monitorcontroller._midnight_rollover',
+                                                                                                                               'snooper_pkg/monitoring_controller.py'),
+                                                   'snooper_pkg.monitoring_controller.MonitorController.generate_current_session_stats': ( 'monitoring_controller.html#monitorcontroller.generate_current_session_stats',
+                                                                                                                                           'snooper_pkg/monitoring_controller.py'),
+                                                   'snooper_pkg.monitoring_controller.MonitorController.generate_last_report_data': ( 'monitoring_controller.html#monitorcontroller.generate_last_report_data',
+                                                                                                                                      'snooper_pkg/monitoring_controller.py'),
+                                                   'snooper_pkg.monitoring_controller.MonitorController.is_paused': ( 'monitoring_controller.html#monitorcontroller.is_paused',
+                                                                                                                      'snooper_pkg/monitoring_controller.py'),
+                                                   'snooper_pkg.monitoring_controller.MonitorController.is_running': ( 'monitoring_controller.html#monitorcontroller.is_running',
+                                                                                                                       'snooper_pkg/monitoring_controller.py'),
+                                                   'snooper_pkg.monitoring_controller.MonitorController.pause_for': ( 'monitoring_controller.html#monitorcontroller.pause_for',
+                                                                                                                      'snooper_pkg/monitoring_controller.py'),
+                                                   'snooper_pkg.monitoring_controller.MonitorController.resume_now': ( 'monitoring_controller.html#monitorcontroller.resume_now',
+                                                                                                                       'snooper_pkg/monitoring_controller.py'),
+                                                   'snooper_pkg.monitoring_controller.MonitorController.run_startup_housekeeping': ( 'monitoring_controller.html#monitorcontroller.run_startup_housekeeping',
+                                                                                                                                     'snooper_pkg/monitoring_controller.py'),
+                                                   'snooper_pkg.monitoring_controller.MonitorController.start_monitoring': ( 'monitoring_controller.html#monitorcontroller.start_monitoring',
+                                                                                                                             'snooper_pkg/monitoring_controller.py'),
+                                                   'snooper_pkg.monitoring_controller.MonitorController.stop_monitoring': ( 'monitoring_controller.html#monitorcontroller.stop_monitoring',
+                                                                                                                            'snooper_pkg/monitoring_controller.py'),
+                                                   'snooper_pkg.monitoring_controller.seconds_until_midnight': ( 'monitoring_controller.html#seconds_until_midnight',
+                                                                                                                 'snooper_pkg/monitoring_controller.py')},
+            'snooper_pkg.process_monitor': { 'snooper_pkg.process_monitor.get_current_processes': ( 'process_monitor.html#get_current_processes',
+                                                                                                    'snooper_pkg/process_monitor.py'),
+                                             'snooper_pkg.process_monitor.start_process_monitoring': ( 'process_monitor.html#start_process_monitoring',
+                                                                                                       'snooper_pkg/process_monitor.py')},
+            'snooper_pkg.report_window': { 'snooper_pkg.report_window.fmt_duration': ( 'report_window.html#fmt_duration',
+                                                                                       'snooper_pkg/report_window.py'),
+                                           'snooper_pkg.report_window.show_apps': ( 'report_window.html#show_apps',
+                                                                                    'snooper_pkg/report_window.py'),
+                                           'snooper_pkg.report_window.show_report': ( 'report_window.html#show_report',
+                                                                                      'snooper_pkg/report_window.py'),
+                                           'snooper_pkg.report_window.show_summary': ( 'report_window.html#show_summary',
+                                                                                       'snooper_pkg/report_window.py'),
+                                           'snooper_pkg.report_window.show_titles': ( 'report_window.html#show_titles',
+                                                                                      'snooper_pkg/report_window.py'),
+                                           'snooper_pkg.report_window.update_titles': ( 'report_window.html#update_titles',
+                                                                                        'snooper_pkg/report_window.py')},
+            'snooper_pkg.reporter': { 'snooper_pkg.reporter._clean_events': ('reporter.html#_clean_events', 'snooper_pkg/reporter.py'),
+                                      'snooper_pkg.reporter._events_data': ('reporter.html#_events_data', 'snooper_pkg/reporter.py'),
+                                      'snooper_pkg.reporter._session_data': ('reporter.html#_session_data', 'snooper_pkg/reporter.py'),
+                                      'snooper_pkg.reporter._summary_data': ('reporter.html#_summary_data', 'snooper_pkg/reporter.py'),
+                                      'snooper_pkg.reporter.build_session_report_data': ( 'reporter.html#build_session_report_data',
+                                                                                          'snooper_pkg/reporter.py')},
+            'snooper_pkg.tray': { 'snooper_pkg.tray.UiDispatcher': ('tray.html#uidispatcher', 'snooper_pkg/tray.py'),
+                                  'snooper_pkg.tray.UiDispatcher.__init__': ('tray.html#uidispatcher.__init__', 'snooper_pkg/tray.py'),
+                                  'snooper_pkg.tray.UiDispatcher._process': ('tray.html#uidispatcher._process', 'snooper_pkg/tray.py'),
+                                  'snooper_pkg.tray.UiDispatcher.submit': ('tray.html#uidispatcher.submit', 'snooper_pkg/tray.py'),
+                                  'snooper_pkg.tray.open_current_session_report': ( 'tray.html#open_current_session_report',
+                                                                                    'snooper_pkg/tray.py'),
+                                  'snooper_pkg.tray.open_last_session_report': ( 'tray.html#open_last_session_report',
+                                                                                 'snooper_pkg/tray.py'),
+                                  'snooper_pkg.tray.run_tray': ('tray.html#run_tray', 'snooper_pkg/tray.py')}}}

snooper_pkg/config.py

@@ -0,0 +1,54 @@
+"""Central configuration values for Snooper's monitoring, data retention, reporting, privacy, and pause behaviour.
+
+Docs: https://sayanbanerjee32.github.io/snooper_pkg/config.html.md"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/00_config.ipynb.
+
+# %% auto #0
+__all__ = ['APP_NAME', 'LOG_FILENAME', 'LOG_LEVEL', 'PROCESS_MONITORING_INTERVAL_SECONDS', 'EXCLUDED_PROCESSES',
+           'DATABASE_FILENAME', 'DATA_RETENTION_DAYS', 'FG_APP_MONITORING_INTERVAL_SECONDS',
+           'FG_APP_MONITORING_MIN_IDLE_SECONDS', 'STREAMING_APP_MIN_IDLE_SECONDS', 'NUM_TOP_APP_IN_REPORT',
+           'NUM_TOP_WINDOW_IN_REPORT', 'SHOW_WINDOW_TITLES', 'DEFAULT_PAUSE_MINUTES']
+
+# %% ../nbs/00_config.ipynb #f2a11914
+APP_NAME = "Snooper"
+
+
+# %% ../nbs/00_config.ipynb #2c47f2da
+LOG_FILENAME = "snooper.log"
+
+# %% ../nbs/00_config.ipynb #e0c32039
+LOG_LEVEL = "WARNING"  # DEBUG, INFO, WARNING, ERROR
+
+# %% ../nbs/00_config.ipynb #f99ee53a
+PROCESS_MONITORING_INTERVAL_SECONDS = 5
+
+# %% ../nbs/00_config.ipynb #f8d4d24d
+EXCLUDED_PROCESSES = {'sudo','python'}
+
+# %% ../nbs/00_config.ipynb #13babdaf
+DATABASE_FILENAME = "snooper.db"
+
+# %% ../nbs/00_config.ipynb #941e072f
+DATA_RETENTION_DAYS = 7
+
+# %% ../nbs/00_config.ipynb #d380659a
+FG_APP_MONITORING_INTERVAL_SECONDS = 2
+
+# %% ../nbs/00_config.ipynb #97baa2a4
+FG_APP_MONITORING_MIN_IDLE_SECONDS = 60
+
+# %% ../nbs/00_config.ipynb #0a8552af
+STREAMING_APP_MIN_IDLE_SECONDS = {'youtube': 600, 'netflix': 600, 'twitch': 600}
+
+# %% ../nbs/00_config.ipynb #199d6147
+NUM_TOP_APP_IN_REPORT = 10
+
+# %% ../nbs/00_config.ipynb #c58e4eb3
+NUM_TOP_WINDOW_IN_REPORT = 5
+
+# %% ../nbs/00_config.ipynb #84bab75b
+SHOW_WINDOW_TITLES = True
+
+# %% ../nbs/00_config.ipynb #e2cf94c1
+DEFAULT_PAUSE_MINUTES = 30

snooper_pkg/db.py

@@ -0,0 +1,304 @@
+"""SQLite persistence APIs for monitoring sessions, foreground activity, and process events.
+
+Docs: https://sayanbanerjee32.github.io/snooper_pkg/db.html.md"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/01_db.ipynb.
+
+# %% auto #0
+__all__ = ['ProcessEvent', 'Session', 'ForegroundEvent', 'init_db', 'log_process_event', 'get_processes', 'start_session',
+           'end_session', 'get_last_completed_session', 'close_stale_open_sessions', 'get_session_by_session_id',
+           'log_fg_app_events', 'get_foreground_events', 'delete_old_data']
+
+# %% ../nbs/01_db.ipynb #f9f7bca0
+import logging
+logger = logging.getLogger(__name__)
+
+
+# %% ../nbs/01_db.ipynb #6421ef53
+from datetime import datetime, timedelta
+from fastlite import *
+from platformdirs import user_data_path
+
+# %% ../nbs/01_db.ipynb #e1ae96a1
+import snooper_pkg.config as cf
+
+# %% ../nbs/01_db.ipynb #de4ffec3
+class ProcessEvent:
+    "A recorded process start or stop event."
+
+    session_id: str  # Monitoring session containing the event
+    pid: int         # Operating-system process identifier
+    app: str         # Process or application name
+    event_type: str  # Event type: `start` or `stop`
+    timestamp: str   # ISO-formatted event timestamp
+    id: int | None = None  # Database-generated primary key
+
+# %% ../nbs/01_db.ipynb #9ed8b625
+class Session:
+    "A single continuous monitoring session."
+
+    session_id: str       # Unique session identifier
+    start_time: str       # ISO-formatted session start time
+    end_time: str | None  # ISO-formatted end time; `None` while open
+    status: str           # Session state: `open` or `closed`
+    end_reason: str | None  # Reason the session ended
+
+# %% ../nbs/01_db.ipynb #038a14fd
+class ForegroundEvent:
+    "An interval during which an application or idle state was in the foreground."
+
+    session_id: str       # Monitoring session containing the interval
+    app: str              # Foreground application name
+    pid: int              # Foreground process identifier
+    window_title: str     # Foreground window title
+    start_time: str       # ISO-formatted interval start time
+    end_time: str         # ISO-formatted interval end time
+    hwnd: int             # Windows window handle
+    is_idle: bool         # Whether the interval represents user idle time
+    id: int | None = None  # Database-generated primary key
+
+# %% ../nbs/01_db.ipynb #3d9026f4
+def _db_timestamp(value: str | datetime) -> str:
+    "Convert a timestamp into the string format stored in SQLite."
+    return value.isoformat(sep=" ", timespec="seconds") if isinstance(value, datetime) else value
+
+# %% ../nbs/01_db.ipynb #fe74016d
+DATA_DIR = user_data_path(cf.APP_NAME, appauthor=False)
+DATABASE_PATH = DATA_DIR / cf.DATABASE_FILENAME
+
+db = None
+process_events = sessions = fore_ground_app_events = None
+
+# %% ../nbs/01_db.ipynb #75286d2b
+def init_db(
+                path=None # database path for the application
+            ):
+    "Open the database connection and create tables. Uses `DATABASE_PATH` if `path` is None."
+    global db, process_events, sessions, fore_ground_app_events
+    if path is None: path = DATABASE_PATH
+    path.parent.mkdir(parents=True, exist_ok=True)
+    db = database(path)
+    process_events = db.create(ProcessEvent, if_not_exists=True, transform=True)
+    sessions = db.create(Session, pk="session_id", if_not_exists=True, transform=True)
+    fore_ground_app_events = db.create(ForegroundEvent, if_not_exists=True, transform=True)
+    return db
+
+# %% ../nbs/01_db.ipynb #35a9d475
+def log_process_event(
+    session_id: str,  # Session receiving the event
+    pid: int,         # Operating-system process identifier
+    app: str,         # Process or application name
+    event_type: str,  # Event type: `start` or `stop`
+    timestamp: str,   # ISO-formatted event timestamp
+):
+    "Record a process start or stop event."
+    return process_events.insert(
+        session_id=session_id,
+        pid=pid,
+        app=app,
+        event_type=event_type,
+        timestamp=timestamp,
+    )
+
+# %% ../nbs/01_db.ipynb #70e04342
+def get_processes(
+    session_id: str,  # Session whose completed process intervals are requested
+) -> list[dict]:
+    "Return paired process start/stop intervals for a session."
+    return db.q(
+        """
+        SELECT
+            s.session_id,
+            s.pid,
+            s.app,
+            s.timestamp AS start_time,
+            e.timestamp AS stop_time,
+            (julianday(e.timestamp) - julianday(s.timestamp)) * 86400
+                AS duration_seconds
+        FROM process_event s
+        JOIN process_event e
+            ON s.pid = e.pid
+            AND s.app = e.app
+            AND s.session_id = e.session_id
+        WHERE s.event_type = 'start'
+            AND e.event_type = 'stop'
+            AND s.session_id = ?
+        """,
+        [session_id],
+    )
+
+# %% ../nbs/01_db.ipynb #9e0b447c
+def start_session(
+    session_id: str,  # Unique identifier for the new session
+    start_time: str,  # ISO-formatted session start time
+):
+    "Create and return a new open monitoring session."
+    start_time = _db_timestamp(start_time)
+    return sessions.insert(
+        session_id=session_id,
+        start_time=start_time,
+        status="open",
+    )
+
+# %% ../nbs/01_db.ipynb #e72f7a86
+def end_session(
+    session_id: str,          # Session to close
+    end_time: str,            # ISO-formatted session end time
+    end_reason: str = "NA",   # Reason the session ended
+):
+    "Close a monitoring session and record why it ended."
+    end_time = _db_timestamp(end_time)
+    return sessions.update(
+        session_id=session_id,
+        end_time=end_time,
+        status="closed",
+        end_reason=end_reason,
+    )
+
+# %% ../nbs/01_db.ipynb #0c1f5f71
+def get_last_completed_session() -> dict:
+    "Return the most recently completed session, or an empty dictionary."
+    rows = db.q(
+        """
+        SELECT session_id, start_time, end_time
+        FROM session
+        WHERE status = 'closed'
+        ORDER BY julianday(end_time) DESC
+        LIMIT 1
+        """
+    )
+    return rows[0] if rows else {}
+
+# %% ../nbs/01_db.ipynb #babf2013
+def close_stale_open_sessions(    
+    end_time: str,  # Timestamp used to close stale sessions
+) -> list[str]:
+    "Close sessions left open before startup and return their identifiers."
+    end_time = _db_timestamp(end_time)
+    open_sessions_dict_list = db.q("""
+            SELECT 
+                session_id
+            FROM session 
+            WHERE status = 'open'
+            AND julianday(start_time) < julianday(?)
+            """, [end_time])
+    closed_session_list = []
+    if open_sessions_dict_list:
+        for open_sessions_dict in open_sessions_dict_list: 
+            end_session(session_id = open_sessions_dict['session_id'], end_time = end_time, end_reason = 'interrupted')
+            closed_session_list.append(open_sessions_dict['session_id'])
+    return closed_session_list
+
+# %% ../nbs/01_db.ipynb #eacbf030
+def get_session_by_session_id(
+    session_id: str,  # Identifier of the requested session
+) -> dict:
+    "Return a session by ID, using the current time for an open session's end."
+    rows = db.q(
+        """
+        SELECT
+            session_id,
+            start_time,
+            COALESCE(end_time, ?) AS end_time
+        FROM session
+        WHERE session_id = ?
+        ORDER BY julianday(start_time) DESC
+        LIMIT 1
+        """,
+        [
+            datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+            session_id,
+        ],
+    )
+    return rows[0] if rows else {}
+
+# %% ../nbs/01_db.ipynb #1602e56e
+def log_fg_app_events(
+    session_id: str,   # Session receiving the interval
+    app: str,          # Foreground application name
+    pid: int,          # Foreground process identifier
+    window_title: str, # Foreground window title
+    start_time: str,   # ISO-formatted interval start time
+    end_time: str,     # ISO-formatted interval end time
+    hwnd: int,         # Windows window handle
+    is_idle: bool,     # Whether this was an idle interval
+):
+    "Record a completed foreground-window or idle interval."
+    return fore_ground_app_events.insert(
+        session_id=session_id,
+        app=app,
+        pid=pid,
+        window_title=window_title,
+        start_time=start_time,
+        end_time=end_time,
+        hwnd=hwnd,
+        is_idle=is_idle,
+    )
+
+# %% ../nbs/01_db.ipynb #680919a5
+def get_foreground_events(
+    session_id: str,  # Session whose foreground intervals are requested
+) -> list[dict]:
+    "Return a session's foreground intervals in chronological order."
+    rows = db.q(
+        """
+        SELECT *
+        FROM foreground_event
+        WHERE session_id = ?
+        ORDER BY julianday(start_time)
+        """,
+        [session_id],
+    )
+    return rows or []
+
+# %% ../nbs/01_db.ipynb #61154a49
+def delete_old_data(
+    now_ts: str | datetime | None = None,  # Retention reference time; defaults to now
+) -> str:
+    "Delete data belonging to closed sessions older than the retention period."
+    if isinstance(now_ts, str):
+        now_dt = datetime.fromisoformat(now_ts)
+    else:
+        now_dt = now_ts or datetime.now()
+
+    retention_days = getattr(cf, "DATA_RETENTION_DAYS", 365)
+    cutoff_ts = (
+        now_dt - timedelta(days=retention_days)
+    ).isoformat(timespec="seconds")
+
+    db.q(
+        """
+        DELETE FROM process_event
+        WHERE session_id IN (
+            SELECT session_id
+            FROM session
+            WHERE status = 'closed'
+              AND julianday(end_time) < julianday(?)
+        )
+        """,
+        [cutoff_ts],
+    )
+
+    db.q(
+        """
+        DELETE FROM foreground_event
+        WHERE session_id IN (
+            SELECT session_id
+            FROM session
+            WHERE status = 'closed'
+              AND julianday(end_time) < julianday(?)
+        )
+        """,
+        [cutoff_ts],
+    )
+
+    db.q(
+        """
+        DELETE FROM session
+        WHERE status = 'closed'
+          AND julianday(end_time) < julianday(?)
+        """,
+        [cutoff_ts],
+    )
+
+    return cutoff_ts

snooper_pkg/foreground_tracker.py

@@ -0,0 +1,98 @@
+"""Track the active Windows foreground application and persist completed foreground and idle intervals.
+
+Docs: https://sayanbanerjee32.github.io/snooper_pkg/foreground_tracker.html.md"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/03_foreground_tracker.ipynb.
+
+# %% auto #0
+__all__ = ['get_foreground_window_info', 'is_streaming_app', 'start_foreground_app_monitoring']
+
+# %% ../nbs/03_foreground_tracker.ipynb #0f83e8bf
+import logging
+logger = logging.getLogger(__name__)
+
+
+# %% ../nbs/03_foreground_tracker.ipynb #3fc06c45
+import psutil
+from datetime import datetime
+from time import sleep
+
+# %% ../nbs/03_foreground_tracker.ipynb #4cbec422
+import snooper_pkg.config as cf
+from snooper_pkg.db import *
+from snooper_pkg.idle_detector import *
+
+# %% ../nbs/03_foreground_tracker.ipynb #4939c6b1
+import sys
+def _require_windows():
+    if sys.platform != "win32":
+        raise RuntimeError("Windows idle detection is only available on Windows")
+
+
+# %% ../nbs/03_foreground_tracker.ipynb #9672487f
+def get_foreground_window_info() -> tuple[str, int, int, str]:
+    "Return the foreground window title, handle, process ID, and process name."
+    _require_windows()
+    import win32gui, win32process
+    hwnd = win32gui.GetForegroundWindow()
+    title = win32gui.GetWindowText(hwnd) or "Unknown"
+    tid, pid = win32process.GetWindowThreadProcessId(hwnd)
+    if not isinstance(pid, int) or pid <= 0: return title, hwnd, -1, "UNKNOWN"
+    try: process_name = psutil.Process(pid).name()
+    except (psutil.NoSuchProcess, psutil.AccessDenied, ValueError, psutil.Error): return title, hwnd, -1, "UNKNOWN"
+    return title, hwnd, pid, process_name
+
+# %% ../nbs/03_foreground_tracker.ipynb #9f7f5ced
+def is_streaming_app(
+    title: str,  # Foreground window title to inspect
+    streaming_app_min_idle_time: dict[str, int | float],  # Title substrings mapped to idle thresholds in seconds
+) -> int | float | None:
+    "Return the idle threshold for the first configured title match, or `None`."
+    for s in streaming_app_min_idle_time.keys():
+        if s.lower() in title.lower():
+            return streaming_app_min_idle_time[s]
+    return None
+
+# %% ../nbs/03_foreground_tracker.ipynb #f101b187
+def start_foreground_app_monitoring(
+    session_id: str,  # Monitoring session receiving foreground intervals
+    stop_event: object,  # Stop signal providing an `is_set()` method
+    time_interval: int | float = cf.FG_APP_MONITORING_INTERVAL_SECONDS,  # Seconds between foreground samples
+    min_idle_time_gap: int | float = cf.FG_APP_MONITORING_MIN_IDLE_SECONDS,  # General idle threshold in seconds
+    streaming_app_min_idle_time: dict[str, int | float] = cf.STREAMING_APP_MIN_IDLE_SECONDS,  # Title-specific idle thresholds
+) -> None:
+    "Sample foreground state until stopped and record each completed interval."
+    fg_dict = {}
+    try:
+        while not stop_event.is_set():
+            title, hwnd, pid, process_name = get_foreground_window_info()
+            if is_streaming_app(title, streaming_app_min_idle_time) is not None: 
+                min_idle_time = is_streaming_app(title, streaming_app_min_idle_time)
+                is_idle = get_idle_seconds() > min_idle_time
+            else: is_idle = get_idle_seconds() > min_idle_time_gap
+            if is_idle:
+                title, hwnd, pid, process_name = "Idle", -1, -1, "IDLE"
+            if fg_dict.get("pid") != pid or fg_dict.get("hwnd") != hwnd or fg_dict.get("window_title") != title:
+                if fg_dict:
+                    fg_dict["end_time"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+                    log_fg_app_events(**fg_dict)
+                fg_dict = {
+                    "session_id":session_id,
+                    "window_title": title,
+                    "pid": pid,
+                    "hwnd": hwnd,
+                    "app": process_name,
+                    "start_time": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+                    "is_idle":is_idle,
+                    "end_time": None
+                }
+            else:
+                fg_dict["end_time"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+            sleep(time_interval)
+    except KeyboardInterrupt:
+        logger.exception("Stopped by user.")
+    finally:
+        if fg_dict: 
+            fg_dict["end_time"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+            log_fg_app_events(**fg_dict)
+

snooper_pkg/idle_detector.py

@@ -0,0 +1,54 @@
+"""Windows idle-time measurement based on system tick counts for the most recent user input.
+
+Docs: https://sayanbanerjee32.github.io/snooper_pkg/idle_detector.html.md"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/02_idle_detector.ipynb.
+
+# %% auto #0
+__all__ = ['LASTINPUTINFO', 'get_last_input_tick', 'get_idle_seconds']
+
+# %% ../nbs/02_idle_detector.ipynb #4cab5d99
+import logging
+logger = logging.getLogger(__name__)
+
+
+# %% ../nbs/02_idle_detector.ipynb #c6affeda
+import ctypes
+from ctypes import wintypes
+
+# %% ../nbs/02_idle_detector.ipynb #56597405
+import sys
+def _require_windows():
+    if sys.platform != "win32":
+        raise RuntimeError("Windows idle detection is only available on Windows")
+
+# %% ../nbs/02_idle_detector.ipynb #e6a637cf
+class LASTINPUTINFO(ctypes.Structure):
+    "ctypes representation of the Windows `LASTINPUTINFO` structure."
+
+    _fields_ = [
+        ("cbSize", wintypes.UINT),   # Size of this structure in bytes
+        ("dwTime", wintypes.DWORD),  # Tick count when the last input occurred
+    ]
+
+
+# %% ../nbs/02_idle_detector.ipynb #3f90a87c
+def get_last_input_tick():
+    "Call `GetLastInputInfo` and return its last-input tick count in milliseconds."
+    _require_windows()
+
+    info = LASTINPUTINFO()
+    info.cbSize = ctypes.sizeof(info)
+    
+    ok = ctypes.windll.user32.GetLastInputInfo(ctypes.byref(info))
+    if not ok:
+        raise ctypes.WinError()
+    return info.dwTime
+
+# %% ../nbs/02_idle_detector.ipynb #2083d992
+def get_idle_seconds():
+    "Return the elapsed seconds between system uptime and the last input tick."
+    _require_windows()
+    current_tick = ctypes.windll.kernel32.GetTickCount64()
+    last_input_tick = get_last_input_tick()
+    return (current_tick - last_input_tick)/1000