halfedge 0.7.0__tar.gz → 0.11.0__tar.gz

{halfedge-0.7.0/src/halfedge.egg-info → halfedge-0.11.0}/PKG-INFO

@@ -1,19 +1,13 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: halfedge
-Version: 0.7.0
+Version: 0.11.0
 Summary: A typical half-edge data structure with some padding
+Author: Shay Hill
 Author-email: Shay Hill <shay_public@hotmail.com>
-License: MIT
-Requires-Python: >=3.8
+License-Expression: MIT
+Requires-Dist: paragraphs>=1.0.1
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: paragraphs
-Provides-Extra: dev
-Requires-Dist: commitizen; extra == "dev"
-Requires-Dist: coverage; extra == "dev"
-Requires-Dist: pre-commit; extra == "dev"
-Requires-Dist: pylint; extra == "dev"
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: tox; extra == "dev"
 
 # A typical halfedges data structure with some padding
 
@@ -35,11 +29,11 @@ mesh.remove_edge(edge)
 
 ## Particulars
 
-The idea (for 18 years and counting) has been to create an interface that is neither too complex, too verbose, nor too magical. I've been all over the place as to where that line should be. This is my current thinking.
+The idea (for 19 years and counting) has been to create an interface that is neither too complex, too verbose, nor too magical. I've been all over the place as to where that line should be. This is my current thinking.
 
 ### Reflection
 
-If you set `edge_a.orig = vert_a`, then the `Edge.vert` setter will *automagically* set `vert_a.edge = edge_a`. This is true for any setter that might otherwise break the mesh. Sometimes, this reflection will happen when it isn't strictly necessary. Imagine you have `face_a` with three edges: `edge_a`, `edge_b` and `edge_c`. `face_a` has a pointer to `edge_a`, but it could point to any of the three edges and still be correct per the requirements of the halfedge data structure. If you directly set `edge_b.face = face_a`, everything would still be correct (`face_a.edge` would still be `edge_a` and that would still be correct), but the `Edge.edge` setter will nevertheless set `face_a.edge = edge_b`.
+If you set `edge_a.orig = vert_a`, then the `Edge.vert` setter will *automagically* set `vert_a.edge = edge_a`. This is true for any setter that might otherwise break the mesh. Sometimes, this reflection will happen when it isn't strictly necessary. Imagine you have `face_a` with three edges: `edge_a`, `edge_b` and `edge_c`. `face_a` has a pointer to `edge_a`, but it could point to any of the three edges and still be correct per the requirements of the halfedge data structure. If you directly set `edge_b.face = face_a`, everything would still be correct (`face_a.edge` would still be `edge_a` and that would still be correct), but the `Edge.edge` setter will nevertheless "reflectively" set `face_a.edge = edge_b`.
 
 ### id
 
@@ -64,50 +58,66 @@ Face(
 
 The `is_hole` `__init__` kwarg is shorthand for
 
-    class IsHole(ContagionAttribute):
-        pass
+```python
+class IsHole(ContagionAttribute):
+    pass
+
+face = Face()
+face.add_attrib(IsHole())
+```
 
-    vert = Vert()
-    vert.add_attrib(IsHole())
 
 The `face_instance.is_hole` property getter is shorthand for
 
-    vert.get_attrib(IsHole())
+```python
+vert.get_attrib(IsHole())
+```
 
 More on `Attrib` classes below and in `type_attrib.py`.
 
 ### Element Attributes
 
-By halfedge convention, each Vert instance holds a pointer to one Edge instance, each Face instance holds a pointer to one Edge instance, and each Edge instance holds four pointers (orig, pair, face, next). These describe the geometry of a mesh, but there may be other attributes you would like to assign to these instances. For example, each Face instance might have a color or each Vert instance an (x, y) coordinate. There is no objectively correct way define these attributes or to combine them when two elements are merged. If you assign position vertices to your verts, will they be xy tuples or numpy arrays? Do a red and a blue face behave like paint and combine to make a purple face? Or do they behave like DNA to make a red *or* blue face depending on which is dominant?
+By halfedge convention
 
-These cannot be stored as simple attributes (e.g., `face.color`), because it wouldn't be clear what to do when two faces were combined--by, for instance, deleting a shared edge. Somewhere, you have to define a rule for how different colored faces merge or how coordinate locations combine when merging verts. So, properties like color must be defined here as `Attrib` instances. To create an attribute, inherit from `Attrib` or one of its children defined in `type_attrib.py`. Define `merge`, `split`, and `_infer_value` methods to determine how (for instance, face color) will behave when merged or cached.
+- each Vert instance holds a pointer to one Edge instance;
+- each Face instance holds a pointer to one Edge instance; and
+- each Edge instance holds four pointers (orig, pair, face, next).
 
-You cannot assign these with `instance.attribute`. Instead assign with `vert.add_attrib(attrib_instance)`. This will add the Attrib to a `attrib` dict in Vert instance dict. Retrieve the value with `vert_instance.get_attrib(attrib_class)`. Everything will be keyed to the class name, so you will need a new ElemAttribBase descendant for each attribute type.
+These describe the geometry of a mesh, but there may be other attributes you would like to assign to these instances. For example, each Face instance might have a color. There is no objectively correct way to define a face color, nor to merge colors when two faces are merged, nor to split a color when faces are split. Do a red and a blue face behave like paint and combine to make a purple face? Or do they behave like DNA to make a red *or* blue face depending on which is dominant? This library will not guess.
 
-    class Coordinate(IncompatibleAttribute[Tuple[float, float]]):
-        pass
+For each such attribute, you will need to define `merge` and `split` methods to explicate how the attribute 1) combines when elements are merged; and 2) behaves when an element is split. Do this by creating a new descendent of `Attrib` or one of `Attrib`'s children defined in `type_attrib.py`. See the docstring in that file for more information.
 
