feat(skills): add spacecraft-python-guidelines

Introduce a new language-guidelines skill for Python (targeting Python 3.12+) systems programming. Defines static typing rules (strict mypy configuration), boundary validation (Pydantic v2 schemas), asyncio event loop non-blocking safety, ProcessPoolExecutor CPU scaling, slots (__slots__) optimization classes, and Ruff linting rules. Includes zip and skill bundles and README registration.

Co-Authored-By: Antigravity (Gemini 3.5 Flash) <noreply@google.com>

Author: UnbreakableMJ

README.md

@@ -51,6 +51,7 @@ the rules re-attached to every prompt.
 | [`spacecraft-missing-pkg`](spacecraft-missing-pkg/) | Handles missing-package situations in the Spacecraft Software workflow. |
 | [`spacecraft-nim-guidelines`](spacecraft-nim-guidelines/) | Type-safe highly-concurrent Nim guidance (targeting Nim 2.0+) — ARC/ORC deterministic memory management, move semantics (`sink`/`lent`), structured parallelism via `Malebolgia`, asynchronous networking with `Chronos`, safe FFI custom destructors (`=destroy`), and warnings-as-errors compiler configuration. |
 | [`spacecraft-ocamel-guidelines`](spacecraft-ocamel-guidelines/) | Type-safe highly-concurrent OCaml guidance — direct-style I/O fibers via `Eio` and Domainslib task parallelism pools, Saturn lock-free structures, Software Transactional Memory with Kcas, C FFI memory safety (`CAMLparam`/`CAMLlocal`/`CAMLreturn`), and warning-as-errors compilation flags. |
