Avoid mutables as function argument defaults.

Mutable default values for functions are considered an anti-pattern
(cf. bug #430 and
https://docs.python-guide.org/writing/gotchas/#mutable-default-arguments).

Mutable default values (empty lists and dictionaries) were used
in the "interpreted role function" API:
Interpreted role functions must accept (optional)
"options" and "content" arguments and must not modify passed values.

OTOH, the actual default value is irrelevant for the API, so there is
no need to use mutable defaults in the specification.
As a precaution and example for robust coding, mutable defaults
are replaced with None in the function definitions.

The documentation is updated to the current implementation (including
changes in [r8254] to apply feature request #63).

Fixes bug #430.

git-svn-id: https://svn.code.sf.net/p/docutils/code/trunk@8919 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

1 files changed, 15 insertions, 8 deletions

diff --git a/docutils/docs/howto/rst-roles.txt b/docutils/docs/howto/rst-roles.txt
index 281f0c0ed..7bfcc3de7 100644
--- a/docutils/docs/howto/rst-roles.txt
+++ b/docutils/docs/howto/rst-roles.txt
@@ -33,10 +33,10 @@ The role function creates and returns inline elements (nodes) and does
 any additional processing required.  Its signature is as follows::
 
     def role_fn(name, rawtext, text, lineno, inliner,
-                options={}, content=[]):
+                options=None, content=None):
         code...
 
-    # Set function attributes for customization:
+    # Optional function attributes for customization:
     role_fn.options = ...
     role_fn.content = ...
 
@@ -52,7 +52,8 @@ Options and Content`_).  The role function parameters are as follows:
 
 * ``text``: The interpreted text content.
 
-* ``lineno``: The line number where the interpreted text begins.
+* ``lineno``: The line number where the text block containing the
+  interpreted text begins.
 
 * ``inliner``: The ``docutils.parsers.rst.states.Inliner`` object that
   called role_fn.  It contains the several attributes useful for error
@@ -187,10 +188,14 @@ This is equivalent to::
 Here is the implementation of the role::
 
     def rfc_reference_role(role, rawtext, text, lineno, inliner,
-                           options={}, content=[]):
+                           options=None, content=None):
+        if "#" in text:
+            rfcnum, section = utils.unescape(text).split("#", 1)
+        else:
+            rfcnum, section  = utils.unescape(text), None
         try:
-            rfcnum = int(text)
-            if rfcnum <= 0:
+            rfcnum = int(rfcnum)
+            if rfcnum < 1:
                 raise ValueError
         except ValueError:
             msg = inliner.reporter.error(
@@ -200,8 +205,10 @@ Here is the implementation of the role::
             return [prb], [msg]
         # Base URL mainly used by inliner.rfc_reference, so this is correct:
         ref = inliner.document.settings.rfc_base_url + inliner.rfc_url % rfcnum
-        set_classes(options)
-        node = nodes.reference(rawtext, 'RFC ' + utils.unescape(text), refuri=ref,
+        if section is not None:
+            ref += "#"+section
+        options = normalize_role_options(options)
+        node = nodes.reference(rawtext, 'RFC ' + str(rfcnum), refuri=ref,
                                **options)
         return [node], []