oscura 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

oscura/{extensibility → core/extensibility}/docs.py

@@ -5,7 +5,7 @@ including API reference, usage examples, and metadata extraction from docstrings
 
 
 Example:
-    >>> from oscura.extensibility.docs import generate_extension_docs
+    >>> from oscura.core.extensibility.docs import generate_extension_docs
     >>> from pathlib import Path
     >>>
     >>> # Generate documentation for an extension
@@ -561,39 +561,65 @@ def _process_section(
         include_examples: Extract examples
     """
     if section in ["args", "arguments", "parameters"]:
-        # Parse parameters
-        for line in content:
-            line = line.strip()
-            if ":" in line:
-                parts = line.split(":", 1)
-                param_name = parts[0].strip()
-                param_desc = parts[1].strip()
-                func_doc.parameters.append((param_name, param_desc))
-
+        _process_parameters_section(func_doc, content)
     elif section in ["returns", "return"]:
-        func_doc.returns = "\n".join(content).strip()
-
+        _process_returns_section(func_doc, content)
     elif section in ["example", "examples"] and include_examples:
-        # Extract code blocks
-        in_code = False
-        code_lines = []
-
-        for line in content:
-            if ">>>" in line or "..." in line:
-                in_code = True
-                code_lines.append(line.strip())
-            elif in_code:
-                if line.strip() and not line.strip().startswith("#"):
-                    if not (">>>" in line or "..." in line):
-                        in_code = False
-                        if code_lines:
-                            func_doc.examples.append("\n".join(code_lines))
-                            code_lines = []
-                    else:
-                        code_lines.append(line.strip())
-
-        if code_lines:
-            func_doc.examples.append("\n".join(code_lines))
+        _process_examples_section(func_doc, content)
+
+
+def _process_parameters_section(func_doc: FunctionDoc, content: list[str]) -> None:
+    """Process parameters section.
+
+    Args:
+        func_doc: FunctionDoc to populate.
+        content: Section content lines.
+    """
+    for line in content:
+        line = line.strip()
+        if ":" in line:
+            parts = line.split(":", 1)
+            param_name = parts[0].strip()
+            param_desc = parts[1].strip()
+            func_doc.parameters.append((param_name, param_desc))
+
+
+def _process_returns_section(func_doc: FunctionDoc, content: list[str]) -> None:
+    """Process returns section.
+
+    Args:
+        func_doc: FunctionDoc to populate.
+        content: Section content lines.
+    """
+    func_doc.returns = "\n".join(content).strip()
+
+
+def _process_examples_section(func_doc: FunctionDoc, content: list[str]) -> None:
+    """Process examples section.
+
+    Args:
+        func_doc: FunctionDoc to populate.
+        content: Section content lines.
+    """
+    in_code = False
+    code_lines = []
+
+    for line in content:
+        if ">>>" in line or "..." in line:
+            in_code = True
+            code_lines.append(line.strip())
+        elif in_code:
+            if line.strip() and not line.strip().startswith("#"):
+                if not (">>>" in line or "..." in line):
+                    in_code = False
+                    if code_lines:
+                        func_doc.examples.append("\n".join(code_lines))
+                        code_lines = []
+                else:
+                    code_lines.append(line.strip())
+
+    if code_lines:
+        func_doc.examples.append("\n".join(code_lines))
 
 
 def _get_name_from_ast(node: ast.expr) -> str:
@@ -622,13 +648,30 @@ def _generate_markdown(docs: ExtensionDocs) -> str:
     Returns:
         Markdown string
     """
-    lines = []
+    lines: list[str] = []
+
+    # Title and metadata
+    _add_markdown_header(lines, docs)
 
-    # Title
+    # Dependencies
+    _add_markdown_dependencies(lines, docs)
+
+    # Modules
+    _add_markdown_modules(lines, docs)
+
+    return "\n".join(lines)
+
+
+def _add_markdown_header(lines: list[str], docs: ExtensionDocs) -> None:
+    """Add header section to markdown.
+
+    Args:
+        lines: List to append lines to.
+        docs: ExtensionDocs to render.
+    """
     lines.append(f"# {docs.name}")
     lines.append("")
 
-    # Metadata
     if docs.version:
         lines.append(f"**Version:** {docs.version}")
         lines.append("")
@@ -639,7 +682,14 @@ def _generate_markdown(docs: ExtensionDocs) -> str:
         lines.append(docs.description)
         lines.append("")
 
-    # Dependencies
+
+def _add_markdown_dependencies(lines: list[str], docs: ExtensionDocs) -> None:
+    """Add dependencies section to markdown.
+
+    Args:
+        lines: List to append lines to.
+        docs: ExtensionDocs to render.
+    """
     if "dependencies" in docs.metadata:
         lines.append("## Dependencies")
         lines.append("")
@@ -647,7 +697,14 @@ def _generate_markdown(docs: ExtensionDocs) -> str:
             lines.append(f"- {dep}")
         lines.append("")
 
-    # Modules
+
+def _add_markdown_modules(lines: list[str], docs: ExtensionDocs) -> None:
+    """Add modules section to markdown.
+
+    Args:
+        lines: List to append lines to.
+        docs: ExtensionDocs to render.
+    """
     for module in docs.modules:
         lines.append(f"## Module: {module.name}")
         lines.append("")
@@ -656,43 +713,74 @@ def _generate_markdown(docs: ExtensionDocs) -> str:
             lines.append("")
 
         # Classes
-        for cls in module.classes:
-            lines.append(f"### Class: {cls.name}")
-            lines.append("")
-            if cls.docstring:
-                lines.append(cls.docstring)
-                lines.append("")
-
-            # Methods
-            if cls.methods:
-                lines.append("#### Methods")
-                lines.append("")
-                for method in cls.methods:
-                    lines.append(f"##### {method.name}")
-                    lines.append("")
-                    if method.signature:
-                        lines.append("```python")
-                        lines.append(method.signature)
-                        lines.append("```")
-                        lines.append("")
-                    if method.docstring:
-                        lines.append(method.docstring)
-                        lines.append("")
+        _add_markdown_classes(lines, module)
 
         # Functions
-        for func in module.functions:
-            lines.append(f"### Function: {func.name}")
+        _add_markdown_functions(lines, module)
+
+
+def _add_markdown_classes(lines: list[str], module: ModuleDoc) -> None:
+    """Add classes section to markdown.
+
+    Args:
+        lines: List to append lines to.
+        module: ModuleDoc to render.
+    """
+    for cls in module.classes:
+        lines.append(f"### Class: {cls.name}")
+        lines.append("")
+        if cls.docstring:
+            lines.append(cls.docstring)
             lines.append("")
-            if func.signature:
-                lines.append("```python")
-                lines.append(func.signature)
-                lines.append("```")
-                lines.append("")
-            if func.docstring:
-                lines.append(func.docstring)
-                lines.append("")
 
-    return "\n".join(lines)
+        # Methods
+        if cls.methods:
+            lines.append("#### Methods")
+            lines.append("")
+            _add_markdown_methods(lines, cls.methods)
+
+
+def _add_markdown_methods(lines: list[str], methods: list[FunctionDoc]) -> None:
+    """Add methods section to markdown.
+
+    Args:
+        lines: List to append lines to.
+        methods: List of method documentation.
+    """
+    for method in methods:
+        lines.append(f"##### {method.name}")
+        lines.append("")
+        _add_markdown_function_details(lines, method)
+
+
+def _add_markdown_functions(lines: list[str], module: ModuleDoc) -> None:
+    """Add functions section to markdown.
+
+    Args:
+        lines: List to append lines to.
+        module: ModuleDoc to render.
+    """
+    for func in module.functions:
+        lines.append(f"### Function: {func.name}")
+        lines.append("")
+        _add_markdown_function_details(lines, func)
+
+
+def _add_markdown_function_details(lines: list[str], func: FunctionDoc) -> None:
+    """Add function/method details to markdown.
+
+    Args:
+        lines: List to append lines to.
+        func: FunctionDoc to render.
+    """
+    if func.signature:
+        lines.append("```python")
+        lines.append(func.signature)
+        lines.append("```")
+        lines.append("")
+    if func.docstring:
+        lines.append(func.docstring)
+        lines.append("")
 
 
 def _generate_html(docs: ExtensionDocs) -> str:

oscura/{extensibility → core/extensibility}/extensions.py

@@ -250,7 +250,7 @@ class ExtensionPointRegistry:
             cls._instance._hook_error_policy = HookErrorPolicy.CONTINUE
             cls._instance._log_hook_errors = True
             cls._instance._initialized = False  # type: ignore[has-type]
-            cls._instance._registration_counter = 0  # type: ignore[misc, attr-defined]
+            cls._instance._registration_counter: int = 0  # type: ignore[misc, attr-defined]
         return cls._instance
 
     def initialize(self) -> None:
@@ -530,99 +530,183 @@ class ExtensionPointRegistry:
         if name:
             return self.get_algorithm(category, name)
 
-        # Auto-select based on criteria
+        # Get and filter candidates
         candidates = list(self._algorithms[category].values())  # type: ignore[attr-defined]
-
         if not candidates:
             raise KeyError(f"No algorithms registered in category '{category}'")
 
-        # Filter by required capabilities (EXT-003)
-        if required_capabilities:
-            filtered = []
-            for algo in candidates:
-                if all(algo.can(cap) for cap in required_capabilities):
-                    filtered.append(algo)
-            candidates = filtered
+        candidates = self._filter_by_capabilities(candidates, required_capabilities, category)
+        candidates = self._filter_by_constraints(candidates, constraints, category)
 
-        if not candidates:
+        # Select best match
+        sort_key = self._get_sort_key(optimize_for)
+        candidates.sort(key=sort_key)
+        return candidates[0]
+
+    def _filter_by_capabilities(
+        self,
+        candidates: list[RegisteredAlgorithm],
+        required_capabilities: list[str] | None,
+        category: str,
+    ) -> list[RegisteredAlgorithm]:
+        """Filter algorithms by required capabilities.
+
+        Args:
+            candidates: List of candidate algorithms.
+            required_capabilities: Required capabilities.
+            category: Category name for error messages.
+
+        Returns:
+            Filtered list of algorithms.
+
+        Raises:
+            KeyError: If no algorithms match capabilities.
+        """
+        if not required_capabilities:
+            return candidates
+
+        filtered = [
+            algo for algo in candidates if all(algo.can(cap) for cap in required_capabilities)
+        ]
+
+        if not filtered:
             raise KeyError(f"No algorithms match required capabilities in category '{category}'")
 
-        # Apply constraints
-        if constraints:
-            filtered = []
-            for algo in candidates:
-                match = True
-                for key, value in constraints.items():
-                    if key.startswith("performance."):
-                        perf_key = key.split(".", 1)[1]
-                        if algo.performance.get(perf_key) != value:
-                            match = False
-                            break
-                    elif key.startswith("capabilities."):
-                        cap_key = key.split(".", 1)[1]
-                        if algo.capabilities.get(cap_key) != value:
-                            match = False
-                            break
-                    elif key == "supports":
-                        if isinstance(value, list):
-                            if not any(s in algo.supports for s in value):
-                                match = False
-                                break
-                        elif value not in algo.supports:
-                            match = False
-                            break
-                    elif key == "memory_usage":
-                        if algo.memory_usage != value:
-                            match = False
-                            break
-                if match:
-                    filtered.append(algo)
-            candidates = filtered
+        return filtered
 
-        if not candidates:
+    def _filter_by_constraints(
+        self,
+        candidates: list[RegisteredAlgorithm],
+        constraints: dict[str, Any] | None,
+        category: str,
+    ) -> list[RegisteredAlgorithm]:
+        """Filter algorithms by constraints.
+
+        Args:
+            candidates: List of candidate algorithms.
+            constraints: Constraint dictionary.
+            category: Category name for error messages.
+
+        Returns:
+            Filtered list of algorithms.
+
+        Raises:
+            KeyError: If no algorithms match constraints.
+        """
+        if not constraints:
+            return candidates
+
+        filtered = [algo for algo in candidates if self._matches_constraints(algo, constraints)]
+
+        if not filtered:
             raise KeyError(f"No algorithms match constraints in category '{category}'")
 
-        # Sort by optimization criteria
+        return filtered
+
+    def _matches_constraints(
+        self,
+        algo: RegisteredAlgorithm,
+        constraints: dict[str, Any],
+    ) -> bool:
+        """Check if algorithm matches all constraints.
+
+        Args:
+            algo: Algorithm to check.
+            constraints: Constraint dictionary.
+
+        Returns:
+            True if all constraints match.
+        """
+        for key, value in constraints.items():
+            if not self._check_single_constraint(algo, key, value):
+                return False
+        return True
+
+    def _check_single_constraint(
+        self,
+        algo: RegisteredAlgorithm,
+        key: str,
+        value: Any,
+    ) -> bool:
+        """Check if algorithm matches a single constraint.
+
+        Args:
+            algo: Algorithm to check.
+            key: Constraint key.
+            value: Expected value.
+
+        Returns:
+            True if constraint matches.
+        """
+        if key.startswith("performance."):
+            return self._check_performance_constraint(algo, key, value)
+        elif key.startswith("capabilities."):
+            return self._check_capabilities_constraint(algo, key, value)
+        elif key == "supports":
+            return self._check_supports_constraint(algo, value)
+        elif key == "memory_usage":
+            memory_check: bool = bool(algo.memory_usage == value)
+            return memory_check
+        return True
+
+    def _check_performance_constraint(
+        self, algo: RegisteredAlgorithm, key: str, value: Any
+    ) -> bool:
+        """Check performance constraint."""
+        perf_key = key.split(".", 1)[1]
+        result: bool = bool(algo.performance.get(perf_key) == value)
+        return result
+
+    def _check_capabilities_constraint(
+        self, algo: RegisteredAlgorithm, key: str, value: Any
+    ) -> bool:
+        """Check capabilities constraint."""
+        cap_key = key.split(".", 1)[1]
+        result: bool = bool(algo.capabilities.get(cap_key) == value)
+        return result
+
+    def _check_supports_constraint(self, algo: RegisteredAlgorithm, value: Any) -> bool:
+        """Check supports constraint."""
+        if isinstance(value, list):
+            result: bool = bool(any(s in algo.supports for s in value))
+            return result
+        else:
+            in_supports: bool = bool(value in algo.supports)
+            return in_supports
+
+    def _get_sort_key(self, optimize_for: str) -> Any:
+        """Get sort key function for optimization criterion.
+
+        Args:
+            optimize_for: Optimization target.
+
+        Returns:
+            Sort key function.
+        """
         if optimize_for == "speed":
 
-            def sort_key(a):  # type: ignore[no-untyped-def]
-                return (
-                    0
-                    if a.performance.get("speed") == "fast"
-                    else 1
-                    if a.performance.get("speed") == "medium"
-                    else 2,
-                    -a.priority,
-                )
+            def sort_key(a: RegisteredAlgorithm) -> tuple[int, int]:
+                speed = a.performance.get("speed")
+                rank = 0 if speed == "fast" else 1 if speed == "medium" else 2
+                return (rank, -a.priority)
         elif optimize_for == "accuracy":
 
-            def sort_key(a):  # type: ignore[no-untyped-def]
-                return (
-                    0
-                    if a.performance.get("accuracy") == "high"
-                    else 1
-                    if a.performance.get("accuracy") == "medium"
-                    else 2,
-                    -a.priority,
-                )
+            def sort_key(a: RegisteredAlgorithm) -> tuple[int, int]:
+                acc = a.performance.get("accuracy")
+                rank = 0 if acc == "high" else 1 if acc == "medium" else 2
+                return (rank, -a.priority)
         elif optimize_for == "memory":
 
-            def sort_key(a):  # type: ignore[no-untyped-def]
-                return (
-                    0
-                    if a.performance.get("memory") == "low"
-                    else 1
-                    if a.performance.get("memory") == "medium"
-                    else 2,
-                    -a.priority,
-                )
+            def sort_key(a: RegisteredAlgorithm) -> tuple[int, int]:
+                mem = a.performance.get("memory")
+                rank = 0 if mem == "low" else 1 if mem == "medium" else 2
+                return (rank, -a.priority)
         else:
-            # Default to priority only
-            def sort_key(a):  # type: ignore[no-untyped-def]
-                return -a.priority
 
-        candidates.sort(key=sort_key)
-        return candidates[0]  # type: ignore[no-any-return]
+            def sort_key(a: RegisteredAlgorithm) -> tuple[int, int]:
+                return (-a.priority, 0)
+
+        return sort_key
 
     def list_algorithms(
         self,

oscura/{extensibility → core/extensibility}/logging.py

@@ -5,7 +5,7 @@ and per-plugin configuration for proper log management.
 
 
 Example:
-    >>> from oscura.extensibility.logging import get_plugin_logger
+    >>> from oscura.core.extensibility.logging import get_plugin_logger
     >>> logger = get_plugin_logger("my_plugin")
     >>> logger.info("Plugin initialized")
 

oscura/{extensibility → core/extensibility}/measurements.py

@@ -15,7 +15,7 @@ from .registry import AlgorithmRegistry
 if TYPE_CHECKING:
     from collections.abc import Callable
 
-    from ..core.types import WaveformTrace
+    from oscura.core.types import WaveformTrace
 
 
 @dataclass

oscura/{extensibility → core/extensibility}/plugins.py

@@ -117,7 +117,7 @@ class PluginManager:
     """
 
     # Standard entry point groups
-    ENTRY_POINT_GROUPS = [  # noqa: RUF012
+    ENTRY_POINT_GROUPS = [
         "oscura.decoders",
         "oscura.measurements",
         "oscura.loaders",

oscura/{extensibility → core/extensibility}/templates.py

@@ -312,7 +312,41 @@ def _write_readme(template: PluginTemplate) -> None:
     class_name = _get_class_name(template)
     entry_point_group = _get_entry_point_group(template.plugin_type)
 
-    content = textwrap.dedent(f"""\
+    content = _generate_readme_content(template, class_name, entry_point_group)
+    (template.output_dir / "README.md").write_text(content)
+
+
+def _generate_readme_content(
+    template: PluginTemplate, class_name: str, entry_point_group: str
+) -> str:
+    """Generate README.md content.
+
+    Args:
+        template: Plugin template configuration.
+        class_name: PascalCase class name.
+        entry_point_group: Entry point group name.
+
+    Returns:
+        README content as string.
+    """
+    header = _generate_readme_header(template, class_name)
+    usage = _generate_readme_usage(template, class_name)
+    dev = _generate_readme_development(template)
+    metadata = _generate_readme_metadata(template, entry_point_group)
+    return f"{header}\n{usage}\n{dev}\n{metadata}"
+
+
+def _generate_readme_header(template: PluginTemplate, class_name: str) -> str:
+    """Generate README header and installation section.
+
+    Args:
+        template: Plugin template configuration.
+        class_name: Class name.
+
+    Returns:
+        Header section content.
+    """
+    return textwrap.dedent(f"""\
         # {class_name}
 
         {template.description}
@@ -325,7 +359,20 @@ def _write_readme(template: PluginTemplate) -> None:
         cd {template.output_dir.name}
         pip install -e .
         ```
+    """)
+
+
+def _generate_readme_usage(template: PluginTemplate, class_name: str) -> str:
+    """Generate usage section.
 
+    Args:
+        template: Plugin template configuration.
+        class_name: Class name.
+
+    Returns:
+        Usage section content.
+    """
+    return textwrap.dedent(f"""\
         ## Usage
 
         The plugin integrates automatically with Oscura via entry points:
@@ -359,7 +406,19 @@ def _write_readme(template: PluginTemplate) -> None:
         # Show plugin info
         oscura plugin info {template.name}
         ```
+    """)
+
+
+def _generate_readme_development(template: PluginTemplate) -> str:
+    """Generate development section.
 
+    Args:
+        template: Plugin template configuration.
+
+    Returns:
+        Development section content.
+    """
+    return textwrap.dedent(f"""\
         ## Development
 
         ### Running Tests
@@ -380,7 +439,20 @@ def _write_readme(template: PluginTemplate) -> None:
         # Type checking
         mypy {template.name}.py
         ```
+    """)
+
+
+def _generate_readme_metadata(template: PluginTemplate, entry_point_group: str) -> str:
+    """Generate metadata section.
+
+    Args:
+        template: Plugin template configuration.
+        entry_point_group: Entry point group name.
 
+    Returns:
+        Metadata section content.
+    """
+    return textwrap.dedent(f"""\
         ## Plugin Type: {template.plugin_type}
 
         This is a **{template.plugin_type}** plugin for Oscura.
@@ -407,8 +479,6 @@ def _write_readme(template: PluginTemplate) -> None:
         {template.version}
     """)
 
-    (template.output_dir / "README.md").write_text(content)
-
 
 def _write_pyproject_toml(template: PluginTemplate) -> None:
     """Write pyproject.toml for plugin packaging.