pcpulse 0.1.0__py3-none-any.whl

pcpulse/__init__.py

@@ -0,0 +1,6 @@
+"""PCPulse public API."""
+from .collectors import collect_snapshot
+from .health import run_checks
+from .models import HealthCheck, Snapshot
+__all__ = ["HealthCheck", "Snapshot", "collect_snapshot", "run_checks"]
+__version__ = "0.1.0"

pcpulse/cli.py

@@ -0,0 +1,67 @@
+import argparse
+import json
+
+from . import __version__, collect_snapshot, run_checks
+from .serialization import to_json, to_markdown
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pcpulse",
+        description="Privacy-first cross-platform PC diagnostics.",
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    snapshot = sub.add_parser("snapshot", help="Collect a local system snapshot.")
+    snapshot.add_argument("--json", action="store_true")
+    snapshot.add_argument("--markdown", action="store_true")
+    snapshot.add_argument("--include-identity", action="store_true")
+
+    doctor = sub.add_parser("doctor", help="Run conservative local health checks.")
+    doctor.add_argument("--json", action="store_true")
+
+    sub.add_parser("schema", help="Show the current snapshot schema version.")
+    return parser
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+
+    if args.command == "schema":
+        print("1.0")
+        return 0
+
+    if args.command == "snapshot":
+        snapshot = collect_snapshot(include_identity=args.include_identity)
+        if args.json:
+            print(to_json(snapshot))
+        elif args.markdown:
+            print(to_markdown(snapshot), end="")
+        else:
+            print(f"OS: {snapshot.os}")
+            print(f"Kernel: {snapshot.kernel}")
+            print(f"Architecture: {snapshot.architecture}")
+            print(
+                f"CPU: {snapshot.cpu.logical_cores} logical / "
+                f"{snapshot.cpu.physical_cores} physical"
+            )
+            print(f"CPU load: {snapshot.cpu.load_percent}%")
+            print(f"Memory: {snapshot.memory.used_percent}% used")
+        return 0
+
+    if args.command == "doctor":
+        checks = run_checks(collect_snapshot())
+        if args.json:
+            print(json.dumps([check.__dict__ for check in checks], indent=2))
+        else:
+            for check in checks:
+                print(f"[{check.status.upper()}] {check.message}")
+        return 0 if not any(check.status == "error" for check in checks) else 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pcpulse/collectors.py

@@ -0,0 +1,25 @@
+from datetime import datetime, timezone
+import getpass, platform, time
+import psutil
+from .models import CpuInfo, DiskInfo, MemoryInfo, Snapshot
+SCHEMA_VERSION = "1.0"
+def collect_snapshot(*, include_identity: bool = False) -> Snapshot:
+    vm = psutil.virtual_memory()
+    disks, seen = [], set()
+    for part in psutil.disk_partitions(all=False):
+        if part.mountpoint in seen: continue
+        seen.add(part.mountpoint)
+        try:
+            u = psutil.disk_usage(part.mountpoint)
+            disks.append(DiskInfo(part.mountpoint, u.total, u.free, u.percent))
+        except (OSError, PermissionError):
+            disks.append(DiskInfo(part.mountpoint, None, None, None))
+    return Snapshot(
+        collected_at=datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        schema_version=SCHEMA_VERSION, os=platform.system(), kernel=platform.release(),
+        architecture=platform.machine(),
+        cpu=CpuInfo(psutil.cpu_count(), psutil.cpu_count(logical=False), psutil.cpu_percent(interval=0.05)),
+        memory=MemoryInfo(vm.total, vm.available, vm.used, vm.percent), disks=disks,
+        uptime_seconds=max(0.0, time.time() - psutil.boot_time()),
+        hostname=platform.node() if include_identity else None,
+        username=getpass.getuser() if include_identity else None)

pcpulse/health.py

