Cleanup

README.md

@@ -1,13 +1,13 @@
-# PRIK
-
-**Python Runtime Interop Kit.**
+# PRIK — Python Runtime Interop Kit
 
 **Turn Fortran into natural Python APIs.**
 
-Build clean, importable native extensions from supported Fortran without
-writing low-level binding code. PRIK preserves modules, derived types, arrays,
-and native behavior, and generates an editable `.pyi` contract so you can
-shape the Python API.
+PRIK wraps Fortran code into clean, importable native extensions for Python
+without requiring you to write low-level binding code.
+
+It is a Fortran-to-Python binding generator that preserves modules, derived
+types, arrays, callbacks, and native behavior, and generates an editable
+`.pyi` contract so you can shape the resulting Python API.
 
 **Project status: Alpha (`0.1.x`).** Core Fortran wrapper workflows are
 implemented and tested across supported compilers, but public APIs may still

prik/preprocessing_test_example.md → docs/developer/compiler-preprocessing.md

@@ -1,4 +1,13 @@
-# Compiler-Backed Preprocessing Notes
+---
+title: Compiler Preprocessing Reference
+audience: developers, contributors
+prerequisites: repository structure, native project compiler flags
+related: source-map.md, c-parser-reference.md, fortran-parser-reference.md, ../user/examples/recipes/compiler-preprocessing.md
+status: maintained
+publication: draft
+---
+
+# Compiler-Backed Preprocessing Reference
 
 `prik/pipeline/preprocessing.py` owns compiler-backed preprocessing for the wrapper
 pipeline. The parsers consume one expanded source stream; they do not evaluate
@@ -40,8 +49,7 @@ Built-in adapters cover GCC-compatible C/Clang (`-E -x c`), GNU Fortran
 compiler families. A custom template must write expanded source to stdout:
 
 ```bash
-python -m prik parse include/api.h --language c \
-  --preprocess compiler \
+python -m prik parse include/api.h --language c --preprocess compiler \
   --preprocessor-adapter command-template \
   --preprocess-template 'vendor-cc --preprocess {include_dirs} {defines} {source}'
 ```

docs/developer/feature-to-code-map.md

@@ -28,7 +28,7 @@ before documentation may call the behavior supported.
 
 <!-- PRIK_C_DOCS_START
 | CLI stage selection and output | `docs/user/getting-started/beginner-workflow.md`, `docs/user/reference/cli-commands.md` | `prik/cli.py`, `prik/parsers/fortran/cli.py`, `prik/parsers/c/cli.py` | `tests/fortran/command_line_interface/pipeline/`, parser CLI tests, documentation example tests | Command output and diagnostics match checked expectations |
-| Compiler preprocessing | `docs/user/examples/recipes/compiler-preprocessing.md`, parser references | `prik/pipeline/preprocessing.py`, parser CLI helpers | `tests/fortran/source_preprocessing/preprocessing/`, `tests/fortran/source_preprocessing/preprocessing/test_parser_boundaries.py`, C preprocessing tests | Preprocessed input and dependency facts are stable |
+| Compiler preprocessing | `docs/user/examples/recipes/compiler-preprocessing.md`, `docs/developer/compiler-preprocessing.md`, parser references | `prik/pipeline/preprocessing.py`, parser CLI helpers | `tests/fortran/source_preprocessing/preprocessing/`, `tests/fortran/source_preprocessing/preprocessing/test_parser_boundaries.py`, C preprocessing tests | Preprocessed input and dependency facts are stable |
 | C parse output | `docs/developer/c-parser-reference.md`, `docs/user/examples/recipes/inspect-c-api.md` | `prik/parsers/c/parser.py`, `models.py`, `lexer.py`, `type_resolver.py` | `tests/c/parsing/test_c_declarations_and_declarators.py`, `tests/c/parsing/test_c_fixture_suite.py` | Parser facts and diagnostics match fixtures |
 | Semantic IR | `docs/user/reference/semantic-ir.md` | `prik/semantics/models.py`, `fortran2ir.py`, `c2ir.py` | `tests/fortran/semantic_ir/semantics/`, `tests/c/semantics/conversion/` | Source facts lower without losing wrapper-relevant meaning |
 | Generated Fortran bridge | `docs/user/reference/fortran-wrapper.md` | `prik/wrapper_codegen/fortran/bridge.py`, `prik/wrapper_codegen/printers/source_printers.py` | `tests/fortran/infrastructure/wrapper_codegen/`, `tests/fortran/` | Generated bridge compiles and preserves native calling contract |

docs/developer/index.md

