syned.util package

Submodules

syned.util.json_tools module

Functions to read/write syned objects in json files.

Notes

Common syned classes are imported at module level so they are available when loading json files. To load objects from other packages (e.g. shadow4), pass their import statements via the exec_commands keyword, or supply a list of package modules via extra_packages and the import statements will be generated automatically with get_exec_commands_for_package().

syned.util.json_tools.get_exec_commands_for_package(package)

Build a string of import statements for all classes defined in a package.

Walks every submodule of package with pkgutil and collects classes whose __module__ matches the submodule name (i.e. classes defined there, not re-exported ones). The resulting string can be passed as exec_commands to the json loaders so they can instantiate objects by class name.

Parameters:

package (module) – The top-level package to inspect (e.g. import mypackage; get_exec_commands_for_package(mypackage)).

Returns:

Newline-separated from <module> import <Class>, ... statements.

Return type:

str

syned.util.json_tools.load_from_json_dictionary_recurrent(jsn, verbose=False, exec_commands=None, _ns=None)

Convert a dictionary (obtained from a JSON file) into a syned object.

This function is called recursively for every nested dict in the JSON tree. The _ns namespace dict is created once at the top level and passed down unchanged so that all exec and eval calls share the same scope. This avoids the Python scoping pitfall where names introduced by exec(commands) inside a function are not visible to a subsequent eval() call (because exec writes to the function’s local dict while eval reads from globals by default).

Parameters:

• jsn (dict) – Dictionary with JSON file information.

• verbose (bool, optional) – Print debug information.

• exec_commands (str or list of str, optional) – Import statements to execute before deserializing.

• _ns (dict or None) – Shared namespace for exec / eval. Created automatically on the first call; do not pass this from user code.

Return type:

instance of SynedObject

syned.util.json_tools.load_from_json_file(file_name, exec_commands=None, extra_packages=None)

Load a syned object from a json file.

Parameters:

• file_name (str) – Path to the JSON file.

• exec_commands (str, optional) – Import statements to execute before deserializing (e.g. for classes outside of syned).

• extra_packages (list of module, optional) –

  Additional packages whose classes should be made available during deserialization. Import statements are generated automatically via get_exec_commands_for_package(). Example:

  import shadow4
  obj = load_from_json_file("beamline.json", extra_packages=[shadow4])
  

Return type:

instance of SynedObject

syned.util.json_tools.load_from_json_text(text, exec_commands=None, extra_packages=None)

Load a syned object from a JSON string.

Parameters:

• text (str) – JSON text.

• exec_commands (str, optional) – Import statements to execute before deserializing.

• extra_packages (list of module, optional) – Additional packages whose classes should be made available during deserialization. Import statements are generated automatically via get_exec_commands_for_package().

Return type:

instance of SynedObject

syned.util.json_tools.load_from_json_url(file_url, exec_commands=None, extra_packages=None)

Load a syned object from a remote json file.

Parameters:

• file_url (str) – URL of the JSON file.

• exec_commands (str, optional) – Import statements to execute before deserializing.

• extra_packages (list of module, optional) – Additional packages whose classes should be made available during deserialization. Import statements are generated automatically via get_exec_commands_for_package().

Return type:

instance of SynedObject

Module contents

syned.util.deprecated(reason: str = '')

Decorator to mark functions as deprecated. It will result in a warning being emitted when the function is used.