pynenc.util.import_app

Utilities for discovering and loading Pynenc application instances.

The CLI uses --app to locate the user’s Pynenc instance. Accepted formats (see :func:find_app_instance):

• auto-discovery – no --app scans the current directory and succeeds when exactly one importable Python file defines a Pynenc instance.

• module.attr – tasks.app imports tasks module, finds the Pynenc instance.

• package.module – mypackage.tasks standard Python import.

• file path – path/to/tasks.py loads the file directly.

Key components:

• find_app_instance: Main entry point for --app resolution.

• extract_module_info: Extracts module metadata from a live Pynenc instance.

• create_app_from_info: Re-hydrates a Pynenc instance from stored AppInfo.

Module Contents

Functions

_validate_app_spec	Reject common format mistakes with actionable error messages.
_is_file_path	Check whether the spec looks like a filesystem path rather than a module name.
_find_pynenc_in_module	Scan a loaded module for a Pynenc instance.
_find_pynenc_instances_in_module	Scan a loaded module for public Pynenc instances.
_iter_auto_discovery_files	Return top-level Python files to inspect for local app auto-discovery.
_looks_like_pynenc_app_source	Cheaply filter out helper scripts before importing app candidates.
_find_single_app_in_current_directory	Auto-discover a single local Pynenc instance.
_load_module_from_file	Load a .py file as a module and register it in sys.modules.
_resolve_file_path	Resolve an --app value that is a filesystem path.
_resolve_dotted_path	Resolve a dotted --app value like tasks.app or mypackage.tasks.
find_app_instance	Find and load a Pynenc application instance.
_find_app_in_user_modules	Scan loaded non-pynenc modules for one that holds app as a top-level variable.
_find_app_variable_in_module	Return the public attribute name in module whose value is app.
extract_module_info	Extract module name, filepath, and app variable name from a Pynenc instance.
_import_app_from_module	Try to import the original module and retrieve the app by variable name.
_scan_loaded_modules	Scan already-imported modules for a Pynenc instance matching app_id.
_find_pynenc_by_id_in_module	Check a single module for a Pynenc instance with the given app_id.
create_app_from_info	Re-hydrate a Pynenc instance from stored AppInfo metadata.

Data

logger
APP_FORMAT_HELP

API

pynenc.util.import_app.logger

‘getLogger(…)’

pynenc.util.import_app.APP_FORMAT_HELP = <Multiline-String>

pynenc.util.import_app._validate_app_spec(app_spec: str) → None

Reject common format mistakes with actionable error messages.

Parameters:

app_spec (str) – The raw --app value from the CLI.

Raises:

ValueError – If the format is invalid.

pynenc.util.import_app._is_file_path(app_spec: str) → bool

Check whether the spec looks like a filesystem path rather than a module name.

pynenc.util.import_app._find_pynenc_in_module(module: types.ModuleType) → pynenc.app.Pynenc

Scan a loaded module for a Pynenc instance.

Parameters:

module (types.ModuleType) – The module to scan.

Returns:

The first Pynenc instance found.

Raises:

ValueError – If no instance is found.

pynenc.util.import_app._find_pynenc_instances_in_module(module: types.ModuleType) → list[tuple[str, pynenc.app.Pynenc]]

Scan a loaded module for public Pynenc instances.

Parameters:

module (types.ModuleType) – The module to scan.

Returns:

(variable_name, app) pairs, de-duplicated by object identity.

pynenc.util.import_app._iter_auto_discovery_files() → list[pathlib.Path]

Return top-level Python files to inspect for local app auto-discovery.

pynenc.util.import_app._looks_like_pynenc_app_source(path: pathlib.Path) → bool

Cheaply filter out helper scripts before importing app candidates.

pynenc.util.import_app._find_single_app_in_current_directory() → pynenc.app.Pynenc

Auto-discover a single local Pynenc instance.

This intentionally scans only top-level Python files in the current working directory. If that finds zero or multiple apps, the caller must pass --app explicitly.

Returns:

The discovered Pynenc instance.

Raises:

ValueError – If discovery finds zero or multiple apps.

pynenc.util.import_app._load_module_from_file(file_path: str) → types.ModuleType

Load a .py file as a module and register it in sys.modules.

The file’s directory is added to sys.path so child processes (e.g. multiprocessing.spawn) can re-import the module by name.

Parameters:

file_path (str) – Absolute or relative path to the .py file.

Returns:

The loaded module.

