Add support for optional decorator parentheses

[angus-lherrou]

• fixes raise a more descriptive exception when @command decorator isn't called #1359

Checklist:

• Add tests that demonstrate the correct behavior of the change. Tests should fail without the change.
• Add or update relevant docs, in the docs folder and in code.
• Add an entry in CHANGES.rst summarizing the change and linking to the issue.
• Add .. versionchanged:: entries in any relevant code docs.
• Run pre-commit hooks and fix any issues.
• Run pytest and tox, no tests failed.

[angus-lherrou]

Maintainers, I'm not sure if this change needs any docs updates?

[ThiefMaster]

Wouldn't it be better if the decorators were smart enough to work even without parentheses, ie if there's exactly one positional argument and that argument is a callable, assume it's the decorated function...

[davidism]

I go back and forth on that pattern. Right now I'm on the side of "there should be one way to do things". Even if we can detect it, better to tell everyone to do something consistently. I'd have to look at the mypy docs, but I have a feeling the "decorator or factory" pattern makes typing more complicated too.

For example, non-factory decorators don't typically also support the factory pattern. (Although maybe they should, then PyCharm incorrectly doing @pass_context() wouldn't cause an error either...)

[ThiefMaster]

I know pytest does it for example, but no idea if they use type hints..

[ThiefMaster]

https://github.com/pytest-dev/pytest/blob/main/src/_pytest/fixtures.py#L1239-L1272

[davidism]

@angus-lherrou if you're up for it, want to implement this dual option instead of showing an error? If not, we can merge this then make another issue about supporting plain decorators.

[angus-lherrou]

My first thought was actually the same, but I spent some time trying to implement the optional parentheses and it just wasn't working the way I was hoping it would. I can take a look at how pytest implements it and take another crack at it.

[angus-lherrou]

@davidism I figured it out! When I tried before I didn't realize that I needed to call the inner function before returning it if the decorator isn't called at the invocation site.

[angus-lherrou]

I suppose it would be good to add this new capability in the documentation somewhere