@@ -18,6 +18,7 @@ tests, then provides focused contribution workflows.
 - [Repository structure](repository-structure.md)
 - [Source map](source-map.md)
 - [Feature-to-code map](feature-to-code-map.md)
+- [Compiler preprocessing reference](compiler-preprocessing.md)
 - [Fortran parser reference](fortran-parser-reference.md)
 - [Quality assurance](quality-assurance.md)
 - [Build system](build-system.md)

docs/developer/source-map.md

@@ -40,7 +40,7 @@ change crosses ownership boundaries.
 | Change area | Open first | Public docs to update | Focused evidence |
 | --- | --- | --- | --- |
 | CLI flags, stage selection, output formatting, diagnostics | `prik/cli.py` | `docs/user/reference/cli-commands.md`, `docs/user/getting-started/beginner-workflow.md` | `tests/fortran/command_line_interface/pipeline/`, `tests/shared/docs/test_examples.py` |
-| Compiler preprocessing, include paths, macros, and target flags | `prik/pipeline/preprocessing.py` | `docs/user/examples/recipes/compiler-preprocessing.md`, `docs/developer/fortran-parser-reference.md` | `tests/fortran/source_preprocessing/preprocessing/`, `tests/fortran/source_preprocessing/preprocessing/test_parser_boundaries.py` |
+| Compiler preprocessing, include paths, macros, and target flags | `prik/pipeline/preprocessing.py` | `docs/user/examples/recipes/compiler-preprocessing.md`, `docs/developer/compiler-preprocessing.md`, `docs/developer/fortran-parser-reference.md` | `tests/fortran/source_preprocessing/preprocessing/`, `tests/fortran/source_preprocessing/preprocessing/test_parser_boundaries.py` |
 | Fortran parser facts and diagnostics | `prik/parsers/fortran/parser.py` | `docs/developer/fortran-parser-reference.md`, `docs/user/examples/recipes/inspect-fortran-api.md` | `tests/fortran/source_parsing/parsing/` |
 | Semantic `.pyi` parsing, conversion, printing, package generation, and round-trip behavior | `prik/parsers/pyi/parser.py`, `prik/pipeline/pyi.py`, `prik/semantics/pyi2ir.py`, `prik/wrapper_codegen/printers/pyi_printer.py` | `docs/user/reference/semantic-pyi-format.md`, `docs/user/reference/pyi-contracts/index.md`, `docs/user/examples/recipes/semantic-pyi-contracts.md` | `tests/fortran/semantic_pyi_format/`, `tests/fortran/semantic_pyi_format/pipeline/test_contract_package_generation.py`, `tests/fortran/semantic_pyi_format/pipeline/test_contract_loading.py`, `tests/fortran/semantic_pyi_format/end_to_end/test_authoritative_contract_runtime.py`, `tests/fortran/semantic_pyi_format/pipeline/` |
 | Wrapper-planning errors and support claims | `prik/semantics/policy_completion.py`, `prik/wrapper_codegen/planner.py` | `docs/user/reference/diagnostic-codes.md`, `docs/user/language-support/feature-matrix.md` | `tests/fortran/infrastructure/policy/`, feature-local `policy/`, and `tests/fortran/infrastructure/wrapper_codegen/` |
@@ -55,7 +55,7 @@ change crosses ownership boundaries.
 | Source navigation documentation | `docs/developer/source-map.md`, `docs/developer/feature-to-code-map.md`, package README files | `docs/developer/source-map.md` | `tests/shared/docs/test_structure.py` |
 
 <!-- PRIK_C_DOCS_START
-| Compiler preprocessing, include paths, macros, target flags | `prik/pipeline/preprocessing.py` | `docs/user/examples/recipes/compiler-preprocessing.md`, `docs/developer/c-parser-reference.md`, `docs/developer/fortran-parser-reference.md` | `tests/fortran/source_preprocessing/preprocessing/`, `tests/fortran/source_preprocessing/preprocessing/test_parser_boundaries.py` |
+| Compiler preprocessing, include paths, macros, target flags | `prik/pipeline/preprocessing.py` | `docs/user/examples/recipes/compiler-preprocessing.md`, `docs/developer/compiler-preprocessing.md`, `docs/developer/c-parser-reference.md`, `docs/developer/fortran-parser-reference.md` | `tests/fortran/source_preprocessing/preprocessing/`, `tests/fortran/source_preprocessing/preprocessing/test_parser_boundaries.py` |
 PRIK_C_DOCS_END -->
 
 <!-- PRIK_C_DOCS_START

docs/user/examples/recipes/build-and-import-python-api.md

@@ -13,11 +13,11 @@ Use this recipe when a Python script needs to build a wrapper and load the
 generated extension directly.
 
 `build_fortran_extension` returns a result object with the module name, shared
