MikeFaith/pm3py
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ff8c5d4e73424fef394b37f163cf4fee99a84ac7
pm3py/docs/plans/2026-03-18-refactor-progress.md
michael 27ae5bd756 refactor: scaffold sniff/, transponders/, reader/, sim/ sub-packages 
Phases 2-4 of package refactor. Creates the full directory tree with
__init__.py files per the design doc. Actual code migration from the
sim worktree is a separate effort — models have deep inheritance chains
and auth mixins that need base class extraction first.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-18 19:28:55 -07:00

3.2 KiB
Raw Blame History

pm3py Refactor Progress

Design: 2026-03-18-refactor-design.md Branch: refactor/core-package Started: 2026-03-18

Phase 1 — Create core/, normalize names, fix imports

Status: Complete

What was done

  • Created pm3py/core/ sub-package
  • Moved all source modules into core/:
    • protocol.py, transport.py, client.py, hw.py, hf.py, lf.py — moved as-is
    • hf_14a.py → hf_iso14a.py (renamed)
    • hf_15.py → hf_iso15.py (renamed)
    • hf_mf.py → hf_mfc.py (renamed)
  • Normalized client attributes:
    • hf.a14 → hf.iso14a
    • hf.mf → hf.mfc
    • hf.iso15 — unchanged
  • Created core/__init__.py re-exporting: Proxmark3, FirmwareInfo, PM3Transport, PM3Error, PM3Response, PM3Status, Cmd
  • Updated pm3py/__init__.py to import from .core.*
  • Updated all 10 test files (imports + attribute references)
  • 30/30 tests passing

Backward compatibility

  • from pm3py import Proxmark3 still works (re-exported)
  • Breaking: hf.a14 → hf.iso14a, hf.mf → hf.mfc
  • Breaking: Direct imports like from pm3py.hf_14a import ... → from pm3py.core.hf_iso14a import ...

Phase 2 — Extract sniff/

Status: Scaffolded — extraction deferred

hf_iso15.py is 94 lines of clean reader commands + thin sniff() firmware call. The trace parsing, 15693 decoders, NDEF annotation, and ANSI formatting described in the design doc haven't been written yet. Nothing to extract.

Created pm3py/sniff/__init__.py placeholder. Will extract into sub-modules when sniff infrastructure is implemented.

Phase 3 — Scaffold transponders/

Status: Complete (scaffolded)

Created full directory tree per design:

  • transponders/hf/iso14443a3/nxp/ — MIFARE Classic, Ultralight, NTAG
  • transponders/hf/iso14443a4/nxp/ — DESFire, NTAG 5
  • transponders/hf/iso15693/nxp/ — ICODE SLIX2
  • transponders/hf/iso15693/st/ — ST25TV
  • transponders/lf/atmel/ — T55xx
  • transponders/lf/em/ — EM4100, EM4x05

All directories have __init__.py. Model migration from sim worktree is a separate effort — the sim framework has ~7.8k LOC with deep inheritance chains (Transponder → Tag15693 → NxpIcodeTag → IcodeSlix2Tag, etc.) and auth mixins (NxpPasswordAuth, NxpAesAuth). Base class extraction needs to happen alongside model migration.

Phase 4 — Scaffold reader/ and sim/

Status: Complete (scaffolded)

Created directory trees per design:

  • reader/hf/nxp/ — NXP reader ICs (CLRC663, PN5xx)
  • reader/hf/st/ — ST reader ICs
  • reader/lf/
  • reader/modes/ — inventory, programming, access control workflows
  • sim/ — sim session, table compiler, relay (migrate from worktree)

All directories have __init__.py. Sim migration (~41 files, 7.8k LOC) is a separate effort.

Next Steps

  • Sniff infrastructure: implement trace parsing, 15693 decoders, NDEF annotation, ANSI formatting in sniff/
  • Transponder migration: extract base classes from sim worktree, populate transponders/ modules
  • Sim migration: move sim session, table compiler, relay into sim/
  • Reader modes: implement inventory, programming, access workflows in reader/modes/