pingu_98/MrDraw
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

[doc] Added *args, **kwargs to all hooks and documented adjusted gcode hook signature

Browse source
This commit is contained in:
Gina Häußge 2015-04-29 17:31:01 +02:00
parent ad17e22201
commit 30d79f48de
1 changed files with 14 additions and 11 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
docs/plugins/hooks.rst
View file

@ -3,6 +3,12 @@
Available plugin hooks Available plugin hooks
====================== ======================
.. note::
All of the hooks below take at least two parameters, ``*args`` and ``**kwargs``. Please make sure those are present.
They will act as placeholders if additional parameters are added to the hooks in the future and will allow
your plugin to stay compatible to OctoPrint without any necessary adjustments from you in these cases.
.. contents:: .. contents::
:local: :local:
@ -39,13 +45,13 @@ octoprint.comm.protocol.action
octoprint.comm.protocol.gcode octoprint.comm.protocol.gcode
----------------------------- -----------------------------
.. py:function:: hook(comm_instance, cmd, cmd_type=None, with_checksum=None) .. py:function:: hook(comm_instance, cmd, cmd_type=None, *args, **kwargs)
Preprocess and optionally suppress a GCODE command before it is being sent to the printer. Preprocess and optionally suppress a GCODE command before it is being sent to the printer.
Hook handlers may use this to rewrite or completely suppress certain commands before they enter the send queue of Hook handlers may use this to rewrite or completely suppress certain commands before they enter the send queue of
the communication layer. The hook handler will be called with the ``cmd`` to be sent to the printer as well as the communication layer. The hook handler will be called with the ``cmd`` to be sent to the printer as well as
the parameters for sending like ``cmd_type`` and ``with_checksum``. the ``cmd_type`` parameter.
If the handler does not wish to handle the command, it should simply perform a ``return cmd`` as early as possible, If the handler does not wish to handle the command, it should simply perform a ``return cmd`` as early as possible,
that will ensure that no changes are applied to the command. that will ensure that no changes are applied to the command.
@ -54,10 +60,8 @@ octoprint.comm.protocol.gcode
OctoPrint that the ``cmd`` has been scraped altogether and not send anything. OctoPrint that the ``cmd`` has been scraped altogether and not send anything.
More granular manipulation of the sending logic is possible by not just returning ``cmd`` (be it the original, a More granular manipulation of the sending logic is possible by not just returning ``cmd`` (be it the original, a
rewritten variant or a None value) but a 2-tuple (cmd, cmd_type) or a 3-tuple (cmd, cmd_type, with_checksum). This rewritten variant or a None value) but also a 2-tuple ``(cmd, cmd_type)``. This
allows to also rewrite the ``cmd_type`` and the ``with_checksum`` parameter used for sending. Note that the latter allows to also rewrite the ``cmd_type`` parameter used for sending.
should only be necessary in very rare circumstances, since usually plugins should not need to have to decide whether
a command should be sent with a checksum or not.
Defining a ``cmd_type`` other than None will make sure OctoPrint takes care of only having one command of that type Defining a ``cmd_type`` other than None will make sure OctoPrint takes care of only having one command of that type
in its sending queue. Predefined types are ``temperature_poll`` for temperature polling via ``M105`` and in its sending queue. Predefined types are ``temperature_poll`` for temperature polling via ``M105`` and
@ -78,8 +82,7 @@ octoprint.comm.protocol.gcode
from the currently streamed GCODE file or via other means (e.g. user input our status polling). from the currently streamed GCODE file or via other means (e.g. user input our status polling).
:param str cmd_type: Type of command, ``temperature_poll`` for temperature polling or ``sd_status_poll`` for SD :param str cmd_type: Type of command, ``temperature_poll`` for temperature polling or ``sd_status_poll`` for SD
printing status polling. printing status polling.
:param boolean with_checksum: Whether the ``cmd`` was to be sent with a checksum (True) or not (False) :return: A rewritten ``cmd``, a tuple of ``cmd`` and ``cmd_type``
:return: A rewritten ``cmd``, a tuple of ``cmd`` and ``cmd_type`` or ``cmd``, ``cmd_type`` and ``with_checksum``
or None to suppress sending of the ``cmd`` to the printer. See above for details. or None to suppress sending of the ``cmd`` to the printer. See above for details.
.. _sec-plugins-hook-comm-protocol-scripts: .. _sec-plugins-hook-comm-protocol-scripts:
@ -197,7 +200,7 @@ octoprint.comm.transport.serial.factory
octoprint.filemanager.extension_tree octoprint.filemanager.extension_tree
------------------------------------ ------------------------------------
.. py:function:: hook() .. py:function:: hook(*args, **kwargs)
Return additional entries for the tree of accepted file extensions for uploading/handling by the file manager. Return additional entries for the tree of accepted file extensions for uploading/handling by the file manager.
@ -212,7 +215,7 @@ octoprint.filemanager.extension_tree
.. code-block:: python .. code-block:: python
:linenos: :linenos:
def support_x3g_machinecode(): def support_x3g_machinecode(*args, **kwargs):
return dict( return dict(
machinecode=dict( machinecode=dict(
x3g=["x3g", "s3g"] x3g=["x3g", "s3g"]
@ -233,7 +236,7 @@ octoprint.filemanager.extension_tree
octoprint.filemanager.preprocessor octoprint.filemanager.preprocessor
---------------------------------- ----------------------------------
.. py:function:: hook(path, file_object, links=None, printer_profile=None, allow_overwrite=False) .. py:function:: hook(path, file_object, links=None, printer_profile=None, allow_overwrite=False, *args, **kwargs)
Replace the ``file_object`` used for saving added files to storage by calling :func:`~octoprint.filemanager.util.AbstractFileWrapper.save`. Replace the ``file_object`` used for saving added files to storage by calling :func:`~octoprint.filemanager.util.AbstractFileWrapper.save`.