py_import (erlang_python v3.0.0)

View Source

Import and path registry for Python interpreters.

This module manages the global import and path registries that are applied to all Python interpreters. Imports and paths are applied immediately to all running interpreters and stored for new interpreters.

Configuration

Imports and paths can be configured in the application environment:

   {erlang_python, [
       {imports, [{json, dumps}, {math, sqrt}, {os, getcwd}]},
       {paths, ["/path/to/modules"]}
   ]}

Examples

   %% Register modules for import in all interpreters (immediate + future)
   ok = py_import:ensure_imported(json).
   ok = py_import:ensure_imported(math, sqrt).
  
   %% Add paths to sys.path in all interpreters (immediate + future)
   ok = py_import:add_path("/path/to/my/modules").
  
   %% Check registry contents
   Imports = py_import:all_imports().
   Paths = py_import:all_paths().

Summary

Types

py_func/0
py_module/0

Functions

add_path(Path)

Add a path to sys.path in all interpreters.

add_paths(Paths)

Add multiple paths to sys.path in all interpreters.

all_imports()

Get all registered imports from the global registry.

all_paths()

Get all registered paths from the global registry.

clear_imports()

Clear all registered imports from the global registry.

clear_paths()

Clear all registered paths from the global registry.

ensure_imported(Module)

Register a module for import in all interpreters.

ensure_imported(Module, Func)

Register a module/function for import in all interpreters.

import_list()

List all registered imports.

init()

Initialize the import and path registry ETS tables.

is_imported(Module)

Check if a module is registered in the import registry.

is_imported(Module, Func)

Check if a module/function is registered in the import registry.

is_path_added(Path)

Check if a path is registered in the path registry.

Types

py_func/0

-type py_func() :: atom() | binary() | string().

py_module/0

-type py_module() :: atom() | binary() | string().

Functions

add_path(Path)

-spec add_path(string() | binary() | atom()) -> ok.

Add a path to sys.path in all interpreters.

Adds the path immediately to sys.path in all running interpreters (contexts and event loops) and stores it for future interpreters.

Example:

  ok = py_import:add_path("/path/to/my/modules"),
  {ok, Result} = py:call(mymodule, myfunc, []).

add_paths(Paths)

-spec add_paths([string() | binary() | atom()]) -> ok.

Add multiple paths to sys.path in all interpreters.

Adds all paths to the global path registry. Paths are added in order, so the first path in the list will be first in sys.path.

Example:

  ok = py_import:add_paths(["/path/to/lib1", "/path/to/lib2"]),
  {ok, Result} = py:call(mymodule, myfunc, []).

all_imports()

-spec all_imports() -> [{binary(), binary() | all}].

Get all registered imports from the global registry.

Returns a list of {Module, Func | all} tuples representing all modules/functions registered for automatic import.

Example:

  ok = py_import:ensure_imported(json),
  ok = py_import:ensure_imported(math, sqrt),
  [{<<"json">>, all}, {<<"math">>, <<"sqrt">>}] = py_import:all_imports().

all_paths()

-spec all_paths() -> [binary()].

Get all registered paths from the global registry.

Returns a list of paths in the order they were added.

Example:

  ok = py_import:add_path("/path/to/modules"),
  [<<"/path/to/modules">>] = py_import:all_paths().

clear_imports()

-spec clear_imports() -> ok.

Clear all registered imports from the global registry.

Removes all entries from the registry. Does not affect already-running interpreters.

clear_paths()

-spec clear_paths() -> ok.

Clear all registered paths from the global registry.

Removes all entries from the path registry. Does not affect already-running interpreters.

ensure_imported(Module)

-spec ensure_imported(py_module()) -> ok | {error, term()}.

Register a module for import in all interpreters.

Imports the module immediately in all running interpreters and adds it to the registry for future interpreters.

The __main__ module is never cached.

Example:

  ok = py_import:ensure_imported(json),
  {ok, Result} = py:call(json, dumps, [Data]).

ensure_imported(Module, Func)

-spec ensure_imported(py_module(), py_func()) -> ok | {error, term()}.

Register a module/function for import in all interpreters.

Imports the module immediately in all running interpreters and adds it to the registry for future interpreters.

The __main__ module is never cached.

Example:

  ok = py_import:ensure_imported(json, dumps),
  {ok, Result} = py:call(json, dumps, [Data]).

import_list()

-spec import_list() -> {ok, #{binary() => [binary()]}} | {error, term()}.

List all registered imports.

Returns a map of modules to their registered functions. Module names are binary keys, function lists are the values. An empty list means only the module is registered (no specific functions).

Example:

  ok = py_import:ensure_imported(json),
  ok = py_import:ensure_imported(json, dumps),
  ok = py_import:ensure_imported(json, loads),
  ok = py_import:ensure_imported(math),
  {ok, #{<<"json">> => [<<"dumps">>, <<"loads">>],
         <<"math">> => []}} = py_import:import_list().

init()

-spec init() -> ok.

Initialize the import and path registry ETS tables.

This is called automatically during application startup. Also loads imports and paths from application config. Safe to call multiple times - does nothing if already initialized.

is_imported(Module)

-spec is_imported(py_module()) -> boolean().

Check if a module is registered in the import registry.

is_imported(Module, Func)

-spec is_imported(py_module(), py_func()) -> boolean().

Check if a module/function is registered in the import registry.

is_path_added(Path)

-spec is_path_added(string() | binary() | atom()) -> boolean().

Check if a path is registered in the path registry.