Importer Module

Module: piethorn.filehandle.importer

Overview

This module provides project-root discovery, source-directory tracking, direct module loading, and runtime wrappers around package trees.

CallerRoot

class CallerRoot(path=EMPTY_PATH, source_dir=None, allow_path_changes=True, allow_source_changes=True)

Tracks a project root path and optional source directory.

Important properties:

  • path

  • has_path

  • source_dir

  • parent

  • children

Methods

child(path, source_dir=None)

Return or create a cached child root.

with_caller_context

with_caller_context(*, needs_caller_root=False, check_output=False, out=Any)

Decorator used by the importer helpers to inject project-root and caller-root context.

to_path

to_path(*args, sub_to_source=False, resolve=False, strict=False, project_root=_PROJECT_ROOT)

Resolve one or more path fragments relative to the current tracked project or source directory.

to_path("child.py", sub_to_source=True, project_root=caller_root)

change_source_dir

change_source_dir(source_dir, *, path=None, strict=False, project_root=_PROJECT_ROOT)

Validate and update the tracked source directory.

change_source_dir("pkg", path=root, project_root=caller_root)

convert_dot_notation

convert_dot_notation(s, *, project_root=_PROJECT_ROOT)

Convert dotted import notation into an existing project-relative path.

convert_dot_notation("child", project_root=caller_root)  # "child.py"

load_target_module

load_target_module(name, path, at_local=False)

Load a Python module directly from a filesystem path and register it in sys.modules.

ModuleInfo

class ModuleInfo(path, *, name=None, submodules=None)

Metadata object describing a filesystem-backed module or package.

Important properties:

  • import_name

  • name

  • path

  • parent

  • sub_modules

  • module

  • is_built

Important methods:

build_module()

Build the runtime Module and then build submodules.

build_submodules()

Build the submodules already registered under this module.

Example

info = ModuleInfo(package_path)
module = info.module

Module

class Module(..., module_info=None)

Runtime wrapper that exposes a package tree as attributes and lazily builds child modules.

Behavior

Attribute lookup checks:

  1. the loaded Python module object

  2. known submodule metadata on disk

Autodoc