refactor(corekit): move pcapkit.utilities.chardet into corekit #1712

Activity

1. JarryShaw

   added

   refactorRestructuring for its own sake — neither a fix nor a new capability (refactor: prefix)Restructuring for its own sake — neither a fix nor a new capability (refactor: prefix)

   blockedDeferred pending another issue or decision; see the last comment for what unblocks itDeferred pending another issue or decision; see the last comment for what unblocks it

   on Oct 14, 2026
2. JarryShaw

   added this to PyPCAPKiton Oct 14, 2026
3. JarryShaw

   moved this to Blocked in PyPCAPKiton Oct 14, 2026
4. JarryShaw commented on Oct 14, 2026

   

   JarryShaw

   on Oct 14, 2026

   OwnerAuthor

   More actions

   The ruling on #1715 applies here too: the move updates every import path directly, with no re-export left at pcapkit/utilities/chardet.py.
5. JarryShaw

   added

   wipWork in flight - a covering PR is open or an agent is actively on itWork in flight - a covering PR is open or an agent is actively on it

   and removed

   blockedDeferred pending another issue or decision; see the last comment for what unblocks itDeferred pending another issue or decision; see the last comment for what unblocks it

   on Oct 14, 2026
6. JarryShaw commented on Oct 14, 2026

   

   JarryShaw

   on Oct 14, 2026

   OwnerAuthor

   More actions

   #1707 has merged. A worker is on it, with no re-export at the old path (the ruling on #1715). In strings.py it changes only the import line, so it does not collide with #1706.
7. JarryShaw

   moved this from Blocked to WIP in PyPCAPKiton Oct 14, 2026
8. JarryShaw commented on Oct 14, 2026

   

   JarryShaw

   on Oct 14, 2026

   OwnerAuthor

   More actions

   I'm kinda debating what's the criteria for corekit or utilities. Not sure if chardet and many other modules under corekit and utilities should live.
9. JarryShaw commented on Oct 14, 2026

   

   JarryShaw

   on Oct 14, 2026

   OwnerAuthor

   More actions

   Understood. I am holding #1729, the chardet move, until the criterion is settled. Next I will post an inventory of every module in pcapkit/corekit and pcapkit/utilities: what each imports from pcapkit, who imports it, and whether it carries packet or protocol knowledge. Each module gets a proposed rule applied to it, so the decision is about concrete moves rather than names.
10. JarryShaw

    added

    needs: decisionWaiting on the maintainer to decide — not blocked by other workWaiting on the maintainer to decide — not blocked by other work

    on Oct 14, 2026
11. JarryShaw

    moved this from WIP to Needs decision in PyPCAPKiton Oct 14, 2026
