python
Audit
- Macro ID
- python
- Source
- XS
- Type
- Generator
- Classification reason
- Generator, like the other script macros: the output is what the script computes, far from the code typed in the content, which the reader never sees. The parameters only change how the script runs and how its output is processed.
- Status
- Reviewed
- Criteria version
- 15.20
- XWiki version
- 18.8.0
- Audit date
- 2026-10-21
- Auditor
- Compared macros
- velocity groovy
Lucas CharpentierSources
Where to gather the information the criteria are checked against, see Gather the sources.
| Other sources specific to this macro |
|---|
| Criterion | Result | Notes |
|---|---|---|
| D1 wording | OK | "Python" is the name of the technology, and the macro is audited as a developer macro, in the Development category, so the name is fine. The French and German names are "Python" too, like velocity and groovy. |
| D2 summary | OK | "Executes a python script." says what the macro does, and for a generic script macro this is enough, like "Fetches information from a JIRA server". It does not say that the output of the script is inserted in the page as wiki syntax, which the output and wiki parameters tell. Recorded like velocity and groovy. |
| D3 category | OK | only Development, where users look for a script macro, like velocity and groovy. |
| D4 quick-action | OK | Quick Actions finds the macro first for "python" and in fourth place for "script", among Script, Groovy, PHP and Python, and in eighth place for "execute". "java", "run code", "program" and "eval" do not find it. The French and German names are the same as the English one, so only the English name, the ID and two synonyms are checked. A technical macro named after its technology is OK even when few synonyms find it, like html, velocity and groovy. |
| L1 consistency | OK | compared with velocity and groovy, the other script macros, which also take a mandatory script as content: the Quick Action opens the Edit Macro dialog with a required Content text area, and the macro declares inline support. The wiki parameter defaults to true, like them, since the output of a script is wiki syntax. |
| L2 doc-parameters | KO | the parameters are documented only on the legacy extensions.xwiki.org page, https://extensions.xwiki.org/xwiki/bin/view/Extension/Python%20Macro, not in the new documentation, and that page has no parameter table. The content, jars and output are not documented, and wiki is only mentioned. Recorded like velocity and groovy. |
| L3 doc-example | OK | Example 1 is the plain use, a script that prints a line, and renders "Hello World", so it is used as the most common example. Example 2 repeats it word for word, Example 3 is a loop over the squares of a chessboard that renders a list of lines, and Example 4 prints the module search path, which is a poor example for a public page. All four render without error and can be typed in the editor, so the plain use is shown and the result is OK, with this note. No XWiki Standard page calls the macro, the GitHub code search only finds the rendering tests of its own module. |
| I1 pattern | OK | compared with the reference generator, children. The Python Quick Action opens the Edit Macro dialog with an empty Content text area, and the macro needs its script to do anything, so the dialog is OK, like include and the other script macros. |
| I2 zero-config | OK | submitting the dialog with an empty content keeps it open with no message, the generic behavior of the dialog for a mandatory value. A written in the source renders nothing, with no error, which is the expected result of an empty script, and the editor keeps the placeholder "macro:python" after saving and reopening the page. |
| I3 instant | N/A | N/A for a generator. The Quick Action opens the Edit Macro dialog with an empty Content text area, see I1. |
| I4 cursor | N/A | N/A for a generator. After submitting the dialog, the macro widget is selected, and the script can only be changed through the dialog. |
| I5 focus | OK | the content, the script, is the only mandatory parameter: the Edit Macro dialog shows its text area first, with the focus in it, and every field is visible without scrolling. |
| E1 wysiwyg | OK | with a script that prints text, the editor shows its rendered output, "Hello World" for Example 1, the same as in view mode. A script with no output, like output="false", or only an assignment, shows the generic placeholder "macro:python" with no hint of the script. Recorded OK on the most common example, like velocity and groovy. |
| E2 errors | KO | invalid values are accepted silently. output="maybe" is read as false and the whole output disappears, wiki="maybe" is accepted, and an unknown parameter is ignored, the last one being generic. A jars value with a missing attachment, gives "Can't find script engine with name [python]", which blames the engine and says nothing of the attachment or the parameter, a wrong message. Two references without a separator give the same message. A value that is not a JAR but looks like a URL is accepted with no message. |
| E3 nesting | OK | in a list item, a table cell and a box the macro renders its output with no error. The content is code, so a list, a table or a box typed as the script gives the syntax error of Python, for example "SyntaxError: mismatched input '*' expecting EOF", which is expected, and the technical message counts under E2. The content is not editable in place in any of these cases. |
| E4 inline-support | OK | the macro declares inline support, and its output renders inside a sentence with no block element. |
| E5 empty | N/A | N/A for a generator. The editor shows the output of the script, or "macro:python" when it is empty, and the content can only be typed in the Edit Macro dialog. |
| E6 inplace | N/A | N/A for a generator. The script is still edited only in a plain text area of 7 rows of the Edit Macro dialog, with no code editing aid, which is worth an improvement outside the criteria. |
Parameters
| Parameter | C1 clarity | C2 mandatory | C3 defaults | C4 input-assistance | C5 groups | C6 order | C7 alternatives | C8 advanced | C9 technical | C13 constraints | Notes |
|---|---|---|---|---|---|---|---|---|---|---|---|
| $content | OK | OK | N/A | OK | N/A | OK | N/A | N/A | N/A | N/A | C1: the name "Content" and the description "The python script to execute" are clear for a developer macro. C2: the content is mandatory, which is right, an empty script does nothing. C4: a plain text area in the Edit Macro dialog, counted under E6. C6: the content comes first, before the optional parameters. |
| jars | OK | OK | OK | KO | OK | OK | N/A | KO | OK | KO | C1: the name is the ID, and the description with its examples is clear for a developer macro. It says "List of JARs" without saying how to separate several values. C2: optional, which is right. C3: empty means no extra JAR, which is the right default. C4, minor: a free text field for attachment references or URLs, with no picker, and a missing attachment is reported as a missing script engine, see E2. The values are free text, so the KO is minor. C5: four fields in the group, content included, within the limit. C6: no common example sets it, and it is visible in the dialog without scrolling. C8: a rarely used parameter, set by no example of the documentation and by no XWiki Standard call, and not marked as advanced. C9: the parameter is inherited from the script macros, and a Jython script can import Java classes, so a library on its class loader has a realistic use, even with no documented example. Recorded like jars of groovy and script, unlike velocity. C13: a list of references in a single field with the separator undeclared: two references without a separator are refused with a misleading message and the description does not say which separator to use. |
| output | OK | OK | OK | OK | OK | OK | N/A | OK | OK | OK | C1: the description "Specifies whether the output result should be inserted back in the page" is understandable for a developer macro. The English name is the ID, "output". C2: optional, which is right. C3: the checkbox preselects the default, true. C4: a checkbox for a boolean. C6: no common example sets it, and it is visible in the group with only three other fields. C8: output="false" is the way to run a script that only sets variables, which is a frequent use, so it is not rarely used. Recorded like output of velocity and groovy. C9: realistic use, the examples of the documentation of the script macros set it. |
| wiki | OK | OK | OK | OK | OK | OK | N/A | KO | OK | OK | C1: the description "Specifies whether wiki syntax in the script execution result will be rendered or not" is clear for a developer macro. The English name is the ID, "wiki". C2: optional, which is right. C3: the checkbox preselects the default, true. C4: a checkbox for a boolean. C8, minor: wiki="false" is a realistic but rare use, for a script that outputs text with wiki characters, and the field is not marked as advanced. Recorded like wiki of velocity and groovy. C9: realistic use, for a script that outputs text with wiki characters. |
KOs and tickets
Every KO needs a ticket covering it, see Report the KOs. One ticket can cover several KOs. Known issues filed for this macro are suggested in italics: link them as existing tickets when they cover the KO.
| KO | Criterion | Existing tickets | New tickets |
|---|---|---|---|
| L2 | L2 doc-parameters | XINFRA-525 | |
| E2 | E2 errors | XCOMMONS-3847 (partial), XRENDERING-823 (partial), XWIKI-25579 (partial) | |
| C4:jars | C4 input-assistance, jars | XWIKI-25568 | |
| C8:jars | C8 advanced, jars | XWIKI-25476 | |
| C13:jars | C13 constraints, jars | XWIKI-25509 | |
| C8:wiki | C8 advanced, wiki | XWIKI-25476 |
Tickets
| Ticket | Origin | KOs covered | KOs partly covered |
|---|---|---|---|
| XCOMMONS-3847 | New | E2 | |
| XRENDERING-823 | New | E2 | |
| XWIKI-25476 | New | C8:jars C8:wiki | |
| XINFRA-525 | New | L2 | |
| XWIKI-25509 | New | C13:jars | |
| XWIKI-25568 | New | C4:jars | |
| XWIKI-25579 | New | E2 |
Known issues of this macro
No known issue is specific to this macro.
68 more known issues affect every macro: see the Known issues.
