# Monitoring controller
## Scheduling helpers
------------------------------------------------------------------------
source
### seconds_until_midnight
``` python
def seconds_until_midnight(
now:NoneType=None
):
```
*Return the number of seconds from `now` until the next midnight.*
## Controller state
------------------------------------------------------------------------
source
### MonitorController
``` python
def MonitorController(
debug:bool=True
):
```
*Own monitoring session state, worker threads, timers, and UI
callbacks.*
## Session lifecycle
------------------------------------------------------------------------
source
### MonitorController.start_monitoring
``` python
def start_monitoring():
```
*Start a new session and its process and foreground monitoring threads.*
------------------------------------------------------------------------
source
### MonitorController.stop_monitoring
``` python
def stop_monitoring(
stop_reason:str='None'
):
```
*Stop active workers, close the session, and record its stop reason.*
------------------------------------------------------------------------
source
### MonitorController.is_running
``` python
def is_running():
```
*Return whether a monitoring session is currently running.*
## Startup housekeeping
------------------------------------------------------------------------
source
### MonitorController.run_startup_housekeeping
``` python
def run_startup_housekeeping():
```
*Close stale sessions and delete data older than the retention cutoff.*
## Report data
------------------------------------------------------------------------
source
### MonitorController.generate_current_session_stats
``` python
def generate_current_session_stats():
```
*Build report data for the active session, or return `{}` when none
exists.*
------------------------------------------------------------------------
source
### MonitorController.generate_last_report_data
``` python
def generate_last_report_data():
```
*Build report data for the latest completed session, or return `{}`.*
## Pause and resume
------------------------------------------------------------------------
source
### MonitorController.is_paused
``` python
def is_paused():
```
*Return whether the configured pause end time is still in the future.*
------------------------------------------------------------------------
source
### MonitorController.pause_for
``` python
def pause_for(
minutes:NoneType=None
):
```
*Stop active monitoring, schedule automatic resume, and return the pause
end time.*
------------------------------------------------------------------------
source
### MonitorController.resume_now
``` python
def resume_now():
```
*Cancel any pending resume timer and resume monitoring immediately.*
- `stop_monitoring()` uses the literal string `"None"` as its default
`stop_reason`. Confirm whether this should remain `"None"`, become
Python `None`, or use a defined reason such as `"unknown"`.
- Constructing
[`MonitorController`](https://sayanbanerjee32.github.io/snooper_pkg/monitoring_controller.html#monitorcontroller)
immediately runs database housekeeping. Confirm that this constructor
side effect is intentional.
- `resume_now()` calls `_auto_resume()` even when no pause is active. If
the controller was manually stopped, this starts a new monitoring
session and emits resume callbacks. Confirm that this is the intended
distinction between “resume” and “start”.
- The callback contracts are implicit: `on_notify` is called with one
string, while `on_state_change` is called without arguments. They may
also be invoked from timer threads. Confirm that the tray layer safely
transfers any Tkinter work to the Tk main thread.
- `start_monitoring()` does not reset `session_stop`, so while a later
session is running that attribute may still contain the previous
session’s stop time. Confirm whether consumers rely on it being `None`
during an active session.