@@ -0,0 +1,16 @@
+from .models import HealthCheck, Snapshot
+def run_checks(snapshot: Snapshot) -> list[HealthCheck]:
+    checks = []
+    mem = snapshot.memory.used_percent
+    if mem is None: checks.append(HealthCheck("memory.available","unknown","Memory usage is unavailable."))
+    elif mem >= 95: checks.append(HealthCheck("memory.usage","error","Memory usage is critically high.",{"used_percent":mem}))
+    elif mem >= 85: checks.append(HealthCheck("memory.usage","warning","Memory usage is high.",{"used_percent":mem}))
+    else: checks.append(HealthCheck("memory.usage","ok","Memory usage is within the normal threshold.",{"used_percent":mem}))
+    for d in snapshot.disks:
+        v=d.used_percent
+        if v is None: status,msg="unknown",f"Disk usage unavailable for {d.path}."
+        elif v >= 95: status,msg="error",f"Disk usage is critically high on {d.path}."
+        elif v >= 85: status,msg="warning",f"Disk usage is high on {d.path}."
+        else: status,msg="ok",f"Disk usage is within the normal threshold on {d.path}."
+        checks.append(HealthCheck(f"disk.usage:{d.path}",status,msg,{"used_percent":v}))
+    return checks

pcpulse/models.py

@@ -0,0 +1,41 @@
+from dataclasses import asdict, dataclass, field
+from typing import Any
+@dataclass(frozen=True)
+class CpuInfo:
+    logical_cores: int | None
+    physical_cores: int | None
+    load_percent: float | None
+@dataclass(frozen=True)
+class MemoryInfo:
+    total_bytes: int | None
+    available_bytes: int | None
+    used_bytes: int | None
+    used_percent: float | None
+@dataclass(frozen=True)
+class DiskInfo:
+    path: str
+    total_bytes: int | None
+    free_bytes: int | None
+    used_percent: float | None
+@dataclass(frozen=True)
+class Snapshot:
+    collected_at: str
+    schema_version: str
+    os: str
+    kernel: str
+    architecture: str
+    cpu: CpuInfo
+    memory: MemoryInfo
+    disks: list[DiskInfo] = field(default_factory=list)
+    uptime_seconds: float | None = None
+    hostname: str | None = None
+    username: str | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+@dataclass(frozen=True)
+class HealthCheck:
+    id: str
+    status: str
+    message: str
+    details: dict[str, Any] = field(default_factory=dict)

pcpulse/serialization.py

@@ -0,0 +1,12 @@
+import json
+from typing import Any
+from .models import Snapshot
+def to_dict(snapshot: Snapshot) -> dict[str, Any]: return snapshot.to_dict()
+def to_json(snapshot: Snapshot) -> str: return json.dumps(to_dict(snapshot), indent=2)
+def to_markdown(snapshot: Snapshot) -> str:
+    rows=[("OS",snapshot.os),("Kernel",snapshot.kernel),("Architecture",snapshot.architecture),("CPU logical",snapshot.cpu.logical_cores),("CPU physical",snapshot.cpu.physical_cores),("CPU load",snapshot.cpu.load_percent),("Memory used",snapshot.memory.used_percent),("Uptime seconds",snapshot.uptime_seconds)]
+    out=["# PCPulse System Snapshot","","| Metric | Value |","|---|---|"]
+    out += [f"| {k} | {v if v is not None else 'unavailable'} |" for k,v in rows]
+    out += ["","## Disks"]
+    out += [f"- {d.path}: {d.used_percent if d.used_percent is not None else 'unavailable'}% used" for d in snapshot.disks]
+    return "\n".join(out)+"\n"

pcpulse-0.1.0.dist-info/METADATA

