@@ -269,6 +269,88 @@ Currently available lexers:
269269
270270If you use a non-existing lexer then the value of the template field will be rendered as a pretty-printed object.
271271
272+ Limitations
273+ ^^^^^^^^^^^
274+ To prevent misuse, the following limitations must be observed when defining and assigning templated fields in the
275+ operator's constructor (when such exists, otherwise - see below):
276+
277+ 1. Templated fields' corresponding parameters passed into the constructor must be named exactly
278+ as the fields. The following example is invalid, as the parameter passed into the constructor is not the same as the
279+ templated field:
280+
281+ .. code-block :: python
282+
283+ class HelloOperator (BaseOperator ):
284+ template_fields = " field_a"
285+
286+ def __init__ (field_a_id ) -> None : # <- should be def __init__(field_a)-> None
287+ self .field_a = field_a_id # <- should be self.field_a = field_a
288+
289+ 2. Templated fields' instance members must be assigned with their corresponding parameter from the constructor,
290+ either by a direct assignment or by calling the parent's constructor (in which these fields are
291+ defined as ``template_fields ``) with explicit an assignment of the parameter.
292+ The following example is invalid, as the instance member ``self.field_a `` is not assigned at all, despite being a
293+ templated field:
294+
295+ .. code-block :: python
296+
297+ class HelloOperator (BaseOperator ):
298+ template_fields = (" field_a" , " field_b" )
299+
300+ def __init__ (field_a , field_b ) -> None :
301+ self .field_b = field_b
302+
303+
304+ The following example is also invalid, as the instance member ``self.field_a `` of ``MyHelloOperator `` is initialized
305+ implicitly as part of the ``kwargs `` passed to its parent constructor:
306+
307+ .. code-block :: python
308+
309+ class HelloOperator (BaseOperator ):
310+ template_fields = " field_a"
311+
312+ def __init__ (field_a ) -> None :
313+ self .field_a = field_a
314+
315+
316+ class MyHelloOperator (HelloOperator ):
317+ template_fields = (" field_a" , " field_b" )
318+
319+ def __init__ (field_b , ** kwargs ) -> None : # <- should be def __init__(field_a, field_b, **kwargs)
320+ super ().__init__ (** kwargs) # <- should be super().__init__(field_a=field_a, **kwargs)
321+ self .field_b = field_b
322+
323+ 3. Applying actions on the parameter during the assignment in the constructor is not allowed.
324+ Any action on the value should be applied in the ``execute() `` method.
325+ Therefore, the following example is invalid:
326+
327+ .. code-block :: python
328+
329+ class HelloOperator (BaseOperator ):
330+ template_fields = " field_a"
331+
332+ def __init__ (field_a ) -> None :
333+ self .field_a = field_a.lower() # <- assignment should be only self.field_a = field_a
334+
335+ When an operator inherits from a base operator and does not have a constructor defined on its own, the limitations above
336+ do not apply. However, the templated fields must be set properly in the parent according to those limitations.
337+
338+ Thus, the following example is valid:
339+
340+ .. code-block :: python
341+
342+ class HelloOperator (BaseOperator ):
343+ template_fields = " field_a"
344+
345+ def __init__ (field_a ) -> None :
346+ self .field_a = field_a
347+
348+
349+ class MyHelloOperator (HelloOperator ):
350+ template_fields = " field_a"
351+
352+ The limitations above are enforced by a pre-commit named 'validate-operators-init'.
353+
272354Add template fields with subclassing
273355^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
274356A common use case for creating a custom operator is for simply augmenting existing ``template_fields ``.
0 commit comments