pyscaf-core 0.1.0__tar.gz

pyscaf_core-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+
+# Virtual environments
+.venv/
+
+# Tools cache
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+
+# IDE
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

pyscaf_core-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: pyscaf-core
+Version: 0.1.0
+Requires-Python: >=3.12
+Requires-Dist: click>=8.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: questionary>=2.0
+Requires-Dist: rich>=13.0
+Requires-Dist: tomlkit>=0.12

pyscaf_core-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "pyscaf-core"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = [
+    "pydantic>=2.0",
+    "pyyaml>=6.0",
+    "tomlkit>=0.12",
+    "click>=8.0",
+    "questionary>=2.0",
+    "rich>=13.0",
+]
+
+[build-system]
+requires = ["hatchling>=1.26.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pyscaf_core"]

pyscaf_core-0.1.0/src/pyscaf_core/__init__.py

@@ -0,0 +1,15 @@
+__all__ = [
+    "__version__",
+    "Action",
+    "ActionManager",
+    "CLIOption",
+    "ChoiceOption",
+    "build_cli",
+    "cli_option_to_key",
+    "make_main",
+]
+__version__ = "0.1.0"
+
+from pyscaf_core.actions import Action, ChoiceOption, CLIOption, cli_option_to_key
+from pyscaf_core.actions.manager import ActionManager
+from pyscaf_core.cli import build_cli, make_main

pyscaf_core-0.1.0/src/pyscaf_core/actions/__init__.py

