@nockdev/awf 6.2.0

package/.agent/skills/languages/python/data/async.yaml

@@ -0,0 +1,265 @@
+# =============================================================================
+# Python Async Patterns (Feb 2026)
+# Version: Python 3.13/3.14
+# =============================================================================
+
+metadata:
+  skill: python
+  domain: async
+  version: "3.14"
+  updated: "2026-02-05"
+  patterns_count: 5
+
+patterns:
+  - id: py101
+    name: TaskGroup (Structured Concurrency)
+    category: concurrency
+    version: "3.11+"
+    description: |
+      Structured concurrency with TaskGroup.
+      Automatic cancellation on exception. Replaces gather for most cases.
+    text: taskgroup structured concurrency async gather parallel
+    example: |
+      import asyncio
+      from typing import Any
+
+      async def fetch_user(user_id: int) -> dict[str, Any]:
+          await asyncio.sleep(0.1)  # Simulate API call
+          return {"id": user_id, "name": f"User {user_id}"}
+
+      async def fetch_posts(user_id: int) -> list[dict]:
+          await asyncio.sleep(0.1)
+          return [{"id": 1, "title": "Hello"}]
+
+      # ✅ TaskGroup for structured concurrency
+      async def get_user_data(user_id: int) -> dict[str, Any]:
+          async with asyncio.TaskGroup() as tg:
+              user_task = tg.create_task(fetch_user(user_id))
+              posts_task = tg.create_task(fetch_posts(user_id))
+          
+          # All tasks complete or all cancelled on error
+          return {
+              "user": user_task.result(),
+              "posts": posts_task.result(),
+          }
+
+      # ✅ Exception handling
+      async def fetch_all_or_fail():
+          try:
+              async with asyncio.TaskGroup() as tg:
+                  tg.create_task(fetch_user(1))
+                  tg.create_task(failing_task())  # If this fails
+          except* ValueError as eg:
+              # ExceptionGroup handling (3.11+)
+              for exc in eg.exceptions:
+                  print(f"Caught: {exc}")
+    severity: HIGH
+    docs_url: https://docs.python.org/3/library/asyncio-task.html#task-groups
+
+  - id: py102
+    name: asyncio.to_thread
+    category: concurrency
+    version: "3.9+"
+    description: |
+      Run blocking code in thread pool without blocking event loop.
+      Use for file I/O, CPU-bound tasks, or sync libraries.
+    text: to_thread blocking sync thread pool executor
+    example: |
+      import asyncio
+      import time
+      from pathlib import Path
+
+      # ✅ Blocking file I/O in async context
+      async def read_file_async(path: Path) -> str:
+          return await asyncio.to_thread(path.read_text)
+
+      # ✅ CPU-bound work
+      def cpu_intensive_sync(n: int) -> int:
+          """Sync function - would block event loop"""
+          return sum(i * i for i in range(n))
+
+      async def process_data(n: int) -> int:
+          # Run in thread pool
+          result = await asyncio.to_thread(cpu_intensive_sync, n)
+          return result
+
+      # ✅ Sync library integration
+      import requests  # Sync library
+
+      async def fetch_with_requests(url: str) -> str:
+          response = await asyncio.to_thread(requests.get, url)
+          return response.text
+
+      # ✅ Multiple blocking operations
+      async def process_files(paths: list[Path]) -> list[str]:
+          async with asyncio.TaskGroup() as tg:
+              tasks = [
+                  tg.create_task(read_file_async(p))
+                  for p in paths
+              ]
+          return [t.result() for t in tasks]
+    severity: HIGH
+    docs_url: https://docs.python.org/3/library/asyncio-task.html#asyncio.to_thread
+
+  - id: py103
+    name: Timeout and Cancellation
+    category: control-flow
+    version: "3.11+"
+    description: |
+      Proper timeout handling with asyncio.timeout.
+      Replaces wait_for for cleaner cancellation.
+    text: timeout cancellation cancel asyncio wait_for
+    example: |
+      import asyncio
+      from contextlib import asynccontextmanager
+
+      # ✅ Modern timeout (3.11+)
+      async def fetch_with_timeout(url: str) -> str:
+          async with asyncio.timeout(5.0):
+              # Auto-cancelled after 5 seconds
+              return await fetch(url)
+
+      # ✅ Nested timeouts
+      async def complex_operation():
+          async with asyncio.timeout(30):  # Overall timeout
+              await step1()
+              async with asyncio.timeout(10):  # Step-specific
+                  await step2()
+              await step3()
+
+      # ✅ Deadline-based timeout
+      async def with_deadline():
+          deadline = asyncio.get_event_loop().time() + 5.0
+          async with asyncio.timeout_at(deadline):
+              await long_operation()
+
+      # ✅ Graceful cancellation handling
+      async def cancellable_task():
+          try:
+              while True:
+                  await asyncio.sleep(1)
+                  await do_work()
+          except asyncio.CancelledError:
+              # Cleanup before propagating
+              await cleanup()
+              raise
+
+      # ✅ Shield from cancellation
+      async def protected_operation():
+          # This won't be cancelled even if parent is
+          result = await asyncio.shield(critical_db_write())
+          return result
+    severity: HIGH
+    docs_url: https://docs.python.org/3/library/asyncio-task.html#timeouts
+
+  - id: py104
+    name: Async Generators and Iterators
+    category: iteration
+    version: "3.6+"
+    description: |
+      Async iteration patterns for streaming data.
+      Memory-efficient processing of large datasets.
+    text: async generator iterator yield stream aiter anext
+    example: |
+      from typing import AsyncIterator
+      import asyncio
+
+      # ✅ Async generator
+      async def fetch_pages(url: str) -> AsyncIterator[dict]:
+          page = 1
+          while True:
+              data = await fetch(f"{url}?page={page}")
+              if not data["items"]:
+                  break
+              yield data
+              page += 1
+
+      # ✅ Consuming async iterator
+      async def process_all_pages(url: str) -> list[dict]:
+          results = []
+          async for page in fetch_pages(url):
+              results.extend(page["items"])
+          return results
+
+      # ✅ Async comprehension
+      async def get_active_users():
+          return [
+              user async for user in fetch_users()
+              if user["active"]
+          ]
+
+      # ✅ aiter/anext for manual iteration
+      async def get_first_n(ait: AsyncIterator, n: int) -> list:
+          results = []
+          for _ in range(n):
+              try:
+                  results.append(await anext(ait))
+              except StopAsyncIteration:
+                  break
+          return results
+
+      # ✅ Buffered async iteration
+      async def buffered_process(items: AsyncIterator, batch_size: int = 100):
+          batch = []
+          async for item in items:
+              batch.append(item)
+              if len(batch) >= batch_size:
+                  await process_batch(batch)
+                  batch = []
+          if batch:
+              await process_batch(batch)
+    severity: MEDIUM
+    docs_url: https://peps.python.org/pep-0525/
+
+  - id: py105
+    name: httpx Async Client
+    category: http
+    version: "3.9+"
+    description: |
+      Modern async HTTP client. Preferred over aiohttp for new projects.
+      HTTP/2 support, connection pooling, streaming.
+    text: httpx http client async requests api connection pool
+    example: |
+      import httpx
+      from typing import Any
+
+      # ✅ Async context manager (connection pooling)
+      async def fetch_users() -> list[dict[str, Any]]:
+          async with httpx.AsyncClient(
+              base_url="https://api.example.com",
+              timeout=httpx.Timeout(10.0),
+              headers={"Authorization": f"Bearer {token}"},
+          ) as client:
+              response = await client.get("/users")
+              response.raise_for_status()
+              return response.json()
+
+      # ✅ Parallel requests
+      async def fetch_multiple(urls: list[str]) -> list[dict]:
+          async with httpx.AsyncClient() as client:
+              async with asyncio.TaskGroup() as tg:
+                  tasks = [
+                      tg.create_task(client.get(url))
+                      for url in urls
+                  ]
+              return [t.result().json() for t in tasks]
+
+      # ✅ Streaming response
+      async def download_large_file(url: str, path: str):
+          async with httpx.AsyncClient() as client:
+              async with client.stream("GET", url) as response:
+                  async with aiofiles.open(path, "wb") as f:
+                      async for chunk in response.aiter_bytes(8192):
+                          await f.write(chunk)
+
+      # ✅ Retry with tenacity
+      from tenacity import retry, stop_after_attempt, wait_exponential
+
+      @retry(stop=stop_after_attempt(3), wait=wait_exponential())
+      async def fetch_with_retry(url: str) -> dict:
+          async with httpx.AsyncClient() as client:
+              response = await client.get(url)
+              response.raise_for_status()
+              return response.json()
+    severity: HIGH
+    docs_url: https://www.python-httpx.org/