@@ -0,0 +1,255 @@
+Metadata-Version: 2.5
+Name: pcpulse
+Version: 0.1.0
+Summary: Privacy-first cross-platform PC diagnostics library and CLI.
+Author: Matthew Para
+License: MIT License
+        
+        Copyright (c) 2026 Matthew Para
+        
+        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.
+License-File: LICENSE
+Keywords: cli,diagnostics,hardware,pc,privacy,system
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: psutil<8,>=5.9
+Requires-Dist: rich<15,>=13
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PCPulse
+
+**Local-first, privacy-conscious, cross-platform PC diagnostics for humans, scripts, support tools, and developer applications.**
+
+PCPulse is an open-source Python library and CLI for collecting useful system diagnostics without requiring a cloud service. It turns local machine information into typed Python objects and stable machine-readable output.
+
+## Highlights
+
+- Cross-platform system snapshots
+- CPU, memory, disk, OS, architecture, and uptime information
+- JSON and Markdown output
+- Conservative local health checks with `pcpulse doctor`
+- Versioned snapshot schema
+- Privacy-first identity handling
+- Python library API for integration into other tools
+- No telemetry or mandatory network service
+- MIT licensed
+- Tests, linting, type checking, CI, security guidance, and contributor documentation
+
+## Installation
+
+Install the published package when available:
+
+    python -m pip install pcpulse
+
+For development:
+
+    git clone https://github.com/matthewpara567/pcpulse.git
+    cd pcpulse
+    python -m pip install -e '.[dev]'
+
+## Quick start
+
+Collect a human-readable snapshot:
+
+    pcpulse snapshot
+
+Get JSON:
+
+    pcpulse snapshot --json
+
+Get Markdown:
+
+    pcpulse snapshot --markdown
+
+Run health checks:
+
+    pcpulse doctor
+
+Get machine-readable health checks:
+
+    pcpulse doctor --json
+
+Identity information is excluded by default. Opt in explicitly:
+
+    pcpulse snapshot --include-identity
+
+## Python API
+
+    from pcpulse import collect_snapshot, run_checks
+
+    snapshot = collect_snapshot()
+    print(snapshot.to_dict())
+
+    for check in run_checks(snapshot):
+        print(check.status, check.message)
+
+The library is intended to be the stable integration layer. The CLI is an interface over that library.
+
+## Privacy
+
+PCPulse is designed around a local-first model:
+
+- No telemetry is required.
+- No account is required.
+- No cloud backend is required.
+- Hostname and username are not collected unless explicitly requested.
+- Collectors are read-only diagnostics and do not intentionally modify the host.
+- Applications should sanitize reports before sharing them externally.
+
+A diagnostic report can still contain machine-specific information such as operating-system details, mount paths, hardware counts, or uptime. Review output before publishing it.
+
+## Snapshot schema
+
+Snapshots carry an explicit schema version so consumers can distinguish format changes:
+
+    "schema_version": "1.0"
+
+The canonical JSON Schema is stored at:
+
+    schemas/snapshot-1.0.schema.json
+
+Consumers should treat schema changes as compatibility-sensitive and avoid assuming that every platform exposes every metric.
+
+## Health checks
+
+`pcpulse doctor` performs conservative checks for conditions such as high memory usage and high disk utilization.
+
+A check can report:
+
+- `ok`
+- `warning`
+- `error`
+- `unknown`
+
+Unknown is preferred over inventing a value when the operating system does not expose a metric.
+
+## Architecture
+
+PCPulse separates:
+
+1. **Collectors** — read local system information.
+2. **Models** — provide typed Python representations.
+3. **Serialization** — converts snapshots to JSON or Markdown.
+4. **Health checks** — interprets selected metrics.
+5. **CLI** — provides a user-facing command interface.
+
+This separation makes PCPulse useful as a library without requiring applications to scrape terminal output.
+
+## Development
+
+Install development dependencies:
+
+    python -m pip install -e '.[dev]'
+
+Run the test suite:
+
+    pytest -q
+
+Run linting:
+
+    ruff check .
+
+Run type checking:
+
+    mypy src
+
+## Contributing
+
+Bug fixes, documentation improvements, tests, platform compatibility work, and carefully scoped features are welcome.
+
+Before opening a pull request:
+
+- Keep the change focused.
+- Add or update tests where appropriate.
+- Document public API or schema changes.
+- Consider privacy implications.
+- Run the test, lint, and type-check commands.
+- Avoid unrelated formatting churn.
+
+See CONTRIBUTING.md for details.
+
+## Security
+
+Please do not disclose vulnerabilities in public issues. Follow SECURITY.md for responsible reporting.
+
+Security-sensitive areas include unintended network activity, unsafe parsing, dependency vulnerabilities, command execution, and accidental disclosure of local information.
+
+## Project structure
+
+    pcpulse/
+    ├── .github/
+    │   ├── ISSUE_TEMPLATE/
+    │   └── workflows/
+    ├── docs/
+    ├── examples/
+    ├── schemas/
+    ├── src/
+    │   └── pcpulse/
+    ├── tests/
+    ├── CHANGELOG.md
+    ├── CODE_OF_CONDUCT.md
+    ├── CONTRIBUTING.md
+    ├── GOVERNANCE.md
+    ├── LICENSE
+    ├── MAINTAINERS.md
+    ├── README.md
+    ├── RELEASING.md
+    ├── SECURITY.md
+    ├── SUPPORT.md
+    └── pyproject.toml
+
+## Design principles
+
+PCPulse follows a few simple principles:
+
+- **Local-first:** the core collector should work without a cloud service.
+- **Privacy-first:** identity data is opt-in.
+- **Structured:** machine-readable output is a first-class interface.
+- **Best-effort:** unavailable metrics are represented as unavailable.
+- **Read-only:** diagnostics should not silently modify the host.
+- **Compatibility-conscious:** public API and schema changes should be deliberate.
+- **Small core:** features should justify their maintenance cost.
+
+## Roadmap
+
+Potential future work includes:
+
+- More detailed platform-specific hardware metrics
+- Battery, temperature, and fan information where safely available
+- Pluggable collectors
+- Richer diagnostic bundles
+- More schema validation tooling
+- Additional operating-system compatibility tests
+- Release provenance and artifact-integrity improvements
+
+Roadmap items are not promises and may change as the project evolves.
+
+## License
+
+PCPulse is released under the MIT License. See LICENSE.
+
+## Status
+
+PCPulse is currently an early open-source project. APIs and schema details may evolve before the first stable release.