-    vert = Vert()
-    vert.add_attrib(Coordinate((1, 2)))
-    assert vert.get_attrib(Coordinate).value == (1, 2)
+```python
+# `Vector2Attrib` is a child of `Attrib` defined in `type_attrib.py`.
+# It defines suitable (YMMV) `merge` (average) and `split` (fail) methods for
+# an (x, y) coordinate.
+class Coordinate(Vector2Attrib):
+    pass
+
+vert = Vert()
+vert.add_attrib(Coordinate((1, 2)))
+assert vert.get_attrib(Coordinate).value == (1, 2)
+```
 
-These element attributes can also be passed at `__init__`
+You cannot assign or access these attributes with `vert.attribute`. Instead assign with `vert.add_attrib(attrib_instance)`. Retrieve the value with `vert.get_attrib(attrib_class)`. Everything will be keyed to the class name, so you will need a new ElemAttribBase descendant for each attribute type.
 
-    vert = Vert(Coordinate(1, 2))
-    assert vert.get_attrib(Coordinate).value == (1, 2)
+These element attributes can also be passed at `__init__`
 
-The Attrib classes and merge and split methods that will be called when two elements are merged (e.g., merge two faces when removing the edge between them) or split (e.g., split an edge into two edges).
+```python
+vert = Vert(Coordinate(1, 2))
+assert vert.get_attrib(Coordinate).value == (1, 2)
+```
 
 ### You Should Know
 
 A canonical half-edge data structure stores:
 
-* a set of verts (redundant)
-* for each vert, a pointer to an edge
-* a set of edges
-* for each edge, pointers to vert, pair, face, next
-* a set of faces (redundant)
-* for each face, a pointer to an edge
+- a set of verts (redundant)
+- for each vert, a pointer to an edge
+- a set of edges
+- for each edge, pointers to vert, pair, face, next
+- a set of faces (redundant)
+- for each face, a pointer to an edge
 
 This implementation only stores a set of edges. Sets of verts and faces are generated by iterating through references in edge instances. This makes for slower code, but does not violate DRY and makes for dramatically cleaner code.
 

{halfedge-0.7.0 → halfedge-0.11.0}/README.md

@@ -18,11 +18,11 @@ mesh.remove_edge(edge)
 
 ## Particulars
 
-The idea (for 18 years and counting) has been to create an interface that is neither too complex, too verbose, nor too magical. I've been all over the place as to where that line should be. This is my current thinking.
+The idea (for 19 years and counting) has been to create an interface that is neither too complex, too verbose, nor too magical. I've been all over the place as to where that line should be. This is my current thinking.
 
 ### Reflection
 
