Binding

class PlasmaCalcs.tools.oop_tools.binding.Binding(namespace, *default_targets, keep_local=False, methodtype=None)

Bases: object

context manager for binding environment.

provides these function decorators:

@self (or @self.bind()) –> bind function or class to each target from self.default_targets.

@self.binder(*targets) –> bind function or class to each target from targets.

bindings at the corresponding attribute name e.g. target.(func.__name__) = func.

Upon exiting, restore original state for names in self.namespace of any objects

decorated via @self, @self.bind(), or @self.bind_to().

To bind, but ALSO keep the function in the local namespace (i.e. don’t remove it upon exiting),

use keep_local=True. Either in ‘self.bind(keep_local=True)’

or ‘with binding.to(*targets, keep_local=True)’.

To bind a special method type (e.g., staticmethod, classmethod), use the methodtype parameter,

e.g. methodtype=staticmethod. Either in ‘self.bind(methodtype=staticmethod)’

or ‘with binding.to(…, methodtype=staticmethod)’

Also, upon exiting context, (i.e., after ‘with’ block),

restore self.keep_local and self.methodtype to their original values
(or their values just before the most recent call to self.to(…),
if context hasn’t been exited since last call to self.to.)

EXAMPLE:

# originally, foo1, Foo3, foo4, foo5 undefined, but foo2 defined as foo2_original.

binding = Binding(locals())

with binding.to(MyClass):

@binding

def foo1(self, args): # binds MyClass.foo1 = foo1

# <code for foo1>

@binding.binder(MySecondClass)

def foo2(self, args): # binds MySecondClass.foo2 = foo2

# <code for foo2>

@binding.bind() # equivalent to @binding

class Foo3(self, args): # binds MyClass.Foo3 = Foo3

# <code for Foo3>

@binding.binder(MySecondClass, MyThirdClass)

def foo4(self, args): # binds MySecondClass.foo4 = foo4; MyThirdClass.foo4 = foo4

# <code for foo4>

@binding.bind(keep_local=True)

def foo5(self, args): # MyClass.foo5 = foo5

# <code for foo5>

@binding.bind(methodtype=staticmethod)

def foo6(args): # MyClass.foo6 = staticmethod(foo6)

# <code for foo6>

# upon exiting, alter the local namespace: delete foo1, Foo3, foo4; set foo2 = foo2_original.

# (do not delete foo5 from the namespace since keep_local=True was used for foo5.)

ARGS:

namespace: dict

the namespace to clean up upon exiting the context.

This class was designed with the intention that:

namespace=locals().

*default_targets: classes

the targets to which objects decorated with @self.bind() will be bound
If this list is empty, trying to use self.bind() will raise a ValueError.
To enter custom targets, use self.bind_to instead.

keep_local: bool, default False

default value for whether to keep local copies of the bound functions.

E.g. if self.keep_local=True, then by default we will keep local copies.

Methods

`bind`(*[, keep_local, methodtype])	returns decorator; decorator(f) binds f to target.(f.__name__) for target in self.default_targets,
`bind_to`(cls, f, *[, keep_local, methodtype])	bind f to cls.
`binder`(*targets[, keep_local, methodtype])	returns decorator(f); decorator(f) binds f to target.(f.__name__) for target in targets,
`cleanup`()	cleans up self.namespace appropriately, following these rules:
`direct_bind`(f, *targets[, keep_local, ...])	binds f to target.(f.__name__) for target in targets, then flags f appropriately for cleanup.
`get_target`()	gets binding target of self.
`set_target`(target)	sets binding target of self to target.
`to`(*targets[, keep_local, methodtype])	sets targets in self then returns self.
`with_targets`(*targets)	return Binding object with same namespace as self, but using the provided targets instead.
`_reset_flagged`()	resets/creates flagged trackers in self.

Attributes

`target`	@self.bind() binds objects to target.(object.__name__).
`targetting`	alias to to
`with_target`	alias to with_targets

