Text of peps.python.org › pep-0468 as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 468 – Preserving the order of **kwargs in a function. | peps.python.org

PEP 468 – Preserving the order of **kwargs in a function. PEP 468 – Preserving the order of **kwargs in a function. Author : Eric Snow <ericsnowcurrently at gmail.com> Discussions-To : Python-Ideas list Status : Final Type : Standards Track Created : 05-Apr-2014 Python-Version : 3.6 Post-History : 05-Apr-2014, 08-Sep-2016 Resolution : Python-Dev message Table of Contents Abstract Motivation Use Cases Serialization Debugging Other Use Cases Concerns Performance Other Python Implementations Specification Relationship to **-unpacking syntax Relationship to inspect.Signature C-API Syntax Backward-Compatibility Reference Implementation Alternate Approaches Opt-out Decorator Opt-in Decorator __kworder__ Compact dict with faster iteration ***kwargs annotations dict.__order__ KWArgsDict.__order__ Acknowledgements Footnotes References Copyright Abstract The **kwargs syntax in a function definition indicates that the interpreter should collect all keyword arguments that do not correspond to other named parameters.

However, Python does not preserved the order in which those collected keyword arguments were passed to the function. In some contexts the order matters. This PEP dictates that the collected keyword arguments be exposed in the function body as an ordered mapping. Motivation Python’s **kwargs syntax in function definitions provides a powerful means of dynamically handling keyword arguments. In some applications of the syntax (see Use Cases ), the semantics applied to the collected keyword arguments requires that order be preserved.

Unsurprisingly, this is similar to how OrderedDict is related to dict. Currently to preserved the order you have to do so manually and separately from the actual function call. This involves building an ordered mapping, whether an OrderedDict or an iterable of 2-tuples, which is then passed as a single argument to the function. [1] With the capability described in this PEP, that boilerplate would no longer be required.

For comparison, currently: kwargs = OrderedDict () kwargs [ 'eggs' ] = ... ... def spam ( a , kwargs ): ... and with this proposal: def spam ( a , ** kwargs ): ... Alyssa (Nick) Coghlan, speaking of some of the uses cases, summed it up well [2] : These * can * all be done today , but * not * by using keyword arguments . In my view , the problem to be addressed is that keyword arguments * look * like they should work for these cases , because they have a definite order in the source code .

The only reason they don 't work is because the interpreter throws that ordering information away . It 's a textbook case of a language feature becoming an attractive nuisance in some circumstances : the simple and obvious solution for the above use cases * doesn 't actually work* for reasons that aren' t obviously clear if you don 't have a firm grasp of Python' s admittedly complicated argument handling . This observation is supported by the appearance of this proposal over the years and the numerous times that people have been confused by the constructor for OrderedDict. [3] [4] [5] Use Cases As Alyssa noted, the current behavior of **kwargs is unintuitive in cases where one would expect order to matter.

Aside from more specific cases outlined below, in general “anything else where you want to control the iteration order and set field names and values in a single call will potentially benefit.” [6] That matters in the case of factories (e.g. __init__()) for ordered types. Serialization Obviously OrderedDict would benefit (both __init__() and update()) from ordered kwargs. However, the benefit also extends to serialization APIs [2] : In the context of serialisation , one key lesson we have learned is that arbitrary ordering is a problem when you want to minimise spurious diffs , and sorting isn 't a simple solution.

Tools like doctest don 't tolerate spurious diffs at all, but are often amenable to a sorting based answer . The cases where it would be highly desirable to be able use keyword arguments to control the order of display of a collection of key value pairs are ones like : * printing out key : value pairs in CLI output * mapping semantic names to column order in a CSV * serialising attributes and elements in particular orders in XML * serialising map keys in particular orders in human readable formats like JSON and YAML ( particularly when they 're going to be placed under source control ) Debugging In the words of Raymond Hettinger [7] : It makes it easier to debug if the arguments show - up in the order they were created .

AFAICT , no purpose is served by scrambling them . Other Use Cases Mock objects. [8] Controlling object presentation. Alternate namedtuple() where defaults can be specified. Specifying argument priority by order. Concerns Performance As already noted, the idea of ordered keyword arguments has come up on a number of occasions. Each time it has been met with the same response, namely that preserving keyword arg order would have a sufficiently adverse effect on function call performance that it’s not worth doing.

However, Guido noted the following [9] : Making ** kwds ordered is still open , but requires careful design and implementation to avoid slowing down function calls that don 't benefit. As will be noted below, there are ways to work around this at the expense of increased complication. Ultimately the simplest approach is the one that makes the most sense: pack collected key word arguments into an OrderedDict. However, without a C implementation of OrderedDict there isn’t much to discuss.

That changed in Python 3.5. [10] Note: in Python 3.6 dict is order-preserving. This virtually eliminates performance concerns. Other Python Implementations Another important issue to consider is that new features must be cognizant of the multiple Python implementations. At some point each of them would be expected to have implemented ordered kwargs. In this regard there doesn’t seem to be an issue with the idea. [11] An informal survey of the major Python implementations has indicated that this feature will not be a significant burden.

Specification Starting in version 3.6 Python will preserve the order of keyword arguments as passed to a function. To accomplish this the collected kwargs will now be an ordered mapping. Note that this does not necessarily mean OrderedDict. dict in CPython 3.6 is now ordered, similar to PyPy. This will apply only to functions for which the definition uses the **kwargs syntax for collecting otherwise unspecified keyword arguments.

Only the order of those keyword arguments will be preserved. Relationship to **-unpacking syntax The ** unpacking syntax in function calls has no special connection with this proposal. Keyword arguments provided by unpacking will be treated in exactly the same way as they are now: ones that match defined parameters are gather there and the remainder will be collected into the ordered kwargs (just like any other unmatched keyword argument).

Note that unpacking a mapping with undefined order, such as dict, will preserve its iteration order like normal. It’s just that the order will remain undefined. The ordered mapping into which the unpacked key-value pairs will then be packed will not be able to provide any alternate ordering. This should not be surprising. There have been brief discussions of simply passing these mappings through to the functions kwargs without unpacking and repacking them, but that is both outside the scope of this proposal and probably a bad idea regardless. (There is a reason those discussions were brief.) Relationship to inspect.Signature Signature objects should need no changes.

The kwargs parameter of inspect.BoundArguments (returned by Signature.bind() and Signature.bind_partial()) will change from a dict to an OrderedDict. C-API No changes. Syntax No syntax is added or changed by this proposal. Backward-Compatibility The following will change: iteration order of kwargs will now be consistent (except of co

The rest of this page is on the live site.