plating 0.0.0.dev0__py3-none-any.whl

plating/plater.py

@@ -0,0 +1,487 @@
+#
+# plating/plater.py
+#
+"""Garnish documentation plating system."""
+
+from pathlib import Path
+
+from jinja2 import DictLoader, Environment, select_autoescape
+from provide.foundation import logger
+
+from plating.errors import PlatingRenderError, TemplateError, handle_error
+from plating.plating import PlatingBundle, PlatingDiscovery
+from plating.schema import SchemaProcessor
+
+
+class PlatingPlater:
+    """Documentation plater using .plating bundles."""
+
+    def __init__(
+        self,
+        bundles: list[PlatingBundle] | None = None,
+        schema_processor: SchemaProcessor | None = None,
+    ):
+        """Initialize plater with bundles and optional schema processor.
+
+        Args:
+            bundles: List of PlatingBundle objects to render
+            schema_processor: Optional schema processor for schema extraction
+        """
+        self.bundles = bundles or []
+        self.schema_processor = schema_processor
+        self.provider_schema = None
+
+        if self.schema_processor:
+            try:
+                self.provider_schema = self.schema_processor.extract_provider_schema()
+            except Exception as e:
+                handle_error(e, logger)
+                logger.warning(f"Failed to extract provider schema: {e}")
+
+    def plate(self, output_dir: Path, force: bool = False) -> None:
+        """Plate all bundles to the output directory.
+
+        Args:
+            output_dir: Directory to write plated documentation
+            force: Force plating even if output exists
+        """
+        output_dir = Path(output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        for bundle in self.bundles:
+            try:
+                self._plate_bundle(bundle, output_dir, force)
+            except PlatingRenderError:
+                raise  # Re-raise our custom errors
+            except Exception as e:
+                error = PlatingRenderError(bundle.name, str(e))
+                handle_error(error, logger)
+                logger.error(f"Failed to plate bundle {bundle.name}: {e}")
+
+    def _plate_bundle(
+        self, bundle: PlatingBundle, output_dir: Path, force: bool
+    ) -> None:
+        """Plate a single bundle.
+
+        Args:
+            bundle: The PlatingBundle to render
+            output_dir: Directory to write output
+            force: Force overwrite existing files
+        """
+        # Load bundle assets
+        logger.trace(f"Loading assets for bundle {bundle.name}")
+        template_content = bundle.load_main_template()
+        if not template_content:
+            logger.debug(f"No template found for {bundle.name}, skipping")
+            return
+
+        examples = bundle.load_examples()
+        partials = bundle.load_partials()
+
+        # Create plating context
+        context = _create_plating_context(
+            bundle,
+            self._get_schema_for_component(bundle),
+            self.schema_processor.provider_name
+            if self.schema_processor
+            else "provider",
+        )
+
+        # Add examples to context
+        context["examples"] = examples
+
+        # Plate template
+        try:
+            plated = self._plate_template(template_content, context, partials)
+        except Exception as e:
+            logger.error(f"Template rendering failed for {bundle.name}: {e}")
+            return  # Skip this bundle on error
+
+        # Determine output path
+        subdir = _get_output_subdir(bundle.component_type)
+        output_path = output_dir / subdir / f"{bundle.name}.md"
+
+        # Check if file exists and force flag
+        if output_path.exists() and not force:
+            logger.debug(
+                f"Output file {output_path} exists, skipping (use force=True to overwrite)"
+            )
+            return
+
+        # Write output
+        try:
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            output_path.write_text(plated)
+            logger.info(f"Successfully plated {bundle.name} to {output_path}")
+        except OSError as e:
+            raise PlatingRenderError(bundle.name, f"Failed to write output file: {e}")
+
+    def _get_schema_for_component(self, bundle: PlatingBundle) -> dict | None:
+        """Get schema for a component from the provider schema.
+
+        Args:
+            bundle: The bundle to get schema for
+
+        Returns:
+            Component schema dict or None
+        """
+        if not self.provider_schema:
+            return None
+
+        # Try to find the component schema
+        provider_schemas = self.provider_schema.get("provider_schemas", {})
+        for provider_key, provider_data in provider_schemas.items():
+            # Check resources
+            if bundle.component_type == "resource":
+                schemas = provider_data.get("resource_schemas", {})
+                if bundle.name in schemas:
+                    return schemas[bundle.name]
+                if f"pyvider_{bundle.name}" in schemas:
+                    return schemas[f"pyvider_{bundle.name}"]
+
+            # Check data sources
+            elif bundle.component_type == "data_source":
+                schemas = provider_data.get("data_source_schemas", {})
+                if bundle.name in schemas:
+                    return schemas[bundle.name]
+                if f"pyvider_{bundle.name}" in schemas:
+                    return schemas[f"pyvider_{bundle.name}"]
+
+            # Check functions
+            elif bundle.component_type == "function":
+                functions = provider_data.get("functions", {})
+                if bundle.name in functions:
+                    return functions[bundle.name]
+                if f"pyvider_{bundle.name}" in functions:
+                    return functions[f"pyvider_{bundle.name}"]
+
+        return None
+
+    def _plate_template(
+        self, template_content: str, context: dict, partials: dict[str, str]
+    ) -> str:
+        """Plate a Jinja2 template with context.
+
+        Args:
+            template_content: The template string
+            context: Rendering context dictionary
+            partials: Partial templates dictionary
+
+        Returns:
+            Plated template string
+        """
+        # Set up Jinja2 environment
+        templates = {"main.tmpl": template_content}
+        templates.update(partials)
+
+        env = Environment(
+            loader=DictLoader(templates),
+            autoescape=select_autoescape(["html", "xml"]),
+        )
+
+        # Add custom template functions
+        env.globals["schema"] = lambda: context.get("schema_markdown", "")
+        env.globals["example"] = lambda name: _format_example(
+            context.get("examples", {}).get(name, "")
+        )
+        env.globals["include"] = lambda filename: partials.get(filename, "")
+
+        # Plate template
+        template = env.get_template("main.tmpl")
+        return template.render(**context)
+
+
+def _create_plating_context(
+    bundle: PlatingBundle, schema: dict | None, provider_name: str
+) -> dict:
+    """Create plating context for a bundle.
+
+    Args:
+        bundle: The PlatingBundle
+        schema: Component schema dict or None
+        provider_name: Name of the provider
+
+    Returns:
+        Context dictionary for template plating
+    """
+    context = {
+        "name": bundle.name,
+        "type": _format_component_type(bundle.component_type),
+        "provider_name": provider_name,
+        "component_type": bundle.component_type,
+    }
+
+    if schema:
+        context["description"] = schema.get("description", "")
+        context["schema_markdown"] = _plate_schema_markdown(schema)
+
+        # Add function-specific fields
+        if bundle.component_type == "function" and "signature" in schema:
+            context["signature"] = _format_function_signature(schema)
+            context["arguments"] = _format_function_arguments(schema)
+
+    return context
+
+
+def _format_component_type(component_type: str) -> str:
+    """Format component type for display.
+
+    Args:
+        component_type: Raw component type
+
+    Returns:
+        Formatted component type
+    """
+    return {
+        "resource": "Resource",
+        "data_source": "Data Source",
+        "function": "Function",
+    }.get(component_type, component_type.title())
+
+
+def _get_output_subdir(component_type: str) -> str:
+    """Get output subdirectory for component type.
+
+    Args:
+        component_type: Component type
+
+    Returns:
+        Output subdirectory name
+    """
+    return {
+        "resource": "resources",
+        "data_source": "data_sources",
+        "function": "functions",
+    }.get(component_type, "resources")
+
+
+def _format_example(example_code: str) -> str:
+    """Format example code for display.
+
+    Args:
+        example_code: Raw example code
+
+    Returns:
+        Formatted example with code block
+    """
+    if not example_code:
+        return ""
+    return f"```terraform\n{example_code}\n```"
+
+
+def _plate_schema_markdown(schema: dict) -> str:
+    """Plate schema to markdown format.
+
+    Args:
+        schema: Schema dictionary
+
+    Returns:
+        Markdown formatted schema
+    """
+    lines = ["## Schema", ""]
+
+    block = schema.get("block", {})
+    attributes = block.get("attributes", {})
+
+    # Separate attributes by type
+    required_attrs = []
+    optional_attrs = []
+    computed_attrs = []
+
+    for attr_name, attr_def in attributes.items():
+        attr_type = _format_type_string(attr_def.get("type"))
+        description = attr_def.get("description", "")
+
+        if attr_def.get("required"):
+            required_attrs.append((attr_name, attr_type, description))
+        elif attr_def.get("computed") and not attr_def.get("optional"):
+            computed_attrs.append((attr_name, attr_type, description))
+        else:
+            optional_attrs.append((attr_name, attr_type, description))
+
+    # Format sections
+    if required_attrs:
+        lines.extend(["### Required", ""])
+        for name, type_str, desc in required_attrs:
+            lines.append(f"- `{name}` ({type_str}) - {desc}")
+        lines.append("")
+
+    if optional_attrs:
+        lines.extend(["### Optional", ""])
+        for name, type_str, desc in optional_attrs:
+            lines.append(f"- `{name}` ({type_str}) - {desc}")
+        lines.append("")
+
+    if computed_attrs:
+        lines.extend(["### Read-Only", ""])
+        for name, type_str, desc in computed_attrs:
+            lines.append(f"- `{name}` ({type_str}) - {desc}")
+        lines.append("")
+
+    # Handle nested blocks
+    blocks = block.get("block_types", {})
+    if blocks:
+        lines.extend(["### Blocks", ""])
+        for block_name, block_def in blocks.items():
+            max_items = block_def.get("max_items", 0)
+            if max_items == 1:
+                lines.append(f"- `{block_name}` (Optional)")
+            else:
+                lines.append(f"- `{block_name}` (Optional, List)")
+        lines.append("")
+
+    # Return empty string if no content was generated
+    if len(lines) == 2:  # Just "## Schema" and empty line
+        return ""
+
+    return "\n".join(lines)
+
+
+def _format_type_string(type_info) -> str:
+    """Format type information to human-readable string.
+
+    Args:
+        type_info: Type information (string, list, or dict)
+
+    Returns:
+        Formatted type string
+    """
+    if not type_info:
+        return "Dynamic"
+
+    if isinstance(type_info, str):
+        return type_info.title()
+
+    if isinstance(type_info, list) and len(type_info) >= 2:
+        container_type = type_info[0]
+        element_type = type_info[1]
+
+        if container_type == "list":
+            return f"List of {_format_type_string(element_type)}"
+        elif container_type == "set":
+            return f"Set of {_format_type_string(element_type)}"
+        elif container_type == "map":
+            return f"Map of {_format_type_string(element_type)}"
+        elif container_type == "object":
+            if isinstance(element_type, dict):
+                attrs = ", ".join(
+                    f"{k}: {_format_type_string(v)}" for k, v in element_type.items()
+                )
+                return f"Object({attrs})"
+            return "Object"
+
+    return "Dynamic"
+
+
+def _format_function_signature(schema: dict) -> str:
+    """Format function signature from schema.
+
+    Args:
+        schema: Function schema
+
+    Returns:
+        Formatted function signature
+    """
+    signature = schema.get("signature", {})
+    params = []
+
+    # Parameters
+    for param in signature.get("parameters", []):
+        param_name = param.get("name", "arg")
+        param_type = param.get("type", "any")
+        params.append(f"{param_name}: {param_type}")
+
+    # Variadic parameter
+    if "variadic_parameter" in signature:
+        variadic = signature["variadic_parameter"]
+        variadic_name = variadic.get("name", "args")
+        variadic_type = variadic.get("type", "any")
+        params.append(f"...{variadic_name}: {variadic_type}")
+
+    # Return type
+    return_type = signature.get("return_type", "any")
+    param_str = ", ".join(params)
+
+    return f"({param_str}) -> {return_type}"
+
+
+def _format_function_arguments(schema: dict) -> str:
+    """Format function arguments from schema.
+
+    Args:
+        schema: Function schema
+
+    Returns:
+        Formatted arguments list
+    """
+    signature = schema.get("signature", {})
+    lines = []
+
+    # Parameters
+    for param in signature.get("parameters", []):
+        param_name = param.get("name", "arg")
+        param_type = param.get("type", "any")
+        description = param.get("description", "")
+        lines.append(f"- `{param_name}` ({param_type}) - {description}")
+
+    # Variadic parameter
+    if "variadic_parameter" in signature:
+        variadic = signature["variadic_parameter"]
+        variadic_name = variadic.get("name", "args")
+        variadic_type = variadic.get("type", "any")
+        description = variadic.get("description", "")
+        lines.append(f"- `...{variadic_name}` ({variadic_type}) - {description}")
+
+    return "\n".join(lines)
+
+
+def generate_docs(
+    output_dir: Path | str = "docs",
+    provider_name: str | None = None,
+    package_name: str = "pyvider.components",
+    component_type: str | None = None,
+    force: bool = False,
+) -> None:
+    """Generate documentation for all discovered plating bundles.
+
+    This is the main entry point for documentation generation.
+
+    Args:
+        output_dir: Directory to write documentation
+        provider_name: Optional provider name for schema extraction
+        package_name: Package to search for plating bundles
+        component_type: Optional filter for component type
+        force: Force overwrite existing files
+    """
+    # Discover bundles
+    discovery = PlatingDiscovery(package_name)
+    bundles = discovery.discover_bundles(component_type)
+
+    if not bundles:
+        logger.warning(f"No plating bundles found in {package_name}")
+        return
+
+    logger.info(f"Found {len(bundles)} plating bundles")
+
+    # Initialize schema processor if provider name given
+    schema_processor = None
+    if provider_name:
+        try:
+            # Create mock generator for schema processor
+            mock_generator = type(
+                "MockGenerator",
+                (),
+                {"provider_name": provider_name, "provider_dir": Path.cwd()},
+            )()
+            schema_processor = SchemaProcessor(mock_generator)
+        except Exception as e:
+            logger.warning(f"Failed to initialize schema processor: {e}")
+
+    # Create renderer and plate
+    plater = PlatingPlater(bundles, schema_processor)
+    plater.plate(Path(output_dir), force)
+
+    logger.info(f"Documentation generated in {output_dir}")
+
+
+# 🍲🥄📄🪄

plating/plating.py

@@ -0,0 +1,207 @@
+#
+# plating/garnish.py
+#
+"""Garnish bundle discovery and management."""
+
+import importlib.util
+from pathlib import Path
+
+import attrs
+
+
+@attrs.define
+class PlatingBundle:
+    """Represents a single .plating bundle with its assets."""
+
+    name: str
+    plating_dir: Path
+    component_type: str  # "resource", "data_source", "function"
+
+    @property
+    def docs_dir(self) -> Path:
+        """Directory containing documentation templates and partials."""
+        return self.plating_dir / "docs"
+
+    @property
+    def examples_dir(self) -> Path:
+        """Directory containing example Terraform files."""
+        return self.plating_dir / "examples"
+
+    @property
+    def fixtures_dir(self) -> Path:
+        """Directory containing fixture files for tests (inside examples dir)."""
+        return self.examples_dir / "fixtures"
+
+    def load_main_template(self) -> str | None:
+        """Load the main template file for this component."""
+        # Main template is typically <component_name>.tmpl.md
+        template_file = self.docs_dir / f"{self.name}.tmpl.md"
+
+        if not template_file.exists():
+            return None
+
+        try:
+            return template_file.read_text(encoding="utf-8")
+        except Exception:
+            return None
+
+    def load_examples(self) -> dict[str, str]:
+        """Load all example files as a dictionary."""
+        examples = {}
+
+        if not self.examples_dir.exists():
+            return examples
+
+        for example_file in self.examples_dir.glob("*.tf"):
+            try:
+                examples[example_file.stem] = example_file.read_text(encoding="utf-8")
+            except Exception:
+                continue
+
+        return examples
+
+    def load_partials(self) -> dict[str, str]:
+        """Load all partial files from docs directory.
+
+        Partials are files starting with underscore (_) in the docs directory.
+        """
+        partials = {}
+
+        if not self.docs_dir.exists():
+            return partials
+
+        # Load only files starting with underscore (partial convention)
+        for partial_file in self.docs_dir.glob("_*"):
+            if partial_file.is_file():
+                try:
+                    partials[partial_file.name] = partial_file.read_text(
+                        encoding="utf-8"
+                    )
+                except Exception:
+                    continue
+
+        return partials
+
+    def load_fixtures(self) -> dict[str, str]:
+        """Load all fixture files from fixtures directory."""
+        fixtures = {}
+
+        if not self.fixtures_dir.exists():
+            return fixtures
+
+        for fixture_file in self.fixtures_dir.rglob("*"):
+            if fixture_file.is_file():
+                try:
+                    # Use relative path from fixtures dir as key
+                    rel_path = fixture_file.relative_to(self.fixtures_dir)
+                    fixtures[str(rel_path)] = fixture_file.read_text(encoding="utf-8")
+                except Exception:
+                    continue
+
+        return fixtures
+
+
+class PlatingDiscovery:
+    """Discovers .plating bundles from installed packages."""
+
+    def __init__(self, package_name: str = "pyvider.components"):
+        self.package_name = package_name
+
+    def discover_bundles(
+        self, component_type: str | None = None
+    ) -> list[PlatingBundle]:
+        """Discover all .plating bundles from the installed package."""
+        bundles = []
+
+        # Find the package location
+        try:
+            spec = importlib.util.find_spec(self.package_name)
+            if not spec or not spec.origin:
+                return bundles
+        except (ModuleNotFoundError, ValueError):
+            # Package doesn't exist or invalid package name
+            return bundles
+
+        package_path = Path(spec.origin).parent
+
+        # Search for .plating directories
+        for plating_dir in package_path.rglob("*.plating"):
+            if not plating_dir.is_dir():
+                continue
+
+            # Skip hidden directories
+            if plating_dir.name.startswith("."):
+                continue
+
+            # Determine component type from path
+            bundle_component_type = self._determine_component_type(plating_dir)
+            if component_type and bundle_component_type != component_type:
+                continue
+
+            # Check if this is a multi-component bundle
+            sub_component_bundles = self._discover_sub_components(
+                plating_dir, bundle_component_type
+            )
+            if sub_component_bundles:
+                # Multi-component bundle - use individual components
+                bundles.extend(sub_component_bundles)
+            else:
+                # Single component bundle
+                component_name = plating_dir.name.replace(".plating", "")
+
+                bundle = PlatingBundle(
+                    name=component_name,
+                    plating_dir=plating_dir,
+                    component_type=bundle_component_type,
+                )
+
+                bundles.append(bundle)
+
+        return bundles
+
+    def _discover_sub_components(
+        self, plating_dir: Path, component_type: str
+    ) -> list[PlatingBundle]:
+        """Discover individual components within a multi-component .plating bundle."""
+        sub_bundles = []
+
+        # Look for subdirectories that contain docs/ and examples/ folders
+        for item in plating_dir.iterdir():
+            if not item.is_dir():
+                continue
+
+            # Check if this looks like a component directory
+            docs_dir = item / "docs"
+            if docs_dir.exists() and docs_dir.is_dir():
+                # Determine component type from subdirectory name
+                sub_component_type = item.name
+                if sub_component_type not in ["resource", "data_source", "function"]:
+                    # Fall back to parent component type if not a recognized type
+                    sub_component_type = component_type
+
+                # This appears to be an individual component
+                bundle = PlatingBundle(
+                    name=item.name,  # Use the directory name as component name
+                    plating_dir=item,  # Point to the individual component directory
+                    component_type=sub_component_type,
+                )
+                sub_bundles.append(bundle)
+
+        return sub_bundles
+
+    def _determine_component_type(self, plating_dir: Path) -> str:
+        """Determine component type from the .plating directory path."""
+        path_parts = plating_dir.parts
+
+        if "resources" in path_parts:
+            return "resource"
+        elif "data_sources" in path_parts:
+            return "data_source"
+        elif "functions" in path_parts:
+            return "function"
+        else:
+            # Default to resource if unclear
+            return "resource"
+
+
+# 🍲🥄📄🪄