The return value of BaseCommand.handle() is treated as output, but this is undocumented

[Ned Batchelder]

The docs for handle() (​https://docs.djangoproject.com/en/1.8/howto/custom-management-commands/#django.core.management.BaseCommand.handle) don't mention what its return value means.

The code treats it as output, and writes it to self.stdout(). This should be documented.

(Note: the behavior changed slightly between 1.4 and 1.8: In 1.4, we returned a binary string, and it worked fine, in 1.8, this fails with a DecodeError because of "results.endswith(ending)" ).

[Tim Graham]

Good enough?

docs/howto/custom-management-commands.txt

@@ -300 +300 @@
 
     The actual logic of the command. Subclasses must implement this method.
 
+    The method may return a string which will be printed to ``stdout`` (wrapped
+    by ``BEGIN;`` and ``COMMIT;`` if :attr:`output_transaction` is ``True``).
+
 .. method:: BaseCommand.check(app_configs=None, tags=None, display_num_errors=False)
 
     Uses the system check framework to inspect the entire Django project for

[Ned Batchelder]

Even better: mention that it's a Unicode string. I stumbled on all this due to a UnicodeDecodeError from a bytestring being returned.

[Tim Graham <timograham@…>]

In 3f766d44:

Fixed #25515 -- Documented the return value of BaseCommand.handle()

[Tim Graham <timograham@…>]

In d81b0812:

[1.9.x] Fixed #25515 -- Documented the return value of BaseCommand.handle()

Backport of 3f766d44c5ea000ecf47829ca565b1921dab2ac1 from master

[Tim Graham <timograham@…>]

In 9be9c511:

[1.8.x] Fixed #25515 -- Documented the return value of BaseCommand.handle()

Backport of 3f766d44c5ea000ecf47829ca565b1921dab2ac1 from master