Summary

Add keyword argument support for @blocktag.

Review Request #14697 — Created Nov. 18, 2025 and submitted Dec. 10, 2025, 12:27 a.m.

Information

Owner

chipx86

Repository

Djblets

Branch

release-5.x

Bugs

Depends On

Reviewers

Groups

djblets

People

Description

@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.

Testing Done

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.

Commits

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.	d0a9a5f0a42396b55bc234194a25ace87832d7d6

Summary

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.

d0a9a5f0a42396b55bc234194a25ace87832d7d6

Issues

Description	From	Last Updated
We don't use kwargs anywhere in the implementation. Should we leave it off for now?	david	Nov. 28, 2025, 7:44 p.m.
We need to add args and *kwargs to this section.	david	Nov. 28, 2025, 7:44 p.m.
Can we do RemovedInDjblets70Warning.warn() if args or kwargs are truthy? That'll also make it easier to find later.	david	Dec. 1, 2025, 4:14 p.m.
Can we use an f-string here instead of %-formatting?	david	Nov. 28, 2025, 6:49 p.m.
Missing "Returns" in this docstring.	david	Nov. 28, 2025, 6:50 p.m.
Can we use f-strings here?	david	Nov. 28, 2025, 7:11 p.m.

flake8 passed.

JSHint passed.

djblets/util/decorators.py (Diff revision 1)

The issue has been dropped. Show all issues

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

chipx86 Nov. 28, 2025, 8:03 p.m.

It's for compatibility. The old code took it, so we'd have to deprecate its removal. Adding that.

djblets/util/decorators.py (Diff revision 1)
The issue has been resolved. Show all issues
```
We need to add *args and **kwargs to this section.
```
djblets/util/tests/test_blocktag.py (Diff revision 1)
The issue has been resolved. Show all issues
```
Can we use an f-string here instead of %-formatting?
```
djblets/util/tests/test_blocktag.py (Diff revision 1)
The issue has been resolved. Show all issues
```
Missing "Returns" in this docstring.
```

djblets/util/tests/test_blocktag.py (Diff revision 1)

The issue has been dropped. Show all issues

Can we use f-strings here?

chipx86 Nov. 28, 2025, 8:03 p.m.

I originally had it that way, but the second line got to be a pain due to the {} escaping.

"""
{{% my_blockag {args} %}}
{{{{my_var1}}}}{{{{my_var2}}}}
{{% endmy_blocktag %}}
"""


Sort of a "pick your poison", but escaping % felt more readable in the next.

Change Summary:


Deprecated *args and **kwargs.
Switched to an f-string in one place.
Updated docs for a missing Return.

Commits:

	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
	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.	09cc83decc162e6a9f93531f19356027f0b7391b

Diff:

Revision 2 (+872 -110)

Show changes

	djblets/util/decorators.py
	djblets/util/tests/test_blocktag.py

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

djblets/util/decorators.py (Diff revisions 1 - 2)

The issue has been resolved. Show all issues

Can we do RemovedInDjblets70Warning.warn() if args or kwargs are truthy? That'll also make it easier to find later.

Change Summary:

Added warnings when using deprecated *args and **kwargs.

Commits:

	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.	09cc83decc162e6a9f93531f19356027f0b7391b
	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.	d0a9a5f0a42396b55bc234194a25ace87832d7d6

Diff:

Revision 3 (+898 -108)

Show changes

	djblets/util/decorators.py
	djblets/util/tests/test_blocktag.py

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

Ship it!

```
Ship It!
```

Ship it!

```
Ship It!
```

Status:: Completed
Change Summary:: Pushed to release-5.x (0341f45)