Skip to main content

DOCSIS 3.x/4.0 Proactive Network Maintenance Toolkit

Project description

PyPNM Logo

PyPNM - Proactive Network Maintenance Toolkit

PyPNM Version PyPI - Version PyPI - Python Version Daily Build CodeQL PyPI Install Check Kubernetes (kind) GHCR Publish Dockerized License: Apache-2.0 Ubuntu

PyPNM is a DOCSIS 3.x/4.0 Proactive Network Maintenance toolkit for engineers who want repeatable, scriptable visibility into modem health. It can run purely as a Python library or as a FastAPI web service for real-time dashboards and offline analysis workflows.

Table of contents

Choose your path

Path Description
Kubernetes deploy (kind) Run PyPNM in a local kind cluster (GHCR image).
Docker deploy Install and run the containerized PyPNM service.
Use PyPNM as a library Install pypnm-docsis into an existing Python environment.
Run the full platform Clone the repo and use the full FastAPI + tooling stack.

Kubernetes | Docker

Docker (Recommended) - Install Docker | Install PyPNM Container | Commands

Fast install (helper script; latest release auto-detected):

TAG="v1.0.13.0"
PORT=8080

curl -fsSLo install-pypnm-docker-container.sh \
  https://raw.githubusercontent.com/PyPNMApps/PyPNM/main/scripts/install-pypnm-docker-container.sh

chmod +x install-pypnm-docker-container.sh

sudo ./install-pypnm-docker-container.sh --tag ${TAG} --port ${PORT}

If Docker isn’t on your host yet, follow the Install Docker prerequisites guide first.

More Docker options and compose workflows: PyPNM Docker Installation and Developer Workflow.

Kubernetes (kind) dev clusters

Kubernetes quick links:

We continuously test the manifests with a kind-based CI smoke test (Kubernetes (kind) badge above). Follow the kind quickstart or the detailed deployment guide to run PyPNM inside a local single-node cluster; multi-node scenarios are not covered yet (see pros/cons).

Script-only deployment (no repo clone) is documented in PyPNM deploy.

Prerequisites

Operating systems

Linux, validated on:

  • Ubuntu 22.04 LTS
  • Ubuntu 24.04 LTS

Other modern Linux distributions may work but are not yet part of the test matrix.

Shell dependencies

From a fresh system, install Git:

sudo apt update
sudo apt install -y git

Python and remaining dependencies are handled by the installer.

Getting started

Install from PyPI (library only)

If you only need the library, install from PyPI:

pip install pypnm-docsis

Uninstall and cleanup:

pip uninstall pypnm-docsis
rm -f ~/.ssh/pypnm_secrets.key

For full FastAPI service usage and development, use the repository-based flow below.

1) Clone

git clone https://github.com/PyPNMApps/PyPNM.git
cd PyPNM

2) Install

Run the installer:

./install.sh

Common flags (use as needed):

Flag Purpose
--development Installs Docker Engine + kind/kubectl. See Development Install.
--clean Removes prior install artifacts (venv/build/dist/cache) before installing. Preserves data and system configuration.
--purge-cache Clears pip cache after activating the venv (use with --clean when troubleshooting stale installs).
--pnm-file-retrieval-setup Launches tools/pnm/pnm_file_retrieval_setup.py after install. See the PNM File Retrieval Overview.
--demo-mode Seeds demo data/paths for offline exploration. See the demo mode guide.
--production Reverts demo-mode changes and restores your previous system.json backup.

Installer extras: adds shell aliases when available; source your rc file once to pick them up.

3) Activate the virtual environment

If you used the installer defaults, activate the .env environment:

source .env/bin/activate

4) Configure system settings

System configuration lives in deploy/docker/config/system.json.

  • Config menu: source ~/.bashrc && config-menu
  • System Configuration Reference: field-by-field descriptions and defaults If you installed with --pnm-file-retrieval-setup, it runs automatically and backs up system.json first.

5) Run the FastAPI service launcher

HTTP (default: http://127.0.0.1:8000):

pypnm

Development hot-reload:

pypnm --reload

6) (Optional) Serve the documentation

HTTP (default: http://127.0.0.1:8001):

mkdocs serve

7) Explore the API

Installed services and docs are available at the following URLs:

Git Clone Docker
FastAPI Swagger UI FastAPI Swagger UI
FastAPI ReDoc FastAPI ReDoc
MkDocs docs MkDocs docs

Documentation

SNMP notes

  • SNMPv2c is supported
  • SNMPv3 is currently stubbed and not yet supported

CableLabs specifications & MIBs

PNM architecture & guidance

License

Apache License 2.0 and NOTICE

Next steps

Maintainer

Maurice Garcia

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pypnm_docsis-1.0.13.0.tar.gz (1.3 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

pypnm_docsis-1.0.13.0-py3-none-any.whl (1.3 MB view details)

Uploaded Python 3

File details

Details for the file pypnm_docsis-1.0.13.0.tar.gz.

File metadata

  • Download URL: pypnm_docsis-1.0.13.0.tar.gz
  • Upload date:
  • Size: 1.3 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for pypnm_docsis-1.0.13.0.tar.gz
Algorithm Hash digest
SHA256 3d30bd6ea357c04899a6c6e830a31c9f5155b098443bea17d9eb2eaf95de7fa7
MD5 5651b85cb532729c7e985d0d2203c106
BLAKE2b-256 2d688ed923a52845633c89c044ba50d01612fe92519a4b3c09b750456b3f7897

See more details on using hashes here.

File details

Details for the file pypnm_docsis-1.0.13.0-py3-none-any.whl.

File metadata

File hashes

Hashes for pypnm_docsis-1.0.13.0-py3-none-any.whl
Algorithm Hash digest
SHA256 ce872076c526d1a2f49e8140427d6a579ef7fb3c4db7f9663632b5a540ffce85
MD5 2fb3bdccb50d08cb33c96125b24c2fed
BLAKE2b-256 374c815954f4285bd9e383cf7792c328b3a589a2e2534ebde287bee3a64ddfb6

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page