knit-graphs 0.0.9__py3-none-any.whl → 0.0.11__py3-none-any.whl

docs/source/conf.py

@@ -1,11 +1,11 @@
 """
-    Configuration file for the Sphinx documentation builder.
-    =============================================================================
-    SPHINX DOCUMENTATION CONFIGURATION
-    =============================================================================
-    This file configures how Sphinx generates documentation from your Python code.
-    For the full list of built-in configuration values, see:
-    https://www.sphinx-doc.org/en/master/usage/configuration.html
+Configuration file for the Sphinx documentation builder.
+=============================================================================
+SPHINX DOCUMENTATION CONFIGURATION
+=============================================================================
+This file configures how Sphinx generates documentation from your Python code.
+For the full list of built-in configuration values, see:
+https://www.sphinx-doc.org/en/master/usage/configuration.html
 """
 
 import os
@@ -19,17 +19,17 @@ from importlib.metadata import PackageNotFoundError, version
 # Add the project root and source directory to Python path so Sphinx can import your modules
 
 # Path to your source code (adjust if not using src/ layout)
-sys.path.insert(0, os.path.abspath('..'))  # Project root
-sys.path.insert(0, os.path.abspath('../src'))  # Source directory
-sys.path.insert(0, os.path.abspath('.'))  # Docs directory
+sys.path.insert(0, os.path.abspath(".."))  # Project root
+sys.path.insert(0, os.path.abspath("../src"))  # Source directory
+sys.path.insert(0, os.path.abspath("."))  # Docs directory
 
 # =============================================================================
 # PROJECT INFORMATION
 # =============================================================================
 
-project = 'knit-graphs'
-copyright = f'{datetime.now().year}, Megan Hofmann'
-author = 'Megan Hofmann'
+project = "knit-graphs"
+copyright = f"{datetime.now().year}, Megan Hofmann"
+author = "Megan Hofmann"
 
 try:
     # Get version from installed package metadata
@@ -49,19 +49,17 @@ release = version
 # Extensions to enable (these add functionality to Sphinx)
 extensions = [
     # Core Sphinx extensions
-    'sphinx.ext.autodoc',  # Generate docs from docstrings
-    'sphinx.ext.autosummary',  # Generate summary tables automatically
-    'sphinx.ext.viewcode',  # Add [source] links to documentation
-    'sphinx.ext.napoleon',  # Support Google/NumPy docstring styles
-    'sphinx.ext.intersphinx',  # Link to other project docs (e.g., Python docs)
-    'sphinx.ext.githubpages',  # Publish to GitHub Pages (.nojekyll file)
-    'sphinx.ext.todo',  # Support TODO items in docs
-    'sphinx.ext.coverage',  # Check documentation coverage
-    'sphinx.ext.doctest',  # Test code snippets in documentation
-
+    "sphinx.ext.autodoc",  # Generate docs from docstrings
+    "sphinx.ext.autosummary",  # Generate summary tables automatically
+    "sphinx.ext.viewcode",  # Add [source] links to documentation
+    "sphinx.ext.napoleon",  # Support Google/NumPy docstring styles
+    "sphinx.ext.intersphinx",  # Link to other project docs (e.g., Python docs)
+    "sphinx.ext.githubpages",  # Publish to GitHub Pages (.nojekyll file)
+    "sphinx.ext.todo",  # Support TODO items in docs
+    "sphinx.ext.coverage",  # Check documentation coverage
+    "sphinx.ext.doctest",  # Test code snippets in documentation
     # Third-party extensions (these need to be installed)
-    'sphinx_autodoc_typehints',  # Better type hint rendering
-    'myst_parser',  # Support for Markdown files (optional)
+    "myst_parser",  # Support for Markdown files (optional)
 ]
 
 # =============================================================================