Raises:

• ValueError – If the file does not exist or the spec cannot be created.

• ModuleNotFoundError – If the file has unresolvable imports.

pynenc.util.import_app._resolve_file_path(app_spec: str) → types.ModuleType

Resolve an --app value that is a filesystem path.

Parameters:

app_spec (str) – A path like path/to/tasks.py or path/to/tasks.

Returns:

The loaded module.

pynenc.util.import_app._resolve_dotted_path(app_spec: str) → types.ModuleType

Resolve a dotted --app value like tasks.app or mypackage.tasks.

Strategies (tried in order):

1. importlib.import_module(app_spec) — works for installed packages.

2. Import the parent module (last component treated as attribute name), e.g. pkg.mod.app → import pkg.mod.

3. Treat the first component as a local .py file in cwd, e.g. tasks.app → load tasks.py.

Parameters:

app_spec (str) – The dotted module path.

Returns:

The loaded module.

Raises:

ValueError – If no strategy succeeds.

pynenc.util.import_app.find_app_instance(app_spec: str | None = None) → pynenc.app.Pynenc

Find and load a Pynenc application instance.

If app_spec is empty, pynenc scans top-level Python files in the current directory and succeeds only when it finds exactly one Pynenc instance.

Accepted explicit --app formats:

• tasks.app – loads tasks.py from the current directory, scans for a Pynenc() instance.

• mypackage.tasks – standard importlib.import_module.

• path/to/tasks.py – loads the file directly.

Parameters:

app_spec (str | None) – The --app value from the CLI.

Returns:

The Pynenc application instance.

Raises:

ValueError – If discovery fails, the spec is malformed, or the target has no Pynenc instance.

pynenc.util.import_app._find_app_in_user_modules(app: pynenc.app.Pynenc) → tuple[str, str, str] | None

Scan loaded non-pynenc modules for one that holds app as a top-level variable.

The Pynenc class is defined in pynenc.app, so app.__module__ always returns "pynenc.app" — not the user module where app = Pynenc() was written. This helper finds the correct user module by identity-checking attributes across all loaded modules.

Parameters:

app (Pynenc) – The application instance to locate.

Returns:

(module_name, module_filepath, variable_name) or None.

pynenc.util.import_app._find_app_variable_in_module(module: types.ModuleType, app: pynenc.app.Pynenc) → str | None

Return the public attribute name in module whose value is app.

Parameters:

• module (types.ModuleType) – Module to inspect.

• app (Pynenc) – The instance to match by identity.

Returns:

Attribute name, or None if not found.

pynenc.util.import_app.extract_module_info(app: pynenc.app.Pynenc) → tuple[str | None, str | None, str | None]

Extract module name, filepath, and app variable name from a Pynenc instance.

Scans loaded user modules to find the one that holds app as a top-level variable. Falls back to app.__module__ when no user module claims it (e.g. during unit tests).

Parameters:

app (Pynenc) – Pynenc application instance.

Returns:

Tuple of (module_name, module_filepath, app_variable_name).

pynenc.util.import_app._import_app_from_module(app_info: pynenc.app_info.AppInfo) → pynenc.app.Pynenc | None

Try to import the original module and retrieve the app by variable name.

Parameters:

app_info (AppInfo) – Application metadata with module path and variable.

Returns:

The matching Pynenc instance, or None.

pynenc.util.import_app._scan_loaded_modules(app_id: str) → pynenc.app.Pynenc | None

Scan already-imported modules for a Pynenc instance matching app_id.

Parameters:

app_id (str) – The application ID to match.

Returns:

The matching instance, or None.

pynenc.util.import_app._find_pynenc_by_id_in_module(module: types.ModuleType, mod_name: str, app_id: str) → pynenc.app.Pynenc | None

Check a single module for a Pynenc instance with the given app_id.

Parameters:

• module (types.ModuleType) – The module to inspect.

• mod_name (str) – Module name for logging.

• app_id (str) – The application ID to match.

Returns:

The matching instance, or None.

pynenc.util.import_app.create_app_from_info(app_info: pynenc.app_info.AppInfo) → pynenc.app.Pynenc | None

Re-hydrate a Pynenc instance from stored AppInfo metadata.

Strategies (tried in order):

1. Import the original module and retrieve the named variable.

2. Scan already-imported modules for a matching app_id.

Parameters:

app_info (AppInfo) – Application metadata.

Returns:

The re-hydrated instance, or None if not found.