v0.1.3

CHANGELOG.md

@@ -3,6 +3,26 @@
 This project follows a lightweight "keep a log" style.
 
 
+## 0.1.3 - Refactoring and robustness
+
+- **Added**:
+    - `undirected_edges_unique(...)` for undirected containers and use it internally for component generator extraction.
+    - Read-only accessors `PeriodicComponent.snf` and `PeriodicComponent.tree_parent_map()` and updated `canonical_lift(...)` to avoid touching private component caches.
+
+- **Changed**:
+    - `LiftPatch.to_networkx(as_undirected=True, ...)` now stores direction and orig-edge snapshots under a single reserved edge attribute `__pbcgraph__` to avoid collisions with user attributes.
+    - Minor: code that previously read `_pbc_*` or `orig_edges` from NetworkX exports must now read `__pbcgraph__`.
+
+- **Performance**:
+    - `lift_patch(...)` avoids redundant incoming-edge traversal for undirected containers (no semantic change).
+    - Refactored `edges()`, `neighbors()`, and `in_neighbors()` to use streaming deterministic iteration (avoid building a full edge list just to sort it).
+
+- **Refactors**:
+    - Refactored `LiftPatch.to_networkx(...)` into small helpers (no behavior change).
+    - Split `pbcgraph.alg.lift` into `_lift_patch` and `_canonical_lift` implementation modules, keeping the public API unchanged.
+    - General refactors: introduce an internal constant `PBC_META_KEY` for NetworkX export metadata, simplify internal key filtering in undirected containers, and apply small style cleanups.
+
+
 ## 0.1.2 - Finite lifts and canonical lifts
 
 - **Finite lift patches**

docs/examples/lift_patch.ipynb

@@ -39,6 +39,7 @@
     "    PeriodicMultiGraph,\n",
     "    PeriodicDiGraph,\n",
     "    PeriodicMultiDiGraph,\n",
+    "    PBC_META_KEY,\n",
     ")\n"
    ]
   },
@@ -152,7 +153,7 @@
     "You can still request an undirected view from the patch export:\n",
     "\n",
     "- `undirected_mode='multigraph'`: one undirected multiedge per directed edge\n",
-    "- `undirected_mode='orig_edges'`: one undirected edge with `orig_edges=[...]`\n"
+    "- `undirected_mode='orig_edges'`: one undirected edge with `__pbcgraph__={'orig_edges': [...]}`\n"
    ]
   },
   {
@@ -190,7 +191,7 @@
     "for u, v, data in nxU.edges(data=True):\n",
     "    if {u, v} != {('A', (0,)), ('B', (0,))}:\n",
     "        continue\n",
-    "    print(u, '--', v, 'label=', data.get('label'), 'tail=', data.get('_pbc_tail'), 'head=', data.get('_pbc_head'))\n"
+    "    print(u, '--', v, 'label=', data.get('label'), 'tail=', data.get(PBC_META_KEY, {}).get('tail'), 'head=', data.get(PBC_META_KEY, {}).get('head'))\n"
    ]
   },
   {
@@ -205,7 +206,7 @@
     "print(type(nxC))\n",
     "data = nxC.edges[('A', (0,)), ('B', (0,))]\n",
     "print('orig_edges records:')\n",
-    "pprint(data['orig_edges'])\n"
+    "pprint(data[PBC_META_KEY]['orig_edges'])\n"
    ]
   },
   {
@@ -286,4 +287,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

docs/general/concepts.md

@@ -133,9 +133,19 @@ Important details:
 - **Undirected views of directed patches** are available via
   `LiftPatch.to_networkx(as_undirected=True, undirected_mode=...)`:
     - `undirected_mode='multigraph'`: one undirected multiedge per directed
-      edge; direction metadata is stored in `_pbc_tail`/`_pbc_head`.
+      edge; direction metadata is stored under the `__pbcgraph__` edge
+      attribute.
     - `undirected_mode='orig_edges'`: collapsed simple graph; each undirected
-      adjacency stores `orig_edges=[...]` snapshots.
+      adjacency stores `orig_edges=[...]` snapshots under the `__pbcgraph__`
+      edge attribute.
+
+
+
+**NetworkX export metadata key.** Direction/origin information is stored under a single
+reserved edge attribute named `__pbcgraph__`. In code, prefer using the constant
+`PBC_META_KEY` (exported from `pbcgraph`) instead of hardcoding the string.
+The library reserves this key for its own metadata; attempting to set it as a user
+edge attribute will raise an error.
 
 These export options avoid silent loss of information when you want an
 undirected representation for an inherently directed relation.

src/pbcgraph/__about__.py

@@ -1,4 +1,4 @@
-__version__ = '0.1.2'
+__version__ = '0.1.3'
 
 __all__ = [
     '__version__',

src/pbcgraph/__init__.py

@@ -73,6 +73,7 @@
 )
 from pbcgraph.component import PeriodicComponent
 
+from pbcgraph.core.constants import PBC_META_KEY
 from pbcgraph.core.exceptions import PBCGraphError, StaleComponentError
 from pbcgraph.core.types import (
     TVec,
@@ -88,6 +89,7 @@
 
 __all__ = [
     '__version__',
+    'PBC_META_KEY',
     # containers
     'PeriodicDiGraph',
     'PeriodicGraph',