-library path, generated source paths, and other build artifacts.
+library path, generated source paths, and other build artifacts. Call its
+`import_module()` method when the script should load the built extension.
 
 <!-- prik-doc-test: exact -->
 ```python
-from importlib.util import module_from_spec, spec_from_file_location
 from pathlib import Path
 from tempfile import TemporaryDirectory
 
@@ -28,9 +28,7 @@ from prik import build_fortran_extension
 source = Path("tests/fortran/building_shared_library/end_to_end/fixtures/native/fruntime_abi_f90.f90")
 with TemporaryDirectory() as output_dir:
     build = build_fortran_extension(source, output_dir=output_dir)
-    spec = spec_from_file_location(build.module_name, build.shared_library)
-    module = module_from_spec(spec)
-    spec.loader.exec_module(module)
+    module = build.import_module()
     native_module = module.fruntime_abi_f90
 
     print(build.module_name)
@@ -47,7 +45,11 @@ fruntime_abi_f90
 
 ## Notes
 
-- This pattern avoids editing `sys.path`.
+- `import_module()` avoids editing `sys.path` and registers the extension under
+  `build.module_name` in the normal Python module cache.
+- The shared-library file must exist. Direct builds can import immediately;
+  Makefile and source-only results can import after their extension has been
+  built.
 - `TemporaryDirectory` keeps documentation and tests from leaving build
   artifacts in the checkout.
 - Use the returned artifact paths when debugging generated code.

docs/user/examples/recipes/compiler-preprocessing.md

@@ -2,7 +2,7 @@
 title: Use Compiler Preprocessing Options
 audience: users, developers
 prerequisites: installation, native project compiler flags
-related: ../../../developer/c-parser-reference.md, ../../../developer/fortran-parser-reference.md
+related: ../../../developer/compiler-preprocessing.md, ../../../developer/c-parser-reference.md, ../../../developer/fortran-parser-reference.md
 status: maintained
 publication: draft
 ---
@@ -40,6 +40,8 @@ PRIK_C_DOCS_END -->
 
 ## Notes
 
+- For the pipeline model, adapters, diagnostics, and include-exposure policy,
+  see the [compiler preprocessing reference](../../../developer/compiler-preprocessing.md).
 - Pass the same important include paths, macros, and target flags used by the
   native project.
 - Compiler-backed semantic and `.pyi` stages can also probe target datatype

docs/user/reference/python-api.md

@@ -187,7 +187,7 @@ plain NumPy arrays are for ordinary array-data parameters.
 | `build_fortran_extension` | Builds a Python extension from semantic Fortran source inputs plus optional native-only sources, artifacts, compiler flags, include paths, libraries, and ordered link items. |
 | `build_pyi_extension` | Builds a Python extension from semantic `.pyi` contracts plus explicit native artifacts. |
 | `build_pyi_extension_from_manifest` | Replays a saved semantic `.pyi` wrapper build manifest, either building directly or regenerating `Makefile.prik`. |
-| `WrapperBuildResult` | Result model returned by wrapper build functions. |
+| `WrapperBuildResult` | Result model returned by wrapper build functions; `import_module()` explicitly loads its built extension. |
 | `NativeBuildPlan` | Structured native implementation compile/link plan attached to a wrapper build result. |
 | `NativeCompilationUnit` | Native source compilation unit and produced object recorded in a native build plan. |
 | `NativePrebuiltArtifact` | Caller-supplied native object, archive, or shared library recorded in a native build plan. |
@@ -205,6 +205,13 @@ the semantic contract paths. Semantic `.pyi` build results also expose a
 normalized replay `manifest`; Makefile mode writes that manifest to
 `<out-dir>/prik-build.json` before generating `Makefile.prik`.
 
+When a program needs the generated extension immediately, call
+`result.import_module()`. It loads `result.shared_library` under
+`result.module_name` without changing `sys.path` and returns the imported
+module. The method requires that the shared-library file already exists, so a
+direct build can import at once and a Makefile result can import after `make`
+has produced the extension.
+
 ## Target type and NumPy helpers
 
 | Symbol | Purpose |

mkdocs.yml

@@ -117,6 +117,7 @@ nav:
       - Source Map: developer/source-map.md
       - Feature To Code Map: developer/feature-to-code-map.md
       - Repository Structure: developer/repository-structure.md
+      - Compiler Preprocessing Reference: developer/compiler-preprocessing.md
       # PRIK_C_DOCS: - C Parser Reference: developer/c-parser-reference.md
       - Fortran Parser Reference: developer/fortran-parser-reference.md
       - Quality Assurance: developer/quality-assurance.md