_reset_flagged(): resets/creates flagged trackers in self.

bind(*, keep_local=None, methodtype=None)

returns decorator; decorator(f) binds f to target.(f.__name__) for target in self.default_targets,

and also flags f appropriately for cleanup later when exiting the Binding context.

kwargs determine the behavior for the resulting decorator:

keep_local: bool or None, default None: if None, use self.keep_local instead. (self.keep_local=False by default)

if True, instead don’t flag for cleanup, and return the original function.

else (default), flag for cleanup, and return a BindingError object

(which is only relevant if attempting to access the function before cleanup).
methodtype: None, staticmethod, or classmethod: if None, use self.methodtype instead. (self.methodtype=None by default)

if still not None, bind methodtype(f) instead of f.

bind_to(cls, f, *, keep_local=None, methodtype=None)

bind f to cls. Equivalent to self.direct_bind(self, f, cls, **kw) with same kw as provided here.

keep_local: bool or None, default None: if None, use self.keep_local instead. (self.keep_local=False by default)

if True, instead don’t flag for cleanup, and return the original function.

else (default), flag for cleanup, and return a BindingError object

(which is only relevant if attempting to access the function before cleanup).
methodtype: None, staticmethod, or classmethod: if None, use self.methodtype instead. (self.methodtype=None by default)

if still not None, bind methodtype(f) instead of f.

binder(*targets, keep_local=None, methodtype=None)

returns decorator(f); decorator(f) binds f to target.(f.__name__) for target in targets,

and also flags f appropriately for cleanup later when exiting the Binding context.

if keep_local and methodtype determine behavior for the resulting decorator_maker:

keep_local: bool or None, default None: if None, use self.keep_local instead. (self.keep_local=False by default)

if True, instead don’t flag for cleanup, and return the original function.

else (default), flag for cleanup, and return a BindingError object

(which is only relevant if attempting to access the function before cleanup).
methodtype: None, staticmethod, or classmethod: if None, use self.methodtype instead. (self.methodtype=None by default)

if still not None, bind methodtype(f) instead of f.

cleanup(): cleans up self.namespace appropriately, following these rules:

1) previously-defined names in self.namespace (defined first without using self)

which were overwritten to point at an object wrapped by self

will be restored to their original values.

2) previously undefined objects in self.namespace

which were written to point at an object wrapped by self

will be removed from self.namespace.

direct_bind(f, *targets, keep_local=None, methodtype=None)

binds f to target.(f.__name__) for target in targets, then flags f appropriately for cleanup.

named “direct” bind because this is not a function decorator.

keep_local: bool or None, default None: if None, use self.keep_local instead. (self.keep_local=False by default)

if True, instead don’t flag for cleanup, and return the original function.

else (default), flag for cleanup, and return a BindingError object

(which is only relevant if attempting to access the function before cleanup).
methodtype: None, staticmethod, or classmethod: if None, use self.methodtype instead. (self.methodtype=None by default)

if still not None, bind methodtype(f) instead of f.

get_target(): gets binding target of self. makes ValueError if self has not precisely 1 target.

set_target(target): sets binding target of self to target. (used in self.bind)

property target: @self.bind() binds objects to target.(object.__name__).

When len(self.default_targets)==0, roughly an alias to self.default_targets.

Otherwise irrelevant; see self.default_targets instead.

property targetting: alias to to

to(*targets, keep_local=NO_VALUE, methodtype=NO_VALUE): sets targets in self then returns self.

convenient for writing context entry like this:

binding = Binding(locals())

with binding.to(MyClass1):

@binding

def foo1(args):

#…

if keep_local and/or methodtype are provided,

set those attributes in self, but ALSO provide the instruction to self

to return those attributes to their previous state upon next exiting context.

property with_target: alias to with_targets

with_targets(*targets): return Binding object with same namespace as self, but using the provided targets instead.