Improve the writing operations doc page.
@@ -3,8 +3,8 @@ Writing Operations
:doc:`Operations <../operations>` are defined as Python functions. They are passed the current deploy state, the target host and any operation arguments. Operation functions read state from the host, comparing it to the arguments, and yield **commands**.
-Input: reserved arguments
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Input: arguments
+~~~~~~~~~~~~~~~~
There are a number of arguments ``pyinfra`` uses that cannot be used within operations:
@@ -12,6 +12,14 @@ There are a number of arguments ``pyinfra`` uses that cannot be used within oper
+ The arguments ``state``, ``host``, ``frameinfo`` and ``_line_number`` are reserved for internal use within ``pyinfra``
+ The *first* argument cannot accept ``set`` objects, as these will be removed for use as the operation name (this is legacy support for 0.x and will be removed in v2)
+In addition to any operation arguments, the function *must* take a ``state`` & ``host`` arguments, both defaulting to ``None``.
+
+.. code:: python
+
+ @operation
+ def my_operation(..., state=None, host=None):
+ ...
+
Output: commands
~~~~~~~~~~~~~~~~
@@ -46,7 +54,7 @@ remote file based on the ``present`` kwargs:
from pyinfra.api import operation
@operation
- def file(state, host, name, present=True):
+ def file(name, present=True, state=None, host=None):
'''
Manage the state of files.
