bootstack 0.1.0__py3-none-any.whl

bootstack/cli/__init__.py

@@ -0,0 +1,133 @@
+"""CLI entry point for bootstack.
+
+The bootstack CLI provides commands for:
+- Creating new projects (start)
+- Running applications (run)
+- Building for distribution (build)
+- Adding components (add)
+
+Usage:
+    bootstack start <appname>        Create a new project
+    bootstack run [path]             Run the application
+    bootstack dev [path]             Run with hot reload (live edit-and-save)
+    bootstack promote --pyinstaller  Enable PyInstaller support
+    bootstack build                  Build for distribution
+    bootstack add page <ClassName>   Add a new page (AppShell)
+    bootstack add view <ClassName>   Add a new view
+    bootstack add dialog <ClassName> Add a new dialog
+    bootstack add i18n               Add i18n support
+    bootstack doctor                 Diagnose project and environment health
+    bootstack gallery                 Launch the widget gallery
+    bootstack icons                   Browse Bootstrap Icons
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Sequence
+
+from bootstack.cli import add, appicon, build, dev, doctor, icons, promote, run, start
+from bootstack.cli.demo import run_demo
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Dispatch CLI commands registered in bootstack."""
+    parser = argparse.ArgumentParser(
+        prog="bootstack",
+        description="bootstack command line interface",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""\
+Examples:
+  bootstack start MyApp              Create a new project
+  bootstack start MyApp --template appshell  Create an AppShell project
+  bootstack start MyApp --theme superhero    Use a specific theme
+  bootstack run                      Run the application
+  bootstack dev app.py               Run with hot reload
+  bootstack promote --pyinstaller    Enable PyInstaller support
+  bootstack build                    Build for distribution
+  bootstack add view SettingsView    Add a new view
+  bootstack doctor                   Diagnose project and environment health
+  bootstack gallery                  Launch the widget gallery
+  bootstack icons                    Browse Bootstrap Icons
+
+For more information on a command:
+  bootstack <command> --help
+""",
+    )
+
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=_get_version(),
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Print full tracebacks on error",
+    )
+
+    subparsers = parser.add_subparsers(
+        dest="command",
+        title="commands",
+        metavar="<command>",
+    )
+
+    # Register commands
+    start.add_parser(subparsers)
+    run.add_parser(subparsers)
+    dev.add_parser(subparsers)
+    promote.add_parser(subparsers)
+    build.add_parser(subparsers)
+    add.add_parser(subparsers)
+    doctor.add_parser(subparsers)
+    icons.add_parser(subparsers)
+    appicon.add_parser(subparsers)
+
+    # Gallery command
+    gallery_parser = subparsers.add_parser(
+        "gallery",
+        help="Launch the widget gallery",
+    )
+    gallery_parser.set_defaults(func=lambda args: run_demo())
+
+    # demo is kept as a backwards-compatible alias
+    demo_parser = subparsers.add_parser(
+        "demo",
+        help=argparse.SUPPRESS,
+    )
+    demo_parser.set_defaults(func=lambda args: run_demo())
+
+    # Parse arguments
+    args = parser.parse_args(argv)
+    func = getattr(args, "func", None)
+
+    if func is None:
+        parser.print_help()
+        sys.exit(0)
+
+    # Execute command
+    try:
+        func(args)
+    except KeyboardInterrupt:
+        print("\nInterrupted.")
+        sys.exit(1)
+    except Exception as e:
+        if getattr(args, "verbose", False):
+            import traceback
+            traceback.print_exc()
+        else:
+            print(f"Error: {e}")
+            print("(Run with --verbose for the full traceback.)")
+        sys.exit(1)
+
+
+def _get_version() -> str:
+    """Get the bootstack version string."""
+    try:
+        import bootstack
+
+        return f"bootstack {bootstack.__version__}"
+    except Exception:
+        return "bootstack (unknown version)"

bootstack/cli/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running bootstack CLI as python -m bootstack.cli."""
+
+from bootstack.cli import main
+
+if __name__ == "__main__":
+    main()

bootstack/cli/add.py

@@ -0,0 +1,395 @@
+"""bootstack add command - Add views, dialogs, and i18n to a project."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from bootstack.cli.config import TtkbConfig, find_config
+from bootstack.cli.templates import (
+    _build_func_name,
+    create_dialog,
+    create_page,
+    create_view,
+)
+
+
+def add_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Add the 'add' subcommand parser."""
+    parser = subparsers.add_parser(
+        "add",
+        help="Add components to the project",
+        description="Add views, pages, dialogs, or i18n support to the project.",
+    )
+    add_subparsers = parser.add_subparsers(dest="component")
+
+    # bootstack add page <ClassName>
+    page_parser = add_subparsers.add_parser(
+        "page",
+        help="Add a new page (for AppShell projects)",
+    )
+    page_parser.add_argument(
+        "class_name",
+        help="Page class name (CamelCase, e.g., 'DashboardPage')",
+    )
+    page_parser.add_argument(
+        "--dir",
+        type=Path,
+        default=None,
+        help="Target directory (default: src/<app>/pages/)",
+    )
+    page_parser.add_argument(
+        "--scrollable",
+        action="store_true",
+        help="Make the page scrollable (wraps content in a ScrollView)",
+    )
+    page_parser.set_defaults(func=run_add_page)
+
+    # bootstack add view <ClassName>
+    view_parser = add_subparsers.add_parser(
+        "view",
+        help="Add a new view",
+    )
+    view_parser.add_argument(
+        "class_name",
+        help="View class name (CamelCase, e.g., 'SettingsView')",
+    )
+    view_parser.add_argument(
+        "--container",
+        choices=["grid", "pack"],
+        default=None,
+        help="Container type (default: from bootstack.toml or 'grid')",
+    )
+    view_parser.add_argument(
+        "--dir",
+        type=Path,
+        default=None,
+        help="Target directory (default: src/<app>/views/)",
+    )
+    view_parser.set_defaults(func=run_add_view)
+
+    # bootstack add dialog <ClassName>
+    dialog_parser = add_subparsers.add_parser(
+        "dialog",
+        help="Add a new dialog",
+    )
+    dialog_parser.add_argument(
+        "class_name",
+        help="Dialog class name (CamelCase, e.g., 'ConfirmDialog')",
+    )
+    dialog_parser.add_argument(
+        "--dir",
+        type=Path,
+        default=None,
+        help="Target directory (default: src/<app>/dialogs/)",
+    )
+    dialog_parser.set_defaults(func=run_add_dialog)
+
+    # bootstack add i18n
+    i18n_parser = add_subparsers.add_parser(
+        "i18n",
+        help="Add internationalization support",
+    )
+    i18n_parser.add_argument(
+        "--languages",
+        nargs="+",
+        default=["es"],
+        help="Locale codes to scaffold (default: es)",
+    )
+    i18n_parser.add_argument(
+        "--po",
+        action="store_true",
+        help="Scaffold .po catalog files in assets/locales/ instead of a Python "
+             "translations module",
+    )
+    i18n_parser.set_defaults(func=run_add_i18n)
+
+    parser.set_defaults(func=lambda args: parser.print_help())
+
+
+def run_add_view(args: argparse.Namespace) -> None:
+    """Add a new view to the project."""
+    class_name = args.class_name
+
+    # Validate class name
+    if not class_name[0].isupper():
+        print("Error: Class name should be CamelCase (e.g., 'SettingsView')")
+        return
+
+    # Find project configuration
+    config_path = find_config()
+    if config_path is None:
+        print("Error: No bootstack.toml found. Are you in a bootstack project?")
+        return
+
+    project_root = config_path.parent
+    config = TtkbConfig.load(config_path)
+
+    # Reject in AppShell projects - views belong to the basic template
+    if config.app.template == "appshell":
+        print("Error: 'bootstack add view' is for basic-template projects.")
+        print("This project uses the 'appshell' template. Use 'bootstack add page' instead.")
+        return
+
+    # Determine container type
+    container = args.container
+    if container is None:
+        container = config.layout.default_container
+
+    # Determine target directory
+    if args.dir:
+        target_dir = args.dir
+    else:
+        # Parse entry point to find source directory
+        entry_path = Path(config.app.entry)
+        if entry_path.parts[0] == "src" and len(entry_path.parts) >= 2:
+            module_name = entry_path.parts[1]
+            target_dir = project_root / "src" / module_name / "views"
+        else:
+            target_dir = project_root / "views"
+
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    # Ensure __init__.py exists
+    init_file = target_dir / "__init__.py"
+    if not init_file.exists():
+        init_file.write_text('"""Views package."""\n', encoding="utf-8")
+
+    # Create view
+    file_path = create_view(class_name, target_dir, container)
+
+    print(f"Created view: {file_path.relative_to(project_root)}")
+
+
+def run_add_page(args: argparse.Namespace) -> None:
+    """Add a new page to an AppShell project."""
+    class_name = args.class_name
+
+    # Validate class name
+    if not class_name[0].isupper():
+        print("Error: Class name should be CamelCase (e.g., 'DashboardPage')")
+        return
+
+    # Find project configuration
+    config_path = find_config()
+    if config_path is None:
+        print("Error: No bootstack.toml found. Are you in a bootstack project?")
+        return
+
+    project_root = config_path.parent
+    config = TtkbConfig.load(config_path)
+
+    # Check that this is an AppShell project
+    if config.app.template != "appshell":
+        print("Error: 'bootstack add page' is for AppShell projects.")
+        print("This project uses the 'basic' template. Use 'bootstack add view' instead.")
+        return
+
+    # Determine target directory and module name for the import hint
+    entry_path = Path(config.app.entry)
+    if entry_path.parts[0] == "src" and len(entry_path.parts) >= 2:
+        module_name = entry_path.parts[1]
+        default_target = project_root / "src" / module_name / "pages"
+    else:
+        module_name = None
+        default_target = project_root / "pages"
+
+    target_dir = args.dir if args.dir else default_target
+
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    # Ensure __init__.py exists
+    init_file = target_dir / "__init__.py"
+    if not init_file.exists():
+        init_file.write_text('"""Pages package."""\n', encoding="utf-8")
+
+    # Create page
+    scrollable = args.scrollable
+    file_path = create_page(class_name, target_dir, scrollable=scrollable)
+
+    func_name = _build_func_name(class_name)
+    print(f"Created page: {file_path.relative_to(project_root)}")
+    print()
+    print("This created the file only - it is NOT yet shown in the sidebar.")
+    print("To register it with the AppShell, paste these lines into main.py")
+    print("inside your shell.page_nav() block:")
+    print()
+    import_module = f"{module_name}.pages" if module_name else "<module>.pages"
+    print(f"  from {import_module}.{file_path.stem} import {func_name}")
+    scrollable_arg = ", scrollable=True" if scrollable else ""
+    print(f'  with nav.add_page("<id>", text="<Label>", icon="<icon>",')
+    print(f'                    padding=20, gap=12, horizontal_items="stretch"{scrollable_arg}):')
+    print(f"      {func_name}()")
+
+
+def run_add_dialog(args: argparse.Namespace) -> None:
+    """Add a new dialog to the project."""
+    class_name = args.class_name
+
+    # Validate class name
+    if not class_name[0].isupper():
+        print("Error: Class name should be CamelCase (e.g., 'ConfirmDialog')")
+        return
+
+    # Find project configuration
+    config_path = find_config()
+    if config_path is None:
+        print("Error: No bootstack.toml found. Are you in a bootstack project?")
+        return
+
+    project_root = config_path.parent
+    config = TtkbConfig.load(config_path)
+
+    # Determine target directory
+    if args.dir:
+        target_dir = args.dir
+    else:
+        # Parse entry point to find source directory
+        entry_path = Path(config.app.entry)
+        if entry_path.parts[0] == "src" and len(entry_path.parts) >= 2:
+            module_name = entry_path.parts[1]
+            target_dir = project_root / "src" / module_name / "dialogs"
+        else:
+            target_dir = project_root / "dialogs"
+
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    # Ensure __init__.py exists
+    init_file = target_dir / "__init__.py"
+    if not init_file.exists():
+        init_file.write_text('"""Dialogs package."""\n', encoding="utf-8")
+
+    # Create dialog
+    file_path = create_dialog(class_name, target_dir)
+
+    print(f"Created dialog: {file_path.relative_to(project_root)}")
+
+
+def run_add_i18n(args: argparse.Namespace) -> None:
+    """Add internationalization support to the project.
+
+    By default this scaffolds a Python translations module (the simplest path -
+    no tooling, bundled with your code). With `--po` it scaffolds `.po`
+    catalog files in `assets/` for a file-based workflow.
+    """
+    languages = args.languages
+
+    config_path = find_config()
+    if config_path is None:
+        print("Error: No bootstack.toml found. Are you in a bootstack project?")
+        return
+    project_root = config_path.parent
+
+    if args.po:
+        _scaffold_po_catalogs(project_root, languages)
+    else:
+        config = TtkbConfig.load(config_path)
+        entry_path = Path(config.app.entry)
+        module_name = entry_path.parts[1] if len(entry_path.parts) > 1 else None
+        _scaffold_i18n_module(project_root, module_name, languages)
+
+
+def _scaffold_i18n_module(project_root, module_name, languages) -> None:
+    """Scaffold a Python translations module using add_translations()."""
+    if not module_name:
+        print("Error: could not determine the project module from bootstack.toml.")
+        return
+
+    target = project_root / "src" / module_name / "i18n.py"
+    if target.exists():
+        print(f"{target.relative_to(project_root)} already exists - not overwritten.")
+        return
+
+    target.write_text(_get_i18n_module_template(languages), encoding="utf-8")
+    print(f"Created: {target.relative_to(project_root)}")
+    print()
+    print("Wire it into main.py - call it before creating the app:")
+    print()
+    print(f"  from {module_name}.i18n import install_translations")
+    print("  install_translations()")
+    print("  with bs.AppShell(...):  # or bs.App(...)")
+    print("      ...")
+    print()
+    print("Then add your strings to i18n.py. Widget text auto-localizes - once a")
+    print('translation is registered, bs.Label("Save") shows it for the active locale.')
+
+
+def _scaffold_po_catalogs(project_root, languages) -> None:
+    """Scaffold .po catalog files in assets/locales/ for a file-based workflow."""
+    locales_dir = project_root / "assets" / "locales"
+    locales_dir.mkdir(parents=True, exist_ok=True)
+
+    for lang in languages:
+        po_file = locales_dir / f"{lang}.po"
+        if not po_file.exists():
+            po_file.write_text(_get_po_template(lang), encoding="utf-8")
+            print(f"Created: {po_file.relative_to(project_root)}")
+
+    print()
+    print("These .po files live under assets/, so the build bundles them already")
+    print("(assets/** is in [build.datas]). Fill in the translations, then load them")
+    print("at startup - before the app:")
+    print()
+    print("  from bootstack.i18n import load_po")
+    for lang in languages:
+        print(f'  load_po("assets/locales/{lang}.po")')
+    print()
+    print('Widget text then auto-localizes - bs.Label("Save") shows the translation.')
+
+
+def _get_i18n_module_template(languages) -> str:
+    """Python translations-module template using add_translations()."""
+    blocks = []
+    for lang in languages:
+        blocks.append(
+            f'    add_translations("{lang}", {{\n'
+            f'        # "Save": "...",\n'
+            f'        # "Cancel": "...",\n'
+            f'    }})'
+        )
+    body = "\n".join(blocks) if blocks else "    pass"
+    return (
+        '"""Application translations.\n'
+        "\n"
+        "Call install_translations() at startup, before creating the app, so the\n"
+        "strings are registered when widgets resolve their text. Widget text\n"
+        "auto-localizes: a plain string is translated when a translation exists.\n"
+        '"""\n'
+        "\n"
+        "from bootstack.i18n import add_translations\n"
+        "\n"
+        "\n"
+        "def install_translations() -> None:\n"
+        '    """Register the application\'s translations."""\n'
+        f"{body}\n"
+    )
+
+
+def _get_po_template(lang: str) -> str:
+    """Get a .po file template."""
+    from datetime import datetime, timezone
+
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M%z")
+
+    return f'''\
+# {lang.upper()} translations for the application.
+# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
+# This file is distributed under the same license as the PACKAGE package.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: 1.0\\n"
+"Report-Msgid-Bugs-To: \\n"
+"POT-Creation-Date: {now}\\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\\n"
+"Language-Team: {lang.upper()} <LL@li.org>\\n"
+"Language: {lang}\\n"
+"MIME-Version: 1.0\\n"
+"Content-Type: text/plain; charset=UTF-8\\n"
+"Content-Transfer-Encoding: 8bit\\n"
+
+# Example translation
+# msgid "Hello"
+# msgstr "Hello"
+'''