+| [`spacecraft-python-guidelines`](spacecraft-python-guidelines/) | Type-safe highly-concurrent Python guidance (targeting Python 3.12+) — strict static typing (`mypy`), boundary validation (`Pydantic v2`), non-blocking asynchronous event loops (`asyncio`), multiprocess CPU scaling (`ProcessPoolExecutor`), memory-optimized slots classes, and Ruff linting rules. |
 | [`spacecraft-rust-guidelines`](spacecraft-rust-guidelines/) | High-performance concurrent Rust guidance — concurrency model selection, lock-free synchronisation, memory layout, tooling gates, and unsafe hygiene — plus a distilled idiom layer (`references/idioms.md`, adapted from Apollo's Rust Best Practices, MIT) covering borrowing, clippy discipline, testing, dispatch, and type-state. |
 | [`spacecraft-standard`](spacecraft-standard/) | Authoritative compliance reference (The Steelbore Standard). |
 | [`spacecraft-swift-guidelines`](spacecraft-swift-guidelines/) | Type-safe highly-concurrent Swift guidance (targeting Swift 6.2+) — Swift 6.2 concurrency, explicit `@concurrent` background offloading, isolated conformances, `@MainActor` isolated ViewModels, Swift Testing `@Suite` and `@Test` parameterized checks, and ARC reference cycle safety. |

spacecraft-python-guidelines.skill

@@ -0,0 +1,85 @@
+---
+name: spacecraft-python-guidelines
+description: Use for writing type-safe highly-concurrent memory-safe Python code following Spacecraft Software standards. Triggers on any request involving Python, pip, poetry, pyproject.toml, ruff, mypy (strict mode), type hints, asyncio (event loops, run_in_executor), multiprocessing (ProcessPoolExecutor), GIL boundaries (Python 3.12 sub-interpreters, 3.13 free-threaded), Pydantic (v2), slots (__slots__), context managers, or pytest testing. Trigger even when implicit, e.g. "write a Python asyncio task", "configure mypy in pyproject.toml", "parallelize this math loop in Python", or "add custom Pydantic validators". Do NOT trigger for Jython or IronPython unless JVM/CLR interoperability is explicitly requested. By Mohamed Hammad and Spacecraft Software.
+license: GPL-3.0-or-later
+maintainer: Mohamed Hammad <Mohamed.Hammad@SpacecraftSoftware.org>
+website: https://Construct.SpacecraftSoftware.org/
+---
+
+# Spacecraft Python Guidelines
+
+**Maintainer:** Mohamed Hammad | **Contact:** [Mohamed.Hammad@SpacecraftSoftware.org](mailto:Mohamed.Hammad@SpacecraftSoftware.org)
+**Copyright:** (C) 2026 Mohamed Hammad & Spacecraft Software | **License:** GPL-3.0-or-later
+**Website:** [https://Construct.SpacecraftSoftware.org/](https://Construct.SpacecraftSoftware.org/)
+
+**You are an expert Python systems engineer at Spacecraft Software specializing in high-performance, strictly typed, and concurrent systems targeting Python 3.12+ (CPython/free-threaded).** Always follow these rules when writing or reviewing Python code. Never deviate. Instructions are explicit, checklist-driven, and self-contained.
+
+## Core Philosophy
+- **Stability first (Standard §3 Priority 1).** Python is dynamically typed at runtime, but static analysis tools (`mypy` in strict mode) must verify type safety at compile/lint time. Banish untyped function arguments and reject code that suppresses type checker warnings.
+- **Then Performance (Priority 2).** Minimize allocations and memory footprints in hot loops (use generators, comprehensions, and declare `__slots__` on performance-sensitive classes). Bypass Global Interpreter Lock (GIL) bottlenecks cleanly.
+- **Explicit Concurrency.** Ensure that asynchronous, non-blocking I/O tasks (`asyncio`) and parallel CPU tasks (`multiprocessing`) are logically isolated. Never run blocking operations inside an active async event loop thread.
+- **Defensive API boundaries.** Validate and decode all dynamic, external payloads (API responses, file configurations) into type-safe, validated objects using `Pydantic` (v2) schemas immediately at system boundaries.
+
+## Memory Safety & Type Safety
+- **Strict Typing Configuration:** Enforce mypy strict checks. Configure `pyproject.toml` with:
+  `[tool.mypy] strict = true, disallow_any_generics = true, plugins = ["pydantic.mypy"]`
+  All functions, methods, and return statements must carry explicit type annotations.
+- **Safe Optionals:** Explicitly declare variables that can hold `None` using `Optional[T]` or union syntax `T | None`. Check against `None` using identity checks (`is None`) before operating.
+- **Boundary Validation:** Decode incoming unstructured data mapping using `Pydantic` (v2) or `msgspec` models. Avoid passing raw, unchecked dictionaries around the codebase.
+- **Resource Management:** Guarantee the lifecycle of files, network sessions, and locks using context managers (`with` or `async with` blocks) to prevent file descriptor leaks and lock hangs.
+
+## Concurrency vs. Performance Tradeoffs
+- **When Concurrency Helps (Do Async / Multi-process):**
+  - **Asynchronous Event Loop:** Handling thousands of concurrent, non-blocking network requests, socket connections, and async file operations via `asyncio`.
+  - **CPU-bound Parallelism:** Spawning compute-intensive computations (data transformations, numeric operations) onto separate interpreter cores via `ProcessPoolExecutor` to bypass the GIL.
+  - **Blocking Task Offloading:** Wrapping synchronous or blocking libraries (like standard filesystem operations) inside `loop.run_in_executor(None, sync_func)` to prevent blocking the async loop.
+- **When Concurrency Hurts (Do NOT Block / Sprawl):**
+  - **Synchronous loop blocking:** Calling blocking functions (e.g. `time.sleep()`, synchronous database queries, or `requests.get()`) directly inside `async` functions, which freezes the event loop.
+  - **CPU-bound Threading:** Spawning `threading.Thread` or `ThreadPoolExecutor` for CPU-heavy tasks. The GIL prevents parallel execution, causing high scheduler context-switch overhead.
+  - **Pool Initialization Storms:** Spawning process pools dynamically inside loops. Reuse a persistent process pool executor instance.
+
+## Mandatory Abstraction Choice
+Always choose the concurrency model corresponding to the workload:
+- **Compute-heavy workload:** A persistent process pool using `concurrent.futures.ProcessPoolExecutor` sized to CPU core count.
+- **Asynchronous I/O workload:** Non-blocking async/await event loops using `asyncio`.
+- **Blocking calls in async:** Run offloaded to thread executors via `loop.run_in_executor`.
+- **Data validation:** Pydantic (v2) models with the `pydantic.mypy` plugin enabled.
+- **Memory footprint reduction:** Adding `__slots__` to data holder classes.
+
+## Required Techniques
+1. **Slots Declaration:** Declare `__slots__` inside performance-sensitive data classes (e.g., `class Packet: __slots__ = ("id", "value")`) to suppress dynamic `__dict__` generation, reducing memory consumption by 30-50%.
+2. **Generators for Large Sets:** Prefer generator expressions `(x for x in data)` and generator functions (`yield`) instead of list comprehensions when processing large collections (size > 1000) to keep memory usage flat.
+3. **Pydantic Model Parsing:** Parse inputs immediately via Pydantic `.model_validate_json()` or `.model_validate()`. Configure Pydantic options with `extra = "forbid"` and `frozen = True` (immutability).
+4. **Pytest Warning Gates:** Configure `pytest` to treat warnings as errors via `filterwarnings = ["error"]` inside `pyproject.toml`.
+5. **Ruff Format & Lint Check:** Run `ruff check` and `ruff format` to verify syntax formatting.
+
+## Build, Tooling & CI (Non-Negotiable)
+- **Toolchain floor:** Python ≥ 3.12, Poetry or pip-tools dependency management.
+- **Mypy Strict:** Static analysis step executing `mypy --strict` on all CI runs.
+- **Formatter & Linter:** Ruff configured with ASYNC, ANN, B, E, F, I, RUF, TCH, and UP rules.
+- **Testing:** `pytest` test suites running with `pytest-asyncio` for asynchronous targets.
+
+## Anti-Patterns (Never Do These)
+- Leaving function arguments or returns untyped.
+- Executing synchronous blocking operations (`requests`, `time.sleep`) inside async functions.
+- Initializing process or thread pools dynamically inside loops (always share a persistent executor).
+- Using `threading.Thread` or `ThreadPoolExecutor` for CPU-bound computations.
+- Storing large datasets in memory via list comprehensions when generators can stream them.
+- Disabling compiler/lint warnings via `# type: ignore` without documenting why.
+
+## Pre-Commit Checklist (Verify Every Time)
+- [ ] Mypy static analysis passes cleanly with `--strict` enabled
+- [ ] No untyped parameters or variables are left in production files
+- [ ] Sync blocking calls inside async procedures are wrapped in `run_in_executor`
+- [ ] CPU-bound processing operations utilize `ProcessPoolExecutor`
+- [ ] Data objects use `__slots__` to prevent dynamic dictionary allocation
+- [ ] Boundary inputs are validated using Pydantic (v2) models
+- [ ] Ruff format check and lints pass cleanly with zero warnings
+- [ ] Unit tests (pytest) execute and pass cleanly under warnings-as-errors policy
+- [ ] Closeable resources (files, sessions) are handled using context managers
+
+## References & Further Reading
+- Load `references/Spacecraft_Python_Guidelines.md` for full skeletons (ProcessPoolExecutor parallel math, asyncio session fetcher, Pydantic v2 boundaries, slots class, pytest-asyncio suite, and pyproject.toml) when deeper patterns are needed.
+- *Further reading* (consulted for background only): Python Concurrency Proposals, PEP 484 (Typing Specification), Ruff Linter manual, and Pydantic v2 Documentation.
+
+When the user requests Python code or review, activate this skill, apply the checklist, and produce code a senior Spacecraft systems engineer would ship.

spacecraft-python-guidelines.zip

@@ -0,0 +1,266 @@
+# Spacecraft Python Guidelines — Full Reference
+
+**Version:** 1.0
+**Date:** 2026-07-13
+**Author:** Mohamed Hammad & Spacecraft Software
+**Compatibility:** Claude 3.5+, Claude 4, Grok, and all advanced reasoning models
+
+This document expands on the `SKILL.md` for Python systems programming. It provides complete, compile-checked configurations and skeletons for ProcessPoolExecutor parallelism, asyncio execution, Pydantic v2 validations, slots optimizations, and testing.
+
+---
+
+## 1. Concurrency: ProcessPoolExecutor & Asyncio run_in_executor
+
+Do not block the single-threaded `asyncio` event loop. Offload CPU-heavy calculations to a process pool (bypassing the GIL) and synchronous blocking operations to thread executors.
+
+```python
+import asyncio
+from concurrent.futures import ProcessPoolExecutor, ThreadPoolExecutor
+import time
+from typing import List
+
+# Helper CPU-bound math calculation
+def compute_factorial_sync(n: int) -> int:
+    if n < 0:
+        raise ValueError("Must be non-negative")
+    res = 1
+    for i in range(2, n + 1):
+        res *= i
+    return res
+
+# Helper blocking I/O operation
+def blocking_file_read(filepath: str) -> str:
+    # Simulates blocking OS operation
+    time.sleep(0.1)
+    with open(filepath, "r", encoding="utf-8") as f:
+        return f.read()
+
+class TelemetryManager:
+    def __init__(self, max_processes: int = 4, max_threads: int = 8) -> None:
+        self.process_pool = ProcessPoolExecutor(max_workers=max_processes)
+        self.thread_pool = ThreadPoolExecutor(max_workers=max_threads)
+
+    async def shutdown(self) -> None:
+        self.process_pool.shutdown(wait=True)
+        self.thread_pool.shutdown(wait=True)
+
+    async def calculate_batch_factorials(self, numbers: List[int]) -> List[int]:
+        """Runs GIL-bound CPU math inside a ProcessPoolExecutor concurrently."""
+        loop = asyncio.get_running_loop()
+        tasks = [
+            loop.run_in_executor(self.process_pool, compute_factorial_sync, num)
+            for num in numbers
+        ]
+        results: List[int] = await asyncio.gather(*tasks)
+        return results
+
+    async def read_files_async(self, filepaths: List[str]) -> List[str]:
+        """Runs blocking system operations inside ThreadPoolExecutor to prevent event loop lag."""
+        loop = asyncio.get_running_loop()
+        tasks = [
+            loop.run_in_executor(self.thread_pool, blocking_file_read, path)
+            for path in filepaths
+        ]
+        results: List[str] = await asyncio.gather(*tasks)
+        return results
+```
+
+---
+
+## 2. Typing & Pydantic v2 Ingress Validation
+
+Validate and parse raw dynamic data immediately at the entrance boundaries using Pydantic (v2) models. Use strict typing annotations for mypy.
+
+```python
+from datetime import datetime
+import json
+from uuid import UUID
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+from typing import Union, Dict, Any
+
+class TelemetryPacket(BaseModel):
+    # Configure model to be immutable and forbid extra parameters
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid"
+    )
+
+    packet_id: UUID = Field(alias="packetId")
+    value: float = Field(ge=0.0) # validation: must be >= 0.0
+    timestamp: datetime
+
+# Functional result mappings
+class ValidationSuccess:
+    __slots__ = ("data",)
+    def __init__(self, data: TelemetryPacket) -> None:
+        self.data = data
+
+class ValidationFailure:
+    __slots__ = ("error",)
+    def __init__(self, error: str) -> None:
+        self.error = error
+
+ValidationResult = Union[ValidationSuccess, ValidationFailure]
+
+def parse_incoming_payload(json_str: str) -> ValidationResult:
+    try:
+        # Pydantic v2 direct JSON parsing (faster than json.loads)
+        packet = TelemetryPacket.model_validate_json(json_str)
+        return ValidationSuccess(packet)
+    except ValidationError as e:
+        return ValidationFailure(str(e))
+```
+
+---
+
+## 3. Slots Attribute Memory Optimization
+
+For classes that hold data and are instantiated frequently (e.g. millions of packet structures), define `__slots__` to prevent dynamic `__dict__` generation, lowering memory usage.
+
+```python
+from uuid import UUID
+from typing import Tuple
+
+class CompactReading:
+    # Explicit slots reduce memory layout size and speed up variable lookup
+    __slots__ = ("sensor_id", "measurements")
+
+    def __init__(self, sensor_id: UUID, measurements: Tuple[float, ...]) -> None:
+        self.sensor_id: UUID = sensor_id
+        self.measurements: Tuple[float, ...] = measurements
+
+    def average(self) -> float:
+        if not self.measurements:
+            return 0.0
+        return sum(self.measurements) / len(self.measurements)
+```
+
+---
+
+## 4. Testing: pytest & pytest-asyncio
+
+Test concurrent routines and validations using `pytest` and `pytest-asyncio`. Ensure warnings are treated as errors.
+
+```python
+# tests/test_telemetry.py
+import pytest
+from uuid import uuid4
+from datetime import datetime, timezone
+from telemetry_manager import TelemetryManager
+from telemetry_schemas import parse_incoming_payload, ValidationSuccess, ValidationFailure
+
+@pytest.fixture
+def manager() -> TelemetryManager:
+    return TelemetryManager(max_processes=2, max_threads=2)
+
+@pytest.mark.asyncio
+async def test_factorial_calculations(manager: TelemetryManager) -> None:
+    numbers = [5, 6, 7]
+    results = await manager.calculate_batch_factorials(numbers)
+    assert results == [120, 720, 5040]
+
+def test_pydantic_valid_parsing() -> None:
+    uuid_str = str(uuid4())
+    payload = f'{{"packetId": "{uuid_str}", "value": 45.2, "timestamp": "2026-07-12T20:00:00Z"}}'
+    
+    result = parse_incoming_payload(payload)
+    
+    assert isinstance(result, ValidationSuccess)
+    assert result.data.value == 45.2
+    assert result.data.timestamp.tzinfo == timezone.utc
+
+def test_pydantic_invalid_parsing() -> None:
+    # Value violates constraint (must be >= 0.0)
+    payload = '{"packetId": "invalid-uuid", "value": -10.0, "timestamp": "2026-07-12T20:00:00Z"}'
+    
+    result = parse_incoming_payload(payload)
+    
+    assert isinstance(result, ValidationFailure)
+```
+
+---
+
+## 5. Tooling Configuration (`pyproject.toml`)
+
+Standard configuration mapping for `Ruff` rules, `Mypy` strict settings, and `Pytest` warnings.
+
+```toml
+[tool.poetry]
+name = "telemetry-service"
+version = "0.1.0"
+description = "Spacecraft Telemetry Service in Python"
+authors = ["Mohamed Hammad <Mohamed.Hammad@SpacecraftSoftware.org>"]
+license = "GPL-3.0-or-later"
+
+[tool.poetry.dependencies]
+python = "^3.12"
+pydantic = "^2.5.0"
+pytest = "^7.4.0"
+pytest-asyncio = "^0.21.0"
+ruff = "^0.1.0"
+mypy = "^1.6.0"
+
+[tool.mypy]
+strict = true
+disallow_any_generics = true
+warn_unused_ignores = true
+plugins = ["pydantic.mypy"]
+
+[tool.pydantic-mypy]
+init_forbid_extra = true
+init_typed = true
+warn_required_dynamic_aliases = true
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E", "F", "W",    # Pycodestyle & Pyflakes
+    "B",              # Flake8-bugbear
+    "I",              # Isort
+    "RUF",            # Ruff-specific rules
+    "ANN",            # Type annotations
+    "ASYNC",          # Asyncio lints
+    "TCH",            # Type checking blocks
+    "UP"              # Pyupgrade
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+addopts = "-ra -q"
+testpaths = ["tests"]
+filterwarnings = [
+    "error", # Treat all warnings as compilation errors
+]
+```
+
+---
+
+## 6. Common Pitfalls & Troubleshooting
+
+| Pitfall | Symptom | Corrective Action |
+| :--- | :--- | :--- |
+| **Synchronous sleep in async** | Event loop blocks, other jobs halt | Replace `time.sleep` with `await asyncio.sleep`. |
+| **Synchronous filesystem in async** | Event loop thread freezes | Offload execution using `loop.run_in_executor(None, sync_func)`. |
+| **Threading for math operations** | High CPU context switches, slow speed | Replace threading with `ProcessPoolExecutor`. |
+| **Loose typing annotations** | Mypy fails in strict mode | Annotate variables and parameters explicitly. |
+| **Dynamic properties on dataclasses**| Memory growth on long processes | Declare class variables inside `__slots__` tuple. |
+| **Mocking Pydantic dynamic fields** | Mypy failures on class initializers | Configure Pydantic Mypy plugin with `init_typed = true`. |
+
+---
+
+## 7. Code Review Compliance Gate
+
+Before merging Python code, verify:
+1. Static typing assertions pass under strict Mypy checks (no untyped parameters).
+2. Asynchronous loops do not execute synchronous blocking operations.
+3. Heavy numerical calculations run in separate processes (`ProcessPoolExecutor`).
+4. High frequency data structures define `__slots__` tuples.
+5. Ingress parsing checks are wrapped in Pydantic models configured with `frozen=True`.
+6. Ruff lints pass cleanly and pytest treats warnings as error configurations.