pktlib 0.2.0__tar.gz

pktlib-0.2.0/LICENSE

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

pktlib-0.2.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: pktlib
+Version: 0.2.0
+Summary: Read, edit and write Cisco Packet Tracer .pkt files in Python
+Keywords: cisco,packet-tracer,pkt,ccna,networking,network-labs,netacad
+Author: Conor McShane
+Author-email: Conor McShane <117556909+conor-sometimes@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Education
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/conor-sometimes/pktlib
+Project-URL: Issues, https://github.com/conor-sometimes/pktlib/issues
+Description-Content-Type: text/markdown
+
+# pktlib
+
+[![PyPI](https://img.shields.io/pypi/v/pktlib)](https://pypi.org/project/pktlib/)
+[![Python](https://img.shields.io/pypi/pyversions/pktlib)](https://pypi.org/project/pktlib/)
+[![CI](https://github.com/conor-sometimes/pktlib/actions/workflows/ci.yml/badge.svg)](https://github.com/conor-sometimes/pktlib/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/conor-sometimes/pktlib/blob/main/LICENSE)
+
+Read, edit and write Cisco Packet Tracer `.pkt` files (and `.pka` activities) from Python. Build a network in code,
+open it in Packet Tracer, and it works.
+
+Tested on **Packet Tracer 8.2.0** (build 8.2.0.0162). Plain Python 3.10+, no dependencies.
+MIT licensed. Not affiliated with Cisco.
+
+```python
+import pktlib
+
+net = pktlib.new()
+r1 = net.router("R1", "2911", at=(300, 200))
+sw = net.switch("SW1", at=(300, 320))
+pc = net.pc("PC1", at=(300, 440), ip="192.168.1.10/24", gateway="192.168.1.1")
+
+pc["fa0"].connect(sw["fa0/1"])  # the right cable is picked for you
+sw["fa0/2"].connect(r1["g0/0"])
+r1["g0/0"].address = "192.168.1.1/24"  # interface, ip address, no shutdown
+r1.config("""
+router ospf 1
+ network 192.168.1.0 0.0.0.255 area 0
+""")
+net.save("lab.pkt")
+```
+
+## Installation
+
+pktlib is [on PyPI](https://pypi.org/project/pktlib/):
+
+```
+pip install pktlib
+```
+
+In a uv project, `uv add pktlib`. To use only the command line (`pktlib audit lab.pkt`,
+`pktlib info`, `pktlib dump`) without installing anything into a project:
+
+```
+pipx install pktlib
+# or run it once with uv
+uvx pktlib audit lab.pkt
+```
+
+The latest unreleased version: `pip install git+https://github.com/conor-sometimes/pktlib`.
+
+## What it does
+
+- **Build** routers, switches, PCs, phones and any of the 64 models in the 8.2 palette;
+  cable them, address them, configure them with IOS text, fit modules, draw labels.
+- **Read** any `.pkt`: devices, ports, cables, addresses, VLANs, config. Files from older
+  Packet Tracers (6.2 and up) load and save as 8.2.
+- **Activities** (`.pka`, `pktlib.activity`): read one, score a network against it, or write
+  a new one from two networks that Packet Tracer grades with Check Results.
+- **Check** a file before handing it in: `pktlib audit lab.pkt` finds duplicate addresses,
+  wrong gateways, shut ports, missing clock rates and config Packet Tracer drops.
+- **Teach** with it: troubleshooting labs with planted faults, an answer key and grading
+  (`pktlib.lab`); ping checks students click in Packet Tracer.
+- **Round-trip**: `pktlib dump lab.pkt` turns any file into a script that rebuilds it.
+
+Every behaviour was seen in Packet Tracer before pktlib relied on it. Where Packet Tracer
+does something surprising, pktlib handles it; [docs/packet-tracer.md](https://github.com/conor-sometimes/pktlib/blob/main/docs/packet-tracer.md)
+lists what and how we know.
+
+## Command line
+
+| Command | What it does |
+|---|---|
+| `pktlib info lab.pkt` | devices, links and addresses |
+| `pktlib audit lab.pkt` | problems you can see without running the simulation; exit code 1 if any |
+| `pktlib dump lab.pkt [out.py]` | a Python script that rebuilds the file |
+| `pktlib decode lab.pkt [out.xml]` / `encode in.xml out.pkt` | the raw XML |
+
+## Documentation
+
+- [Guide](https://github.com/conor-sometimes/pktlib/blob/main/docs/guide.md): the API, with errors and warnings
+- [For students](https://github.com/conor-sometimes/pktlib/blob/main/docs/students.md) and [for lecturers](https://github.com/conor-sometimes/pktlib/blob/main/docs/lecturers.md)
+- [Packet Tracer notes](https://github.com/conor-sometimes/pktlib/blob/main/docs/packet-tracer.md): editions, device models, the quirks pktlib
+  handles, the file format
+- [Examples](https://github.com/conor-sometimes/pktlib/blob/main/examples/README.md): every example, by folder; [which were opened in Packet Tracer](https://github.com/conor-sometimes/pktlib/blob/main/docs/examples.md)
+- [Changelog](https://github.com/conor-sometimes/pktlib/blob/main/CHANGELOG.md)
+
+## Development
+
+```
+uv sync
+just check     # ruff, the type checkers, then the tests (about a minute)
+just soak 3    # every random test on every core but two for 3 hours, counted
+```
+
+[CLAUDE.md](https://github.com/conor-sometimes/pktlib/blob/main/CLAUDE.md) has the project's rules, starting with the main one: Packet Tracer is
+the source of truth.

pktlib-0.2.0/README.md

@@ -0,0 +1,96 @@
+# pktlib
+
+[![PyPI](https://img.shields.io/pypi/v/pktlib)](https://pypi.org/project/pktlib/)
+[![Python](https://img.shields.io/pypi/pyversions/pktlib)](https://pypi.org/project/pktlib/)
+[![CI](https://github.com/conor-sometimes/pktlib/actions/workflows/ci.yml/badge.svg)](https://github.com/conor-sometimes/pktlib/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/conor-sometimes/pktlib/blob/main/LICENSE)
+
+Read, edit and write Cisco Packet Tracer `.pkt` files (and `.pka` activities) from Python. Build a network in code,
+open it in Packet Tracer, and it works.
+
+Tested on **Packet Tracer 8.2.0** (build 8.2.0.0162). Plain Python 3.10+, no dependencies.
+MIT licensed. Not affiliated with Cisco.
+
+```python
+import pktlib
+
+net = pktlib.new()
+r1 = net.router("R1", "2911", at=(300, 200))
+sw = net.switch("SW1", at=(300, 320))
+pc = net.pc("PC1", at=(300, 440), ip="192.168.1.10/24", gateway="192.168.1.1")
+
+pc["fa0"].connect(sw["fa0/1"])  # the right cable is picked for you
+sw["fa0/2"].connect(r1["g0/0"])
+r1["g0/0"].address = "192.168.1.1/24"  # interface, ip address, no shutdown
+r1.config("""
+router ospf 1
+ network 192.168.1.0 0.0.0.255 area 0
+""")
+net.save("lab.pkt")
+```
+
+## Installation
+
+pktlib is [on PyPI](https://pypi.org/project/pktlib/):
+
+```
+pip install pktlib
+```
+
+In a uv project, `uv add pktlib`. To use only the command line (`pktlib audit lab.pkt`,
+`pktlib info`, `pktlib dump`) without installing anything into a project:
+
+```
+pipx install pktlib
+# or run it once with uv
+uvx pktlib audit lab.pkt
+```
+
+The latest unreleased version: `pip install git+https://github.com/conor-sometimes/pktlib`.
+
+## What it does
+
+- **Build** routers, switches, PCs, phones and any of the 64 models in the 8.2 palette;
+  cable them, address them, configure them with IOS text, fit modules, draw labels.
+- **Read** any `.pkt`: devices, ports, cables, addresses, VLANs, config. Files from older
+  Packet Tracers (6.2 and up) load and save as 8.2.
+- **Activities** (`.pka`, `pktlib.activity`): read one, score a network against it, or write
+  a new one from two networks that Packet Tracer grades with Check Results.
+- **Check** a file before handing it in: `pktlib audit lab.pkt` finds duplicate addresses,
+  wrong gateways, shut ports, missing clock rates and config Packet Tracer drops.
+- **Teach** with it: troubleshooting labs with planted faults, an answer key and grading
+  (`pktlib.lab`); ping checks students click in Packet Tracer.
+- **Round-trip**: `pktlib dump lab.pkt` turns any file into a script that rebuilds it.
+
+Every behaviour was seen in Packet Tracer before pktlib relied on it. Where Packet Tracer
+does something surprising, pktlib handles it; [docs/packet-tracer.md](https://github.com/conor-sometimes/pktlib/blob/main/docs/packet-tracer.md)
+lists what and how we know.
+
+## Command line
+
+| Command | What it does |
+|---|---|
+| `pktlib info lab.pkt` | devices, links and addresses |
+| `pktlib audit lab.pkt` | problems you can see without running the simulation; exit code 1 if any |
+| `pktlib dump lab.pkt [out.py]` | a Python script that rebuilds the file |
+| `pktlib decode lab.pkt [out.xml]` / `encode in.xml out.pkt` | the raw XML |
+
+## Documentation
+
+- [Guide](https://github.com/conor-sometimes/pktlib/blob/main/docs/guide.md): the API, with errors and warnings
+- [For students](https://github.com/conor-sometimes/pktlib/blob/main/docs/students.md) and [for lecturers](https://github.com/conor-sometimes/pktlib/blob/main/docs/lecturers.md)
+- [Packet Tracer notes](https://github.com/conor-sometimes/pktlib/blob/main/docs/packet-tracer.md): editions, device models, the quirks pktlib
+  handles, the file format
+- [Examples](https://github.com/conor-sometimes/pktlib/blob/main/examples/README.md): every example, by folder; [which were opened in Packet Tracer](https://github.com/conor-sometimes/pktlib/blob/main/docs/examples.md)
+- [Changelog](https://github.com/conor-sometimes/pktlib/blob/main/CHANGELOG.md)
+
+## Development
+
+```
+uv sync
+just check     # ruff, the type checkers, then the tests (about a minute)
+just soak 3    # every random test on every core but two for 3 hours, counted
+```
+
+[CLAUDE.md](https://github.com/conor-sometimes/pktlib/blob/main/CLAUDE.md) has the project's rules, starting with the main one: Packet Tracer is
+the source of truth.

pktlib-0.2.0/pyproject.toml

@@ -0,0 +1,153 @@
+[project]
+name = "pktlib"
+version = "0.2.0"
+description = "Read, edit and write Cisco Packet Tracer .pkt files in Python"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = []
+keywords = [
+    "cisco",
+    "packet-tracer",
+    "pkt",
+    "ccna",
+    "networking",
+    "network-labs",
+    "netacad",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Education",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Education",
+    "Topic :: System :: Networking",
+    "Typing :: Typed",
+]
+
+[[project.authors]]
+name = "Conor McShane"
+email = "117556909+conor-sometimes@users.noreply.github.com"
+
+[project.urls]
+Homepage = "https://github.com/conor-sometimes/pktlib"
+Issues = "https://github.com/conor-sometimes/pktlib/issues"
+
+[project.scripts]
+pktlib = "pktlib._cli:main"
+
+[build-system]
+requires = ["uv_build>=0.13.5,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "hypothesis>=6.168.5",
+    "mutmut>=3.8.0",
+    "mypy>=2.4.0",
+    "pyright>=1.1.414",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "pytest-randomly>=5.0.0",
+    "pytest-xdist>=3.8.0",
+    "ruff>=0.17.2",
+    "ty>=0.0.92",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = [
+    "-n",
+    "auto",
+    "-ra",
+    "--strict-markers",
+    "--strict-config",
+]
+xfail_strict = true
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+source = ["pktlib"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+fail_under = 95
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "BLE",
+    "C4",
+    "SIM",
+    "FBT",
+    "ANN",
+    "RUF",
+]
+ignore = [
+    "RUF005",
+    "SIM108",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "ANN",
+    "FBT",
+    "E741",
+]
+"{examples,stress,scripts}/**" = [
+    "ANN",
+    "FBT",
+    "E741",
+]
+
+[tool.ty.environment]
+python-version = "3.10"
+
+[tool.mutmut]
+paths_to_mutate = ["src/pktlib/"]
+also_copy = [
+    "src/pktlib/data/",
+    "src/pktlib/spec/",
+    "tests/",
+    "examples/",
+    "stress/",
+    "scripts/",
+    "docs/",
+    "README.md",
+    "CHANGELOG.md",
+    "CLAUDE.md",
+    "LICENSE",
+    "CITATION.cff",
+]
+pytest_add_cli_args = [
+    "-n0",
+    "-p",
+    "no:randomly",
+    "-x",
+    "-q",
+]
+pytest_add_cli_args_test_selection = [
+    "tests/",
+    "--deselect=tests/test_stateful.py",
+    "--deselect=tests/test_fuzz_files.py",
+    "--deselect=tests/test_properties.py",
+]

pktlib-0.2.0/pyproject.toml.orig

@@ -0,0 +1,114 @@
+[project]
+name = "pktlib"
+version = "0.2.0"
+description = "Read, edit and write Cisco Packet Tracer .pkt files in Python"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = []
+authors = [{ name = "Conor McShane", email = "117556909+conor-sometimes@users.noreply.github.com" }]
+keywords = ["cisco", "packet-tracer", "pkt", "ccna", "networking", "network-labs", "netacad"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Education",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Education",
+    "Topic :: System :: Networking",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/conor-sometimes/pktlib"
+Issues = "https://github.com/conor-sometimes/pktlib/issues"
+
+[project.scripts]
+pktlib = "pktlib._cli:main"
+
+[build-system]
+requires = ["uv_build>=0.13.5,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "hypothesis>=6.168.5",
+    "mutmut>=3.8.0",
+    "mypy>=2.4.0",
+    "pyright>=1.1.414",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "pytest-randomly>=5.0.0",
+    "pytest-xdist>=3.8.0",
+    "ruff>=0.17.2",
+    "ty>=0.0.92",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# every core (pytest-xdist), a fresh random order each run (pytest-randomly; -p no:randomly
+# to turn it off, -p randomly -p "randomly_seed=N" to repeat one), and no surprises: an
+# unexpected warning fails, a typo'd marker or setting is an error, an xfail that passes fails
+addopts = ["-n", "auto", "-ra", "--strict-markers", "--strict-config"]
+xfail_strict = true
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+source = ["pktlib"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+fail_under = 95  # line and branch coverage of the package; CI fails below it
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E", "W", "F",  # pycodestyle, pyflakes
+    "I",            # import order
+    "UP",           # pyupgrade, for the oldest supported Python
+    "B",            # bugbear
+    "BLE",          # blind except
+    "C4",           # comprehensions
+    "SIM",          # simplify
+    "FBT",          # boolean positional arguments
+    "ANN",          # annotations on the public API
+    "RUF",
+]
+ignore = [
+    "RUF005",  # [*a, b] over a + [b] is taste, not correctness
+    "SIM108",  # a ternary is not always clearer than an if/else
+]
+
+[tool.ruff.lint.per-file-ignores]
+# scripts and tests: no annotations required; `l` for a line is left alone outside the package
+"tests/**" = ["ANN", "FBT", "E741"]
+"{examples,stress,scripts}/**" = ["ANN", "FBT", "E741"]
+
+[tool.ty.environment]
+python-version = "3.10"
+
+[tool.mutmut]
+# `just mutate`: plant small bugs in the package and check a test catches each one. Slow, so
+# it isn't part of `just check`. The slow random suites are left out: the targeted tests are
+# what should catch a planted bug.
+paths_to_mutate = ["src/pktlib/"]
+also_copy = ["src/pktlib/data/", "src/pktlib/spec/", "tests/", "examples/", "stress/", "scripts/", "docs/", "README.md", "CHANGELOG.md", "CLAUDE.md", "LICENSE", "CITATION.cff"]
+pytest_add_cli_args = ["-n0", "-p", "no:randomly", "-x", "-q"]
+pytest_add_cli_args_test_selection = [
+    "tests/",
+    "--deselect=tests/test_stateful.py",
+    "--deselect=tests/test_fuzz_files.py",
+    "--deselect=tests/test_properties.py",
+]

pktlib-0.2.0/src/pktlib/__init__.py

@@ -0,0 +1,104 @@
+"""pktlib: read, edit and write Cisco Packet Tracer .pkt files, in plain Python.
+
+import pktlib
+
+net = pktlib.new()
+r1 = net.router("R1", "1841+WIC-2T", at=(200, 380))
+sw = net.switch("SW0", at=(200, 260))
+pc = net.pc("PC0", at=(200, 150), ip="192.168.1.10/24", gateway="192.168.1.1")
+pc["fa0"].connect(sw["fa0/1"])
+sw["fa0/2"].connect(r1["fa0/0"])
+r1["fa0/0"].address = "192.168.1.1/24"
+net.save("lab.pkt")
+
+net = pktlib.load("lab.pkt")
+print(pktlib.to_python(net))   # any .pkt -> a script that rebuilds it
+
+Everything public is here, at the top level, and in pktlib.lab. Modules whose names
+start with an underscore are pktlib's own and may change in any release.
+"""
+
+import contextlib as _contextlib
+from importlib import metadata as _metadata
+
+from ._audit import Problem, audit
+from ._codec import decode, encode
+from ._editions import EDITIONS, LATEST
+from ._errors import FileFormatError, NotFound, PktError, PktWarning, TagMismatch
+from ._export import to_python
+from ._iosconfig import refused
+from ._model import (
+    Address,
+    Cable,
+    Device,
+    End,
+    Interface,
+    Link,
+    Network,
+    Pdu,
+    Port,
+    Ports,
+    Profile,
+    RsaKey,
+    load,
+    models,
+    new,
+)
+from ._modules import Slot, module_models
+from ._passwords import matches as password_matches
+from ._ports import canonical_port
+from ._shapes import Note, Shape
+from .lab import Fault, Lab, Result
+
+__all__ = [
+    "EDITIONS",
+    "LATEST",
+    "Address",
+    "Cable",
+    "Device",
+    "End",
+    "Fault",
+    "FileFormatError",
+    "Interface",
+    "Lab",
+    "Link",
+    "Network",
+    "NotFound",
+    "Note",
+    "Pdu",
+    "PktError",
+    "PktWarning",
+    "Port",
+    "Ports",
+    "Problem",
+    "Profile",
+    "Result",
+    "RsaKey",
+    "Shape",
+    "Slot",
+    "TagMismatch",
+    "audit",
+    "canonical_port",
+    "decode",
+    "encode",
+    "load",
+    "models",
+    "module_models",
+    "new",
+    "password_matches",
+    "refused",
+    "to_python",
+]
+
+# Public names say they're pktlib's, not a private module's: pktlib.NotFound in a
+# traceback, and help(pktlib.Network) names the right place.
+for _name in __all__:
+    _obj = globals()[_name]
+    if getattr(_obj, "__module__", "").startswith("pktlib."):
+        with _contextlib.suppress(AttributeError, TypeError):  # typing aliases (Cable, Address) can't be
+            _obj.__module__ = __name__
+
+try:
+    __version__ = _metadata.version("pktlib")
+except _metadata.PackageNotFoundError:  # running from a source tree that isn't installed
+    __version__ = "0+unknown"

pktlib-0.2.0/src/pktlib/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from ._cli import main
+
+sys.exit(main())