@@ -70,19 +68,19 @@ extensions = [
 
 # File extensions that Sphinx will process
 source_suffix = {
-    '.rst': None,  # RestructuredText (default)
-    '.md': 'myst_parser',  # Markdown (requires myst_parser extension)
+    ".rst": None,  # RestructuredText (default)
+    ".md": "myst_parser",  # Markdown (requires myst_parser extension)
 }
 
 # The master toctree document (main page)
-master_doc = 'index'
+master_doc = "index"
 
 # Files and directories to exclude from processing
 exclude_patterns = [
-    '_build',  # Build output directory
-    'Thumbs.db',  # Windows thumbnail cache
-    '.DS_Store',  # macOS metadata
-    '**.ipynb_checkpoints',  # Jupyter notebook checkpoints
+    "_build",  # Build output directory
+    "Thumbs.db",  # Windows thumbnail cache
+    ".DS_Store",  # macOS metadata
+    "**.ipynb_checkpoints",  # Jupyter notebook checkpoints
 ]
 
 # =============================================================================
@@ -90,31 +88,29 @@ exclude_patterns = [
 # =============================================================================
 
 # The theme to use for HTML pages
-html_theme = 'sphinx_rtd_theme'  # Read the Docs theme (clean, professional)
+html_theme = "sphinx_rtd_theme"  # Read the Docs theme (clean, professional)
 
 # Directories containing static files (CSS, JS, images)
-html_static_path = ['_static']
+html_static_path = ["_static"]
 
 
 # Theme-specific options
 html_theme_options = {
-    'logo_only': False,  # Show project name with logo
-    'display_version': True,  # Show version in sidebar
-    'prev_next_buttons_location': 'bottom',  # Navigation button placement
-    'style_external_links': True,  # Style external links differently
-    'vcs_pageview_mode': '',  # Version control integration
-    'style_nav_header_background': '#2980B9',  # Header background color
-
+    "logo_only": False,  # Show project name with logo
+    "prev_next_buttons_location": "bottom",  # Navigation button placement
+    "style_external_links": True,  # Style external links differently
+    "vcs_pageview_mode": "",  # Version control integration
+    "style_nav_header_background": "#2980B9",  # Header background color
     # Table of contents options
-    'collapse_navigation': True,  # Collapse subsections in nav
-    'sticky_navigation': True,  # Keep navigation visible on scroll
-    'navigation_depth': 4,  # Maximum navigation depth
-    'includehidden': True,  # Include hidden toctrees
-    'titles_only': False,  # Show subsection titles in nav
+    "collapse_navigation": True,  # Collapse subsections in nav
+    "sticky_navigation": True,  # Keep navigation visible on scroll
+    "navigation_depth": 4,  # Maximum navigation depth
+    "includehidden": True,  # Include hidden toctrees
+    "titles_only": False,  # Show subsection titles in nav
 }
 
 # Additional HTML options
-html_title = f'{project} Documentation'  # Browser window title
+html_title = f"{project} Documentation"  # Browser window title
 html_short_title = project  # Short title for navigation
 
 
@@ -136,20 +132,20 @@ html_short_title = project  # Short title for navigation
 
 # Default options for all autodoc directives
 autodoc_default_options = {
-    'members': True,  # Include all members
-    'member-order': 'bysource',  # Order members as they appear in source
-    'special-members': '__init__',  # Include __init__ methods
-    'undoc-members': True,  # Include members without docstrings
-    'exclude-members': '__weakref__',  # Exclude certain members
-    'show-inheritance': True,  # Show class inheritance
-    'inherited-members': True,  # Include inherited methods
+    "members": True,  # Include all members
+    "member-order": "bysource",  # Order members as they appear in source
+    "special-members": "__init__",  # Include __init__ methods
+    "undoc-members": True,  # Include members without docstrings
+    "exclude-members": "__weakref__",  # Exclude certain members
+    "show-inheritance": True,  # Show class inheritance
+    "inherited-members": True,  # Include inherited methods
 }
 
 # How to display class signatures
 autodoc_class_signature = "mixed"  # Show __init__ parameters with class
 
 # Order of members in documentation
-autodoc_member_order = 'bysource'  # bysource, alphabetical, or groupwise
+autodoc_member_order = "bysource"  # bysource, alphabetical, or groupwise
 
 # Mock imports for modules that might not be available during doc building
 # Add any modules that cause import errors during doc building
@@ -159,6 +155,10 @@ autodoc_mock_imports = [
     # 'some_optional_dependency',
 ]
 
+# Enable type hints in signatures
+autodoc_typehints = "signature"  # Show type hints in function signatures
+autodoc_typehints_description_target = "documented"  # Where to show type info
+
 # =============================================================================
 # AUTOSUMMARY CONFIGURATION
 # =============================================================================
@@ -193,13 +193,13 @@ napoleon_attr_annotations = True  # Include attribute annotations
 # Links to external documentation
 
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/3', None),
-    'numpy': ('https://numpy.org/doc/stable/', None),
-    'pandas': ('https://pandas.pydata.org/pandas-docs/stable/', None),
-    'matplotlib': ('https://matplotlib.org/stable/', None),
-    'scipy': ('https://docs.scipy.org/doc/scipy/', None),
-    'sklearn': ('https://scikit-learn.org/stable/', None),
-    'typing': ('https://typing.readthedocs.io/en/latest/', None),
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
+    "matplotlib": ("https://matplotlib.org/stable/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
+    "sklearn": ("https://scikit-learn.org/stable/", None),
+    "typing": ("https://typing.readthedocs.io/en/latest/", None),
 }
 
 # =============================================================================
@@ -207,10 +207,8 @@ intersphinx_mapping = {
 # =============================================================================
 # Controls how type hints are displayed in documentation
 
-typehints_fully_qualified = False  # Use short names for types
+# Note: These settings work with sphinx.ext.autodoc built-in type hint support
 always_document_param_types = True  # Always show parameter types
-typehints_document_rtype = True  # Document return types
-typehints_use_rtype = True  # Use :rtype: directive for return types
 
 # =============================================================================
 # TODO EXTENSION CONFIGURATION
@@ -245,16 +243,17 @@ add_module_names = False  # Don't prepend module names to functions
 show_authors = False  # Don't show author info by default
 
 # Syntax highlighting style
-pygments_style = 'sphinx'  # Code highlighting theme
+pygments_style = "sphinx"  # Code highlighting theme
 
 # Language for content that doesn't specify a language
-language = 'en'
+language = "en"
 
 
 # =============================================================================
 # CUSTOM FUNCTIONS AND SETUP
 # =============================================================================
 
+
 def autodoc_skip_member(app, what, name, obj, skip, options):
     """
     Custom function to control which members are included in documentation.
@@ -288,15 +287,16 @@ def setup(app):
         app: The Sphinx application instance
     """
     # Connect custom functions to Sphinx events
-    app.connect('autodoc-skip-member', autodoc_skip_member)
+    app.connect("autodoc-skip-member", autodoc_skip_member)
 
     # Return extension metadata
     return {
-        'version': version,
-        'parallel_read_safe': True,
-        'parallel_write_safe': True,
+        "version": version,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
     }
 
+
 # =============================================================================
 # CHECKLIST FOR SPHINX SETUP
 # =============================================================================

docs/source/index.rst

@@ -3,10 +3,6 @@ knit-graphs
 
 A graph representation of knitted structures where each loop is a node and edges represent yarn and stitch relationships.
 
-.. image:: https://img.shields.io/github/workflow/status/mhofmann-Khoury/knit-graphs/CI
-   :target: https://github.com/mhofmann-Khoury/knit-graphs/actions
-   :alt: Build Status
-
 .. image:: https://img.shields.io/pypi/v/knit-graphs
    :target: https://pypi.org/project/knit-graphs/
    :alt: PyPI Version

knit_graphs/Course.py

@@ -2,9 +2,11 @@
 
 This module contains the Course class which represents a horizontal row of loops in a knitting pattern.
 """
+
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Iterator, cast
+from collections.abc import Iterator
+from typing import TYPE_CHECKING, cast
 
 from knit_graphs.Loop import Loop
 

knit_graphs/Knit_Graph.py

@@ -3,9 +3,11 @@
 This module contains the main Knit_Graph class which serves as the central data structure for representing knitted fabrics.
 It manages the relationships between loops, yarns, and structural elements like courses and wales.
 """
+
 from __future__ import annotations
 
-from typing import Any, Iterator, cast
+from collections.abc import Iterator
+from typing import Any, cast
 
 from networkx import DiGraph
 
@@ -18,9 +20,6 @@ from knit_graphs.Loop import Loop
 from knit_graphs.Pull_Direction import Pull_Direction
 from knit_graphs.Yarn import Yarn
 
-# from knit_graphs.artin_wale_braids.Wale import Wale
-# from knit_graphs.artin_wale_braids.Wale_Group import Wale_Group
-
 
 class Knit_Graph:
     """A representation of knitted structures as connections between loops on yarns.
@@ -77,6 +76,42 @@ class Knit_Graph:
         if self._last_loop is None or loop > self._last_loop:
             self._last_loop = loop
 
+    def remove_loop(self, loop: Loop) -> None:
+        """
+        Remove the given loop from the knit graph.
+        Args:
+            loop (Loop): The loop to be removed.
+
+        Raises:
+            KeyError: If the loop is not in the knit graph.
+
+        """
+        if loop not in self:
+            raise KeyError(f"Loop {loop} not on the knit graph")
+        self.braid_graph.remove_loop(loop)  # remove any crossing associated with this loop.
+        # Remove any stitch edges involving this loop.
+        loop.remove_parent_loops()
+        if self.has_child_loop(loop):
+            child_loop = self.get_child_loop(loop)
+            assert isinstance(child_loop, Loop)
+            child_loop.remove_parent(loop)
+        self.stitch_graph.remove_node(loop)
+        # Remove loop from any floating positions
+        loop.remove_loop_from_front_floats()
+        loop.remove_loop_from_back_floats()
+        # Remove loop from yarn
+        yarn = loop.yarn
+        yarn.remove_loop(loop)
+        if len(yarn) == 0:  # This was the only loop on that yarn
+            self.yarns.discard(yarn)
+        # Reset last loop
+        if loop is self.last_loop:
+            if len(self.yarns) == 0:  # No loops left
+                assert len(self.stitch_graph.nodes) == 0
+                self._last_loop = None
+            else:  # Set to the newest loop formed at the end of any yarns.
+                self._last_loop = max(y.last_loop for y in self.yarns if isinstance(y.last_loop, Loop))
+
     def add_yarn(self, yarn: Yarn) -> None:
         """Add a yarn to the graph without adding its loops.
 
@@ -85,9 +120,13 @@ class Knit_Graph:
         """
         self.yarns.add(yarn)
 
-    def connect_loops(self, parent_loop: Loop, child_loop: Loop,
-                      pull_direction: Pull_Direction = Pull_Direction.BtF,
-                      stack_position: int | None = None) -> None:
+    def connect_loops(
+        self,
+        parent_loop: Loop,
+        child_loop: Loop,
+        pull_direction: Pull_Direction = Pull_Direction.BtF,
+        stack_position: int | None = None,
+    ) -> None:
         """Create a stitch edge by connecting a parent and child loop.
 
         Args:
@@ -106,44 +145,31 @@ class Knit_Graph:
         self.stitch_graph.add_edge(parent_loop, child_loop, pull_direction=pull_direction)
         child_loop.add_parent_loop(parent_loop, stack_position)
 
-    def get_wale_starting_with_loop(self, first_loop: Loop) -> Wale:
-        """Get a wale (vertical column of stitches) starting from the specified loop.
+    def get_wales_ending_with_loop(self, last_loop: Loop) -> set[Wale]:
+        """Get all wales (vertical columns of stitches) that end at the specified loop.
 
         Args:
-            first_loop (Loop): The loop at the start of the wale to be constructed.
+            last_loop (Loop): The last loop of the joined set of wales.
 
         Returns:
-            Wale: A wale object representing the vertical column of stitches starting from the given loop.
+            set[Wale]: The set of wales that end at this loop.
         """
-        wale = Wale(first_loop)
-        cur_loop = first_loop
-        while len(self.stitch_graph.successors(cur_loop)) == 1:
-            cur_loop = [*self.stitch_graph.successors(cur_loop)][0]
-            assert isinstance(wale.last_loop, Loop)
-            wale.add_loop_to_end(cur_loop, self.get_pull_direction(wale.last_loop, cur_loop))
-        return wale
-
-    def get_wales_ending_with_loop(self, last_loop: Loop) -> list[Wale]:
-        """Get all wales (vertical columns of stitches) that end at the specified loop.
+        if len(last_loop.parent_loops) == 0:
+            return {Wale(last_loop, self)}
+        ancestors = last_loop.ancestor_loops()
+        return {Wale(ancestor_loop, self) for ancestor_loop in ancestors}
 
-        Args:
-            last_loop (Loop): The last loop of the joined set of wales.
+    def get_terminal_wales(self) -> dict[Loop, list[Wale]]:
+        """
+        Get wale groups organized by their terminal loops.
 
         Returns:
-            list[Wale]: The set of wales that end at this loop. Only returns multiple wales if this loop is a child of a decrease stitch.
+            dict[Loop, list[Wale]]: Dictionary mapping terminal loops to list of wales that terminate that wale.
         """
-        wales = []
-        if len(last_loop.parent_loops) == 0:
-            return [Wale(last_loop)]
-        for top_stitch_parent in last_loop.parent_loops:
-            wale = Wale(last_loop)
-            wale.add_loop_to_beginning(top_stitch_parent, cast(Pull_Direction, self.get_pull_direction(top_stitch_parent, last_loop)))
-            cur_loop = top_stitch_parent
-            while len(cur_loop.parent_loops) == 1:  # stop at split for decrease or start of wale
-                cur_loop = cur_loop.parent_loops[0]
-                wale.add_loop_to_beginning(cur_loop, cast(Pull_Direction, self.get_pull_direction(cur_loop, cast(Loop, wale.first_loop))))
-            wales.append(wale)
-        return wales
+        wale_groups = {}
+        for loop in self.terminal_loops():
+            wale_groups[loop] = list(self.get_wales_ending_with_loop(loop))
+        return wale_groups
 
     def get_courses(self) -> list[Course]:
         """Get all courses (horizontal rows) in the knit graph in chronological order.
@@ -164,17 +190,13 @@ class Knit_Graph:
         courses.append(course)
         return courses
 
-    def get_wale_groups(self) -> dict[Loop, Wale_Group]:
+    def get_wale_groups(self) -> set[Wale_Group]:
         """Get wale groups organized by their terminal loops.
 
         Returns:
-            dict[Loop, Wale_Group]: Dictionary mapping terminal loops to the wale groups they terminate. Each wale group represents a collection of wales that end at the same terminal loop.
+            set[Wale_Group]: The set of wale-groups that lead to the terminal loops of this graph. Each wale group represents a collection of wales that end at the same terminal loop.
         """
-        wale_groups = {}
-        for loop in self:
-            if self.is_terminal_loop(loop):
-                wale_groups.update({loop: Wale_Group(wale, self) for wale in self.get_wales_ending_with_loop(loop)})
-        return wale_groups
+        return {Wale_Group(terminal_loop, self) for terminal_loop in self.terminal_loops()}
 
     def __contains__(self, item: Loop | tuple[Loop, Loop]) -> bool:
         """Check if a loop is contained in the knit graph.
@@ -197,12 +219,18 @@ class Knit_Graph:
         """
         return cast(Iterator[Loop], iter(self.stitch_graph.nodes))
 
+    def __getitem__(self, item: int) -> Loop:
+        loop = next((loop for loop in self if loop.loop_id == item), None)
+        if loop is None:
+            raise KeyError(f"Loop of id {item} not in knit graph")
+        return loop
+
     def sorted_loops(self) -> list[Loop]:
         """
         Returns:
             list[Loop]: The list of loops in the stitch graph sorted from the earliest formed loop to the latest formed loop.
         """
-        return sorted(list(self.stitch_graph.nodes))
+        return sorted(self.stitch_graph.nodes)
 
     def get_pull_direction(self, parent: Loop, child: Loop) -> Pull_Direction | None:
         """Get the pull direction of the stitch edge between parent and child loops.
@@ -218,7 +246,7 @@ class Knit_Graph:
         if edge is None:
             return None
         else:
-            return cast(Pull_Direction, edge['pull_direction'])
+            return cast(Pull_Direction, edge["pull_direction"])
 
     def get_stitch_edge(self, parent: Loop, child: Loop) -> dict[str, Any] | None:
         """Get the stitch edge data between two loops.
@@ -270,3 +298,10 @@ class Knit_Graph:
             bool: True if the loop has no child loops and terminates a wale, False otherwise.
         """
         return not self.has_child_loop(loop)
+
+    def terminal_loops(self) -> Iterator[Loop]:
+        """
+        Returns:
+            Iterator[Loop]: An iterator over all terminal loops in the knit graph.
+        """
+        return iter(loop for loop in self if self.is_terminal_loop(loop))