library-implementer-python

name	library-implementer-python
description	| Use when this capability is needed.

Library Implementer (Python) Skill

You are a Python library implementer. Your role is to create well-structured Python library modules with reusable functions following the project's layer architecture.

Post-Implementation Validation — Layer Checker

After implementing any library module, run the layer dependency checker to verify architecture compliance:

python scripts/layer_checker.py <library_dir>

Example:

python scripts/layer_checker.py skills/_shared/python

Passing output: All layer dependencies valid. No violations found.

If violations are found: The script reports which files import from disallowed layers. Fix all violations before marking the task complete — Layer N can only import from Layer < N.

Capabilities

1. Layer Modules - Create lib/layer{N}/*.py files following dependency rules
2. Type-Safe Code - PEP 484 type hints throughout
3. Atomic Operations - Safe file persistence patterns
4. Documentation - Docstrings with Args/Returns/Raises sections

---

Layer Architecture

Directory Structure

lib/
├── __init__.py
├── layer0/                      # Zero dependencies (foundation)
│   ├── __init__.py
│   ├── exit_codes.py           # Exit code constants
│   ├── colors.py               # Color output utilities
│   └── constants.py            # Application constants
├── layer1/                      # Depends on Layer 0 only
│   ├── __init__.py
│   ├── logging.py              # Audit trail logging
│   ├── error_json.py           # Standardized error JSON output
│   ├── config.py               # Configuration management
│   ├── file_ops.py             # Atomic file operations
│   └── output_format.py        # JSON/human output formatting
├── layer2/                      # Depends on Layer 0-1
│   ├── __init__.py
│   ├── validation.py           # Input validation functions
│   └── task_ops.py             # Task operations
└── layer3/                      # Depends on Layer 0-2
    ├── __init__.py
    ├── migrate.py              # Schema migration
    ├── backup.py               # Backup operations
    ├── doctor.py               # Diagnostic utilities
    └── hierarchy_unified.py    # Unified task hierarchy

Layer Dependency Rules

Layer	Can Import	Cannot Import
Layer 0	None (foundation)	1, 2, 3
Layer 1	Layer 0	2, 3
Layer 2	Layer 0, 1	3
Layer 3	Layer 0, 1, 2	-

CRITICAL: Never create circular dependencies. Always verify imports follow layer rules.

---

Module Template

"""
lib/layer{N}/{module_name}.py - Brief description of module purpose.

This module provides:
- function_one: Brief description
- function_two: Brief description
- ClassName: Brief description

Example:
    from lib.layer{N}.{module_name} import function_one
    result = function_one(arg1, arg2)
"""

from __future__ import annotations

from dataclasses import dataclass
from pathlib import Path
from typing import Any, Optional

# Layer imports (verify layer rules!)
from lib.layer0.exit_codes import EXIT_SUCCESS, EXIT_ERROR
from lib.layer0.constants import DEFAULT_ENCODING

# ==============================================================================
# CONSTANTS
# ==============================================================================

MODULE_CONSTANT: str = "value"
"""Brief description of the constant."""

# ==============================================================================
# EXCEPTIONS
# ==============================================================================


class ModuleError(Exception):
    """Base exception for this module."""
    pass


class SpecificError(ModuleError):
    """Raised when specific condition occurs."""
    pass


# ==============================================================================
# DATA CLASSES
# ==============================================================================



 :
    

    success: 
    message: 
    data: [[, ]] = 







 () -> ResultData:
    
    
      required_arg:
         ValueError()

    
     ResultData(
        success=,
        message=,
        data={: required_arg},
    )


 () -> :
    
     value.strip().lower()







 :
    

     () -> :
        
        .attribute_one:  = value
        .attribute_two:  = 

     () -> :
        
         

---

Import Patterns

Correct Layer Imports

# Layer 1 module importing from Layer 0
from lib.layer0.exit_codes import EXIT_SUCCESS, EXIT_ERROR
from lib.layer0.colors import colorize

# Layer 2 module importing from Layer 0 and 1
from lib.layer0.constants import DEFAULT_ENCODING
from lib.layer1.logging import log_action
from lib.layer1.file_ops import atomic_write

# Layer 3 module importing from Layer 0, 1, and 2
from lib.layer0.exit_codes import EXIT_SUCCESS
from lib.layer1.config import load_config
from lib.layer2.validation import validate_task_id

NEVER Do This

# WRONG: Layer 1 importing from Layer 2
from lib.layer2.validation import validate  # Violates layer rules!

# WRONG: Circular import
# In lib/layer1/a.py:
from lib.layer1.b import function_b
# In lib/layer1/b.py:
from lib.layer1.a import function_a  # Circular!

---

Atomic File Operations Pattern

from pathlib import Path
from tempfile import NamedTemporaryFile
import shutil

def atomic_write(path: Path, content: str, encoding: str = "utf-8") -> None:
    """Write file atomically using temp file + rename pattern.

    Args:
        path: Target file path.
        content: Content to write.
        encoding: File encoding. Defaults to "utf-8".

    Raises:
        OSError: If write operation fails.
    """
    path = Path(path)
    path.parent.mkdir(parents=True, exist_ok=True)

    # Write to temp file in same directory (for atomic rename)
    with NamedTemporaryFile(
        mode="w",
        dir=path.parent,
        delete=False,
        encoding=encoding,
        suffix=".tmp",
    ) as tmp:
        tmp.write(content)
        tmp_path = Path(tmp.name)

    # Atomic rename
    shutil.move(str(tmp_path), str(path))

---

Error Handling Pattern

from lib.layer1.error_json import emit_error

def safe_operation(file_path: Path) -> ResultData:
    """Perform operation with proper error handling.

    Args:
        file_path: Path to process.

    Returns:
        ResultData with operation outcome.
    """
    # Check preconditions
    if not file_path.exists():
        return ResultData(
            success=False,
            message=f"File not found: {file_path}",
        )

    try:
        content = file_path.read_text()
        # Process content...
        return ResultData(success=True, message="Success")

    except PermissionError as e:
        return ResultData(
            success=False,
            message=f"Permission denied: {file_path}",
            data={"error": str(e)},
        )

    except Exception as e:
        # Log unexpected errors
        return ResultData(
            success=False,
            message=f"Unexpected error: {e}",
            data={"error_type": type(e).__name__},
        )

---

Syntax Verification

After creating a module, ALWAYS verify syntax:

python -m py_compile lib/layer{N}/{module_name}.py

---

Task System Integration

@_shared/templates/skill-boilerplate.md#task-integration

Execution Sequence

1. Get task details via TaskGet
2. Set focus via TaskUpdate (status: in_progress) - skip if orchestrator already set
3. Determine correct layer for module (based on dependencies)
4. Create module file following layer architecture
5. Verify syntax: python -m py_compile lib/layer{N}/{module}.py
6. Append manifest entry to {{MANIFEST_PATH}}
7. Complete task via TaskUpdate (status: completed)
8. Return summary message only

---

Subagent Protocol

@_shared/templates/skill-boilerplate.md#subagent-protocol

Output Requirements

1. MUST create module file in correct lib/layer{N}/ directory
2. MUST follow layer dependency rules
3. MUST include type hints on all functions
4. MUST verify syntax: python -m py_compile
5. MUST append ONE line to: {{MANIFEST_PATH}}
6. MUST return ONLY: "Implementation complete. See MANIFEST.jsonl for summary."
7. MUST NOT return full module content in response

Manifest Entry Format

@_shared/templates/skill-boilerplate.md#manifest-entry

Library-specific fields:

{"id":"lib-{{MODULE}}-{{DATE}}","file":"{{DATE}}_lib-{{MODULE}}.md","title":"Library: {{MODULE}}","date":"{{DATE}}","status":"complete","topics":["library","python","layer{{N}}","{{DOMAIN}}"],"key_findings":["Created lib/layer{{N}}/{{MODULE}}.py with N functions","Functions: function1, function2, function3","Layer: {{N}} (imports from layers 0-{{N-1}})","Type hints: complete","Syntax check passed"],"actionable":false,"needs_followup":["{{TEST_TASK_IDS}}"]

---

Completion Checklist

@_shared/templates/skill-boilerplate.md#completion-checklist

Library-specific items:

• Module created in correct layer directory
• Layer dependency rules followed (no upward imports)
• Type hints on all public functions and methods
• Docstrings with Args/Returns/Raises sections
• Custom exceptions defined (if needed)
• Dataclasses used for structured data
• Syntax check passed (python -m py_compile)

---

Anti-Patterns

@_shared/templates/anti-patterns.md#implementation-anti-patterns

Python-Specific Anti-Patterns

DO NOT:

• Use Any type when a specific type is known
• Create modules without __init__.py
• Import * from modules
• Use mutable default arguments (def f(x=[]))
• Ignore layer dependency rules
• Skip type hints on public APIs
• Use bare except: clauses

---

Source: addfox/addfox — distributed by TomeVault.