-If you set `edge_a.orig = vert_a`, then the `Edge.vert` setter will *automagically* set `vert_a.edge = edge_a`. This is true for any setter that might otherwise break the mesh. Sometimes, this reflection will happen when it isn't strictly necessary. Imagine you have `face_a` with three edges: `edge_a`, `edge_b` and `edge_c`. `face_a` has a pointer to `edge_a`, but it could point to any of the three edges and still be correct per the requirements of the halfedge data structure. If you directly set `edge_b.face = face_a`, everything would still be correct (`face_a.edge` would still be `edge_a` and that would still be correct), but the `Edge.edge` setter will nevertheless set `face_a.edge = edge_b`.
+If you set `edge_a.orig = vert_a`, then the `Edge.vert` setter will *automagically* set `vert_a.edge = edge_a`. This is true for any setter that might otherwise break the mesh. Sometimes, this reflection will happen when it isn't strictly necessary. Imagine you have `face_a` with three edges: `edge_a`, `edge_b` and `edge_c`. `face_a` has a pointer to `edge_a`, but it could point to any of the three edges and still be correct per the requirements of the halfedge data structure. If you directly set `edge_b.face = face_a`, everything would still be correct (`face_a.edge` would still be `edge_a` and that would still be correct), but the `Edge.edge` setter will nevertheless "reflectively" set `face_a.edge = edge_b`.
 
 ### id
 
@@ -47,50 +47,66 @@ Face(
 
 The `is_hole` `__init__` kwarg is shorthand for
 
-    class IsHole(ContagionAttribute):
-        pass
+```python
+class IsHole(ContagionAttribute):
+    pass
+
+face = Face()
+face.add_attrib(IsHole())
+```
 
-    vert = Vert()
-    vert.add_attrib(IsHole())
 
 The `face_instance.is_hole` property getter is shorthand for
 
-    vert.get_attrib(IsHole())
+```python
+vert.get_attrib(IsHole())
+```
 
 More on `Attrib` classes below and in `type_attrib.py`.
 
 ### Element Attributes
 
-By halfedge convention, each Vert instance holds a pointer to one Edge instance, each Face instance holds a pointer to one Edge instance, and each Edge instance holds four pointers (orig, pair, face, next). These describe the geometry of a mesh, but there may be other attributes you would like to assign to these instances. For example, each Face instance might have a color or each Vert instance an (x, y) coordinate. There is no objectively correct way define these attributes or to combine them when two elements are merged. If you assign position vertices to your verts, will they be xy tuples or numpy arrays? Do a red and a blue face behave like paint and combine to make a purple face? Or do they behave like DNA to make a red *or* blue face depending on which is dominant?
+By halfedge convention
 
-These cannot be stored as simple attributes (e.g., `face.color`), because it wouldn't be clear what to do when two faces were combined--by, for instance, deleting a shared edge. Somewhere, you have to define a rule for how different colored faces merge or how coordinate locations combine when merging verts. So, properties like color must be defined here as `Attrib` instances. To create an attribute, inherit from `Attrib` or one of its children defined in `type_attrib.py`. Define `merge`, `split`, and `_infer_value` methods to determine how (for instance, face color) will behave when merged or cached.
+- each Vert instance holds a pointer to one Edge instance;
+- each Face instance holds a pointer to one Edge instance; and
+- each Edge instance holds four pointers (orig, pair, face, next).
 
-You cannot assign these with `instance.attribute`. Instead assign with `vert.add_attrib(attrib_instance)`. This will add the Attrib to a `attrib` dict in Vert instance dict. Retrieve the value with `vert_instance.get_attrib(attrib_class)`. Everything will be keyed to the class name, so you will need a new ElemAttribBase descendant for each attribute type.
+These describe the geometry of a mesh, but there may be other attributes you would like to assign to these instances. For example, each Face instance might have a color. There is no objectively correct way to define a face color, nor to merge colors when two faces are merged, nor to split a color when faces are split. Do a red and a blue face behave like paint and combine to make a purple face? Or do they behave like DNA to make a red *or* blue face depending on which is dominant? This library will not guess.
 
-    class Coordinate(IncompatibleAttribute[Tuple[float, float]]):
-        pass
+For each such attribute, you will need to define `merge` and `split` methods to explicate how the attribute 1) combines when elements are merged; and 2) behaves when an element is split. Do this by creating a new descendent of `Attrib` or one of `Attrib`'s children defined in `type_attrib.py`. See the docstring in that file for more information.
 
