equser 0.0.1__tar.gz

equser-0.0.1/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# AI assistant instructions (developer-local)
+CLAUDE.md
+CLAUDE.local.md

equser-0.0.1/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-02-06
+
+Initial public release. User toolkit for EQ Wave power quality data.
+
+### Modules
+- **equser.data** - Load CPOW and PMon Parquet files with automatic scaling, timestamp parsing
+- **equser.analysis** - Waveform analysis: zero-crossing detection, AC cycle extraction
+- **equser.api** - REST and WebSocket clients for EQ Synapse gateways (requires `[analysis]`)
+- **equser.plotting** - Static matplotlib plots for PMon and CPOW data (requires `[analysis]`)
+- **equser.pmon** - Live sensor acquisition and Avro-to-Parquet conversion (requires `[daq]`)
+- **equser.core** - YAML configuration loading, XDG-compliant path resolution
+- **equser.utils** - Logging with optional color, DateTime with floor-division
+- **equser.notebooks** - Bundled reference notebooks with list/copy API
+- **equser.widgets** - Interactive file selector for JupyterLab (requires `[jupyter]`)
+- **equser.snapshot** - Waveform capture via gateway WebSocket
+
+### Dependency Tiers
+- **Base**: numpy, pyarrow, pyyaml, argcomplete, colorlog (data loading, analysis, CLI)
+- **[daq]**: avro, fastavro (live sensor acquisition)
+- **[analysis]**: matplotlib, requests, websocket-client (plotting + API)
+- **[jupyter]**: `[analysis]` + jupyterlab, duckdb, ipywidgets, ipykernel, nbconvert
+- **[full]**: all of the above
+
+### CLI
+- `equser pmon acquire` - Start power monitoring from EQ Wave sensor
+- `equser pmon convert` - Convert Avro files to Parquet
+- `equser plot` - Plot PMon or CPOW data files
+- `equser notebooks list` - List bundled reference notebooks
+- `equser notebooks copy` - Copy reference notebooks to a directory
+- `equser snapshot` - Capture live waveform data to a Parquet file
+
+[Unreleased]: https://github.com/Energy-Quotient/equser/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Energy-Quotient/equser/releases/tag/v0.1.0

equser-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EQ Systems Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

equser-0.0.1/PKG-INFO