@@ -0,0 +1,213 @@
+"""Action classes for project scaffolding — core engine."""
+
+import importlib
+import logging
+import os
+import pkgutil
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel
+
+from pyscaf_core.tools.format_toml import format_toml
+from pyscaf_core.tools.toml_merge import merge_toml_files
+
+logger = logging.getLogger(__name__)
+
+
+class ChoiceOption(BaseModel):
+    """Represents a choice option with different display formats for CLI and interactive modes."""
+
+    key: str
+    display: str
+    value: Any
+
+
+class CLIOption(BaseModel):
+    name: str
+    type: str = "str"
+    help: str | None = None
+    default: Any = None
+    prompt: str | None = None
+    choices: list[ChoiceOption] | None = None
+    is_flag: bool | None = None
+    multiple: bool | None = None
+    required: bool | None = None
+    postfill_hook: Callable[[dict[str, str]], dict[str, str]] | None = None
+    visible_when: Callable[[dict], bool] | None = None
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    def get_choice_keys(self) -> list[str]:
+        if self.choices and isinstance(self.choices[0], ChoiceOption):
+            return [choice.key for choice in self.choices]
+        return []
+
+    def get_choice_displays(self) -> list[str]:
+        if self.choices and isinstance(self.choices[0], ChoiceOption):
+            return [choice.display for choice in self.choices]
+        return []
+
+    def get_choice_values(self) -> list[Any]:
+        if self.choices and isinstance(self.choices[0], ChoiceOption):
+            return [choice.value for choice in self.choices]
+        return []
+
+    def get_choice_by_key(self, key: str) -> Any | None:
+        if self.choices and isinstance(self.choices[0], ChoiceOption):
+            for choice in self.choices:
+                if choice.key == key:
+                    return choice.value
+        return None
+
+    def get_choice_by_display(self, display: str) -> Any | None:
+        if self.choices and isinstance(self.choices[0], ChoiceOption):
+            for choice in self.choices:
+                if choice.display == display:
+                    return choice.value
+        return None
+
+    def get_default_display(self) -> str | None:
+        if self.type == "choice" and self.choices and isinstance(self.default, int):
+            if 0 <= self.default < len(self.choices):
+                if isinstance(self.choices[0], ChoiceOption):
+                    return self.choices[self.default].display
+        return None
+
+    def get_default_value(self) -> Any:
+        if self.type == "choice" and self.choices and isinstance(self.default, int):
+            if 0 <= self.default < len(self.choices):
+                if isinstance(self.choices[0], ChoiceOption):
+                    return self.choices[self.default].value
+                else:
+                    return self.choices[self.default]
+        return self.default
+
+
+class Action:
+    """Abstract base class for all project actions.
+
+    Actions can:
+    1. Generate file/directory skeleton via the skeleton() method
+    2. Initialize content/behavior via the init() method
+    3. Install dependencies via the install() method
+    """
+
+    depends: set[str] = set()
+    run_preferably_after: str | None = None
+    cli_options: list[CLIOption] = []
+
+    def __init_subclass__(cls) -> None:
+        if hasattr(cls, "depends") and len(cls.depends) > 1 and not getattr(cls, "run_preferably_after", None):
+            raise ValueError(f"Action '{cls.__name__}' has multiple depends but no run_preferably_after")
+
+    def __init__(self, project_path: str | Path):
+        self.project_path = Path(project_path)
+
+    def skeleton(self, context: dict) -> dict[Path, str | None]:
+        """Define the filesystem skeleton for this action.
+
+        Returns a dictionary mapping paths to content:
+        - None -> directory
+        - str -> file with that content
+        """
+        return {}
+
+    def init(self, context: dict) -> None:
+        """Default: merges config.toml from the action's directory into pyproject.toml."""
+        module = importlib.import_module(self.__class__.__module__)
+        module_file = module.__file__
+        if not module_file:
+            raise RuntimeError(f"Module {module} has no __file__ attribute")
+        action_dir = Path(module_file).parent
+        config_path = action_dir / "config.toml"
+        pyproject_path = self.project_path / "pyproject.toml"
+        if config_path.exists():
+            merge_toml_files(input_path=config_path, output_path=pyproject_path)
+            format_toml(pyproject_path)
+            logger.info("Merged %s into %s", config_path, pyproject_path)
+
+    def install(self, context: dict) -> None:
+        """Install dependencies or run post-initialization commands."""
+        return None
+
+    def create_skeleton(self, context: dict) -> set[Path]:
+        """Create the filesystem skeleton for this action."""
+        created_paths: set[Path] = set()
+        skeleton = self.skeleton(context)
+
+        for path, content in skeleton.items():
+            full_path = self.project_path / path
+
+            full_path.parent.mkdir(parents=True, exist_ok=True)
+
+            if content is None:
+                full_path.mkdir(exist_ok=True)
+            else:
+                if full_path.exists():
+                    with open(full_path, "a") as f:
+                        f.write("\n" + content)
+                else:
+                    full_path.write_text(content)
+
+            created_paths.add(full_path)
+
+        return created_paths
+
+    def activate(self, context: dict) -> bool:
+        """Return True if this action should be executed given the current context."""
+        return True
+
+
+def cli_option_to_key(cli_option: CLIOption) -> str:
+    """Convert a CLI option name to a context dictionary key."""
+    return cli_option.name.lstrip("-").replace("-", "_")
+
+
+def discover_actions_from_package(package_path: str, package_name: str) -> list[type[Action]]:
+    """Discover Action subclasses by walking a package directory (pkgutil-based).
+
+    Args:
+        package_path: Filesystem path to the package directory
+        package_name: Fully qualified Python package name for import
+    """
+    actions: list[type[Action]] = []
+    for _, module_name, _ in pkgutil.iter_modules([package_path]):
+        if module_name in ("base", "manager", "__pycache__"):
+            continue
+        mod = importlib.import_module(f"{package_name}.{module_name}")
+        for attr in dir(mod):
+            obj = getattr(mod, attr)
+            if isinstance(obj, type) and issubclass(obj, Action) and obj is not Action:
+                actions.append(obj)
+    return actions
+
+
+def discover_actions_from_entry_points(group: str = "pyscaf_core.plugins") -> list[type[Action]]:
+    """Discover Action subclasses registered via importlib.metadata entry points.
+
+    Each entry point should reference either:
+    - A callable that returns a list of Action subclasses
+    - A module containing Action subclasses
+    """
+    from importlib.metadata import entry_points
+
+    actions: list[type[Action]] = []
+    eps = entry_points().select(group=group)
+    for ep in eps:
+        obj = ep.load()
+        if isinstance(obj, type) and issubclass(obj, Action) and obj is not Action:
+            actions.append(obj)
+        elif callable(obj):
+            result = obj()
+            if isinstance(result, list):
+                actions.extend(result)
+            elif isinstance(result, type) and issubclass(result, Action):
+                actions.append(result)
+        elif isinstance(obj, type(os)):
+            for attr_name in dir(obj):
+                attr = getattr(obj, attr_name)
+                if isinstance(attr, type) and issubclass(attr, Action) and attr is not Action:
+                    actions.append(attr)
+    return actions

