pytek.util
module¶
-
class
pytek.util.
Configurator
(name, get=None, set=None, doc=None)[source]¶ Bases:
object
The
Configurator
class creates helper objects that can be used to easily add methods to a class to configure and query a particular setting on the device.The easiest way to understand it is by example. First, a stripped down usage example:
class MyDevice(object): __metaclass__ = Configurator.ConfigurableMeta @Configurator.config("FOO:BAR") def foobar(self, val): return val.lower() @foobar.setter def foobar(self, val): return val.upper() @Configurator.config def frobbed(self, val): return (val == "ON") @frobbed.setter def frobbed(self, val): return "ON" if val else "OFF"
And now, a more thorough example, expanded from this:
class MyDevice(object): #Make sure it uses the ConfigurableMeta class as its metaclass, # so Configurator objects in the class definition get replaced with # appropriate methods. __metaclass__ = Configurator.ConfigurableMeta #Just some ordinary instance attributes, which we will be the target of # our setting configuring and querying. __foobar = "TAZ" __frobbed = "OFF" #This is where the class actually implements sending command and queries. # The Configurator objects will call these methods. def send_command(self, name, arg): print "~~~> %s %s" % (name, arg) if name == "FOO:BAR": if not isinstance(arg, str): raise TypeError() if arg != arg.upper(): raise ValueError() self.__foobar = arg elif name == "FROBBED": if arg not in ("ON", "OFF"): raise ValueError() self.__frobbed = arg else: raise KeyError() def send_query(self, name): print "???? %s" % name if name == "FOO:BAR": val = self.__foobar elif name == "FROBBED": val = self.__frobbed else: raise KeyError() print " <<<< %s" % val return val #Now, define Configurators for each of our configurable settings. #First, for the FOO:BAR setting, which will be accessed through a # function called `foobar`. @Configurator.config("FOO:BAR") def foobar(self, val): #Translate a value returned by `send_query` into a value to return # to the calling code. return val.lower() @foobar.setter def foobar(self, val): #Translate a value provided by the calling code into a value that # will be passed to `send_command`. return val.upper() #Now, the FROBBED setting. We can use implicit named in the decorator # for this one. @Configurator.config def frobbed(self, val): ''' +++ Querying returns True for "ON", and False for "OFF". ''' if val == "ON": return True if val == "OFF": return False raise ValueError(val) @frobbed.setter def frobbed(self, val): ''' +++ Valid values for configuring are True and False, or synonomously "ON" and "OFF". ''' if val is True or val == "ON": return "ON" elif val is False or val == "OFF": return "OFF" raise ValueError()
With the above code, you could then do the following:
>>> dev = MyDevice() >>> dev.foobar() ???? FOO:BAR <<<< TAZ 'taz' >>> >>> dev.foobar('razzle-dazzle') ~~~> FOO:BAR RAZZLE-DAZZLE >>> >>> dev.foobar() ???? FOO:BAR <<<< RAZZLE-DAZZLE 'razzle-dazzle' >>> >>> >>> dev.frobbed() ???? FROBBED <<<< OFF False >>> dev.frobbed(True) ~~~> FROBBED ON >>> dev.frobbed() ???? FROBBED <<<< ON True >>> >>> dev.frobbed(False) ~~~> FROBBED OFF >>> dev.frobbed() ???? FROBBED <<<< OFF False >>> >>> dev.frobbed("ON") ~~~> FROBBED ON >>> dev.frobbed() ???? FROBBED <<<< ON True >>> >>> dev.frobbed("???") Traceback (most recent call last): File "<stdin>", line 1, in <module> File "src\pytek\util.py", line 125, in config return self(device, val) File "src\pytek\util.py", line 116, in __call__ self.configure(device, self.name, self.set(device, val)) File "temp.py", line 94, in frobbed raise ValueError() ValueError >>> >>> >>> help(dev.foobar) Help on method foobar in module pytek.util: foobar(device, val=None) method of temp.MyDevice instance Configures or queries the value of the ``FOO:BAR`` setting on the device. If a value is given, then the setting is configured to the given value. If the value is `None` (the default), then the setting is queried and the value is returned. >>> >>> help(dev.frobbed) Help on method frobbed in module pytek.util: frobbed(device, val=None) method of temp.MyDevice instance Configures or queries the value of the ``FROBBED`` setting on the device. If a value is given, then the setting is configured to the given value. If the value is `None` (the default), then the setting is queried and the value is returned. Querying returns True for "ON", and False for "OFF". Valid values for configuring are True and False, or synonomously "ON" and "OFF". >>> >>>
Parameters: - name – Specifies the name of the setting accessed by this object.
Should be either a
callable
object with a__name__
attribute, or a string. Strings will be used directly, callables will be filtered throughfunc_to_name
. - get (callable) – Optional: if given, passed to
getter
. - set (callable) – Optional: if given, passed to
setter
. - doc (callable) – Optional: if given, used as the value of the
doc
attribute.
-
DEFAULT_DOCTSTR
= '\nConfigures or queries the value of the ``%(NAME)s`` setting on the device.\nIf a value is given, then the setting is configured to the given value.\nIf the value is `None` (the default), then the setting is queried and the value\nis returned.\n'¶ A string used for default value of the
doc
attribute.
-
classmethod
configure
(device, name, val)[source]¶ The final method in this object used to configure the setting, given the raw value to be sent to the device. This is called by the
__call__
method when appropriate.This delegates to the
send_command
method of the givendevice
.Parameters: - device – The object on which the
send_command
will be invoked. - name (str) – The name of the setting, usually the value of the
name
attribute. This is the first arguments passed tosend_command
. - val (str) – The raw value to configure the setting to. This is the
second argument passed to
send_command
.
- device – The object on which the
-
classmethod
query
(device, name)[source]¶ The final method in this object used to query the setting, returning the raw value from the device. This is called by the
__call__
method when appropriate.This delegates to the
send_query
method of the givendevice
.Parameters: - device – The object on which the
send_query
will be invoked. - name (str) – The name of the setting, usually the value of the
name
attribute. This is the only arguments passed tosend_query
.
- device – The object on which the
-
create_method
(name)[source]¶ Creates a method with the given name which can be installed in a class to delegate to this object’s
__call__
method. Sets the name of the method toname
, and sets the docstr (__doc__
) to the value of this object’sdoc
attribute.This is used by
ConfigurableMeta
to replace Configurator instances in the classes dictionary with functions.
-
update_doc
(func)[source]¶ If the given function has a docstrig (
__doc__
), then this object’sdoc
attribute is updated with it. Otherwise, it does nothing.If
func
‘s docstr begins with'+++'
alone on a line (any amount of leading and trailing whitespace), then the remainder of the docstring is appended to the existing docstring, instead of replacing it.
-
classmethod
func_to_name
(func)[source]¶ Derives a setting name from a function. The implementation here just uses the
__name__
attribute of the givenfunc
, and then usesstr.upper()
to make it all upper case.This is used in
__init__
if the name is acallable
object.
-
classmethod
boolean
(arg, **kwargs)[source]¶ A function decorator utility used to create a
Configurator
object which handles boolean settings. This ends up delegating toset_boolean
to actually set up theget
andset
filters based on responses from the decorated function. All keyword arguments passed to this function are forwarded toset_boolean
.Similar to
config
, you can invoke this with implicit arguments or explicit argumentsFor implicit arguments, you use this method as a function decorator directly, and the
name
to use is derived from the decorated function withfunc_to_name
. In this mode, you can’t specify any additional arguments to pass toset_boolean
.For explicit arguments, you invoke this method directly, and it returns a function decorator. This allows you to pass in a string as the first argument to specify the
name
to use, as well as additional keyword arguments to be forwarded on toset_boolean
.
-
classmethod
config
(arg)[source]¶ A function decorator utility used to create a
Configurator
object and a function decorator to configure itsgetter
.There are two way to invoke this, using implicit naming or explicit naming.
For implicit naming*, simply pass a function in directly, or use this function directly as a decorator. For instance:
@Configurator.config def foobar(self, val): return val
The above code will create a new instance of
cls
(i.e., a Configurator object), and will pass the given functionfoobar
in as thename
parameter to the constructor. This in turn will usefunc_to_name
to derive a value for the instance’sname
attribute from the function, by default (i.e., in the baseConfigurator
class), this is just the name of the function in all uppercase.The function will also be passed to the instance’s
getter
method so that thefoobar
function becomes the instance’sget
filter.This method will then return the Configurator object itself, not the wrapped function.
The alternative is explicit naming, in which this function is not used as a function wrapper, but invoked to return a function wrapper. This gives you some added flexibility such as explitictly giving the
name
to use for the Configurator object. Otherwise, the behavior is essentially the same.For instance:
@Configurator.config('BAZ:RUFFLE') def foobar(self, val): return val
In this case, even though the wrapped function has the same name,
"foobar"
, the created Configurator object will have aname
of"BAZ:RUFFLE"
. Other than that, the effects are the same.In either case, when code like this appears in a class definition, it means that class will have an attribute named
foobar
whose value is a Configurator object. If this class is using theConfigurableMeta
metaclass, then this attribute will be replaced by a proper method generated by the Configurator’screate_method
method.Also note that when the wrapped function is passed to the Configurator’s
getter
method, this method will also pass it toupdate_doc
, so if the wrapped function has a docstring, the Configurator object’sdoc
attribute will be set accordingly. When theConfigurableMeta
gets a hold of it, the corresponding method it adds to the class will receive this docstr from the Configurator object.Note that for the remainder of the class definition, you can use the generated Configurator object. For instance, you can follow up either of the above examples with the following:
@foobar.setter def foobar(self, val): if val is False: return "OFF" return "ON"
Since at this point the
foobar
symbol is actually a Configurator object, you can use its other decorators such assetter
andgetter
.
-
setter
(func)[source]¶ A function wrapper which sets this object’s
set
attribute to the given function and passes the function toupdate_doc
, then returnsself
.The given function should take two arguments and return a string. The first argument will be the device on which the
send_command
method is invoked, the second argument will be the client supplied value they want to configure the setting to. The function should return a corresponding string which will actually be sent to the device.
-
getter
(func)[source]¶ Like
setter
, but sets the object’sget
attribute, used for querying the setting from the device.This is a function wrapper which sets this object’s
get
attribute to the given function and passes the function toupdate_doc
, then returnsself
.The given function should take two arguments and return a string. The first argument will be the device on which the
send_query
method is invoked, the second argument will be the value returned from the device bysend_query
. The function should return a corresponding value which will be returned to the user to reflect the string returned by the device.
-
set_boolean
(func, strict=False, default=False, nocase=False)[source]¶ Configures the objects
set
andget
filters based on a boolean setting.A boolean setting means the setting has a set of possible values that are partitioned into two subsets: true values and false values. On the python side, any value in these subsets corresponds to a value of
True
orFalse
, respectively.This method sets up the object to filter values accordingly, so that querying the setting always returns
True
orFalse
, and configuring the setting can be done withTrue
orFalse
.To do so, you have to pass in a function which can be evaluated immediately to get the set of true values and the set of false values. The function should take a single boolean argument, if the argument value is
True
, return the set of true values, otherwise, return the set of false values. The method will then create appropriate set and get filters based on these values and the other parameters passed into this function (see below).The sets of true values and false values returned by
func
must be sequences. The first value in each sequence will be used as the canonical value, meaning the ones that will actually be passed to the device for the corresponding value. All other values in the sets will be acceptable responses from the device for queries, and will result in the corresponding boolean value being returned to the caller.See also
Parameters: - func (callable) – This function will be called twice, immediately. Once with a value
of
True
, which should return a sequence of true values; and once with a value ofFalse
, which should return a sequence of false values. - strict (bool) –
Optional, default is
False
. IfTrue
, then the generatedset
andget
filters will be strict about values. Theset
filter will only accept boolean values, and will raise aTypeError
otherwise. Theget
filter will only accept values from the true- and false- value sets, and will raise aValueError
if the device returns anything else.If the value of the parameter is
False
, the generated functions are not as strict, and will not raise exceptions for unrecognized values (the way it handles unrecognized values depends on the value of thedefault
parameter). For the non-strictset
filter, values are simply evaluated as bools to choose which value to send. - default (bool) – Optional, default value is
False
. This is only used ifstrict
isFalse
, in which case it determines the default value when an unrecognized value is encountered. - nocase (bool) – Optional, default value is
False
. IfTrue
, then values are considered case-insensitive.
- func (callable) – This function will be called twice, immediately. Once with a value
of
-
class
ConfigurableMeta
[source]¶ Bases:
type
This is a meta class that can be added to classes to more easily support the use of
Configurator
objects as pseudo-methods.The meta class extends the
__new__
function to find all instances ofConfigurator
in the class’s dictionary, and replace it with a method created by the Configurator’screate_method
method.See the example code in the documentation for
Configurator
for an example.
- name – Specifies the name of the setting accessed by this object.
Should be either a
-
class
pytek.util.
Configurable
[source]¶ Bases:
object
Just a simple base classes that uses
ConfigurableMeta
as the metaclass.