[Python-checkins] gh-96526: Clarify format and __format__ docstrings (gh-96648)
ericvsmith
webhook-mailer at python.org
Mon Oct 3 18:28:10 EDT 2022
https://github.com/python/cpython/commit/07b8e85d0e29bc59a7a7d7d662db500c93980edb
commit: 07b8e85d0e29bc59a7a7d7d662db500c93980edb
branch: main
author: Michael <216956+mikez at users.noreply.github.com>
committer: ericvsmith <ericvsmith at users.noreply.github.com>
date: 2022-10-03T15:28:02-07:00
summary:
gh-96526: Clarify format and __format__ docstrings (gh-96648)
files:
M Objects/clinic/longobject.c.h
M Objects/clinic/typeobject.c.h
M Objects/longobject.c
M Objects/typeobject.c
M Python/bltinmodule.c
M Python/clinic/bltinmodule.c.h
diff --git a/Objects/clinic/longobject.c.h b/Objects/clinic/longobject.c.h
index 1cf5b4318859..dde49099cf95 100644
--- a/Objects/clinic/longobject.c.h
+++ b/Objects/clinic/longobject.c.h
@@ -88,7 +88,8 @@ int___getnewargs__(PyObject *self, PyObject *Py_UNUSED(ignored))
PyDoc_STRVAR(int___format____doc__,
"__format__($self, format_spec, /)\n"
"--\n"
-"\n");
+"\n"
+"Convert to a string according to format_spec.");
#define INT___FORMAT___METHODDEF \
{"__format__", (PyCFunction)int___format__, METH_O, int___format____doc__},
@@ -466,4 +467,4 @@ int_from_bytes(PyTypeObject *type, PyObject *const *args, Py_ssize_t nargs, PyOb
exit:
return return_value;
}
-/*[clinic end generated code: output=b29b4afc65e3290e input=a9049054013a1b77]*/
+/*[clinic end generated code: output=bf6074ecf2f32cf4 input=a9049054013a1b77]*/
diff --git a/Objects/clinic/typeobject.c.h b/Objects/clinic/typeobject.c.h
index f2864297b0f4..dc9746abfbe9 100644
--- a/Objects/clinic/typeobject.c.h
+++ b/Objects/clinic/typeobject.c.h
@@ -204,7 +204,9 @@ PyDoc_STRVAR(object___format____doc__,
"__format__($self, format_spec, /)\n"
"--\n"
"\n"
-"Default object formatter.");
+"Default object formatter.\n"
+"\n"
+"Return str(self) if format_spec is empty. Raise TypeError otherwise.");
#define OBJECT___FORMAT___METHODDEF \
{"__format__", (PyCFunction)object___format__, METH_O, object___format____doc__},
@@ -267,4 +269,4 @@ object___dir__(PyObject *self, PyObject *Py_UNUSED(ignored))
{
return object___dir___impl(self);
}
-/*[clinic end generated code: output=3312f873c970bfd1 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=d2fc52440a89f2fa input=a9049054013a1b77]*/
diff --git a/Objects/longobject.c b/Objects/longobject.c
index d9f3d393b998..8b13df4181ec 100644
--- a/Objects/longobject.c
+++ b/Objects/longobject.c
@@ -5528,11 +5528,13 @@ int.__format__
format_spec: unicode
/
+
+Convert to a string according to format_spec.
[clinic start generated code]*/
static PyObject *
int___format___impl(PyObject *self, PyObject *format_spec)
-/*[clinic end generated code: output=b4929dee9ae18689 input=e31944a9b3e428b7]*/
+/*[clinic end generated code: output=b4929dee9ae18689 input=d5e1254a47e8d1dc]*/
{
_PyUnicodeWriter writer;
int ret;
diff --git a/Objects/typeobject.c b/Objects/typeobject.c
index 5aa5cbbd5402..196a6aee4993 100644
--- a/Objects/typeobject.c
+++ b/Objects/typeobject.c
@@ -5824,11 +5824,13 @@ object.__format__
/
Default object formatter.
+
+Return str(self) if format_spec is empty. Raise TypeError otherwise.
[clinic start generated code]*/
static PyObject *
object___format___impl(PyObject *self, PyObject *format_spec)
-/*[clinic end generated code: output=34897efb543a974b input=7c3b3bc53a6fb7fa]*/
+/*[clinic end generated code: output=34897efb543a974b input=b94d8feb006689ea]*/
{
/* Issue 7994: If we're converting to a string, we
should reject format specifications */
diff --git a/Python/bltinmodule.c b/Python/bltinmodule.c
index 551e4f39b27a..2809b03d4a93 100644
--- a/Python/bltinmodule.c
+++ b/Python/bltinmodule.c
@@ -677,16 +677,19 @@ format as builtin_format
format_spec: unicode(c_default="NULL") = ''
/
-Return value.__format__(format_spec)
+Return type(value).__format__(value, format_spec)
-format_spec defaults to the empty string.
-See the Format Specification Mini-Language section of help('FORMATTING') for
-details.
+Many built-in types implement format_spec according to the
+Format Specification Mini-language. See help('FORMATTING').
+
+If type(value) does not supply a method named __format__
+and format_spec is empty, then str(value) is returned.
+See also help('SPECIALMETHODS').
[clinic start generated code]*/
static PyObject *
builtin_format_impl(PyObject *module, PyObject *value, PyObject *format_spec)
-/*[clinic end generated code: output=2f40bdfa4954b077 input=88339c93ea522b33]*/
+/*[clinic end generated code: output=2f40bdfa4954b077 input=45ef3934b86d5624]*/
{
return PyObject_Format(value, format_spec);
}
diff --git a/Python/clinic/bltinmodule.c.h b/Python/clinic/bltinmodule.c.h
index 0feba5742df2..19930a519be0 100644
--- a/Python/clinic/bltinmodule.c.h
+++ b/Python/clinic/bltinmodule.c.h
@@ -183,11 +183,14 @@ PyDoc_STRVAR(builtin_format__doc__,
"format($module, value, format_spec=\'\', /)\n"
"--\n"
"\n"
-"Return value.__format__(format_spec)\n"
+"Return type(value).__format__(value, format_spec)\n"
"\n"
-"format_spec defaults to the empty string.\n"
-"See the Format Specification Mini-Language section of help(\'FORMATTING\') for\n"
-"details.");
+"Many built-in types implement format_spec according to the\n"
+"Format Specification Mini-language. See help(\'FORMATTING\').\n"
+"\n"
+"If type(value) does not supply a method named __format__\n"
+"and format_spec is empty, then str(value) is returned.\n"
+"See also help(\'SPECIALMETHODS\').");
#define BUILTIN_FORMAT_METHODDEF \
{"format", _PyCFunction_CAST(builtin_format), METH_FASTCALL, builtin_format__doc__},
@@ -1212,4 +1215,4 @@ builtin_issubclass(PyObject *module, PyObject *const *args, Py_ssize_t nargs)
exit:
return return_value;
}
-/*[clinic end generated code: output=f3da5510745785af input=a9049054013a1b77]*/
+/*[clinic end generated code: output=3c9497e0ffeb8a30 input=a9049054013a1b77]*/
More information about the Python-checkins
mailing list