pyscaf_core-0.1.0/src/pyscaf_core/actions/manager.py

@@ -0,0 +1,176 @@
+"""Project action manager module — core engine."""
+
+import logging
+from pathlib import Path
+from typing import Any
+
+import questionary
+
+from pyscaf_core.actions import Action, cli_option_to_key
+from pyscaf_core.preference_chain import best_execution_order
+from pyscaf_core.preference_chain.model import Node
+
+logger = logging.getLogger(__name__)
+
+
+class ActionManager:
+    """Manager for all project actions."""
+
+    def __init__(
+        self,
+        project_name: str | Path,
+        context: dict[str, Any],
+        action_classes: list[type[Action]] | None = None,
+        discover: Any = None,
+    ):
+        self.project_path = Path.cwd() / project_name
+        logger.info("Project path: %s", self.project_path)
+        self.context = context
+        self.actions: list[Action] = []
+
+        if action_classes is not None:
+            self._action_classes = action_classes
+        elif discover is not None:
+            self._action_classes = discover()
+        else:
+            from pyscaf_core.actions import discover_actions_from_entry_points
+
+            self._action_classes = discover_actions_from_entry_points()
+
+        self._determine_actions()
+
+    def _determine_actions(self) -> None:
+        """Determine which actions to include based on configuration using the preference chain logic."""
+        nodes: list[Node] = []
+        action_class_by_id: dict[str, type[Action]] = {}
+
+        for action_cls in self._action_classes:
+            action_id = action_cls.__name__.replace("Action", "").lower()
+            depends = getattr(action_cls, "depends", set())
+            after = getattr(action_cls, "run_preferably_after", None)
+
+            node = Node(id=action_id, depends=depends, after=after)
+            nodes.append(node)
+            action_class_by_id[action_id] = action_cls
+
+        logger.debug("Created %d action nodes", len(nodes))
+
+        if not nodes:
+            self.actions = []
+            return
+
+        order = best_execution_order(nodes)
+
+        logger.debug("Final action execution order: %s", order)
+
+        self.actions = [
+            action_class_by_id[action_id](self.project_path)
+            for action_id in order
+            if action_id in action_class_by_id
+        ]
+
+    def run_postfill_hooks(self, context: dict) -> dict:
+        """Run all postfill hooks for actions in optimal order."""
+        for action in self.actions:
+            if action.activate(context):
+                for opt in action.cli_options:
+                    context_key = cli_option_to_key(opt)
+                    if context.get(context_key) is None:
+                        continue
+                    if opt.visible_when and not opt.visible_when(context):
+                        continue
+                    if opt.postfill_hook:
+                        context = opt.postfill_hook(context)
+        return context
+
+    def ask_interactive_questions(self, context: dict) -> dict:
+        """Ask all relevant questions for actions in optimal order, updating the context."""
+        for action in self.actions:
+            if action.activate(context):
+                for opt in action.cli_options:
+                    context_key = cli_option_to_key(opt)
+                    if context.get(context_key) is not None:
+                        continue
+                    if opt.visible_when and not opt.visible_when(context):
+                        continue
+                    prompt = opt.prompt or context_key
+                    if opt.type == "choice":
+                        default = opt.get_default_value()
+                    else:
+                        default = opt.default() if callable(opt.default) else opt.default
+                    if opt.type == "bool":
+                        answer = questionary.confirm(prompt, default=bool(default)).ask()
+                    elif opt.type == "int":
+                        answer = questionary.text(
+                            prompt, default=str(default) if default is not None else ""
+                        ).ask()
+                        answer = int(answer) if answer is not None and answer != "" else None
+                    elif opt.type == "choice" and opt.choices:
+                        choices = opt.get_choice_displays()
+                        default_display = opt.get_default_display()
+
+                        if opt.multiple:
+                            answer = questionary.checkbox(
+                                prompt, choices=choices, default=default_display
+                            ).ask()
+                        else:
+                            answer = questionary.select(
+                                prompt, choices=choices, default=default_display
+                            ).ask()
+
+                        if answer:
+                            if opt.multiple:
+                                converted_answer = []
+                                for display in answer:
+                                    for choice in opt.choices:
+                                        if choice.display == display:
+                                            converted_answer.append(choice.key)
+                                            break
+                                answer = converted_answer
+                            else:
+                                for choice in opt.choices:
+                                    if choice.display == answer:
+                                        answer = choice.key
+                                        break
+
+                    else:
+                        answer = questionary.text(
+                            prompt, default=default if default is not None else ""
+                        ).ask()
+                    context[context_key] = answer
+                    if opt.postfill_hook:
+                        context = opt.postfill_hook(context)
+        return context
+
+    def create_project(self) -> None:
+        """Create the project structure and initialize it."""
+        self.project_path.mkdir(parents=True, exist_ok=True)
+
+        logger.info("Creating project at: %s", self.project_path)
+
+        for action in self.actions:
+            if not action.activate(self.context):
+                logger.info("Skipping %s", action.__class__.__name__)
+                continue
+            action_name = action.__class__.__name__
+            logger.info("Creating skeleton for: %s", action_name)
+            action.create_skeleton(self.context)
+
+        for action in self.actions:
+            if not action.activate(self.context):
+                continue
+            action_name = action.__class__.__name__
+            logger.info("Initializing: %s", action_name)
+            action.init(self.context)
+
+        if not self.context.get("no_install", False):
+            for action in self.actions:
+                if not action.activate(self.context):
+                    continue
+                action_name = action.__class__.__name__
+                logger.info("Installing dependencies for: %s", action_name)
+                action.install(self.context)
+        else:
+            logger.info("Skipping installation.")
+
+        logger.info("Project creation complete!")