-    vert = Vert()
-    vert.add_attrib(Coordinate((1, 2)))
-    assert vert.get_attrib(Coordinate).value == (1, 2)
+```python
+# `Vector2Attrib` is a child of `Attrib` defined in `type_attrib.py`.
+# It defines suitable (YMMV) `merge` (average) and `split` (fail) methods for
+# an (x, y) coordinate.
+class Coordinate(Vector2Attrib):
+    pass
+
+vert = Vert()
+vert.add_attrib(Coordinate((1, 2)))
+assert vert.get_attrib(Coordinate).value == (1, 2)
+```
 
-These element attributes can also be passed at `__init__`
+You cannot assign or access these attributes with `vert.attribute`. Instead assign with `vert.add_attrib(attrib_instance)`. Retrieve the value with `vert.get_attrib(attrib_class)`. Everything will be keyed to the class name, so you will need a new ElemAttribBase descendant for each attribute type.
 
-    vert = Vert(Coordinate(1, 2))
-    assert vert.get_attrib(Coordinate).value == (1, 2)
+These element attributes can also be passed at `__init__`
 
-The Attrib classes and merge and split methods that will be called when two elements are merged (e.g., merge two faces when removing the edge between them) or split (e.g., split an edge into two edges).
+```python
+vert = Vert(Coordinate(1, 2))
+assert vert.get_attrib(Coordinate).value == (1, 2)
+```
 
 ### You Should Know
 
 A canonical half-edge data structure stores:
 
-* a set of verts (redundant)
-* for each vert, a pointer to an edge
-* a set of edges
-* for each edge, pointers to vert, pair, face, next
-* a set of faces (redundant)
-* for each face, a pointer to an edge
+- a set of verts (redundant)
+- for each vert, a pointer to an edge
+- a set of edges
+- for each edge, pointers to vert, pair, face, next
+- a set of faces (redundant)
+- for each face, a pointer to an edge
 
 This implementation only stores a set of edges. Sets of verts and faces are generated by iterating through references in edge instances. This makes for slower code, but does not violate DRY and makes for dramatically cleaner code.
 

halfedge-0.11.0/pyproject.toml

@@ -0,0 +1,92 @@
+[project]
+name = "halfedge"
+version = "0.11.0"
+description = "A typical half-edge data structure with some padding"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Shay Hill", email = "shay_public@hotmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "paragraphs>=1.0.1",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.4,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "commitizen>=4.12.1",
+    "pre-commit>=4.5.1",
+    "pytest>=9.0.2",
+    "ruff>=0.14.14",
+]
+
+
+[tool.commitizen]
+kame = "cz_conventional_commits"
+version = "0.11.0"
+tag_format = "$version"
+major-version-zero = true
+version_files = ["pyproject.toml:^version"]
+
+
+[tool.isort]
+profile = "black"
+
+
+[tool.pytest.ini_options]
+addopts = "--doctest-modules"
+pythonpath = "tests"
+log_cli = true
+testpaths = ["tests"]
+norecursedirs = ["src", ".git", ".venv", "__pycache__", "*.egg"]
+
+
+[tool.ruff.lint.pydocstyle]
+convention = "pep257"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*.py" = [
+    "S101",
+    "D",
+    "F401",
+] # Ignore assertions, docstrings, unused imports in test files
+
+[tool.ruff.format]
+docstring-code-line-length = 88
+
+[tool.ruff.lint]
+
+select = ["ALL"]
+
+ignore = [
+    "PLR",  # magic values
+    "COM",  # trailing commas
+    "ANN",  # forbid Any
+    "S",    # warnings about pickle, random, etc.
+    "N",    # names
+    "B019", # memory leak warning for lru_cache
+]
+
+
+[tool.pyright]
+include = ["src"]
+exclude = ["**/__pycache__.py"]
+
+pythonVersion = "3.11"
+pythonPlatform = "All"
+
+typeCheckingMode = "strict"
+reportCallInDefaultInitializer = true
+reportImplicitStringConcatenation = true
+# reportMissingSuperCall = true
+reportPropertyTypeMismatch = true
+reportUninitializedInstanceVariable = true
+reportUnnecessaryTypeIgnoreComment = true
+reportUnusedCallResult = true
+
+venvPath = "."
+venv = "./.venv"

{halfedge-0.7.0 → halfedge-0.11.0}/src/halfedge/__init__.py

