new_python_file.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/generator/new_python_file.py
 
"""
File Generator
==============
 
Purpose
-------
Create new Option C-compliant Python files with the mandatory 3-line header
block and a complete module docstring skeleton, ready for immediate development.
 
Responsibilities
----------------
- Accept a target path relative to or absolute from the project root.
- Write the mandatory 3-line header block (shebang, encoding, file identity).
- Append the ``from oc_diagnostics import _dbg`` import so the generated file
  is immediately linter-compliant for ``_dbg`` usage checks.
- Append the Option C docstring template including the Diagnostics section.
- Refuse to overwrite existing files unless ``--force`` is explicitly requested.
 
Diagnostics
-----------
Domain: OCT-GENERATOR
Levels:
    L2 — lifecycle
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- Must not overwrite existing files unless ``force=True``.
- Generated file must pass the OCT linter header and docstring checks immediately.
- Target path may be absolute or relative to the project root.
"""
 
from pathlib import Path
import click
from oct.core.project_root import find_project_root
 
SHEBANG = "#!/usr/bin/env python3"
ENCODING = "# -*- coding: utf-8 -*-"
 
# Import block placed after the header so generated files are immediately
# linter-compliant for _dbg usage checks (oc_diagnostics is the source of _dbg).
IMPORT_BLOCK = "from oc_diagnostics import _dbg\n\n"
 
DOCSTRING_TEMPLATE = '''"""
Purpose
-------
Describe the purpose of this module.
 
Responsibilities
----------------
- List the responsibilities of this module.
 
Diagnostics
-----------
Domain: <DOMAIN>
Levels:
    L2 — lifecycle
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- State the contracts and guarantees of this module.
"""
'''
 
TEST_DOCSTRING_TEMPLATE = '''"""
Purpose
-------
Unit tests for {module_name}.
 
Responsibilities
----------------
- Verify the public API of {module_name}.
 
Diagnostics
-----------
Domain: TESTS
Levels:
    L2 — lifecycle
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- Must not modify external state.
- Must be deterministic and repeatable.
"""
'''
 
TEST_BODY_TEMPLATE = '''
{import_line}
 
 
def test_{stem}_placeholder():
    """Placeholder test — replace with real tests."""
    assert True
'''
 
 
def _make_header(rel_posix: str) -> str:
    """Build the 4-line Option C header block (shebang, encoding, identity, blank)."""
    return f"{SHEBANG}\n{ENCODING}\n# {rel_posix}\n\n"
 
 
def _derive_import_path(rel_posix: str) -> str:
    """Convert a relative posix path to a dotted Python import path (without .py)."""
    no_ext = rel_posix.replace(".py", "")
    return no_ext.replace("/", ".")
 
 
def _print_content(label: str, content: str) -> None:
    """Print generated file content with a visual frame."""
    print(f"\n--- {label} ---")
    print(content, end="")
    print("--- end ---")
 
 
def create_new_file(
    project_root: Path, path: str, force: bool,
    dry_run: bool = False, test: bool = False,
    verbose: bool = False,
):
    target = Path(path)
    if not target.is_absolute():
        target = project_root / target
 
    if target.suffix != ".py":
        raise click.ClickException(
            f"oct new only creates Python (.py) files. Got: '{target.suffix or '(no extension)'}'"
        )
 
    # Ensure the target is inside the project root.
    try:
        target.resolve().relative_to(project_root.resolve())
    except ValueError:
        raise click.ClickException(
            f"Target path {target} is outside the project root ({project_root}). "
            "Use a relative path or a path inside the project."
        )
 
    if target.exists() and not force:
        raise click.ClickException(f"File already exists: {target}")
 
    # Derive test file path
    test_target = None
    if test:
        test_target = project_root / "tests" / f"test_{target.stem}.py"
        if test_target.exists() and not force:
            raise click.ClickException(f"Test file already exists: {test_target}")
 
    # Build content (needed for both dry-run verbose preview and actual write)
    rel = target.relative_to(project_root).as_posix()
    header = _make_header(rel)
    main_content = header + IMPORT_BLOCK + DOCSTRING_TEMPLATE
 
    test_content = None
    if test_target:
        test_rel = test_target.relative_to(project_root).as_posix()
        test_header = _make_header(test_rel)
        import_path = _derive_import_path(rel)
        test_docstring = TEST_DOCSTRING_TEMPLATE.format(module_name=target.stem)
        test_body = TEST_BODY_TEMPLATE.format(
            import_line=f"from {import_path} import *",
            stem=target.stem,
        )
        test_content = test_header + test_docstring + test_body
 
    if dry_run:
        if not target.parent.exists():
            print(f"[DRY RUN] Would create directory: {target.parent}")
        # Report __init__.py files that would be created
        current = target.parent
        while current != project_root and current != current.parent:
            try:
                current.relative_to(project_root)
            except ValueError:
                break
            init_file = current / "__init__.py"
            if not init_file.exists():
                print(f"[DRY RUN] Would create package marker: {init_file.relative_to(project_root)}")
            current = current.parent
        print(f"[DRY RUN] Would write file: {target}")
        if test_target:
            print(f"[DRY RUN] Would write test file: {test_target}")
        if verbose:
            _print_content(rel, main_content)
            if test_content:
                _print_content(test_rel, test_content)
        return
 
    target.parent.mkdir(parents=True, exist_ok=True)
 
    # Ensure __init__.py exists in all new package directories up to project root
    current = target.parent
    while current != project_root and current != current.parent:
        try:
            current.relative_to(project_root)
        except ValueError:
            break
        init_file = current / "__init__.py"
        if not init_file.exists():
            init_file.write_text("", encoding="utf-8")
            print(f"  Created package marker: {init_file.relative_to(project_root)}")
        current = current.parent
 
    target.write_text(main_content, encoding="utf-8")
    print(f"Created Option C-compliant file: {target}")
    if verbose:
        _print_content(rel, main_content)
 
    # Generate companion test file
    if test_target and test_content:
        test_target.parent.mkdir(parents=True, exist_ok=True)
        test_target.write_text(test_content, encoding="utf-8")
        print(f"Created companion test file: {test_target}")
        if verbose:
            _print_content(test_rel, test_content)