Pyjo.Loader - Load all kinds of things

from Pyjo.Loader import data_section, find_modules, load_class
from Pyjo.Util import warn

# Find modules in a namespace
for module in find_modules('Some.Namespace'):

    # Load them safely
    e = load_class(module)
    if isinstance(e, Exception):
        warn(f'Loading "{module}" failed: {e}')
        continue

    # And extract files from the DATA section
    print(data_section(module, 'some_file.txt'))

Pyjo.Loader is a class loader and plugin framework. Aside from finding modules and loading classes, it allows multiple files to be stored in the DATA section of a module, which can then be accessed individually. The section is the __DATA__ variable of the module, or its docstring after a line __DATA__.

# Foo.py

__DATA__ = r'''
@@ test.txt
This is the first file.

@@ test2.html (base64)
VGhpcyBpcyB0aGUgc2Vjb25kIGZpbGUu

@@ test
This is the
third file.
'''

Each file has a header starting with @@, followed by the file name and optional instructions for decoding its content. Currently only the Base64 encoding is supported, which can be quite convenient for the storage of binary data.

A class is named as a module of Python, with dots, and is loaded from sys.path. A function that takes a class takes the module, a class, or the dotted name of a module or of a class in it.

See also

Pyjoyment, https://mojolicious.org.

Ported from Mojo::Loader of Mojolicious 9.49.

Functions

Pyjo.Loader.data_section(cls: Class | None, name: str | None = None) → dict[str, str | bytes] | str | bytes | None[source]
all = data_section('Foo.Bar')
index = data_section('Foo.Bar', 'index.html')

Extract embedded file from the DATA section of a module, all files will be cached once they have been accessed for the first time. A file encoded in Base64 is bytes, any other a str.

# List embedded files
for name in data_section('Foo.Bar'):
    print(name)
Pyjo.Loader.file_is_binary(cls: Class, name: str) → bool | None[source]
boolean = file_is_binary('Foo.Bar', 'test.png')

Check if embedded file from the DATA section of a module was Base64 encoded.

Pyjo.Loader.find_modules(ns: str, *, recursive: bool = False) → list[str][source]
modules = find_modules('MyApp.Namespace')
modules = find_modules('MyApp.Namespace', recursive=True)

Search for modules in a namespace, in the directories of sys.path, without loading them. A package, a directory with an __init__.py, is a module too.

These options are currently available:

recursive
recursive=True

Search namespace recursively.

Pyjo.Loader.find_packages(ns: str) → list[str][source]
pkgs = find_packages('MyApp.Namespace')

Search for packages in a namespace non-recursively: the modules in it that are loaded, as sys.modules has them.

Pyjo.Loader.load_class(cls: str) → Pyjo_Exception | bool | None[source]
e = load_class('Foo.Bar')

Load a class and catch exceptions, returns a false value if loading was successful, a true value if the class was not found, or a Pyjo.Exception object if loading failed. A directory without an __init__.py (a namespace package) is not a class. The context of the exception is the line of the module that failed to load, and the exception of Python is its __cause__.

# Handle exceptions
if e := load_class('Foo.Bar'):
    raise Exception(f'Exception: {e}' if isinstance(e, Exception) else 'Not found!')
Pyjo.Loader.load_classes(ns: str) → list[str][source]
classes = load_classes('Foo.Bar')

Load all classes in a namespace recursively.