Protocol Related Classes¶
GeekCMS defines serveral protocols for plugin registration and data operation. All following classes are defined in geekcms.protocol.
Assets Related¶
-
class
_BaseAsset
(*args, **kwargs)¶ _BaseAsset is the base class of
BaseResource
,BaseProduct
andBaseMessage
. Initialize_BaseAsset
would Always raise an Exception, since _BaseAsset should not be initialized.-
set_owner
(self, owenr)¶ Set the owner of asset instance. Instance of derived classes of
_BaseAsset
must defined an owner, which should be the name of theme.
-
classmethod
get_manager_with_fixed_owner
(cls, owner)¶ Return an instance of
ManagerProxyWithOwner
, bound with cls and owner.
-
objects
¶ Retrive an instance of
Manager
, which bound withBaseResource
,BaseProduct
andBaseMessage
and its derived classes.
-
-
class
BaseResource
(*args, **kwargs)¶ class derived from
_BaseAsset
.
-
class
BaseProduct
(*args, **kwargs)¶ class derived from
_BaseAsset
.
-
class
BaseMessage
(*args, **kwargs)¶ class derived from
_BaseAsset
.
BaseResource
, BaseProduct
and BaseMessage
are base classes for data operations.
Developer should derived one of these classes for specific usage. Derived classes should overwrite __init__ method,
since _BaseAsset
defines a __init__ method which always raise an Exception.
-
class
Manager
(target_cls, data=None)¶ The class derives from
UserDict
. target_cls is a class derives fromBaseResource
,BaseProduct
orBaseMessage
. data is a dictionary that used to store instances created by manager. If data isNone
, a default dictionary would be initialized.-
add
(self, item)¶ Add instance.
-
remove
(self, item)¶ Remove instance.
-
keys
(self)¶ Returns a list contanins all the owner of stored items.
-
create
(self, *args, owner, **kwargs)¶ Create and store an instance of
self.target_cls
, with arguments(*args, **kwargs)
. owner is a keyword-only parameter.
-
filter(self, owner):
Return a list of instances that:
- owner is the owner of instance.
isinstance(instance, self.target_cls)
is True.
-
values
(self)¶ Return a list of instances that
isinstance(instance, self.target_cls)
is True.
-
clear
(self)¶ Clean up all stored items.
-
-
class
ManagerProxyWithOwner
(self, owner, manager)¶ Instance of this class would be a proxy of
Manager
with fixed owner. All functions defined inManager
are avaliable, except that the parameter owner is excluded from functions’ parameter list. manager is an instance ofManager
, and owner is the owner to be fixed.
Default Procedure Related¶
-
class
BasePlugin
¶ -
classmethod
get_manager_bind_with_plugin
(cls, other_cls)¶ Return an instance of
ManagerProxyWithOwner
bound to class of asset. other_cls should be one ofBaseResource
,BaseProduct
andBaseMessage
and its derived classes.
-
run
(self, resources=None, products=None, messages=None)¶ The interface that a derived plugin class must overwrite. run should be a function that implements plugin’s bussiness. The return value of run function would be discarded.
resources would be a list contains instances of
BaseResource
or its derived class. products would be a list contains instances ofBaseProduct
or its derived class. messages would be a list contains instances ofBaseMessage
or its derived class.
-
classmethod
All user defined plugin classes should derive from BasePlugin
and overwrite the run function.
Besides, class-level attributes theme and plugin can be defined for further customization. For exmaple:
from geekcms import protocol
class TestPlugin(protocol.BasePlugin):
theme = 'test_theme'
plugin = 'test_plugin'
def run(self):
pass
Explanation of class-level attributes are as follow:
- theme
- Defines the theme that a plugin belongs to. Value of theme that would be used to filter resources, products or messages passed to run method. For instances, suppose class A, B both definded
theme = 'AB'
, and there is another class C defindedtheme = 'C'
. If A‘s run method created some instance of resources owned by ‘AB’, and B, C were executed after A, then B‘s run function might receive instances of resource created by A(or might not, due to the parameter controller) while C‘s run function would not receive instances created by A. This attribute could be omitted, in such case the name of theme’s top-level directory would be adapt.- plugin
- Defines the name of plugin which related to the plugin names of theme settings. This attribute could be omitted, in that case, the class name would be used as the plugin name.
The parameter list of overwrited run function is a bit more complicated. Since the bussiness of plugins various a lot, developers might defind run function with different parameters, such as:
from geekcms import protocol
class TestPlugin(protocol.BasePlugin):
theme = 'test_theme'
# accept all assets.
def run(self, resources, products, messages):
pass
# only accept resources.
def run(self, resources):
pass
# accept nothing.
def run(self):
pass
GeekCMS would detect the signature of run function, with the default order [resources, products, messages]. For example, if developer defined a run function with two positional parameters, then GeekCMS would pass instances of resources and products to such function.
For further control of parameter list, developers should consider using decorators defined in PluginController
.
-
class
PluginController
¶ -
RESOURCES
¶ String indicating
BaseResource
and its derived classes.
-
PRODUCTS
¶ String indicating
BaseProduct
and its derived classes.
-
MESSAGES
¶ String indicating
BaseMessage
and its derived classes.
-
classmethod
accept_owners
(cls, *owners)¶ accept_owners is a decorator for plugin’s run function. The owner of assets passed into run function would be adjusted, with respect to owners. owners should be a list of avaliable owners.
-
classmethod
accept_parameters
(cls, *fixed_params, **typed_params)¶ accept_parameters is a decorator for plugin’s run function. By decorating, the order and type of parameters would be adjusted, with respect to fixed_params and typed_params.
fixed_params should be a list of:
- string of [RESOURCES, PRODUCTS, MESSAGES].
- two-element tuple(or list) in the form of (name, accept_cls), in which name should be string of [RESOURCES, PRODUCTS, MESSAGES] and accept_cls should be class of asset.
typed_params is a dictionary with key-value pairs (name, accept_cls), in which name should be string of [RESOURCES, PRODUCTS, MESSAGES] and accept_cls should be class of asset.
-
Example of accept_parameters:
from geekcms import protocol
pcl = protocol.PluginController
class DerivedMessage(protocol.BaseMessage):
def __init__(self):
pass
class TestPlugin(protocol.BasePlugin):
theme = 'test_theme'
# accept only messages of BaseMessage.
@pcl.accept_parameters(pcl.MESSAGES)
def run(self, messages):
pass
# accept only messages of DerivedMessage.
@pcl.accept_parameters(
(pcl.MESSAGES, DerivedMessage),
)
def run(self, messages):
pass
# accept only messages of DerivedMessage.
@pcl.accept_parameters(
**{pcl.MESSAGES: DerivedMessage}
)
def run(self, messages):
pass
# accept only messages of DerivedMessage.
@pcl.accept_parameters(
messages=DerivedMessage,
)
def run(self, messages):
pass
Example of accept_owners:
from geekcms import protocol
pcl = protocol.PluginController
class TestPlugin(protocol.BasePlugin):
# accept only messages owned by test_theme and another_theme.
@pcl.accept_parameters(pcl.MESSAGES)
@pcl.accept_owners('test_theme', 'another_theme')
def run(self, messages):
pass
Extended Procedure Related¶
-
class
BaseExtendedProcedure
¶ -
get_command_and_explanation
(self)¶ Should be a function returns (command, explanation) tuple, with command as string to trigger the extended procedure and explanation as a brief explanation of the extended procedure. Derived class should overwrite this function.
-
get_doc
(self)¶ Should return string that can be parsed by docopt [1]. Derived class should overwrite this function.
-
run
(self, args)¶ run should be a function that implements plugin’s bussiness. args is the processed arguments return by docopt. The return value of run function would be discarded. Derived class should overwrite this function.
-
Plugins class of extended procedure should derive from BaseExtendedProcedure
.
[1] | https://github.com/docopt/docopt |