nao-core 0.0.38__py3-none-manylinux2014_aarch64.whl

nao_core/templates/context.py

@@ -0,0 +1,193 @@
+"""Context object for Jinja templates in the nao context folder.
+
+This module provides the `nao` object that is exposed to user Jinja templates,
+allowing them to access data from various providers like Notion, databases, etc.
+
+Example template usage:
+    {{ nao.notion.page('https://notion.so/...').content }}
+    {{ nao.notion.page('abc123').title }}
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import cached_property
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from nao_core.config.base import NaoConfig
+
+
+@dataclass
+class NotionPage:
+    """Represents a Notion page with lazy-loaded content."""
+
+    page_url_or_id: str
+    api_key: str
+    _data: dict[str, Any] | None = None
+
+    def _load(self) -> dict[str, Any]:
+        """Lazily load page data from Notion API."""
+        if self._data is None:
+            from notion2md.exporter.block import StringExporter
+            from notion_client import Client
+
+            from nao_core.commands.sync.providers.notion.provider import (
+                extract_page_id,
+                get_page_title,
+                strip_images,
+            )
+
+            page_id = extract_page_id(self.page_url_or_id)
+            client = Client(auth=self.api_key)
+            title = get_page_title(client, page_id)
+
+            # Export to markdown
+            md_exporter = StringExporter(block_id=page_id, token=self.api_key)
+            markdown = md_exporter.export()
+            markdown = strip_images(markdown)
+
+            self._data = {
+                "id": page_id,
+                "title": title,
+                "content": markdown,
+                "url": f"https://notion.so/{page_id}",
+            }
+        return self._data
+
+    @property
+    def id(self) -> str:
+        """The Notion page ID."""
+        return self._load()["id"]
+
+    @property
+    def title(self) -> str:
+        """The page title."""
+        return self._load()["title"]
+
+    @property
+    def content(self) -> str:
+        """The page content as markdown (without frontmatter)."""
+        return self._load()["content"]
+
+    @property
+    def url(self) -> str:
+        """The Notion page URL."""
+        return self._load()["url"]
+
+    def __str__(self) -> str:
+        """Return the content when used directly in a template."""
+        return self.content
+
+
+class NotionProvider:
+    """Provider interface for accessing Notion data in templates."""
+
+    def __init__(self, config: NaoConfig):
+        self._config = config
+        self._page_cache: dict[str, NotionPage] = {}
+
+    def _get_api_key_for_page(self, page_url_or_id: str) -> str:
+        """Find the API key that can access a given page.
+
+        First checks if the page is in any configured Notion config's pages list,
+        otherwise uses the first available API key.
+        """
+        from nao_core.commands.sync.providers.notion.provider import extract_page_id
+
+        try:
+            page_id = extract_page_id(page_url_or_id)
+        except ValueError:
+            page_id = page_url_or_id
+
+        # Check if page is in any config
+        if self._config.notion is None or self._config.notion.pages is None:
+            raise ValueError("No Notion configuration found")
+
+        for configured_page in self._config.notion.pages:
+            try:
+                if extract_page_id(configured_page) == page_id:
+                    return self._config.notion.api_key
+            except ValueError:
+                continue
+
+        # Fallback to the configured API key (page not in explicit list, but config exists)
+        return self._config.notion.api_key
+
+    def page(self, page_url_or_id: str) -> NotionPage:
+        """Get a Notion page by URL or ID.
+
+        Args:
+            page_url_or_id: Either a full Notion URL or a 32-character page ID.
+
+        Returns:
+            NotionPage object with lazy-loaded content.
+
+        Example:
+            {{ nao.notion.page('https://notion.so/My-Page-abc123').content }}
+            {{ nao.notion.page('abc123def456...').title }}
+        """
+        if page_url_or_id not in self._page_cache:
+            api_key = self._get_api_key_for_page(page_url_or_id)
+            self._page_cache[page_url_or_id] = NotionPage(
+                page_url_or_id=page_url_or_id,
+                api_key=api_key,
+            )
+        return self._page_cache[page_url_or_id]
+
+
+class NaoContext:
+    """The main context object exposed as `nao` in user templates.
+
+    This object provides access to data from various providers like Notion,
+    databases, and repositories. Data is lazy-loaded to avoid unnecessary
+    API calls.
+
+    Example template usage:
+        {{ nao.notion.page('url').content }}
+        {{ nao.config.project_name }}
+    """
+
+    def __init__(self, config: NaoConfig):
+        self._config = config
+
+    @cached_property
+    def notion(self) -> NotionProvider:
+        """Access Notion pages and databases.
+
+        Example:
+            {{ nao.notion.page('https://notion.so/...').content }}
+        """
+        return NotionProvider(self._config)
+
+    @property
+    def config(self) -> NaoConfig:
+        """Access the nao configuration.
+
+        Example:
+            {{ nao.config.project_name }}
+        """
+        return self._config
+
+    # Future providers can be added here:
+    # @cached_property
+    # def database(self) -> DatabaseProvider:
+    #     """Access database tables and schemas."""
+    #     return DatabaseProvider(self._config)
+    #
+    # @cached_property
+    # def repo(self) -> RepoProvider:
+    #     """Access git repository files."""
+    #     return RepoProvider(self._config)
+
+
+def create_nao_context(config: NaoConfig) -> NaoContext:
+    """Create a NaoContext for template rendering.
+
+    Args:
+        config: The nao configuration.
+
+    Returns:
+        A NaoContext instance to be used as `nao` in templates.
+    """
+    return NaoContext(config)

nao_core/templates/defaults/databases/columns.md.j2

@@ -0,0 +1,23 @@
+{#
+  Template: columns.md.j2
+  Description: Generates column documentation for a database table
+  
+  Available variables:
+    - table_name (str): Name of the table
+    - dataset (str): Schema/dataset name
+    - columns (list): List of column dictionaries with:
+        - name (str): Column name
+        - type (str): Data type
+        - nullable (bool): Whether the column allows nulls
+        - description (str|None): Column description if available
+    - column_count (int): Total number of columns
+#}
+# {{ table_name }}
+
+**Dataset:** `{{ dataset }}`
+
+## Columns ({{ column_count }})
+
+{% for col in columns %}
+- {{ col.name }} ({{ col.type }}{% if col.description %}, "{{ col.description | truncate_middle(256) }}"{% endif %})
+{% endfor %}

nao_core/templates/defaults/databases/description.md.j2

@@ -0,0 +1,32 @@
+{#
+  Template: description.md.j2
+  Description: Generates table metadata and description documentation
+  
+  Available variables:
+    - table_name (str): Name of the table
+    - dataset (str): Schema/dataset name
+    - row_count (int): Total number of rows in the table
+    - column_count (int): Number of columns in the table
+    - description (str|None): Table description if available
+    - columns (list): List of column dictionaries with:
+        - name (str): Column name
+        - type (str): Data type
+#}
+# {{ table_name }}
+
+**Dataset:** `{{ dataset }}`
+
+## Table Metadata
+
+| Property | Value |
+|----------|-------|
+| **Row Count** | {{ "{:,}".format(row_count) }} |
+| **Column Count** | {{ column_count }} |
+
+## Description
+
+{% if description %}
+{{ description }}
+{% else %}
+_No description available._
+{% endif %}

nao_core/templates/defaults/databases/preview.md.j2

@@ -0,0 +1,22 @@
+{#
+  Template: preview.md.j2
+  Description: Generates a preview of table rows in JSONL format
+  
+  Available variables:
+    - table_name (str): Name of the table
+    - dataset (str): Schema/dataset name
+    - rows (list): List of row dictionaries (first N rows of the table)
+    - row_count (int): Number of preview rows shown
+    - columns (list): List of column dictionaries with:
+        - name (str): Column name
+        - type (str): Data type
+#}
+# {{ table_name }} - Preview
+
+**Dataset:** `{{ dataset }}`
+
+## Rows ({{ row_count }})
+
+{% for row in rows %}
+- {{ row | to_json }}
+{% endfor %}

nao_core/templates/defaults/databases/profiling.md.j2

@@ -0,0 +1,34 @@
+{#
+  Template: profiling.md.j2
+  Description: Generates column-level statistics and profiling data
+  
+  Available variables:
+    - table_name (str): Name of the table
+    - dataset (str): Schema/dataset name
+    - column_stats (list): List of column statistics dictionaries with:
+        - name (str): Column name
+        - type (str): Data type
+        - null_count (int): Number of null values
+        - unique_count (int): Number of unique values
+        - min_value (str|None): Minimum value (for numeric/temporal columns)
+        - max_value (str|None): Maximum value (for numeric/temporal columns)
+        - error (str|None): Error message if stats couldn't be computed
+    - columns (list): List of column dictionaries with:
+        - name (str): Column name
+        - type (str): Data type
+#}
+# {{ table_name }} - Profiling
+
+**Dataset:** `{{ dataset }}`
+
+## Column Statistics
+
+| Column | Type | Nulls | Unique | Min | Max |
+|--------|------|-------|--------|-----|-----|
+{% for stat in column_stats %}
+{% if stat.error %}
+| `{{ stat.name }}` | `{{ stat.type }}` | Error: {{ stat.error }} | | | |
+{% else %}
+| `{{ stat.name }}` | `{{ stat.type }}` | {{ "{:,}".format(stat.null_count) }} | {{ "{:,}".format(stat.unique_count) }} | {{ stat.min_value or "" }} | {{ stat.max_value or "" }} |
+{% endif %}
+{% endfor %}

nao_core/templates/engine.py

@@ -0,0 +1,133 @@
+"""Template engine for rendering Jinja2 templates with user overrides."""
+
+from pathlib import Path
+from typing import Any
+
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+# Path to the default templates shipped with nao
+DEFAULT_TEMPLATES_DIR = Path(__file__).parent / "defaults"
+
+
+class TemplateEngine:
+    """Jinja2 template engine with support for user overrides.
+
+    Templates are looked up in the following order:
+    1. User's project `templates/` directory (if exists)
+    2. Default templates shipped with nao
+
+    This allows users to customize output by creating a `templates/` folder
+    in their nao project and adding templates with the same names as the defaults.
+
+    Example:
+        If the default template is `databases/preview.md.j2`, the user can
+        override it by creating `<project_root>/templates/databases/preview.md.j2`.
+    """
+
+    def __init__(self, project_path: Path | None = None):
+        """Initialize the template engine.
+
+        Args:
+            project_path: Path to the nao project root. If provided,
+                          templates in `<project_path>/templates/` will
+                          take precedence over defaults.
+        """
+        self.project_path = project_path
+        self.user_templates_dir = project_path / "templates" if project_path else None
+
+        # Build list of template directories (user templates first for override)
+        loader_paths: list[Path] = []
+        if self.user_templates_dir and self.user_templates_dir.exists():
+            loader_paths.append(self.user_templates_dir)
+        loader_paths.append(DEFAULT_TEMPLATES_DIR)
+
+        self.env = Environment(
+            loader=FileSystemLoader([str(p) for p in loader_paths]),
+            autoescape=select_autoescape(default_for_string=False, default=False),
+            trim_blocks=True,
+            lstrip_blocks=True,
+            keep_trailing_newline=True,
+        )
+
+        # Register custom filters
+        self._register_filters()
+
+    def _register_filters(self) -> None:
+        """Register custom Jinja2 filters for templates."""
+        import json
+
+        def to_json(value: Any, indent: int | None = None) -> str:
+            """Convert value to JSON string."""
+            return json.dumps(value, indent=indent, default=str)
+
+        def truncate_middle(text: str, max_length: int = 50) -> str:
+            """Truncate text in the middle if it exceeds max_length."""
+            if len(str(text)) <= max_length:
+                return str(text)
+            half = (max_length - 3) // 2
+            text = str(text)
+            return text[:half] + "..." + text[-half:]
+
+        self.env.filters["to_json"] = to_json
+        self.env.filters["truncate_middle"] = truncate_middle
+
+    def render(self, template_name: str, **context: Any) -> str:
+        """Render a template with the given context.
+
+        Args:
+            template_name: Name of the template file (e.g., 'databases/preview.md.j2')
+            **context: Variables to pass to the template
+
+        Returns:
+            Rendered template string
+        """
+        template = self.env.get_template(template_name)
+        return template.render(**context)
+
+    def has_template(self, template_name: str) -> bool:
+        """Check if a template exists.
+
+        Args:
+            template_name: Name of the template to check
+
+        Returns:
+            True if the template exists, False otherwise
+        """
+        try:
+            self.env.get_template(template_name)
+            return True
+        except Exception:
+            return False
+
+    def is_user_override(self, template_name: str) -> bool:
+        """Check if a template is a user override.
+
+        Args:
+            template_name: Name of the template to check
+
+        Returns:
+            True if the user has provided a custom template
+        """
+        if not self.user_templates_dir:
+            return False
+        user_template = self.user_templates_dir / template_name
+        return user_template.exists()
+
+
+# Global template engine instance (lazily initialized)
+_engine: TemplateEngine | None = None
+
+
+def get_template_engine(project_path: Path | None = None) -> TemplateEngine:
+    """Get or create the template engine.
+
+    Args:
+        project_path: Path to the nao project root.
+
+    Returns:
+        The template engine instance
+    """
+    global _engine
+    if _engine is None or (project_path and _engine.project_path != project_path):
+        _engine = TemplateEngine(project_path)
+    return _engine

nao_core/templates/render.py

@@ -0,0 +1,196 @@
+"""Render user Jinja templates in the context folder.
+
+This module discovers and renders `.j2` files in the nao context folder,
+making the `nao` object available for accessing provider data.
+
+Template files are rendered to the same location without the `.j2` extension.
+For example: `docs/report.md.j2` → `docs/report.md`
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from jinja2 import Environment, FileSystemLoader, TemplateError
+
+from .context import create_nao_context
+
+if TYPE_CHECKING:
+    from rich.console import Console
+
+    from nao_core.config.base import NaoConfig
+
+
+@dataclass
+class TemplateRenderResult:
+    """Result of rendering user templates."""
+
+    templates_rendered: int
+    templates_failed: int
+    rendered_files: list[str]
+    errors: list[str]
+
+    def get_summary(self) -> str:
+        """Get a human-readable summary of the render result."""
+        if self.templates_rendered == 0 and self.templates_failed == 0:
+            return "No templates found"
+
+        parts = []
+        if self.templates_rendered > 0:
+            parts.append(f"{self.templates_rendered} rendered")
+        if self.templates_failed > 0:
+            parts.append(f"{self.templates_failed} failed")
+        return ", ".join(parts)
+
+
+def discover_templates(
+    project_path: Path,
+    exclude_dirs: set[str] | None = None,
+) -> list[Path]:
+    """Discover all `.j2` template files in the project.
+
+    Args:
+        project_path: Path to the nao project root.
+        exclude_dirs: Directory names to exclude (default: templates, .git, node_modules, etc.)
+
+    Returns:
+        List of paths to `.j2` files relative to project_path.
+    """
+    if exclude_dirs is None:
+        exclude_dirs = {
+            "templates",  # Don't process accessor template overrides
+            ".git",
+            ".venv",
+            "venv",
+            "node_modules",
+            "__pycache__",
+            ".nao",
+        }
+
+    templates: list[Path] = []
+
+    for path in project_path.rglob("*.j2"):
+        # Skip excluded directories
+        if any(excluded in path.parts for excluded in exclude_dirs):
+            continue
+
+        # Store relative path
+        templates.append(path.relative_to(project_path))
+
+    return sorted(templates)
+
+
+def render_template(
+    template_path: Path,
+    project_path: Path,
+    config: NaoConfig,
+) -> Path:
+    """Render a single template file.
+
+    Args:
+        template_path: Path to the template file (relative to project_path).
+        project_path: Path to the nao project root.
+        config: The nao configuration.
+
+    Returns:
+        Path to the rendered output file.
+
+    Raises:
+        TemplateError: If template rendering fails.
+    """
+    # Create Jinja environment with project as the loader path
+    env = Environment(
+        loader=FileSystemLoader(str(project_path)),
+        autoescape=False,
+        trim_blocks=True,
+        lstrip_blocks=True,
+        keep_trailing_newline=True,
+    )
+
+    # Register custom filters
+    import json
+
+    env.filters["to_json"] = lambda v, indent=None: json.dumps(v, indent=indent, default=str)
+
+    # Create the nao context
+    nao = create_nao_context(config)
+
+    # Load and render the template
+    template = env.get_template(str(template_path))
+    rendered = template.render(nao=nao)
+
+    # Determine output path (remove .j2 extension)
+    output_path = project_path / str(template_path)[:-3]  # Remove .j2
+
+    # Ensure parent directory exists
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Write rendered content
+    output_path.write_text(rendered)
+
+    return output_path
+
+
+def render_all_templates(
+    project_path: Path,
+    config: NaoConfig,
+    console: "Console | None" = None,
+) -> TemplateRenderResult:
+    """Discover and render all user templates in the project.
+
+    Args:
+        project_path: Path to the nao project root.
+        config: The nao configuration.
+        console: Optional Rich console for output.
+
+    Returns:
+        TemplateRenderResult with statistics about what was rendered.
+    """
+    from rich.console import Console
+
+    if console is None:
+        console = Console()
+
+    templates = discover_templates(project_path)
+
+    if not templates:
+        return TemplateRenderResult(
+            templates_rendered=0,
+            templates_failed=0,
+            rendered_files=[],
+            errors=[],
+        )
+
+    rendered_files: list[str] = []
+    errors: list[str] = []
+
+    for template_path in templates:
+        try:
+            output_path = render_template(template_path, project_path, config)
+            rendered_files.append(str(output_path.relative_to(project_path)))
+            console.print(f"  [dim]→[/dim] {template_path} [dim]→[/dim] {output_path.name}")
+        except TemplateError as e:
+            error_msg = f"{template_path}: {e}"
+            errors.append(error_msg)
+            console.print(f"  [red]✗[/red] {template_path}: {e}")
+        except Exception as e:
+            error_msg = f"{template_path}: {type(e).__name__}: {e}"
+            errors.append(error_msg)
+            console.print(f"  [red]✗[/red] {template_path}: {e}")
+
+    return TemplateRenderResult(
+        templates_rendered=len(rendered_files),
+        templates_failed=len(errors),
+        rendered_files=rendered_files,
+        errors=errors,
+    )
+
+
+__all__ = [
+    "TemplateRenderResult",
+    "discover_templates",
+    "render_template",
+    "render_all_templates",
+]