pcpulse-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+pcpulse/__init__.py,sha256=Bl6eFKrkTPYzFIKU6cFuw_iqNEI5k-Va3jlJn8y4yjU,234
+pcpulse/cli.py,sha256=maAG4THY6Se9Vm5eqaFCEuxNNu9xNHV9qLOrl6iD2qA,2257
+pcpulse/collectors.py,sha256=j-YrYUmVfX-isLw8kVSBQzb7idJRfZqPsK7PF_LxrJA,1310
+pcpulse/health.py,sha256=4YGIkRWMFCG3Y3gGW52enEJIh_czwC2fhOY5KxVRQwM,1130
+pcpulse/models.py,sha256=lzq4ZP2GwpBFqGg56pb1OP7-M2D_1_JshDZBAqueLdU,1110
+pcpulse/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pcpulse/serialization.py,sha256=4pKiX-1V3pgodOa3ZvWE91aZHGfNIi0M5eJxVnioN2A,921
+pcpulse-0.1.0.dist-info/METADATA,sha256=L2XwIy-hHqgGdWUKWNrjeUMP7DBmLXToKs5b3Gj_N6c,7866
+pcpulse-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pcpulse-0.1.0.dist-info/entry_points.txt,sha256=lZkcACK5YkP2ffT2MegqeaOV-mb6PjTnhMz7FtG1cEQ,45
+pcpulse-0.1.0.dist-info/licenses/LICENSE,sha256=sTtnfqCK1QklB0VTzAXrtZK3mycLDam3SeKMd0-6IvM,1069
+pcpulse-0.1.0.dist-info/RECORD,,

pcpulse-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

pcpulse-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pcpulse = pcpulse.cli:main

pcpulse-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Para
+
+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.