Clarify call_command()'s handling of args and options

[Malcolm Box]

Minimal example:

management/commands/bug.py

class Command(BaseCommand):
   def add_arguments(self, parser):
       parser.add_argument('-n', action='store', dest='number', type=int)

   def handle(self, **options):
       int(options['number'])

Execute as:

./manage.py bug -n nan

error: argument -n: invalid int value: 'nan'

Test using call_command:

call_command('bug', n='nan')

Raises a ValueError trying to convert options['number']

The core problem seems to be that kwargs to call_command aren't passed through the argparse command processing in the way that *args is.

There's a work-around, which is to use the call_command('bug', '-n nan') format - perhaps this could be called out in the docs?

[Claude Paroz]

This could be clearer in the docs. Something like that?

docs/ref/django-admin.txt

@@ -1763 +1763 @@
   the name of the command to call.
 
 ``*args``
-  a list of arguments accepted by the command.
+  a list of arguments accepted by the command and fed to the parser.
 
 ``**options``
-  named options accepted on the command-line.
+  named options accepted on the command-line. Those will be directly passed to
+  the command without triggering the argument parser.
 
 Examples::

[Tim Graham]

Makes sense, Claude. I expanded that a bit with some examples: ​PR.

[Claude Paroz]

Thanks for the nice worded patch.

[Tim Graham <timograham@…>]

In 5695c142:

Fixed #26294 -- Clarified call_command()'s handling of args and options.

[Tim Graham <timograham@…>]

In 7b2ee757:

[1.9.x] Fixed #26294 -- Clarified call_command()'s handling of args and options.

Backport of 5695c142d282f4681a8d43bb55ec49f11f3fc40e from master

[Tim Graham <timograham@…>]

In a30482a4:

Refs #26294 -- Fixed typo in docs/ref/django-admin.txt.

[Tim Graham <timograham@…>]

In ceb6a64f:

[1.11.x] Refs #26294 -- Fixed typo in docs/ref/django-admin.txt.

Backport of a30482a4b6e5d13e7325238fdc902fbca7e714f4 from master

[Tim Graham <timograham@…>]

In 4cb51412:

[1.10.x] Refs #26294 -- Fixed typo in docs/ref/django-admin.txt.

Backport of a30482a4b6e5d13e7325238fdc902fbca7e714f4 from master