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

• 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.
_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.
extract_module_info	Extract module 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._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) → pynenc.app.Pynenc

Find and load a Pynenc application instance.

Accepted --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 the spec is missing, malformed, or has no Pynenc instance.

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

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

Parameters:

app (Pynenc) – Pynenc application instance.

Returns:

Tuple of (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.