Ah, interesting.  The python version (which is based on the original python code that served as the specification for the C version) has docstrings that explicitly say "new XXX".  The C docstrings and rest docs do not reflect that subtlety.

The docstrings of the two modules and the rest docs should be harmonized.  A single word can make a difference :)

Perhaps this should be brought up on python-dev again, as the issue here clearly applies to more than just datetime.  This in many ways highlights the heart of the subclassing issue.

In the email package I called the method "clone", and all properties that can be changed are accessible as keyword arguments...and in fact that set of properties is explicitly the set of all class non-method attributes.  Policy instance attributes are otherwise read-only.  So I solved the problem by specifying the behavior of the clone method in the face of subclassing, making it an explicit API.  That's more like your first option: specifying the API you need to follow in a subclass in order to support replace.