cs-djutils 20250111.1

My collection of things for working with Django.

My collection of things for working with Django.

Latest release 20250111.1: Documentation update.

Presently this provides:

• BaseCommand: a drop in replacement for django.core.management.base.BaseCommand which uses a cs.cmdutils.BaseCommand style of implementation
• model_batches_qs: a generator yielding QuerySets for batches of a Model

Class BaseCommand(cs.cmdutils.BaseCommand, django.core.management.base.BaseCommand)

A drop in class for django.core.management.base.BaseCommand which subclasses cs.cmdutils.BaseCommand.

This lets me write management commands more easily, particularly if there are subcommands.

This is a drop in in the sense that you still make a management command in nearly the same way:

from cs.djutils import BaseCommand

class Command(BaseCommand):

and manage.py will find it and run it as normal. But from that point on the style is as for cs.cmdutils.BaseCommand:

• no aegparse setup
• direct support for subcommands as methods
• succinct option parsing, if you want additional command line options
• usage text in the subcommand method docstring

A simple command looks like this:

class Command(BaseCommand):

    def main(self, argv):
        """ Usage: {cmd} .......
              Do the main thing.
        """
        ... do stuff based on the CLI args `argv` ...

A command with subcommands looks like this:

class Command(BaseCommand):

    def cmd_this(self, argv):
        """ Usage: {cmd} ......
              Do this.
        """
        ... do the "this" subcommand ...

    def cmd_that(self, argv):
        """ Usage: {cmd} ......
              Do that.
        """
        ... do the "that" subcommand ...

If want some kind of app/client specific "overcommand" composed from other management commands you can import them and make them subcommands of the overcommand:

from .other_command import Command as OtherCommand

class Command(BaseCommand):

    # provide it as the "other" subcommand
    cmd_other = OtherCommand

Option parsing is inline in the command. self comes presupplied with a .options attribute which is an instance of cs.cmdutils.BaseCommandOptions (or some subclass).

Parsing options is light weight. This example adds command line switches to the default switches:

• -x: a Boolean, setting self.options.x
• --thing-limit n: an int, setting self.options.thing_limit=n
• --mode blah: a string, setting self.options.mode=blah The automatic usage text is suitably updated.

Code sketch:

from cs.cmdutils import popopts

class Command(BaseCommand):

    @popopts(
        x=None,
        thing_limit_=int,
        mode_='The run mode.',
    )
    def cmd_this(self, argv):
        """ Usage: {cmd}
              Do this thing.
        """
        options = self.options
        ... now consult options.x or whatever
        ... argv is now the remaining arguments after the options

BaseCommand.Options

BaseCommand.SubCommandClass

BaseCommand.add_arguments(self, parser): Add the Options.COMMON_OPT_SPECS to the argparse parser. This is basicly to support the Django call_command function.

BaseCommand.handle(*, argv, **options): The Django BaseComand.handle method. This creates another instance for argv and runs it.

BaseCommand.run_from_argv(argv): Intercept django.core.management.base.BaseCommand.run_from_argv. Construct an instance of cs.djutils.DjangoBaseCommand and run it.

Class DjangoSpecificSubCommand(cs.cmdutils.SubCommand)

A subclass of cs.cmdutils.SubCOmmand with additional support for Django's BaseCommand.

DjangoSpecificSubCommand.__call__(self, argv: List[str]): Run this SubCommand with argv. This calls Django's BaseCommand.run_from_argv for pure Django commands.

DjangoSpecificSubCommand.is_pure_django_command: Whether this subcommand is a pure Django BaseCommand.

DjangoSpecificSubCommand.usage_text(self, *, cmd=None, **kw): Return the usage text for this subcommand.

model_batches_qs(model, field_name='pk', *, chunk_size=1024, desc=False) -> Iterable[django.db.models.query.QuerySet]

A generator yielding QuerySets which produce nonoverlapping batches of model instances.

Efficient behaviour requires the field to be indexed. Correct behaviour requires the field values to be unique.

Parameters:

• model: the Model to query
• field_name: default 'pk', the name of the field on which to order the batches
• chunk_size: the maximum size of each chunk
• desc: default False; if true then order the batches in descending order instead of ascending order

Example iteration of a Model would look like:

from itertools import chain
from cs.djutils import model_batches_qs
for instance in chain.from_iterable(model_batches_qs(MyModel)):
    ... work with instance ...

By returning QuerySets it is possible to further alter each query:

from cs.djutils import model_batches_qs
for batch_qs in model_batches_qs(MyModel):
    for result in batch_qs.filter(
        some_field__gt=10
    ).select_related(.......):
        ... work with each result in the batch ...

or:

from itertools import chain
from cs.djutils import model_batches_qs
for result in chain.from_iterable(
    batch_qs.filter(
        some_field__gt=10
    ).select_related(.......)
    for batch_qs in model_batches_qs(MyModel)
):
        ... work with each result ...

Release Log

Release 20250111.1: Documentation update.

Release 20250111: New model_batches_qs() generator yielding QuerySets for batches of a Model.

Release 20241222.3: Autocall settings.configure() if required because Django's settings object is a royal PITA.

Release 20241222.2: BaseCommand.Options.settings: call settings.configure() on init if that has not already been done.

Release 20241222.1: Placate the dataclass - upgrade BaseCommand.Options.settings to be a field() with a default_factory.

Release 20241222: BaseCommand.Options: include .settings with the public django.conf.settings names, mostly for cmd_info and cmd_repl.

Release 20241119: New DjangoSpecificSubCommand(CSBaseCommand.SubCommandClass) to include support for pure Django BaseCommands.

Release 20241111: Rename DjangoBaseCommand to just BaseCommand so that we go from cs.djutils import BaseCommand. Less confusing.

Release 20241110: Initial PyPI release with DjangoBaseCommand, cs.cmdutils.BaseCommand subclass suppplanting django.core.management.base.BaseCommand.