Registering a Photons action¶
All the tasks available to the Photons lifx
program are actions that
are registered in one of the Photons modules. An action is a
function that takes in objects that represent the arguments provided
on the command line.
For example, the power_toggle
action is defined as:
from photons_app.actions import an_action
from photons_control.transform import PowerToggle
@an_action(needs_target=True, special_reference=True)
async def power_toggle(collector, target, reference, artifact, **kwargs):
"""
Toggle the power of devices.
``target:power_toggle match:group_label=kitchen -- '{"duration": 2}'``
It takes in a ``duration`` field that is the seconds of the duration.
This defaults to 1 second.
"""
extra = collector.photons_app.extra_as_json
msg = PowerToggle(**extra)
await target.send(msg, reference)
This definition is detailed as follows:
an_action takes in a few arguments
needs_reference=True
means Photons throws an error if the<reference>
argument is not specifiedspecial_reference=True
means thereference
variable provided must be is a Special Referenceneeds_target=True
means a<target>
must be specified.
The collector is the entry point to all functionality registered by the Photons modules.
The
target
is the object that sends messages. Theartifact
(which is not used above) is the last argument given on the command line.The JSON options string provided on the command line is available as the
collector.photons_app.extra_as_json
attribute.All arguments to an action must be provided as keyword arguments. If you do not specify a keyword, the unused arguments will be consumed by the
**kwargs
argument.
Create a script that registers and runs an action:
from photons_app.actions import an_action
from photons_messages import DeviceMessages
@an_action(needs_target=True, special_reference=True)
async def display_label(collector, target, reference, **kwargs):
async for pkt in target.send(DeviceMessages.GetLabel(), reference):
print(f"{pkt.serial}: {pkt.label}")
if __name__ == "__main__":
__import__("photons_core").run('lan:display_label {@:1:}')
The action has the same command-line options available as the lifx
utility,
including the references:
$ python my_script.py match:group_name=kitchen --silent
photons_core.run¶
The run
function takes either a formatted string of environment variables
and sys.argv
values or a list of manually specified arguments.
For example, this:
__import__("photons_core").run("{TRANSPORT_TARGET|lan:env}:{@:1} {@:2:}")
Is the same as this:
import sys
import os
target = os.environ.get("TRANSPORT_TARGET", "lan")
__import__("photons_core").run([f"{transport}:{sys.argv[1]}"] + sys.argv[2:])
An environment variable is mandatory if a default is not provided:
__import__("photons_core").run("{TRANSPORT_TARGET:env}:{@:1} {@:2:}")
By default this will start the core modules, which is likely all that’ll ever
be needed. Run can be given default_activate=[]
to make Photons not load any
modules. If there are other Photons modules in the environment, they can be
loaded with default_activate=["other_module"]
. Not specifying a
default_activate
is equivalent to default_activate=["core"]
. Finally
if it’s desirable to load all Photons modules found in the environment, then
the special __all__
module can be used.
The an_action
decorator¶
-
class
photons_app.actions.
an_action
(target=None, special_reference=False, needs_reference=False, needs_target=False, label='Project')¶ Records a task in the
available_actions
dictionaryIt takes in:
- target
The
type
of the target that applies to this action. For examplelan
orhttp
. This is so that you can have a different task with the same name registered for different targets- needs_reference
Specifies that a reference needs to be specified on the commandline
- special_reference
Allow us to provide more detailed reference to devices.
Empty string or ‘_’ resolves to all serials found on the network
comma seperated list of serials is split by comma.
Otherwise, we use
<resolver>:<options>
to resolve our reference to serials- needs_target
Specifies that it needs the target type specified on the commandline
- label
A string used by the help tasks to sort the actions into groups.