Nexus Generic Module

class nexus.generic.generic_settings

Bases: object

devlog = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>

raise_error = False

exception nexus.generic.NexusError

Bases: Exception

exception nexus.generic.NexusDevWarning(msg: str, indent: str = '    ', cls: str | None = None)

Bases: Warning

exception nexus.generic.NexusUserWarning(msg: str, indent: str = '    ', cls: str | None = None)

Bases: NexusDevWarning

nexus.generic.nocopy(value)

class nexus.generic.NexusUnpickler(file, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=())

Bases: Unpickler

This class is designed for backwards compatibility with pickles generated before Nexus was packaged (PR #5700, December 20, 2025). It shouldn’t touch anything but old Nexus pickles.

Attributes:

memo

Methods

find_class(module, name)	Return an object from a specified module.
load(/)	Load a pickle.

persistent_load

find_class(module, name)

Return an object from a specified module.

If necessary, the module will be imported. Subclasses may override this method (e.g. to restrict unpickling of arbitrary classes and functions).

This method is called whenever a class or a function object is needed. Both arguments passed are str objects.

nexus.generic.log(*items, **kwargs)

nexus.generic.message(msg, header=None, post_header=' message:', indent='    ', logfile=None)

nexus.generic.warn(msg: str, indent: str = '    ', warn_type: str = 'user', cls: str | None = None) → None

Report a warning.

Parameters:

msgstr

The message for the warning.

indentstr. default=” “

The indentation for the warning message.

warn_type{“user”, “dev”, “deprecate”, “class”}

See the notes for a description of when you should use each warning type.

clsstr, optional

Meant to be passed through self.warn() in a class that derives from object_interface.

Notes

If you are a developer who wants to use this function but are unsure of what kind of warning type to use, here are some basic guidelines for choosing:

• If the function you’re putting a warning in will be directly called by a user, you should use "user", as this will show them where in their own script they’ve called the function.

• If the function you’re putting a warning in will be indirectly called by a function that a user has called, and if the problem is due to something the user has done you should use the class’s self.warn() functionality if it inherits from DevBase, otherwise use the warning type "class" and pass in the name of the class and/or function you’re calling from.

• If the function is called indirectly by a user and it is not necessarily their fault that something has gone awry, you should use "dev". This should likely only be used in places where you are mostly sure there won’t be any problems but the code has not been thoroughly tested.

• If you are deprecating a function, use the @nxs_deprecate decorator and supply the version and the replacement that a user should use instead of the soon-to-be-removed function.

nexus.generic.nxs_deprecate(since: str, replacement: str, indent: str = '    ')

Decorator for signaling the deprecation of a Nexus function.

This should itself be deprecated when the minimum Python version is 3.13, when the official warnings.deprecated() decorator is added.

Parameters:

sinceVersion

The version of Nexus when the function was deprecated.

replacementstr

The replacement function for the function being deprecated.

indentstr, default = “ “

Indentation to go before the warning.

nexus.generic.error(msg: str, header: str | None = None, exit: bool = True, trace: int | None = -1, indent: str = '    ', logfile: TextIO | None = None)

Report an error.

Parameters:

msgstr

The message to write

headerstr, optional

Header to print before the message. Will have " error:" appended to it.

exitbool, default=True

Whether or not to force an exit through sys.exit(). See Notes.

traceint or None, default=-1

How much of the traceback to print.

None prints the full traceback, positive integers limit to a number of frames relative to this function, and negative integers limit to a number of frames up to this function. Setting this to 0 will disable the traceback completely.

The default value is -1, which will print only the traceback up to the location that this function was called, but will not show the location of this function.

indentstr, default=” “

A string that will be used to indent the error message.

logfileTextIO, default=generic_settings.devlog

The already-opened file to write to. Typically this is sys.stdout.

Raises:

NexusError

If generic_settings.raise_error = True.

See also

generic_settings

Notes

If you set exit=True, then this will call sys.exit(1), which will force an exit that can not be caught or handled.

class nexus.generic.object_interface

Bases: object

Methods

class_error(message[, header, exit, trace, ...])	Report an error relating to a class.
error(message[, header, exit, trace])	Report an error inside a class.
keys()
open_log(filepath)
save([fpath])
warn(msg[, indent])	Warning from inside a Nexus class.

class_get
class_has
class_items
class_keys
class_log
class_set
class_set_optional
class_set_single
class_warn
clear
close_log
copy
data_repr
items
load
log
tree
values
write

tree(depth=None, all=False, types=False, nindent=1)

data_repr(nindent=1, ret_str_keys=False)

keys()

values()

items()

copy()

clear()

save(fpath=None)

load(fpath=None)

open_log(filepath)

close_log()

write(s)

log(*items, **kwargs)

warn(msg: str, indent: str = '    ')

Warning from inside a Nexus class.

See generic.warn() for description.

error(message, header=None, exit=True, trace=-2)

Report an error inside a class.

This is the same as generic.error(), but with trace=-2 as the default. This has the benefit of only printing a traceback up to the call location, and not inadvertently pointing someone to generic.py.

classmethod class_log(message)

classmethod class_warn(message, header=None, post_header=' Warning:')

classmethod class_error(message, header=None, exit=True, trace=-2, post_header=' Error:')

Report an error relating to a class.

See also

object_interface.error

Used inside subclasses of object_interface.

generic.error

Called when you are not reporting an error specific to a class.

classmethod class_has(k)

classmethod class_keys()

classmethod class_items()

classmethod class_get(k)

classmethod class_set(**kwargs)

classmethod class_set_single(k, v)

classmethod class_set_optional(**kwargs)

class nexus.generic.obj(*vars, **kwargs)

Bases: object_interface

Methods

append(value)
class_error(message[, header, exit, trace, ...])	Report an error relating to a class.
error(message[, header, exit, trace])	Report an error inside a class.
first()
keys()
list(*keys)
open_log(filepath)
save([fpath])
sorted_keys()
warn(msg[, indent])	Warning from inside a Nexus class.

add
add_optional
check_required
check_types
check_types_optional
class_get
class_has
class_items
class_keys
class_log
class_set
class_set_optional
class_set_single
class_warn
clear
close_log
copy
copy_from
copy_to
data_repr
delete
delete_optional
delete_required
dict
extract
extract_optional
get
get_optional
get_path
get_required
inverse
items
last
list_optional
load
log
move_from
move_from_optional
move_to
move_to_optional
obj
path_exists
random_key
select_random
serial
set
set_optional
set_path
shallow_copy
to_dict
to_obj
transfer_from
transfer_to
tree
tuple
values
write

append(value)

list(*keys)

list_optional(*keys)

tuple(*keys)

dict(*keys)

to_dict()

obj(*keys)

to_obj()

first()

last()

select_random()

sorted_keys()

random_key()

set(*objs, **kwargs)

set_optional(*objs, **kwargs)

get(key, value=None)

get_optional(key, value=None)

get_required(key)

delete(*keys)

delete_optional(key, value=None)

delete_required(key)

add(key, value)

add_optional(key, value)

transfer_from(other, keys=None, copy=False, overwrite=True)

transfer_to(other, keys=None, copy=False, overwrite=True)

move_from(other, keys=None, optional=False)

move_to(other, keys=None, optional=False)

move_from_optional(other, keys=None)

move_to_optional(other, keys=None)

copy_from(other, keys=None, deep=True)

copy_to(other, keys=None, deep=True)

extract(keys=None, optional=False)

extract_optional(keys=None)

check_required(keys, exit=True)

check_types(types, optional=False, exit=True)

check_types_optional(types, exit=True)

shallow_copy()

inverse()

path_exists(path)

set_path(path, value=None)

get_path(path, value=None)

serial(s=None, path=None)

class nexus.generic.hobj(*args, **kwargs)

Bases: obj

Methods

append(value)
class_error(message[, header, exit, trace, ...])	Report an error relating to a class.
error(message[, header, exit, trace])	Report an error inside a class.
first()
list(*keys)
open_log(filepath)
save([fpath])
sorted_keys()
warn(msg[, indent])	Warning from inside a Nexus class.

add
add_optional
check_required
check_types
check_types_optional
class_get
class_has
class_items
class_keys
class_log
class_set
class_set_optional
class_set_single
class_warn
clear
close_log
copy
copy_from
copy_to
data_repr
delete
delete_optional
delete_required
dict
extract
extract_optional
get
get_optional
get_path
get_required
inverse
items
keys
last
list_optional
load
log
move_from
move_from_optional
move_to
move_to_optional
obj
path_exists
random_key
select_random
serial
set
set_optional
set_path
shallow_copy
to_dict
to_obj
transfer_from
transfer_to
tree
tuple
values
write

keys()

values()

items()

clear()

class nexus.generic.hidden(*vals, **kwargs)

Bases: hobj

Methods

append(value)
class_error(message[, header, exit, trace, ...])	Report an error relating to a class.
error(message[, header, exit, trace])	Report an error inside a class.
first()
list(*keys)
save([fpath])
sorted_keys()
warn(msg[, indent])	Warning from inside a Nexus class.

add
add_optional
check_required
check_types
check_types_optional
class_get
class_has
class_items
class_keys
class_log
class_set
class_set_optional
class_set_single
class_warn
clear
close_log
copy
copy_from
copy_to
data_repr
delete
delete_optional
delete_required
dict
extract
extract_optional
get
get_optional
get_path
get_required
hidden
inverse
items
keys
last
list_optional
load
log
move_from
move_from_optional
move_to
move_to_optional
obj
open_log
path_exists
public
random_key
select_random
serial
set
set_optional
set_path
shallow_copy
to_dict
to_obj
transfer_from
transfer_to
tree
tuple
values
write

hidden()

public()

open_log(filepath)

close_log()

write(s)

log(*items, **kwargs)