Method signatures in the datetime module documentation
I have started [1] writing documentation for the new PEP 495 (Local Time Disambiguation) features and ran into the following problem. The current documentation is rather inconsistent in presenting the method signatures. For example:
date.replace(year, month, day) [2], but datetime.replace([year[, month[, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]]]]]) [3].
The new signature for datetime.replace in the Python implementation is
def replace(self, hour=None, minute=None, second=None, microsecond=None, tzinfo=True, *, fold=None):
but the C implementation does not accept True for tzinfo or None for the other arguments. The defaults in the Python implementation are really just sentinels to detect which arguments are not provided.
How should I present the signature of the new replace method in the documentation?
[1]: http://bugs.python.org/issue27595 [2]: https://docs.python.org/3/library/datetime.html#datetime.date.replace [3]: https://docs.python.org/3/library/datetime.html#datetime.datetime.replace
On Fri, Jul 29, 2016 at 12:55 PM, Alexander Belopolsky alexander.belopolsky@gmail.com wrote:
How should I present the signature of the new replace method in the documentation?
Having not seeing any replies, let me make a proposal:
datetime.replace(hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=self.fold)
while not a valid method signature, this seems to correctly reflect what replace() does.
On 4 August 2016 at 00:24, Alexander Belopolsky alexander.belopolsky@gmail.com wrote:
On Fri, Jul 29, 2016 at 12:55 PM, Alexander Belopolsky alexander.belopolsky@gmail.com wrote:
How should I present the signature of the new replace method in the documentation?
Having not seeing any replies, let me make a proposal:
datetime.replace(hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=self.fold)
while not a valid method signature, this seems to correctly reflect what replace() does.
Does that mean replace() accepts most of its arguments as either positional or keyword arguments? IMO when the documentation uses the “name=default” notation, it implies keyword argument support, while the [name] notation implies only supporting a positional argument. If replace() actually supported these keywords all along, then I am happy with this proposal.
There are a few bug reports that may be relevant:
https://bugs.python.org/issue13386: notation where there is no simple default value https://bugs.python.org/issue23738: notation for defaults for positional-only parameters
On Wed, Aug 3, 2016 at 10:41 PM, Martin Panter vadmium+py@gmail.com wrote:
If replace() actually supported these keywords all along, then I am happy with this proposal.
With the obvious exception of "fold", it did at least since Python 3.0 (and likely since 2.x where x is 5 ± 1.)
There are a few bug reports that may be relevant:
https://bugs.python.org/issue13386: notation where there is no simple default value https://bugs.python.org/issue23738: notation for defaults for positional-only parameters
Thanks. These are helpful, but they don't address the case in hand where the member function defaults are taken from the other attributes.
participants (2)
-
Alexander Belopolsky -
Martin Panter