Opened 8 years ago

Closed 8 years ago

Last modified 8 years ago

#25515 closed Bug (fixed)

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

Reported by: Ned Batchelder Owned by: nobody
Component: Documentation Version: 1.8
Severity: Normal Keywords:
Cc: rene@… Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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)" ).

Change History (6)

comment:1 by René Fleschenberg, 8 years ago

Cc: rene@… added

comment:2 by Tim Graham, 8 years ago

Has patch: set
Triage Stage: UnreviewedAccepted

Good enough?

  • docs/howto/custom-management-commands.txt

    diff --git a/docs/howto/custom-management-commands.txt b/docs/howto/custom-management-commands.txt
    index f42680b..0430a60 100644
    a b the :meth:`~BaseCommand.handle` method must be implemented.  
    300300
    301301    The actual logic of the command. Subclasses must implement this method.
    302302
     303    The method may return a string which will be printed to ``stdout`` (wrapped
     304    by ``BEGIN;`` and ``COMMIT;`` if :attr:`output_transaction` is ``True``).
     305
    303306.. method:: BaseCommand.check(app_configs=None, tags=None, display_num_errors=False)
    304307
    305308    Uses the system check framework to inspect the entire Django project for

comment:3 by Ned Batchelder, 8 years ago

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

comment:4 by Tim Graham <timograham@…>, 8 years ago

Resolution: fixed
Status: newclosed

In 3f766d44:

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

comment:5 by Tim Graham <timograham@…>, 8 years ago

In d81b0812:

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

Backport of 3f766d44c5ea000ecf47829ca565b1921dab2ac1 from master

comment:6 by Tim Graham <timograham@…>, 8 years ago

In 9be9c511:

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

Backport of 3f766d44c5ea000ecf47829ca565b1921dab2ac1 from master

Note: See TracTickets for help on using tickets.
Back to Top