new_python_file Namespace Reference

Functions
str	_make_header (str rel_posix)
str	_make_package_init_content (str rel_posix)
str	_derive_domain (str rel_posix)
str	_derive_import_path (str rel_posix)
None	_print_content (str label, str content)
None	create_new_file (Path project_root, str path, bool force, bool dry_run=False, bool test=False, bool verbose=False)

Variables
str	SHEBANG = "#!/usr/bin/env python3"
str	ENCODING = "# -*- coding: utf-8 -*-"
str	IMPORT_BLOCK = "\nfrom oc_diagnostics import _dbg\n"
str	DOCSTRING_TEMPLATE
str	TEST_DOCSTRING_TEMPLATE
str	TEST_BODY_TEMPLATE
str	PACKAGE_INIT_DOCSTRING

Detailed Description

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).
- Write the Option C module docstring template next, including the
  Diagnostics section with a ``Domain`` derived from the file's path and a
  Dependencies section, so the docstring is the real module docstring.
- Write the ``from oc_diagnostics import _dbg`` import AFTER the docstring.
  It used to come first, which made the docstring a bare string statement
  (found during the chart C runtime trace work, 2026-09-27).
- 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, docstring,
  diagnostics-profile and dependencies-section checks immediately. It
  fails ``dbg_usage`` until its first function logs something, which is
  the intended reminder.
- Target path may be absolute or relative to the project root.

Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)
- oct.core.project_root (find_project_root, imported but unused; the caller passes project_root)
- click (ClickException for refused paths and existing files)

Function Documentation

_derive_domain()

str new_python_file._derive_domain ( str rel_posix )

protected

The Diagnostics domain for a new module, from its path.

oct's own convention: the package path, upper-cased and joined with
hyphens (``oct/deps/call_graph.py`` -> ``OCT-DEPS``); a module at the
project root takes its own name (``script.py`` -> ``SCRIPT``).

Definition at line 165 of file new_python_file.py.

Here is the caller graph for this function:

_derive_import_path()

str new_python_file._derive_import_path ( str rel_posix )

protected

Convert a relative posix path to a dotted Python import path (without .py).

Definition at line 178 of file new_python_file.py.

Here is the caller graph for this function:

_make_header()

str new_python_file._make_header ( str rel_posix )

protected

Build the 4-line Option C header block (shebang, encoding, identity, blank).

Definition at line 148 of file new_python_file.py.

Here is the caller graph for this function:

_make_package_init_content()

str new_python_file._make_package_init_content ( str rel_posix )

protected

Build a header-bearing package-marker ``__init__.py``.

Plan 151 T6 (oct footgun fix): replaces the previous EMPTY, header-less
``__init__.py`` - which failed the linter's mandatory header rule the
moment it was created - with the standard Option C header block plus a
minimal module docstring, matching the house style of hand-written
package inits.

Definition at line 153 of file new_python_file.py.

Here is the call graph for this function:

Here is the caller graph for this function:

_print_content()

None new_python_file._print_content ( str label, str content )

protected

Print generated file content with a visual frame.

Definition at line 184 of file new_python_file.py.

Here is the caller graph for this function:

create_new_file()

None new_python_file.create_new_file	(	Path	project_root,
		str	path,
		bool	force,
		bool	dry_run = False,
		bool	test = False,
		bool	verbose = False )

Definition at line 191 of file new_python_file.py.

Here is the call graph for this function:

Variable Documentation

DOCSTRING_TEMPLATE

str new_python_file.DOCSTRING_TEMPLATE

Initial value:

=  '''"""
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.
 
Dependencies
------------
- oc_diagnostics (_dbg structured logger)
"""
'''

Definition at line 64 of file new_python_file.py.

ENCODING

str new_python_file.ENCODING = "# -*- coding: utf-8 -*-"

Definition at line 56 of file new_python_file.py.

IMPORT_BLOCK

str new_python_file.IMPORT_BLOCK = "\nfrom oc_diagnostics import _dbg\n"

Definition at line 61 of file new_python_file.py.

PACKAGE_INIT_DOCSTRING

str new_python_file.PACKAGE_INIT_DOCSTRING

Initial value:

=  '''"""
Purpose
-------
Package marker for this Python package.
 
Responsibilities
----------------
- Mark this directory as an importable Python package.
 
Contracts
---------
- Contains no runtime logic; created by ``oct new`` as a package marker.
"""
'''

Definition at line 132 of file new_python_file.py.

SHEBANG

str new_python_file.SHEBANG = "#!/usr/bin/env python3"

Definition at line 55 of file new_python_file.py.

TEST_BODY_TEMPLATE

str new_python_file.TEST_BODY_TEMPLATE

Initial value:

=  '''
{import_line}
 
 
def test_{stem}_placeholder():
    """Placeholder test - replace with real tests."""
    assert True
'''

Definition at line 116 of file new_python_file.py.

TEST_DOCSTRING_TEMPLATE

str new_python_file.TEST_DOCSTRING_TEMPLATE

Initial value:

=  '''"""
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.
"""
'''

Definition at line 92 of file new_python_file.py.