pyscaf_core-0.1.0/src/pyscaf_core/cli.py

@@ -0,0 +1,211 @@
+"""CLI framework for pyscaf-core based applications."""
+
+import sys
+from typing import Any
+
+import click
+from rich.console import Console
+
+from pyscaf_core.actions import (
+    Action,
+    CLIOption,
+    cli_option_to_key,
+    discover_actions_from_entry_points,
+)
+from pyscaf_core.actions.manager import ActionManager
+from pyscaf_core.preference_chain import best_execution_order
+from pyscaf_core.preference_chain.model import Node
+
+
+def set_option_default(opt: CLIOption) -> Any:
+    """Compute the default value for a CLI option."""
+    if opt.type == "choice":
+        default_index = opt.default
+        if default_index is not None and opt.choices:
+            return opt.choices[default_index].key
+        return None
+    return opt.default() if callable(opt.default) else opt.default
+
+
+def collect_cli_options(
+    action_classes: list[type[Action]] | None = None,
+    discover: Any = None,
+) -> list[CLIOption]:
+    """Collect CLI options from all actions in dependency order.
+
+    Args:
+        action_classes: Explicit list of action classes
+        discover: Callable returning action classes
+    """
+    if action_classes is not None:
+        classes = action_classes
+    elif discover is not None:
+        classes = discover()
+    else:
+        classes = discover_actions_from_entry_points()
+
+    deps: list[Node] = []
+    action_class_by_id: dict[str, type[Action]] = {}
+    for action_cls in classes:
+        action_id = action_cls.__name__.replace("Action", "").lower()
+        depends = getattr(action_cls, "depends", set())
+        after = getattr(action_cls, "run_preferably_after", None)
+
+        if depends and after is None:
+            after = next(iter(depends))
+
+        node = Node(id=action_id, depends=depends, after=after)
+        deps.append(node)
+        action_class_by_id[action_id] = action_cls
+
+    if not deps:
+        return []
+
+    order = best_execution_order(deps)
+    cli_options: list[CLIOption] = []
+    for action_id in order:
+        action_cls = action_class_by_id[action_id]
+        cli_options.extend(getattr(action_cls, "cli_options", []))
+    return cli_options
+
+
+def fill_default_context(
+    context: dict,
+    action_classes: list[type[Action]] | None = None,
+    discover: Any = None,
+) -> dict:
+    """Fill the context with default values from all actions."""
+    if action_classes is not None:
+        classes = action_classes
+    elif discover is not None:
+        classes = discover()
+    else:
+        classes = discover_actions_from_entry_points()
+
+    for action_cls in classes:
+        if hasattr(action_cls, "cli_options"):
+            for opt in action_cls.cli_options:
+                name = cli_option_to_key(opt)
+                if name not in context or context[name] is None:
+                    if opt.visible_when and not opt.visible_when(context):
+                        continue
+                    context[name] = set_option_default(opt)
+
+    return context
+
+
+def add_dynamic_options(
+    command: click.Command,
+    action_classes: list[type[Action]] | None = None,
+    discover: Any = None,
+) -> click.Command:
+    """Add dynamic Click options from all actions to a command."""
+    cli_options = collect_cli_options(action_classes=action_classes, discover=discover)
+    for opt in reversed(cli_options):
+        param_decls = [opt.name]
+        click_opts: dict[str, Any] = {}
+        if opt.type == "int":
+            click_opts["type"] = int
+        elif opt.type == "choice" and opt.choices:
+            choice_keys = opt.get_choice_keys()
+            click_opts["type"] = click.Choice(choice_keys, case_sensitive=False)
+            if opt.multiple:
+                click_opts["multiple"] = True
+        elif opt.type == "str":
+            click_opts["type"] = str
+        elif opt.type == "bool":
+            click_opts["type"] = click.BOOL
+            click_opts["default"] = None
+            base_name = opt.name.lstrip("-")
+            param_decls[0] = f"--{base_name}/--no-{base_name}"
+
+        if opt.help:
+            click_opts["help"] = opt.help
+        if opt.required:
+            click_opts["required"] = True
+        command = click.option(*param_decls, **click_opts)(command)
+    return command
+
+
+def build_cli(
+    app_name: str,
+    version: str,
+    action_classes: list[type[Action]] | None = None,
+    discover: Any = None,
+) -> click.Group:
+    """Build a complete Click CLI group for a pyscaf-core based application.
+
+    Args:
+        app_name: Name displayed in CLI help
+        version: Version string for --version
+        action_classes: Explicit list of action classes (mutually exclusive with discover)
+        discover: Callable returning action classes (mutually exclusive with action_classes)
+
+    Returns:
+        A click.Group with an 'init' command wired to ActionManager
+    """
+    console = Console()
+
+    def print_version(ctx: click.Context, param: click.Parameter, value: bool) -> None:
+        if not value or ctx.resilient_parsing:
+            return
+        console.print(f"{app_name} version {version}")
+        ctx.exit()
+
+    @click.group()
+    @click.version_option(
+        version,
+        "--version",
+        "-V",
+        callback=print_version,
+        help="Show the version and exit.",
+    )
+    def cli() -> None:
+        pass
+
+    cli.help = f"{app_name} — project generator with plugin-based action system."
+
+    @click.command()
+    @click.argument("project_name")
+    @click.option(
+        "--interactive",
+        is_flag=True,
+        help="Enable interactive mode (asks questions to the user).",
+    )
+    @click.option("--no-install", is_flag=True, help="Skip installation step.")
+    def init(project_name: str, interactive: bool, no_install: bool, **kwargs: Any) -> None:
+        """Initialize a new customized project structure."""
+        context = dict(kwargs)
+        context["project_name"] = project_name
+        context["interactive"] = interactive
+        context["no_install"] = no_install
+
+        if not interactive:
+            context = fill_default_context(context, action_classes=action_classes, discover=discover)
+
+        manager = ActionManager(project_name, context, action_classes=action_classes, discover=discover)
+        context = manager.run_postfill_hooks(context)
+
+        if interactive:
+            context = manager.ask_interactive_questions(context)
+        manager.context = context
+        manager.create_project()
+
+    init = add_dynamic_options(init, action_classes=action_classes, discover=discover)
+    cli.add_command(init, "init")
+
+    return cli
+
+
+def make_main(cli_group: click.Group) -> Any:
+    """Create a main() entry point from a CLI group."""
+
+    def main() -> None:
+        try:
+            cli_group()
+        except Exception as e:
+            console = Console()
+            console.print(f"[bold red]Error:[/bold red] {e!s}")
+            sys.exit(1)
+
+    return main