pathlib.Path.__new__ takes **kwargs, but doesn't do anything with them (https://github.com/python/cpython/blob/master/Lib/pathlib.py#L979). This doesn't appear to be documented.

This feature should presumably be either documented or removed (probably removed unless I'm missing some reason for having it).

Brief discussion on a typeshed PR at python/typeshed#991 (diff)

Yep, kwargs should be dropped since it isn't used or documented: https://docs.python.org/3/library/pathlib.html#pathlib.PurePath (probably just a hold-over from when it did in some earlier version of the code).

Thanks, I'll add a PR. This doesn't need to be documented, right?

The support of **kwargs in Path.__new__ is needed if you want to implement a subclass of Path with __init__ accepting keyword arguments (and since Path constructor takes variable number of positional arguments, new arguments should be keyword-only).

>>> import pathlib
>>> class MyPath(pathlib.PosixPath):
...     def __init__(self, *args, spam=False):
...         self.spam = spam
... 
>>> p = MyPath('/', spam=True)
>>> p
MyPath('/')
>>> p.spam
True

Removing **kwargs from Path.__new__ will break the above example.

>>> MyPath('/', spam=True)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: __new__() got an unexpected keyword argument 'spam'

Shoot, that's too bad. I guess we should document it then so people are aware that keyword arguments are ignored, else we will break subclasses. There's also an unfortunate difference between PurePath and Path as PurePath doesn't have this quirk.

I don't know whether it was the intension of Antoine or just an oversight. I don't know whether it is used in the wild. But we can at least raise a TypeError for concrete classes PosixPath and WindowsPath if ignoring keyword arguments is a problem. Many extension types don't take keyword arguments, but their subclasses accept and ignore keyword arguments. For example:

>>> filter(None, [], foo=123)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: filter() does not take keyword arguments
>>> class X(filter): pass
... 
>>> X(None, [], foo=123)
<__main__.X object at 0xb6fdcacc>

The support of **kwargs in Path.__new__ is needed if you want to implement a subclass of Path with __init__ accepting keyword arguments

I don't remember exactly, but I think this was the intention indeed. There was originally an openat-using subclass, and IIRC it took additional parameters (such as the directory fd). That got scrapped quite early in the process, so we can remove the **kwargs thing now.

Then I vote for Serhiy's idea of simply raising an exception in the concrete subclasses when a keyword argument is given.

PurePath subclasses cannot support kwargs as __new__() does not accept **kwargs:

>>> from pathlib import PurePath
>>> class MyPurePath(PurePath):
...     def __init__(self, *args, **kargs): pass
... 
>>> MyPurePath('foo', spam=True)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: __new__() got an unexpected keyword argument 'spam'

The behaviour for this should probably be made the same for both Path and PurePath.

As reported in the dupe bug, this bug led to masking a user mistake.

#100481 would fix this without breaking subclassing by adding an __init__() method.

I took #19632 as a fix, but it can obviously be tweaked as long as the deprecation warning sticks around.