Part of: Linktech Engineering Tools Suite
Library: PythonTools
Author: Leon McClatchey, Linktech Engineering LLC
License: MIT
Requires: Python 3.10+
Last Updated: 2026‑08‑20
PythonTools is a deterministic, cross‑project utility library providing stable primitives for execution, logging, path resolution, schema loading, and exception modeling. It is the foundational support library used across the Linktech Engineering Tools Suite, including RunUpdates, VSCode‑Updater, NMS_Tools, TimerDeck, BotScanner and other operator‑grade automation projects.
PythonTools is designed so that adding new functionality cannot negatively affect other projects importing it. Modules are isolated, deterministic, and safe for reuse across multiple applications.
- Overview
- Design Guarantees
- Modules
- Weather Provider Architecture
- Project Ecosystem
- Module Relationships Diagram
- Used By
- Related Project: RunUpdates
- Related Project: NMS_Tools
- Project Status
- Roadmap
- Stability Model
- Philosophy
- License
PythonTools provides stable, reusable modules intended for use across multiple operator‑grade projects. These modules implement deterministic patterns for:
- subprocess execution
- path and environment resolution
- structured JSON logging
- exception modeling
- schema loading and validation
- normalization and inheritance helpers
- frozen‑bundle compatibility
PythonTools is not a “common utilities dumping ground.” It is a stable foundation layer* for the entire Linktech Engineering ecosystem.
PythonTools follows strict design rules:
- Deterministic behavior — no nondeterministic helpers or hidden state
- No global state mutation — modules never modify shared global variables
- No cross‑project contamination — importing PythonTools cannot break other projects
- Stable import surface — modules expand, but existing behavior remains stable
- Predictable subprocess wrappers — normalized exit codes, stdout/stderr, and error modeling
- Consistent exception types — unified error model across all projects
- Safe logging with redaction — secrets never logged
- Frozen‑bundle compatibility — works inside PyInstaller, zipapp, and frozen distributions
These guarantees allow PythonTools to serve as a reliable backbone for multiple automation systems.
PythonTools is organized into domain‑specific modules. Each module is isolated, deterministic, and safe for cross‑project import.
| Module | Purpose |
|---|---|
| ansible | Automation helpers for remote orchestration and playbook execution. |
| cache | Deterministic caching helpers for provider and subsystem data. |
| certs | Certificate and trust store helpers for secure connections. |
| color | Color and style helpers for terminal or structured output. |
| core | Foundational primitives — constants, base classes, shared logic. |
| datetime | Date/time helpers, normalization, and deterministic time handling. |
| finance | Financial/transactional normalization and reporting. |
| http | HTTP client helpers and request/response normalization. |
| location | Location and coordinate helpers (lat/lon, geospatial context). |
| log_helpers | Structured logging, redaction, formatting utilities. |
| market | Market analytics, pricing, and trading integrations. |
| nagios | Monitoring and alerting integration for Nagios systems. |
| net | Networking helpers — sockets, SSH, HTTP, connection utilities. |
| parser | Text/stdout parsing utilities used by RunUpdates and others. |
| parsing | Shared parsing primitives and normalization helpers. |
| sessions | SSH/API/local subprocess session management. |
| system | System‑level helpers (environment, platform, process context). |
| units | Unit conversion and normalization helpers. |
| utils | Transitional helpers; gradually migrated into domain modules. |
| weather | Weather provider architecture and normalized ingestion engine. |
Each module follows the same design guarantees:
- deterministic behavior
- no global state mutation
- safe cross‑project import
- consistent exception and logging models
PythonTools includes a deterministic, provider‑agnostic weather ingestion subsystem used by NMS_Tools and other Linktech Engineering projects. The subsystem provides unified access to multiple upstream weather providers through a stable, normalized schema.
Weather providers register themselves through the WEATHER_PROVIDERS dictionary.
WEATHER_PROVIDERS["nws"].update({
"supports": ("current", "hourly", "weekly", "full"),
"fetch_current": fetch_current_nws,
"fetch_hourly": fetch_hourly_nws,
"fetch_weekly": fetch_weekly_nws,
"fetch_full": fetch_full_nws,
})Each provider implements:
fetch_current(lat, lon, timeout, meta)
fetch_hourly(lat, lon, timeout, meta)
fetch_weekly(lat, lon, timeout, meta)
fetch_full(lat, lon, timeout, meta)PythonTools normalizes all provider output into a deterministic schema:
{
"current": {...},
"hourly": {...},
"weekly": {...},
"alerts": {...}
}Mode definitions:
- current — single observation block
- hourly — 24–48 hour forecast
- weekly — 7–10 day forecast
- full — composite mode: current + hourly + weekly
Alerts are appended by the caller (e.g., NMS_Tools check_weather).
The meta object carries deterministic provider metadata:
cached_obs— NWS observation used for feels‑like, dewpoint, pressurecached_station_id— NWS station identifier- provider URLs (when available)
- provider‑specific metadata
NWS observations are fetched automatically for:
- NWS: hourly, weekly, full
- Open‑Meteo: weekly, full
This ensures consistent feels‑like and dewpoint values across providers.
All providers normalize environmental indices:
index: {
heat_index,
wind_chill,
humidex,
wet_bulb,
vapor_pressure,
saturation_vapor_pressure,
mixing_ratio,
specific_humidity,
air_density,
pressure_altitude
}PythonTools guarantees deterministic calculations and fallback logic.
Providers return different condition codes.
PythonTools normalizes them into a unified set:
condition— numeric codecontext— human‑readable descriptionicon— deterministic icon name
PythonTools guarantees:
- identical schema across providers
- identical schema across modes
- identical schema across locations
- identical schema across frozen and non‑frozen builds
PythonTools is the shared foundation for the Linktech Engineering Tools Suite:
- RunUpdates — update orchestration and system maintenance
- NMS_Tools — network management, market data, weather ingestion, and system checks
- TimerDeck — systemd automation and scheduling
- VSCode-Updater — editor update automation
- BotScanner — security analysis and behavioral scanning
This ecosystem relies on PythonTools for deterministic execution, logging, schema validation, and cross‑project stability.
``` ┌──────────────────────────┐ │ DATA CORE │ │ core, units, system, │ │ datetime, location, cache│ └───────────┬──────────────┘ │ ▼ ┌──────────────────────────┐ │ PARSING CORE │ │ parser, parsing, │ │ log_helpers │ └───────────┬──────────────┘ │ ▼ ┌──────────────────────────┐ │ NETWORK CORE │ │ net, http, sessions │ └───────────┬──────────────┘ │ ▼ ┌──────────────────────────┐ │ DOMAIN LAYERS │ └──────────────────────────┘
market ↔ finance
weather → nagios parsing → nagios location → nagios net → nagios http → nagios
ansible → RunUpdates RunUpdates → parsing, net, sessions, system, core
parser → market, finance, nagios, RunUpdates ```
PythonTools is used across:
- RunUpdates
- NMS_Tools
- TimerDeck
- BotScanner
- Additional internal tools
PythonTools provides foundational components used by
RunUpdates
RunUpdates relies on PythonTools for:
- deterministic subprocess execution
- session and connection management
- stdout parsing and normalization
- system/environment resolution
- logging and redaction
- frozen‑bundle compatibility
PythonTools provides foundational components used by
NMS_Tools
NMS_Tools relies on PythonTools for:
- deterministic subprocess execution
- unified logging and redaction
- schema loading and validation
- market/finance provider architecture
- ticker normalization and trend analysis
- weather and network data ingestion
- stdout parsing and normalization
- frozen‑bundle compatibility for distribution
PythonTools is in active development. Modules are being stabilized as they are exported from existing projects.
- Document subprocess wrappers
- Document path/env resolution
- Document logging model
- Document exception model
- Add semantic versioning
- Add automated tests
- Prepare for PyPI packaging
- Add module reference pages
PythonTools follows a stability model:
- Existing APIs remain stable
- New modules may be added
- Breaking changes require a version bump
- Behavior is deterministic across all supported environments
PythonTools exists to keep application‑level projects clean, deterministic, and focused. It provides stable primitives so projects never need to reinvent execution, logging, or path resolution.
MIT License