knit-graphs 0.0.10__py3-none-any.whl → 0.0.12__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,35 +2,48 @@
 
 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, Sequence
+from typing import TYPE_CHECKING, Generic, TypeVar, overload
 
 from knit_graphs.Loop import Loop
 
 if TYPE_CHECKING:
     from knit_graphs.Knit_Graph import Knit_Graph
 
+LoopT = TypeVar("LoopT", bound=Loop)
+
 
-class Course:
+class Course(Sequence[LoopT], Generic[LoopT]):
     """Course object for organizing loops into knitting rows.
 
     A Course represents a horizontal row of loops in a knitting pattern.
     It maintains an ordered list of loops and provides methods for analyzing the structure and relationships between courses in the knitted fabric.
     """
 
-    def __init__(self, knit_graph: Knit_Graph) -> None:
+    def __init__(self, course_number: int, knit_graph: Knit_Graph[LoopT]) -> None:
         """Initialize an empty course associated with a knit graph.
 
         Args:
             knit_graph (Knit_Graph): The knit graph that this course belongs to.
         """
-        self._knit_graph: Knit_Graph = knit_graph
-        self._loops_in_order: list[Loop] = []
-        self._loop_set: set[Loop] = set()
+        self._course_number: int = course_number
+        self._knit_graph: Knit_Graph[LoopT] = knit_graph
+        self._loops_in_order: list[LoopT] = []
+        self._loop_set: set[LoopT] = set()
+
+    @property
+    def course_number(self) -> int:
+        """
+        Returns:
+            int: The course number of the course.
+        """
+        return self._course_number
 
     @property
-    def loops_in_order(self) -> list[Loop]:
+    def loops_in_order(self) -> list[LoopT]:
         """
         Returns:
             list[Loop]: The list of loops in this course.
@@ -38,22 +51,34 @@ class Course:
         return self._loops_in_order
 
     @property
-    def knit_graph(self) -> Knit_Graph:
+    def loop_ids_in_course(self) -> list[int]:
+        """
+        Returns:
+            list[int]: The loop ids in the course in the order the occur in the course.
+        """
+        return [l.loop_id for l in self.loops_in_order]
+
+    @property
+    def knit_graph(self) -> Knit_Graph[LoopT]:
         """
         Returns:
             Knit_Graph: The knit graph that this course belongs to.
         """
         return self._knit_graph
 
-    def add_loop(self, loop: Loop, index: int | None = None) -> None:
+    def add_loop(self, loop: LoopT, index: int | None = None) -> None:
         """Add a loop to the course at the specified index or at the end.
 
         Args:
             loop (Loop): The loop to add to this course.
             index (int | None, optional): The index position to insert the loop at. If None, appends to the end.
+
+        Raises:
+            ValueError: If the loop is a parent to any loops already in the course.
         """
         for parent_loop in loop.parent_loops:
-            assert parent_loop not in self, f"{loop} has parent {parent_loop}, cannot be added to same course"
+            if parent_loop in self:
+                raise ValueError(f"{loop} has parent {parent_loop}, cannot be added to same course")
         self._loop_set.add(loop)
         if index is None:
             self.loops_in_order.append(loop)
@@ -66,7 +91,7 @@ class Course:
         Returns:
             bool: True if the course has at least one yarn over (loop with no parent loops) to start new wales.
         """
-        return any(not loop.has_parent_loops() for loop in self)
+        return any(not loop.has_parent_loops for loop in self)
 
     def has_decrease(self) -> bool:
         """Check if this course contains any decrease stitches that merge wales.
@@ -76,18 +101,7 @@ class Course:
         """
         return any(len(loop.parent_loops) > 1 for loop in self)
 
-    def __getitem__(self, index: int | slice) -> Loop | list[Loop]:
-        """Get loop(s) at the specified index or slice.
-
-        Args:
-            index (int | slice): The index or slice to retrieve from the course.
-
-        Returns:
-            Loop | list[Loop]: The loop at the specified index, or list of loops for a slice.
-        """
-        return self.loops_in_order[index]
-
-    def in_round_with(self, next_course: Course) -> bool:
+    def in_round_with(self, next_course: Course[LoopT]) -> bool:
         """Check if the next course connects to this course in a circular pattern.
 
         This method determines if the courses are connected in the round (circular knitting) by checking if the next course starts at the beginning of this course.
@@ -98,14 +112,14 @@ class Course:
         Returns:
             bool: True if the next course starts at the beginning of this course, indicating circular knitting.
         """
-        next_start: Loop = cast(Loop, next_course[0])
+        next_start = next_course[0]
         i = 1
-        while not next_start.has_parent_loops():
-            next_start = cast(Loop, next_course[i])
+        while not next_start.has_parent_loops:
+            next_start = next_course[i]
             i += 1
         return self[0] in next_start.parent_loops
 
-    def in_row_with(self, next_course: Course) -> bool:
+    def in_row_with(self, next_course: Course[LoopT]) -> bool:
         """Check if the next course connects to this course in a flat/row pattern.
 
         This method determines if the courses are connected in flat knitting (back and forth) by checking if the next course starts at the end of this course.
@@ -116,39 +130,48 @@ class Course:
         Returns:
             bool: True if the next course starts at the end of this course, indicating flat/row knitting.
         """
-        next_start: Loop = cast(Loop, next_course[0])
+        next_start: LoopT = next_course[0]
         i = 1
-        while not next_start.has_parent_loops():
-            next_start = cast(Loop, next_course[i])
+        while not next_start.has_parent_loops:
+            next_start = next_course[i]
             i += 1
         return self[-1] in next_start.parent_loops
 
-    def __contains__(self, loop: Loop) -> bool:
+    def __contains__(self, loop: object) -> bool:
         """Check if a loop is contained in this course.
 
         Args:
-            loop (Loop): The loop to check for membership in this course.
+            loop (LoopT): The loop to check for membership in this course.
 
         Returns:
             bool: True if the loop is in this course, False otherwise.
         """
         return loop in self._loop_set
 
-    def __iter__(self) -> Iterator[Loop]:
-        """Iterate over loops in this course in order.
+    @overload
+    def __getitem__(self, index: int) -> LoopT: ...
+
+    @overload
+    def __getitem__(self, index: slice) -> list[LoopT]: ...
+
+    def __getitem__(self, index: int | slice) -> LoopT | list[LoopT]:
+        """Get loop(s) at the specified index or slice.
+
+        Args:
+            index (int | slice): The index or slice to retrieve from the course.
 
         Returns:
-            Iterator[Loop]: An iterator over the loops in this course in their natural order.
+            Loop | list[Loop]: The loop at the specified index, or list of loops for a slice.
         """
-        return iter(self.loops_in_order)
+        return self.loops_in_order[index]
 
-    def __reversed__(self) -> Iterator[Loop]:
-        """Iterate over loops in this course in reverse order.
+    def __iter__(self) -> Iterator[LoopT]:
+        """Iterate over loops in this course in order.
 
         Returns:
-            Iterator[Loop]: An iterator over the loops in this course in reverse order.
+            Iterator[Loop]: An iterator over the loops in this course in their natural order.
         """
-        return reversed(self.loops_in_order)
+        return iter(self.loops_in_order)
 
     def __len__(self) -> int:
         """Get the number of loops in this course.
@@ -164,7 +187,7 @@ class Course:
         Returns:
             str: String representation showing the ordered list of loops.
         """
-        return str(self.loops_in_order)
+        return f"Course {self.course_number}: {self.loops_in_order}"
 
     def __repr__(self) -> str:
         """Get string representation of this course for debugging.