How is your code used by developers? In other words, what exactly do they do to determine which arguments should be used and how?
If they rely on documentation automatically generated from your code, and the generator has no clue what to do with
**kwargs, this is indeed problematic. Instead of finding the list of arguments and their meaning in the documentation, they have absolutely no information except the vague “it takes some arguments”.
This problem may probably be solved by documenting the method manually, replacing the documentation generated automatically. This requires extra work from the implementer of the method, but remember, code (and its documentation) is read much more frequently than it's written.
If code is their documentation, the developers who use the method with
**kwargs need two additional steps: they need not only to look at the signature of the method, but also at its actual implementation, in order to find the other method it actually calls. Then, they need to go to this other method to finally find what they were looking for.
This doesn't involve a lot of effort, but still, the effort should be repeated, again and again. The worst part is that you can't help them by adding documentation: if you comment your method, listing the actual arguments, there is a big risk that the next version of the library your method calls will have different arguments, and your documentation will be outdated, since nobody will recall that it needs to be kept up to date.
My recommendation is to rely on
**kwargs only for methods which have a reduced scope. Private methods (and by private in a context of Python, I mean methods starting by
_) which are used in few places in the class are good candidates, for example. On the other hand, methods which are used by dozens of classes all over the code base are very bad candidates.
After all, it shouldn't take too much effort to rewrite the arguments of a method you call within the method you write. Hopefully, most methods don't take more than six to eight arguments, and if they do, ask yourself if you shouldn't be refactoring the code. In all cases:
Making arguments explicit within your method doesn't require a lot of effort,
You may want, later, to validate the arguments anyway (although if you rely only on this point to make arguments explicit, you violate YAGNI).