new_python_file Namespace Reference

Functions
str	_make_header (str rel_posix)
str	_derive_import_path (str rel_posix)
None	_print_content (str label, str content)
	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 = "from oc_diagnostics import _dbg\n\n"
str	DOCSTRING_TEMPLATE
str	TEST_DOCSTRING_TEMPLATE
str	TEST_BODY_TEMPLATE

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).
- 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.

Function Documentation

_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 111 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 106 of file new_python_file.py.

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 117 of file new_python_file.py.

Here is the caller graph for this function:

create_new_file()

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

Definition at line 49 of file new_python_file.py.

ENCODING

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

Definition at line 43 of file new_python_file.py.

IMPORT_BLOCK

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

Definition at line 47 of file new_python_file.py.

SHEBANG

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

Definition at line 42 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 96 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 72 of file new_python_file.py.