@@ -0,0 +1,247 @@
+Metadata-Version: 2.4
+Name: equser
+Version: 0.0.1
+Summary: User toolkit for power quality data from EQ Wave sensors
+Project-URL: Homepage, https://eq.systems
+Project-URL: Documentation, https://equser.eq.systems
+Project-URL: Repository, https://github.com/Energy-Quotient/equser
+Project-URL: Changelog, https://github.com/Energy-Quotient/equser/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Energy-Quotient/equser/issues
+Author-email: Energy Quotient <info@eq.systems>
+Maintainer-email: Kevin Davies <kdavies@eq.systems>
+License: MIT
+License-File: LICENSE
+Keywords: continuous-waveform,cpow,data-acquisition,electrical,energy,eq-wave,monitoring,parquet,power-quality,pq,waveform
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: argcomplete>=3.5
+Requires-Dist: colorlog>=6.9
+Requires-Dist: numpy>=1.24
+Requires-Dist: pyarrow!=21.0.0,>=18.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: analysis
+Requires-Dist: matplotlib>=3.5; extra == 'analysis'
+Requires-Dist: requests>=2.28; extra == 'analysis'
+Requires-Dist: websocket-client>=1.6; extra == 'analysis'
+Provides-Extra: daq
+Requires-Dist: avro>=1.12; extra == 'daq'
+Requires-Dist: fastavro>=1.9; extra == 'daq'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: full
+Requires-Dist: avro>=1.12; extra == 'full'
+Requires-Dist: duckdb>=1.0; extra == 'full'
+Requires-Dist: fastavro>=1.9; extra == 'full'
+Requires-Dist: ipykernel>=6.29; extra == 'full'
+Requires-Dist: ipywidgets>=8.1; extra == 'full'
+Requires-Dist: jupyterlab>=4.4; extra == 'full'
+Requires-Dist: matplotlib>=3.5; extra == 'full'
+Requires-Dist: nbconvert>=7.16; extra == 'full'
+Requires-Dist: requests>=2.28; extra == 'full'
+Requires-Dist: websocket-client>=1.6; extra == 'full'
+Provides-Extra: jupyter
+Requires-Dist: duckdb>=1.0; extra == 'jupyter'
+Requires-Dist: ipykernel>=6.29; extra == 'jupyter'
+Requires-Dist: ipywidgets>=8.1; extra == 'jupyter'
+Requires-Dist: jupyterlab>=4.4; extra == 'jupyter'
+Requires-Dist: matplotlib>=3.5; extra == 'jupyter'
+Requires-Dist: nbconvert>=7.16; extra == 'jupyter'
+Requires-Dist: requests>=2.28; extra == 'jupyter'
+Requires-Dist: websocket-client>=1.6; extra == 'jupyter'
+Description-Content-Type: text/markdown
+
+# equser
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+User toolkit for power quality data from EQ Wave sensors.
+
+## Overview
+
+equser is a Python library for loading, analyzing, and visualizing continuous
+waveform (CPOW) and power monitoring (PMon) data from EQ Wave hardware. It
+provides:
+
+- **Data loading** (`data`): Load CPOW and PMon Parquet files with automatic scaling
+- **Waveform analysis** (`analysis`): Zero-crossing detection, cycle extraction
+- **Visualization** (`plotting`): Static plots for power quality data (requires `[analysis]`)
+- **API client** (`api`): REST and WebSocket clients for EQ Synapse gateways (requires `[analysis]`)
+- **Live acquisition** (`pmon`): Real-time sensor data acquisition (requires `[daq]`)
+- **CLI tools**: Command-line interface for monitoring and conversion
+
+## Installation
+
+### Base installation (data loading + analysis)
+
+```bash
+pip install equser
+```
+
+### With plotting and API support
+
+```bash
+pip install equser[analysis]
+```
+
+### With JupyterLab notebook environment
+
+```bash
+pip install equser[jupyter]
+```
+
+### With live sensor acquisition
+
+```bash
+pip install equser[daq]
+```
+
+### Full installation (all features)
+
+```bash
+pip install equser[full]
+```
+
+## Quick Start
+
+### Load and explore CPOW data
+
+```python
+from equser.data import load_cpow_scaled
+
+result = load_cpow_scaled('20250623_075056.parquet')
+print(f"Voltage A peak: {result['VA'].max():.1f} V")
+print(f"Start time: {result['start_time']}")
+print(f"Sample rate: {result['sample_rate']} Hz")
+```
+
+### Load PMon summary data
+
+```python
+from equser.data import load_pmon
+
+table = load_pmon('20250623_0750.parquet')
+print(table.column_names)
+```
+
+### Analyze waveform zero crossings
+
+```python
+import numpy as np
+from equser.data import load_cpow_scaled, SAMPLE_RATE_HZ
+from equser.analysis import find_zero_crossings
+
+result = load_cpow_scaled('cpow_data.parquet')
+time = np.arange(len(result['VA'])) / SAMPLE_RATE_HZ
+crossings, indices = find_zero_crossings(result['VA'], time)
+print(f"Found {len(crossings)} zero crossings")
+```
+
+### Plot data (requires `[analysis]`)
+
+```python
+from equser.plotting import PowerMonitorPlotter, WaveformPlotter
+
+# Plot power monitor data
+plotter = PowerMonitorPlotter()
+plotter.plot_file('pmon_data.parquet')
+
+# Plot waveform data
+wf_plotter = WaveformPlotter()
+wf_plotter.plot_file('cpow_data.parquet')
+```
+
+### Query a gateway (requires `[analysis]`)
+
+```python
+from equser.api import SynapseClient
+
+client = SynapseClient('http://gateway:8080')
+devices = client.list_devices()
+table = client.get_pmon_data(devices[0]['id'])
+```
+
+### Command Line
+
+```bash
+# Start power monitoring (requires EQ Wave sensor + [daq])
+equser pmon acquire -c config.yaml
+
+# Convert Avro files to Parquet (requires [daq])
+equser pmon convert data/*.avro --remove
+
+# Plot data file (requires [analysis])
+equser plot data.parquet
+```
+
+## Configuration
+
+equser looks for configuration in the following locations (in order):
+
+1. `EQUSER_CONFIG` environment variable
+2. `./equser.yaml` (current directory)
+3. `~/.config/equser/config.yaml` (XDG config)
+4. `/etc/equser/config.yaml` (system-wide)
+
+Example configuration:
+
+```yaml
+sensor:
+  address: "192.168.10.10"
+  port: 1535
+
+pmon:
+  connection:
+    retry_delay: 3
+  parquet:
+    interval: 86400
+    compression:
+      method: ZSTD
+      level: 4
+```
+
+## Dependency Tiers
+
+| Extra | Description | Key Packages |
+|-------|-------------|--------------|
+| *(base)* | Data loading, analysis, CLI | numpy, pyarrow, pyyaml, argcomplete, colorlog |
+| `[daq]` | Live sensor acquisition | avro, fastavro |
+| `[analysis]` | Plotting + API client | matplotlib, requests, websocket-client |
+| `[jupyter]` | Full notebook environment | `[analysis]` + jupyterlab, duckdb, ipywidgets |
+| `[dev]` | Development tools | pytest, ruff, mypy |
+| `[full]` | All of the above (except dev) | - |
+
+## Requirements
+
+- Python 3.10 or later
+- Linux (for hardware integration features)
+
+## Documentation
+
+- [API Documentation](https://equser.eq.systems)
+- [Changelog](CHANGELOG.md)
+
+## License
+
+MIT License - Copyright (c) 2026 EQ Systems Inc.
+
+## About
+
+equser is developed by [Energy Quotient](https://eq.systems) as part of the
+EQ Synapse platform for continuous waveform intelligence in power systems.

equser-0.0.1/README.md

@@ -0,0 +1,179 @@
+# equser
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+User toolkit for power quality data from EQ Wave sensors.
+
+## Overview
+
+equser is a Python library for loading, analyzing, and visualizing continuous
+waveform (CPOW) and power monitoring (PMon) data from EQ Wave hardware. It
+provides:
+
+- **Data loading** (`data`): Load CPOW and PMon Parquet files with automatic scaling
+- **Waveform analysis** (`analysis`): Zero-crossing detection, cycle extraction
+- **Visualization** (`plotting`): Static plots for power quality data (requires `[analysis]`)
+- **API client** (`api`): REST and WebSocket clients for EQ Synapse gateways (requires `[analysis]`)
+- **Live acquisition** (`pmon`): Real-time sensor data acquisition (requires `[daq]`)
+- **CLI tools**: Command-line interface for monitoring and conversion
+
+## Installation
+
+### Base installation (data loading + analysis)
+
+```bash
+pip install equser
+```
+
+### With plotting and API support
+
+```bash
+pip install equser[analysis]
+```
+
+### With JupyterLab notebook environment
+
+```bash
+pip install equser[jupyter]
+```
+
+### With live sensor acquisition
+
+```bash
+pip install equser[daq]
+```
+
+### Full installation (all features)
+
+```bash
+pip install equser[full]
+```
+
+## Quick Start
+
+### Load and explore CPOW data
+
+```python
+from equser.data import load_cpow_scaled
+
+result = load_cpow_scaled('20250623_075056.parquet')
+print(f"Voltage A peak: {result['VA'].max():.1f} V")
+print(f"Start time: {result['start_time']}")
+print(f"Sample rate: {result['sample_rate']} Hz")
+```
+
+### Load PMon summary data
+
+```python
+from equser.data import load_pmon
+
+table = load_pmon('20250623_0750.parquet')
+print(table.column_names)
+```
+
+### Analyze waveform zero crossings
+
+```python
+import numpy as np
+from equser.data import load_cpow_scaled, SAMPLE_RATE_HZ
+from equser.analysis import find_zero_crossings
+
+result = load_cpow_scaled('cpow_data.parquet')
+time = np.arange(len(result['VA'])) / SAMPLE_RATE_HZ
+crossings, indices = find_zero_crossings(result['VA'], time)
+print(f"Found {len(crossings)} zero crossings")
+```
+
+### Plot data (requires `[analysis]`)
+
+```python
+from equser.plotting import PowerMonitorPlotter, WaveformPlotter
+
+# Plot power monitor data
+plotter = PowerMonitorPlotter()
+plotter.plot_file('pmon_data.parquet')
+
+# Plot waveform data
+wf_plotter = WaveformPlotter()
+wf_plotter.plot_file('cpow_data.parquet')
+```
+
+### Query a gateway (requires `[analysis]`)
+
+```python
+from equser.api import SynapseClient
+
+client = SynapseClient('http://gateway:8080')
+devices = client.list_devices()
+table = client.get_pmon_data(devices[0]['id'])
+```
+
+### Command Line
+
+```bash
+# Start power monitoring (requires EQ Wave sensor + [daq])
+equser pmon acquire -c config.yaml
+
+# Convert Avro files to Parquet (requires [daq])
+equser pmon convert data/*.avro --remove
+
+# Plot data file (requires [analysis])
+equser plot data.parquet
+```
+
+## Configuration
+
+equser looks for configuration in the following locations (in order):
+
+1. `EQUSER_CONFIG` environment variable
+2. `./equser.yaml` (current directory)
+3. `~/.config/equser/config.yaml` (XDG config)
+4. `/etc/equser/config.yaml` (system-wide)
+
+Example configuration:
+
+```yaml
+sensor:
+  address: "192.168.10.10"
+  port: 1535
+
+pmon:
+  connection:
+    retry_delay: 3
+  parquet:
+    interval: 86400
+    compression:
+      method: ZSTD
+      level: 4
+```
+
+## Dependency Tiers
+
+| Extra | Description | Key Packages |
+|-------|-------------|--------------|
+| *(base)* | Data loading, analysis, CLI | numpy, pyarrow, pyyaml, argcomplete, colorlog |
+| `[daq]` | Live sensor acquisition | avro, fastavro |
+| `[analysis]` | Plotting + API client | matplotlib, requests, websocket-client |
+| `[jupyter]` | Full notebook environment | `[analysis]` + jupyterlab, duckdb, ipywidgets |
+| `[dev]` | Development tools | pytest, ruff, mypy |
+| `[full]` | All of the above (except dev) | - |
+
+## Requirements
+
+- Python 3.10 or later
+- Linux (for hardware integration features)
+
+## Documentation
+
+- [API Documentation](https://equser.eq.systems)
+- [Changelog](CHANGELOG.md)
+
+## License
+
+MIT License - Copyright (c) 2026 EQ Systems Inc.
+
+## About
+
+equser is developed by [Energy Quotient](https://eq.systems) as part of the
+EQ Synapse platform for continuous waveform intelligence in power systems.

equser-0.0.1/equser/__init__.py

@@ -0,0 +1,60 @@
+"""EQ User Tools - Power Quality Data Toolkit for EQ Wave Sensors
+
+A Python library for loading, analyzing, and visualizing power quality data
+from EQ Wave continuous waveform sensors.
+
+Modules (always available):
+    data: Load CPOW and PMon Parquet files, parse timestamps
+    analysis: Waveform analysis (zero crossings, cycle extraction)
+    pmon: Power monitoring errors, schema, field descriptions
+    core: Configuration and path utilities
+    utils: Logging and datetime utilities
+
+Modules (always available, continued):
+    notebooks: Bundled reference notebooks (list, copy, path helpers)
+
+Modules (require extras):
+    plotting: Visualization tools (requires ``[analysis]`` extra)
+    api: Gateway REST and WebSocket clients (requires ``[analysis]`` extra)
+    widgets: Interactive Jupyter widgets (requires ``[jupyter]`` extra)
+
+Quick start::
+
+    from equser.data import load_cpow_scaled, load_pmon
+    result = load_cpow_scaled('cpow_data.parquet')
+
+    from equser.analysis import find_zero_crossings
+    crossings, indices = find_zero_crossings(result['VA'], time_array)
+"""
+
+from equser._version import __version__, __version_info__
+
+# Core modules always available
+from equser import core
+from equser import utils
+from equser import pmon
+from equser import data
+from equser import analysis
+from equser import notebooks
+
+# Plotting requires [analysis] extra (matplotlib)
+try:
+    from equser import plotting
+    _has_plotting = True
+except ImportError:
+    _has_plotting = False
+
+# API client requires [analysis] extra (requests, websocket-client)
+try:
+    from equser import api
+    _has_api = True
+except ImportError:
+    _has_api = False
+
+__all__ = ['core', 'utils', 'pmon', 'data', 'analysis', 'notebooks',
+           '__version__', '__version_info__']
+
+if _has_plotting:
+    __all__.append('plotting')
+if _has_api:
+    __all__.append('api')

equser-0.0.1/equser/_version.py

@@ -0,0 +1,8 @@
+"""Single-source version for equser package.
+
+Update this file when releasing a new version.
+Follow semantic versioning: https://semver.org/
+"""
+
+__version__ = "0.0.1"
+__version_info__ = tuple(int(x) for x in __version__.split("."))

equser-0.0.1/equser/analysis/__init__.py

@@ -0,0 +1,25 @@
+"""Waveform analysis functions for CPOW data.
+
+Uses only base dependencies (numpy). Plotting helpers that require matplotlib
+are guarded and will raise ImportError with a helpful message if matplotlib
+is not installed.
+
+Usage::
+
+    from equser.analysis import find_zero_crossings, extract_complete_cycles
+
+    crossings, indices = find_zero_crossings(voltage_array, time_array)
+"""
+
+from equser.analysis.waveform import (
+    extract_complete_cycles,
+    find_zero_crossings,
+)
+
+__all__ = [
+    'extract_complete_cycles',
+    'find_zero_crossings',
+]
+
+# plot_extracted_cycles is intentionally not in __all__; import it directly
+# if needed: from equser.analysis.waveform import plot_extracted_cycles