package/.agent/skills/languages/python/data/core.yaml

@@ -0,0 +1,259 @@
+# =============================================================================
+# Python Core Patterns (Feb 2026)
+# Version: Python 3.13/3.14
+# =============================================================================
+
+metadata:
+  skill: python
+  domain: core
+  version: "3.14"
+  updated: "2026-02-05"
+  patterns_count: 6
+
+patterns:
+  - id: py001
+    name: Free-Threaded Python
+    category: performance
+    version: "3.13+"
+    description: |
+      GIL-free mode for true CPU parallelism.
+      Official in 3.14 (PEP 779). Requires python3.14t install.
+    text: free-threaded gil parallel multicore threading nogil
+    example: |
+      # Install free-threaded build: python3.14t
+      # Check: python -c "import sys; print(sys._is_gil_enabled())"
+
+      import threading
+      import time
+
+      def cpu_intensive(n: int) -> int:
+          """CPU-bound task - true parallel in free-threaded mode"""
+          return sum(i * i for i in range(n))
+
+      # ✅ Real parallelism without GIL
+      threads = [
+          threading.Thread(target=cpu_intensive, args=(10_000_000,))
+          for _ in range(4)
+      ]
+
+      start = time.perf_counter()
+      for t in threads:
+          t.start()
+      for t in threads:
+          t.join()
+      print(f"Parallel time: {time.perf_counter() - start:.2f}s")
+    severity: HIGH
+    docs_url: https://docs.python.org/3/howto/free-threading.html
+
+  - id: py002
+    name: JIT Compiler
+    category: performance
+    version: "3.13+"
+    description: |
+      Experimental Just-In-Time compiler for performance.
+      Enable with -X jit flag.
+    text: jit compiler performance optimization speed
+    example: |
+      # Enable JIT (experimental)
+      # python -X jit script.py
+
+      # Or via environment variable
+      # PYTHON_JIT=1 python script.py
+
+      # Check JIT status
+      import sys
+      if hasattr(sys, '_jit'):
+          print(f"JIT enabled: {sys._jit}")
+
+      # ✅ JIT benefits tight loops
+      def fibonacci(n: int) -> int:
+          if n <= 1:
+              return n
+          a, b = 0, 1
+          for _ in range(n - 1):
+              a, b = b, a + b
+          return b
+
+      # JIT compiles hot code paths automatically
+      result = fibonacci(1000)
+    severity: MEDIUM
+    docs_url: https://peps.python.org/pep-0744/
+
+  - id: py003
+    name: Template Strings (t-strings)
+    category: strings
+    version: "3.14"
+    description: |
+      PEP 750 template strings for custom string processing.
+      Similar to f-strings but with deferred evaluation.
+    text: template strings t-strings pep750 formatting
+    example: |
+      # ✅ Template strings (PEP 750) - Python 3.14
+      from string.templatelib import Template
+
+      name = "Alice"
+      age = 30
+
+      # t-string creates Template object (not evaluated immediately)
+      template = t"Hello, {name}! You are {age} years old."
+
+      # Access interpolation parts
+      for part in template.args:
+          print(f"Value: {part.value}, Expr: {part.expr}")
+
+      # ✅ Use case: SQL safe interpolation
+      def sql_escape(template: Template) -> str:
+          parts = []
+          for arg in template.args:
+              if isinstance(arg, str):
+                  parts.append(arg)
+              else:
+                  # Escape value safely
+                  parts.append(escape_sql(arg.value))
+          return "".join(parts)
+
+      query = t"SELECT * FROM users WHERE name = {user_input}"
+      safe_query = sql_escape(query)
+    severity: MEDIUM
+    docs_url: https://peps.python.org/pep-0750/
+
+  - id: py004
+    name: Modern Type Hints
+    category: typing
+    version: "3.12+"
+    description: |
+      Modern type hint syntax with generics, unions, and type aliases.
+      PEP 695 type parameter syntax.
+    text: type hints typing annotations generics typevar
+    example: |
+      from typing import TypeAlias, Annotated, Self
+      from dataclasses import dataclass
+
+      # ✅ PEP 695: Type parameter syntax (3.12+)
+      def first[T](items: list[T]) -> T | None:
+          return items[0] if items else None
+
+      # ✅ Generic class with new syntax
+      class Stack[T]:
+          def __init__(self) -> None:
+              self._items: list[T] = []
+          
+          def push(self, item: T) -> Self:
+              self._items.append(item)
+              return self
+          
+          def pop(self) -> T:
+              return self._items.pop()
+
+      # ✅ Type aliases
+      JsonValue: TypeAlias = str | int | float | bool | None | list["JsonValue"] | dict[str, "JsonValue"]
+
+      # ✅ Annotated for metadata
+      UserId = Annotated[int, "User identifier"]
+
+      # ✅ Union with | (3.10+)
+      def process(data: str | bytes) -> str:
+          if isinstance(data, bytes):
+              return data.decode()
+          return data
+    severity: HIGH
+    docs_url: https://peps.python.org/pep-0695/
+
+  - id: py005
+    name: Pattern Matching
+    category: control-flow
+    version: "3.10+"
+    description: |
+      Structural pattern matching with match-case.
+      Supports guards, captures, and class patterns.
+    text: pattern matching match case structural guards
+    example: |
+      from dataclasses import dataclass
+      from typing import Any
+
+      @dataclass
+      class Point:
+          x: float
+          y: float
+
+      def describe(obj: Any) -> str:
+          match obj:
+              # ✅ Literal patterns
+              case 0:
+                  return "zero"
+              
+              # ✅ Capture with guard
+              case int(n) if n > 0:
+                  return f"positive int: {n}"
+              
+              # ✅ Sequence unpacking
+              case [first, *rest]:
+                  return f"list starting with {first}"
+              
+              # ✅ Class pattern
+              case Point(x=0, y=0):
+                  return "origin"
+              case Point(x=x, y=y) if x == y:
+                  return f"on diagonal at {x}"
+              
+              # ✅ Dict pattern
+              case {"type": "user", "name": name}:
+                  return f"user: {name}"
+              
+              # ✅ Or pattern
+              case "yes" | "y" | "true":
+                  return "affirmative"
+              
+              case _:
+                  return "unknown"
+    severity: HIGH
+    docs_url: https://peps.python.org/pep-0636/
+
+  - id: py006
+    name: Dataclasses and attrs
+    category: data-structures
+    version: "3.7+"
+    description: |
+      Modern data classes with minimal boilerplate.
+      Use dataclasses for simple cases, attrs for advanced.
+    text: dataclass attrs frozen slots kw_only
+    example: |
+      from dataclasses import dataclass, field
+      from typing import ClassVar
+
+      # ✅ Modern dataclass (3.10+ features)
+      @dataclass(frozen=True, slots=True, kw_only=True)
+      class User:
+          id: int
+          name: str
+          email: str
+          tags: list[str] = field(default_factory=list)
+          _count: ClassVar[int] = 0
+          
+          def __post_init__(self) -> None:
+              User._count += 1
+
+      # ✅ With validation via __post_init__
+      @dataclass
+      class Config:
+          host: str
+          port: int = 8080
+          
+          def __post_init__(self) -> None:
+              if not 1 <= self.port <= 65535:
+                  raise ValueError(f"Invalid port: {self.port}")
+
+      # ✅ attrs for advanced cases
+      import attrs
+
+      @attrs.define
+      class Product:
+          name: str = attrs.field(validator=attrs.validators.min_len(1))
+          price: float = attrs.field(validator=attrs.validators.gt(0))
+          
+          @price.validator
+          def _check_price(self, attribute, value):
+              if value > 10000:
+                  raise ValueError("Price too high")
+    severity: MEDIUM
+    docs_url: https://docs.python.org/3/library/dataclasses.html