12. JarryShaw commented on Oct 14, 2026

    

    JarryShaw

    on Oct 14, 2026

    OwnerAuthor

    More actions

    Inventory of every module in both packages, on main (fb7027b25). The import order today is already utilities (all of it), then corekit, then protocols/const, with one exception.

    Proposed rule:

    • utilities holds cross-cutting services: reporting (exceptions, warnings, logging), configuration, compatibility shims and wrappers around third-party libraries. It imports nothing from pcapkit outside utilities, at top level, inside a function or under TYPE_CHECKING. It carries no wire format or protocol behaviour.
    • corekit holds the types the packet model is built from: what protocols, const and foundation subclass, instantiate or decorate with. It may import utilities, and reaches protocols only lazily.

    Applied, only one module moves:

    • utilities.decorators breaks the rule. seekset, beholder and prepare act on Protocol._file and _seekset, and beholder lazily imports protocols.misc.null and raw (decorators.py:130-132). It would move to corekit.decorators (or protocols), adding no import-time cycle. That breaks pcapkit.utilities.{seekset,beholder,prepare} and the logger name pcapkit.utilities.decorators.
    • chardet stays in utilities. It is a leaf third-party wrapper that imports only functools and chardet, so refactor(corekit)!: move chardet into corekit (#1712) #1729 goes against this rule. Either rule is cycle-safe for chardet.
    • feat(utilities): one config module for the tunable limits (PCAPKIT_* environment variables), and one home per duplicated protocol constant #1726's utilities/config.py fits: a configuration service that imports only utilities.warnings.

    The alternative, a "no packet knowledge" test, would also move multidict, version, module, sentinels, io, infoclass, enum and packet into utilities. That is about 8 breaking moves, each dragging the others, and leaves corekit with only fields, protochain, context, packet and byteorder.

    Your call: which rule? Under the proposed one, should #1729 close (chardet stays put), and where should decorators go, corekit or protocols?
13. JarryShaw commented on Oct 14, 2026

    

    JarryShaw

    on Oct 14, 2026

    OwnerAuthor

    More actions

    explain better about the options and criteria for the split of each option
14. JarryShaw commented on Oct 14, 2026

    

    JarryShaw

    on Oct 14, 2026

    OwnerAuthor

    More actions

    Three options. Each comes down to one question asked of a module.

    Option	Question that decides	utilities gets	corekit gets	Breaking moves
    A. Services vs types (recommended)	Is it a service any code could use (reporting, config, compat, third-party wrapper) that imports nothing from pcapkit outside utilities? Then utilities; otherwise corekit.	exceptions, warnings, logging, compat, chardet, config	fields, infoclass, enum, multidict, module, sentinels, version, io, packet, context, protochain, decorators	1: decorators
    B. Packet knowledge	Does it know about packets, wire formats or protocols? Yes means corekit, no means utilities.	A's list plus multidict, version, module, sentinels, io, infoclass, enum	fields, protochain, context, packet, byteorder, decorators	8: the seven listed plus decorators
    C. Who uses it	Is it used only by the packet model (fields, protocols)? Then corekit.	exceptions, warnings, logging, compat, config	A's list plus chardet	2: decorators, and chardet (#1729)

    decorators moves under all three. It works on Protocol._file and imports protocol classes, so it fails every utilities test.

    The trade-offs:

    • A: the rule is checkable by import graph alone, since utilities never imports corekit. It also churns least.
    • B: cleanest by meaning. But the seven modules must move together, because infoclass imports enum and multidict, and enum and module import sentinels. The public types Info, MultiDict, EnumRegistry and VersionInfo would change path.
    • C: keeps your earlier call that chardet belongs with the fields. Its question is the fuzziest, though: compat and exceptions are also used mostly by the packet model, yet stay put.

    All three are cycle-safe as moved.
15. JarryShaw commented on Oct 14, 2026

    

    JarryShaw

    on Oct 14, 2026

    OwnerAuthor

    More actions

    okay, i think we should take A
16. JarryShaw commented on Oct 14, 2026

    

    JarryShaw

    on Oct 14, 2026

    Last edited by JarryShaw

    OwnerAuthor

    More actions

    Recorded: option A.

    • utilities holds cross-cutting services: exceptions, warnings, logging, compat, config and third-party wrappers. It imports nothing from pcapkit outside utilities.
    • corekit holds the types the packet model is built from.

    What this means for the open work:

    • chardet stays in utilities, so this issue's move is withdrawn and refactor(corekit)!: move chardet into corekit (#1712) #1729 closes unmerged.
    • The one move the rule requires, utilities.decorators into corekit, together with writing the rule into the conventions docs, is tracked in refactor(corekit)!: move utilities.decorators into corekit, and state the corekit/utilities rule (#1712, option A) #1735.
17. JarryShaw

    closed this as not plannedon Oct 14, 2026
18. JarryShaw

    removed

    wipWork in flight - a covering PR is open or an agent is actively on itWork in flight - a covering PR is open or an agent is actively on it

    needs: decisionWaiting on the maintainer to decide — not blocked by other workWaiting on the maintainer to decide — not blocked by other work

    on Oct 14, 2026
19. github-project-automation

    moved this from Needs decision to Done in PyPCAPKiton Oct 14, 2026
20. JarryShaw

    added a commit that references this issue on Oct 14, 2026

    refactor(corekit)!: move decorators into corekit (#1735) (#1737)

    ...

    34a197d