The documentation (https://docs.python.org/3/library/functions.html#type) shows type's signature as:

class type(object)
class type(name, bases, dict)


But the "actual" 2nd signature in CPython 3.6+ is:

class type(name, bases, dict, **kwargs)


**kwargs here gets passed to __init_subclass__ in the same way that keywords in a class statement do so that:

type("Bar", (Foo,), {}, spam='ham')

is equivalent to

class Bar(Foo, spam='ham'): pass


It's not clear to me whether this is behavior to rely on. I started using this intuitively, but found that my type checker reasonably complained.

Looking through the commit that implemented PEP 487 (d78448e9), it seems this may have been incidental. Additionally I haven't found mention of this in PEP 487 or the documentation and I can't seem to find any tests for it.

That sounds intentional to me (else the class statement would have a capability that cannot be dynamically emulated by calling type()).

We should probably update the docs (if you could submit a small PR that would be appreciated) and also typeshed (ditto).

Can do.

I have found a blurb in the 3.6 What's New that confirms it was purposeful (https://docs.python.org/3/whatsnew/3.6.html#index-37).

Excellent!

Seems I misframed the issue a bit. I didn't realize keyword arguments besides 'metaclass' were introduced with PEP 3115 with Python 3.0.


In any case I've posted a PR to update the docs and typeshed.
Typeshed PR for reference: https://github.com/python/typeshed/pull/4918

The CPython PR has gone stale waiting for core review, pinging this per the dev guide.

I'll try to review it in the coming weeks.

New changeset 72fcd14a82369ed32a5846d76f50e3026cf4eec2 by Erik Soma in branch 'master':
bpo-42840: Document providing kwargs to type. (#24173)
https://github.com/python/cpython/commit/72fcd14a82369ed32a5846d76f50e3026cf4eec2

New changeset 7101d152f9789ad243912c00349d5da657b217fd by Miss Islington (bot) in branch '3.8':
bpo-42840: Document providing kwargs to type. (GH-24173)
https://github.com/python/cpython/commit/7101d152f9789ad243912c00349d5da657b217fd

New changeset b3c1e2c493e67f84b1034ac6c49492a459b0736d by Miss Islington (bot) in branch '3.9':
bpo-42840: Document providing kwargs to type. (GH-24173)
https://github.com/python/cpython/commit/b3c1e2c493e67f84b1034ac6c49492a459b0736d