@@ -1,4 +1,8 @@
-"""Allow modules to be imported from top-level."""
+"""Import functions into the package namespace.
+
+:author: Shay Hill
+:created: 2026-01-25
+"""
 
 from halfedge.half_edge_constructors import BlindHalfEdges
 from halfedge.half_edge_elements import Edge, Face, MeshElementBase, Vert

{halfedge-0.7.0 → halfedge-0.11.0}/src/halfedge/half_edge_constructors.py

@@ -23,20 +23,20 @@ then passing that raw data to mesh_from_vr would create a mesh with 6 faces and
 from __future__ import annotations
 
 from contextlib import suppress
-from typing import TYPE_CHECKING, Any, Iterable, Sequence, TypeVar
+from typing import TYPE_CHECKING, Any, Self, TypeVar
 
 from paragraphs import par
 
 from halfedge.half_edge_elements import Edge, Face, ManifoldMeshError, Vert
 
 if TYPE_CHECKING:
+    from collections.abc import Iterable, Sequence
+
     from halfedge.type_attrib import Attrib, StaticAttrib
 
 
 _T = TypeVar("_T")
 
-_TBlindHalfEdges = TypeVar("_TBlindHalfEdges", bound="BlindHalfEdges")
-
 
 class BlindHalfEdges:
     """Half-edge structure with no lookups."""
@@ -189,11 +189,11 @@ class BlindHalfEdges:
 
     @classmethod
     def from_vlfi(
-        cls: type[_TBlindHalfEdges],
+        cls,
         vl: Sequence[Vert],
         fi: Iterable[tuple[int, ...]],
         hi: Iterable[tuple[int, ...]] | None = None,
-    ) -> _TBlindHalfEdges:
+    ) -> Self:
         """Create a set of half edges from a vertex list and face index.
 
         :param vl: (vertex list) a seq of vertices

{halfedge-0.7.0 → halfedge-0.11.0}/src/halfedge/half_edge_elements.py

@@ -38,14 +38,15 @@ from __future__ import annotations
 
 from contextlib import suppress
 from itertools import count
-from typing import TYPE_CHECKING, Any, Callable, TypeVar
+from typing import TYPE_CHECKING, Any, Self, TypeVar
 
 from halfedge.type_attrib import Attrib, ContagionAttrib
 
 if TYPE_CHECKING:
+    from collections.abc import Callable
+
     from halfedge.half_edge_constructors import BlindHalfEdges
 
-_TMeshElem = TypeVar("_TMeshElem", bound="MeshElementBase")
 
 _T = TypeVar("_T")
 
@@ -141,7 +142,7 @@ class MeshElementBase:
         except AttributeError:
             return None
 
-    def merge_from(self: _TMeshElem, *elements: _TMeshElem) -> _TMeshElem:
+    def merge_from(self, *elements: Self) -> Self:
         """Fill in missing references from other elements.
 
         :param elements: elements to merge from
@@ -165,7 +166,7 @@ class MeshElementBase:
                 self.set_attrib(merged_attrib)
         return self
 
-    def split_from(self: _TMeshElem, element: _TMeshElem) -> _TMeshElem:
+    def split_from(self, element: Self) -> Self:
         """Pass attributes when dividing or altering elements.
 
         :param element: element to split from
@@ -182,7 +183,7 @@ class MeshElementBase:
                 self.set_attrib(splitted)
         return self
 
-    def __lt__(self: _TMeshElem, other: _TMeshElem) -> bool:
+    def __lt__(self, other: Self) -> bool:
         """Sort by sn.
 
         You'll want to be able to sort Verts at least to make a vlvi (vertex list,

{halfedge-0.7.0 → halfedge-0.11.0}/src/halfedge/half_edge_object.py

@@ -79,6 +79,13 @@ class HalfEdges(StaticHalfEdges):
         Able to infer from:
             * both verts on same face: that face
             * empty mesh: a new Hole
+
+        This is only called when inserting an edge into an existing face (or empty
+        mesh), so the orig and dest should always be connected to only one face (or
+        nothing, which is handled in this method).
+
+        Once the face is split, the two verts will form an edge that connects to two
+        faces.
         """
         if not self.edges:
             return self.new_hole()

halfedge-0.11.0/src/halfedge/py.typed

@@ -0,0 +1,5 @@
+""" This file is used to indicate to mypy that the package is typed.
+
+Do not delete this comment, because empty files choke
+some cloud drives on sync.
+"""