> You could argue the same thing (forcing kwargs) for all Python functions/methods, although, that would make using your APIs very annoying. The `__init__` method for dataclasses are just another method like any other.

While that is self evident at a technical level, it is not quite so from a clarity / documentary perspective: “normal” functions and methods can often hint at their parameters through their naming but it is uncommon for types, for which the composite tends to be much more of an implementation detail.

Of course neither rule is universal e.g. the composite is of prime importance for newtypes, and indeed they often use tuple-style types or have special support with no member names.

> that would make using your APIs very annoying

For Objective C, using named parameters is the only way to call methods. I don't think I read many critique about this particular aspect. IMO it's actually a good thing and increases readability quite a bit.

For JavaScript/TypeScript React codebase, using objects as a poor man's named parameters also very popular approach.

Also I'd like to add, that it seems a recent trend to add feature to IDEs, where it'll add hint for every parameter, somewhat simulating named parameters. So when you write `mymethod(value)`, it'll display it as `mymethod(param:value)`.

So may be not very annoying.

The only little thing I'd like to borrow from JavaScript is using "shortcut", so you could replace `x=x` with `x`, if your local variable happened to have the same name, as parameter name (which happens often enough).

That's always the challenge when iterating on interfaces that other people depend on.

What we do is go through a deprecation phase. Our process is:

* We provide compatibility with the old signature for 2 major releases.

* We document the change and the timeline clearly in the docstring.

* The function gets decorated with a helper that checks the call, and if any keyword-only arguments are provided as positional, it warns and converts them to keyword-only.

* After 2 major releases, we move fully to the new signature.

We buit a Python library called housekeeping (https://github.com/beanbaginc/housekeeping) to help with this. One of the things it contains is a decorator called `@deprecate_non_keyword_only_args`, which takes a deprecation warning class and a function using the signature we're moving to. That decorator handles the check logic and generates a suitable, consistent deprecation message.

That normally looks like:

    @deprecate_non_keyword_only_args(MyDeprecationWarning)
    def my_func(*, a, b, c):
        ...

But this is a bit more tricky with dataclasses, since `__init__()` is generated automatically. Fortunately, it can be patched after the fact. A bit less clean, but doable.

So here's how we'd handle this case with dataclasses:

    from dataclasses import dataclass
    
    from housekeeping import BaseRemovedInWarning, deprecate_non_keyword_only_args
    
    
    class RemovedInMyProject20Warning(BaseRemovedInWarning):
        product = 'MyProject'
        version = '2.0'
    
    
    @dataclass(kw_only=True)
    class MyDataclass:
        a: int
        b: int
        c: str
    
    MyDataclass.__init__ = deprecate_non_keyword_only_args(
        RemovedInMyProject20Warning
    )(MyDataclass.__init__)

Call it with some positional arguments:

    dc = MyDataclass(1, 2, c='hi')

and you'd get:

    testdataclass.py:26: RemovedInMyProject20Warning: Positional arguments `a`, `b` must be passed as keyword arguments when calling `__main__.MyDataclass.__init__()`. Passing as positional arguments will be required in MyProject 2.0.
      dc = MyDataclass(1, 2, c='hi')

We'll probably add explicit dataclass support to this soon, since we're starting to move to kw_only=True for dataclasses.

That's annoying for sure. Though a different problem.

All the kw_only=True argument for dataclasses does is require that you pass any fields you want to provide as keyword arguments instead of positional arguments when instantiating a dataclass. So:

    obj = MyDataclass(a=1, b=2, c=3)

Instead of:

    obj = MyDataclass(1, 2, 3)  # This would be an error with kw_only=True

The problem you're describing in boto3 (and a lot of other API bindings, and a lot of more layered Python code) is that methods often take in **kwargs and pass them down to a common function that's handling them. From the caller's perspective, **kwargs is a black box with no details on what's in there. Without a docstring or an understanding of the call chain, it's not helpful.

Python sort of has a fix for this now, which is to use a TypedDict to define all the possible values in the **kwargs, like so:

    from typing import TypedDict, Unpack


    class MyFuncKwargs(TypedDict):
        arg1: str
        arg2: str
        arg3: int | None


    def my_outer_func(
        **kwargs: Unpack[MyFuncKwargs],
    ) -> None:
        _my_inner_func(**kwargs)


    def _my_inner_func(
        *,
        arg1: str,
        arg2: str,
        arg3: int | None,
    ) -> None:
        ...

By defining a TypedDict and typing **kwargs, the IDE and docs can do a better job of showing what arguments the function really takes, and validating them.

Also useful when the function is just a wrapper around serializing **kwargs to JSON for an API, or something.

But this feature is far from free to use. The more functions you have, the more of these you need to create and maintain.

Ideally, a function could type **kwargs as something like:

    def my_outer_func(
        **kwargs: KwargsOf[_my_inner_func],
    ) -> None:
        ...

And then the IDEs and other tooling can just reference that function. This would help make the problem go away for many of the cases where **kwargs is used and passed around.

In boto3 it helps to add a stubs package for development (and type checking).

Python 3.14 adds that shorthand, but with a slight different (and IMO uglier) syntax:

  fn(x=,y=,z=)

https://peps.python.org/pep-0736/

edit: nevermind, that PEP was rejected :/

there should definitely be an ocaml-like equivalent of "~argument"

Keyword-only arguments? Yes:

https://peps.python.org/pep-3102/

More recently, Python also added support for positional-only parameters:

https://peps.python.org/pep-0570/