Add keyword argument support for @blocktag.

Review Request #14697 — Created Nov. 17, 2025 and updated

Information

Djblets
release-5.x

Reviewers

@blocktag was limited to positional arguments, making it hard for any
blocktag to take in optional values.

Django's built-in @simple_tag does have this support via an internal
(but accessible) utility function, parse_bits(), which takes care of
positional arguments, keyword arguments, and filter expressions.

We now use this function in @blocktag to gain this support in a way
that's consistent with what Django provides. There's arguably a better
way of handling some of this (e.g., they don't fully check if a call
would fail, which signature.bind() would indicate), but there's
benefits to leveraging the logic of the built-in tags.

An explicit tag name can now be given, like with standard tag
registration methods. We also now have proper typing.

Some optimizations have been added. We no longer parse the argument spec
per-tag, but rather when registering the tag. We also no longer
dynamically construct the node class, but rather reuse a standard
definition we now provide. And we also have configuration state we now
pull out and reference rather than re-calculating. These should overall
be wins for the performance.

Unit tests now exist for this.

Djblets and Review Board unit tests pass.

Tested pages throughout Review Board, making sure there were no
obvious unexpected issues.

Tested the new functionality with an in-progress change.

Summary ID
Add keyword argument support for @blocktag.
`@blocktag` was limited to positional arguments, making it hard for any blocktag to take in optional values. Django's built-in `@simple_tag` does have this support via an internal (but accessible) utility function, `parse_bits()`, which takes care of positional arguments, keyword arguments, and filter expressions. We now use this function in `@blocktag` to gain this support in a way that's consistent with what Django provides. There's arguably a better way of handling some of this (e.g., they don't fully check if a call would fail, which `signature.bind()` would indicate), but there's benefits to leveraging the logic of the built-in tags. An explicit tag name can now be given, like with standard tag registration methods. We also now have proper typing. Some optimizations have been added. We no longer parse the argument spec per-tag, but rather when registering the tag. We also no longer dynamically construct the node class, but rather reuse a standard definition we now provide. And we also have configuration state we now pull out and reference rather than re-calculating. These should overall be wins for the performance. Unit tests now exist for this.
52e8bbe6a5fb1899faba31033f14e54b5558027d
Description From Last Updated

We don't use kwargs anywhere in the implementation. Should we leave it off for now?

daviddavid

We need to add *args and **kwargs to this section.

daviddavid

Can we use an f-string here instead of %-formatting?

daviddavid

Missing "Returns" in this docstring.

daviddavid

Can we use f-strings here?

daviddavid
Checks run (2 succeeded)
flake8 passed.
JSHint passed.
david
  1. 
      
  2. djblets/util/decorators.py (Diff revision 1)
     
     
    Show all issues

    We don't use kwargs anywhere in the implementation. Should we leave it off for now?

  3. djblets/util/decorators.py (Diff revision 1)
     
     
    Show all issues

    We need to add *args and **kwargs to this section.

  4. djblets/util/tests/test_blocktag.py (Diff revision 1)
     
     
    Show all issues

    Can we use an f-string here instead of %-formatting?

  5. djblets/util/tests/test_blocktag.py (Diff revision 1)
     
     
    Show all issues

    Missing "Returns" in this docstring.

  6. djblets/util/tests/test_blocktag.py (Diff revision 1)
     
     
     
     
     
     
    Show all issues

    Can we use f-strings here?

  7.