#5088: document behavior of optparse defaults with 'append' action.

diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst
index add582efed71099942e32a24c0f9b04239a5ba71..6dc57bb3a64e2da9669b78b2eede4bd6b810b1ad 100644 (file)
--- a/Doc/library/optparse.rst
+++ b/Doc/library/optparse.rst
@@ -1165,6 +1165,17 @@ must specify for any option using that action.
 
      options.tracks.append(int("4"))
 
+  The ``append`` action calls the ``append`` method on the current value of the
+  option.  This means that any default value specified must have an ``append``
+  method.  It also means that if the default value is non-empty, the default
+  elements will be present in the parsed value for the option, with any values
+  from the command line appended after those default values::
+
+     >>> parser.add_option("--files", action="append", default=['~/.mypkg/defaults'])
+     >>> opts, args = parser.parse_args(['--files', 'overrides.mypkg'])
+     >>> opts.files
+     ['~/.mypkg/defaults', 'overrides.mypkg']
+
 * ``"append_const"`` [required: :attr:`~Option.const`; relevant:
   :attr:`~Option.dest`]