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

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

@@ -6,7 +6,7 @@ versioning, and CLI operations.
 
 
 Example:
-    >>> from oscura.plugins.manager import PluginManager
+    >>> from oscura.core.plugins.manager import PluginManager
     >>> manager = PluginManager()
     >>> manager.discover_and_load()
     >>> plugin = manager.get_plugin("uart_decoder")
@@ -19,21 +19,21 @@ import logging
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
-from oscura.plugins.discovery import discover_plugins, get_plugin_paths
-from oscura.plugins.isolation import IsolationManager, PermissionSet, ResourceLimits
-from oscura.plugins.lifecycle import (
+from oscura.core.plugins.discovery import discover_plugins, get_plugin_paths
+from oscura.core.plugins.isolation import IsolationManager, PermissionSet, ResourceLimits
+from oscura.core.plugins.lifecycle import (
     DependencyGraph,
     PluginLifecycleManager,
 )
-from oscura.plugins.registry import (
+from oscura.core.plugins.registry import (
     PluginConflictError,
     PluginRegistry,
     PluginVersionError,
 )
-from oscura.plugins.versioning import MigrationManager
+from oscura.core.plugins.versioning import MigrationManager
 
 if TYPE_CHECKING:
-    from oscura.plugins.base import PluginBase, PluginCapability, PluginMetadata
+    from oscura.core.plugins.base import PluginBase, PluginCapability, PluginMetadata
 
 logger = logging.getLogger(__name__)
 

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

@@ -5,7 +5,7 @@ registering, and accessing plugins.
 
 
 Example:
-    >>> from oscura.plugins.registry import register_plugin, get_plugin
+    >>> from oscura.core.plugins.registry import register_plugin, get_plugin
     >>> register_plugin(MyDecoder)
     >>> decoder = get_plugin("my_decoder")
 """
@@ -15,14 +15,14 @@ from __future__ import annotations
 import logging
 from typing import TYPE_CHECKING, Any
 
-from oscura.plugins.discovery import (
+from oscura.core.plugins.discovery import (
     OSCURA_API_VERSION,
     DiscoveredPlugin,
     discover_plugins,
 )
 
 if TYPE_CHECKING:
-    from oscura.plugins.base import PluginBase, PluginCapability, PluginMetadata
+    from oscura.core.plugins.base import PluginBase, PluginCapability, PluginMetadata
 
 logger = logging.getLogger(__name__)
 

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

@@ -13,7 +13,7 @@ from typing import TYPE_CHECKING, Any
 if TYPE_CHECKING:
     from collections.abc import Callable
 
-    from oscura.plugins.base import PluginBase
+    from oscura.core.plugins.base import PluginBase
 
 logger = logging.getLogger(__name__)
 

oscura/core/progress.py

@@ -23,7 +23,14 @@ import time
 import warnings
 from typing import TYPE_CHECKING, Protocol
 
-import psutil
+# Lazy import for optional system monitoring
+try:
+    import psutil
+
+    _HAS_PSUTIL = True
+except ImportError:
+    psutil = None  # type: ignore[assignment]
+    _HAS_PSUTIL = False
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -423,6 +430,10 @@ def check_memory_available(required_bytes: int, *, threshold: float = 0.8) -> bo
     References:
         PROG-003: Memory Usage Warnings
     """
+    # If psutil not available, assume memory is sufficient
+    if not _HAS_PSUTIL:
+        return True
+
     memory = psutil.virtual_memory()
     available_bytes = memory.available
     threshold_bytes = available_bytes * threshold
@@ -454,6 +465,10 @@ def warn_memory_usage(
     References:
         PROG-003: Memory Usage Warnings
     """
+    # If psutil not available, skip memory warning
+    if not _HAS_PSUTIL:
+        return
+
     memory = psutil.virtual_memory()
     available_bytes = memory.available
     threshold_bytes = available_bytes * threshold

oscura/core/provenance.py

@@ -17,8 +17,14 @@ import numpy as np
 if TYPE_CHECKING:
     from numpy.typing import NDArray
 
-# Oscura version (in production would import from __version__)
-OSCURA_VERSION = "0.1.0"
+# Oscura version dynamically imported from package metadata (SSOT: pyproject.toml)
+try:
+    from importlib.metadata import version
+
+    OSCURA_VERSION = version("oscura")
+except Exception:
+    # Fallback for development/testing when package not installed
+    OSCURA_VERSION = "0.0.0+dev"
 
 
 @dataclass

oscura/{schemas → core/schemas}/__init__.py

@@ -6,7 +6,7 @@ device mappings, bus configurations, and protocol definitions.
 
 
 Example:
-    >>> from oscura.schemas import load_schema, validate_config
+    >>> from oscura.core.schemas import load_schema, validate_config
     >>> schema = load_schema("packet_format")
     >>> validate_config(config_dict, "packet_format")
     True
@@ -18,7 +18,7 @@ import json
 from pathlib import Path
 from typing import Any
 
-from oscura.config.schema import (
+from oscura.core.config.schema import (
     ConfigSchema,
     get_schema_registry,
     register_schema,

oscura/core/schemas/bus_configuration.json

@@ -0,0 +1,322 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://oscura.io/schemas/bus_configuration.json",
+  "title": "Bus Configuration Schema",
+  "description": "Schema for validating parallel bus configurations for multi-bit protocols (CFG-001).",
+  "type": "object",
+  "required": ["name", "settings"],
+  "additionalProperties": true,
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Bus configuration identifier",
+      "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$",
+      "minLength": 1
+    },
+    "version": {
+      "type": "string",
+      "description": "Configuration version",
+      "pattern": "^\\d+\\.\\d+$"
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable description"
+    },
+    "settings": {
+      "type": "object",
+      "description": "Global bus settings",
+      "properties": {
+        "active_low": {
+          "type": "boolean",
+          "description": "Signals are active-low (inverted)"
+        },
+        "sample_on": {
+          "type": "string",
+          "enum": ["rising", "falling", "both"],
+          "description": "Sample on clock/timing pulse edge"
+        },
+        "bit_numbering": {
+          "type": "string",
+          "enum": ["lsb_0", "msb_0"],
+          "description": "Bit numbering convention"
+        }
+      },
+      "additionalProperties": false
+    },
+    "data_bus": {
+      "type": "object",
+      "description": "Data bus definition",
+      "required": ["name", "width", "bits"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Bus name",
+          "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$"
+        },
+        "width": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 128,
+          "description": "Bus width in bits"
+        },
+        "description": {
+          "type": "string",
+          "description": "Bus description"
+        },
+        "active_low": {
+          "type": "boolean",
+          "description": "Override global active_low setting"
+        },
+        "bits": {
+          "type": "array",
+          "description": "Bit mappings from channel to position",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["channel", "bit"],
+            "properties": {
+              "channel": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Source channel index"
+              },
+              "bit": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Bit position in bus"
+              },
+              "name": {
+                "type": "string",
+                "description": "Signal name",
+                "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$"
+              }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "address_bus": {
+      "type": "object",
+      "description": "Address bus definition",
+      "required": ["name", "width", "bits"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Bus name",
+          "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$"
+        },
+        "width": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 128,
+          "description": "Bus width in bits"
+        },
+        "description": {
+          "type": "string",
+          "description": "Bus description"
+        },
+        "active_low": {
+          "type": "boolean",
+          "description": "Override global active_low setting"
+        },
+        "bits": {
+          "type": "array",
+          "description": "Bit mappings from channel to position",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["channel", "bit"],
+            "properties": {
+              "channel": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Source channel index"
+              },
+              "bit": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Bit position in bus"
+              },
+              "name": {
+                "type": "string",
+                "description": "Signal name",
+                "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$"
+              }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "control_signals": {
+      "type": "array",
+      "description": "Control signal definitions",
+      "items": {
+        "type": "object",
+        "required": ["name", "channel"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Signal name",
+            "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$"
+          },
+          "channel": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Source channel index"
+          },
+          "active_low": {
+            "type": "boolean",
+            "description": "Signal is active-low"
+          },
+          "description": {
+            "type": "string",
+            "description": "Signal description"
+          },
+          "short_name": {
+            "type": "string",
+            "description": "Short name/abbreviation",
+            "maxLength": 8
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "timing": {
+      "type": "object",
+      "description": "Timing constraints and validation",
+      "properties": {
+        "clock_period_ns": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "description": "Clock period in nanoseconds"
+        },
+        "setup_time_ns": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Setup time requirement in nanoseconds"
+        },
+        "hold_time_ns": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Hold time requirement in nanoseconds"
+        },
+        "pulse_width_ns": {
+          "type": "object",
+          "description": "Pulse width requirements by signal type",
+          "additionalProperties": {
+            "type": "number",
+            "minimum": 0
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "transactions": {
+      "type": "object",
+      "description": "Transaction decoding rules",
+      "properties": {
+        "types": {
+          "type": "array",
+          "description": "Transaction type definitions",
+          "items": {
+            "type": "object",
+            "required": ["name", "conditions"],
+            "properties": {
+              "name": {
+                "type": "string",
+                "description": "Transaction type name",
+                "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$"
+              },
+              "conditions": {
+                "type": "object",
+                "description": "Signal conditions for this transaction",
+                "additionalProperties": {
+                  "type": "boolean"
+                }
+              },
+              "sample_on": {
+                "type": "string",
+                "description": "Control signal to sample on"
+              },
+              "capture": {
+                "type": "object",
+                "description": "Buses/signals to capture",
+                "additionalProperties": {
+                  "type": "string"
+                }
+              }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "instruction_decode": {
+      "type": "object",
+      "description": "Instruction decoding (if data contains opcodes)",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Enable instruction decoding"
+        },
+        "opcode_bits": {
+          "type": "array",
+          "description": "Bit range for opcode [start, end]",
+          "items": { "type": "integer", "minimum": 0 },
+          "minItems": 2,
+          "maxItems": 2
+        },
+        "opcodes": {
+          "type": "object",
+          "description": "Opcode to instruction mappings (keys can be integers or binary/hex strings)",
+          "additionalProperties": {
+            "type": "object",
+            "required": ["name"],
+            "properties": {
+              "name": {
+                "type": "string",
+                "description": "Instruction mnemonic"
+              },
+              "description": {
+                "type": "string",
+                "description": "Instruction description"
+              }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "output": {
+      "type": "object",
+      "description": "Output formatting options",
+      "properties": {
+        "format": {
+          "type": "string",
+          "enum": ["raw", "transaction", "annotated"],
+          "description": "Output format type"
+        },
+        "timestamp_format": {
+          "type": "string",
+          "enum": ["absolute", "relative_us", "relative_ns", "sample_index"],
+          "description": "Timestamp format"
+        },
+        "include_raw_values": {
+          "type": "boolean",
+          "description": "Include raw values in output"
+        },
+        "hex_format": {
+          "type": "boolean",
+          "description": "Display values in hexadecimal"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

oscura/core/schemas/device_mapping.json

@@ -0,0 +1,182 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://oscura.io/schemas/device_mapping.json",
+  "title": "Device Mapping Configuration Schema",
+  "description": "Schema for validating device ID to name mappings and device-specific parameters (CFG-001).",
+  "type": "object",
+  "required": ["name", "devices"],
+  "additionalProperties": true,
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Mapping configuration identifier",
+      "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$",
+      "minLength": 1
+    },
+    "version": {
+      "type": "string",
+      "description": "Configuration version",
+      "pattern": "^\\d+\\.\\d+$"
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable description"
+    },
+    "devices": {
+      "type": "object",
+      "description": "Device ID to configuration mappings (keys can be integers or hex strings)",
+      "minProperties": 1,
+      "additionalProperties": {
+        "type": "object",
+        "description": "Device configuration (key is hex 0xNN or decimal ID)",
+        "required": ["name"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Full device name",
+            "minLength": 1
+          },
+          "short_name": {
+            "type": "string",
+            "description": "Short/abbreviated device name",
+            "maxLength": 16
+          },
+          "description": {
+            "type": "string",
+            "description": "Device description"
+          },
+          "category": {
+            "type": "string",
+            "description": "Device category for grouping"
+          },
+          "sample_rate": {
+            "oneOf": [
+              { "type": "number", "exclusiveMinimum": 0 },
+              {
+                "type": "string",
+                "pattern": "^[0-9]+(\\.[0-9]+)?[eE][+-]?[0-9]+$"
+              }
+            ],
+            "description": "Device sample rate in Hz (number or scientific notation string)"
+          },
+          "channels": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Number of channels"
+          },
+          "properties": {
+            "type": "object",
+            "description": "Device-specific properties",
+            "additionalProperties": true
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "categories": {
+      "type": "object",
+      "description": "Category definitions for grouping and display",
+      "patternProperties": {
+        "^[a-zA-Z][a-zA-Z0-9_]*$": {
+          "type": "object",
+          "properties": {
+            "description": {
+              "type": "string",
+              "description": "Category description"
+            },
+            "color": {
+              "type": "string",
+              "description": "Display color (hex format)",
+              "pattern": "^#[0-9A-Fa-f]{6}$"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "channels": {
+      "type": "object",
+      "description": "Channel/lane configuration (keys can be integers or numeric strings)",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Channel name"
+          },
+          "description": {
+            "type": "string",
+            "description": "Channel description"
+          },
+          "default_threshold": {
+            "type": "number",
+            "description": "Default threshold voltage"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "unknown_device": {
+      "type": "object",
+      "description": "Handling for unknown device IDs",
+      "properties": {
+        "policy": {
+          "type": "string",
+          "enum": ["error", "warn", "ignore"],
+          "description": "Action when unknown device encountered"
+        },
+        "default_name": {
+          "type": "string",
+          "description": "Default name for unknown devices"
+        },
+        "default_category": {
+          "type": "string",
+          "description": "Default category for unknown devices"
+        }
+      },
+      "additionalProperties": false
+    },
+    "filters": {
+      "type": "object",
+      "description": "Device filtering options",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Enable filtering"
+        },
+        "include_devices": {
+          "type": "array",
+          "description": "Device IDs to include (whitelist)",
+          "items": {
+            "oneOf": [
+              { "type": "integer" },
+              { "type": "string", "pattern": "^0[xX][0-9A-Fa-f]+$" }
+            ]
+          }
+        },
+        "exclude_devices": {
+          "type": "array",
+          "description": "Device IDs to exclude (blacklist)",
+          "items": {
+            "oneOf": [
+              { "type": "integer" },
+              { "type": "string", "pattern": "^0[xX][0-9A-Fa-f]+$" }
+            ]
+          }
+        },
+        "include_categories": {
+          "type": "array",
+          "description": "Categories to include",
+          "items": { "type": "string" }
+        },
+        "exclude_categories": {
+          "type": "array",
+          "description": "Categories to exclude",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}