bpo-42431: Fix outdated bytes comments (GH-23458)

Also move definitions of internal macros F_LJUST etc to private header.

3 files changed, 39 insertions, 25 deletions

diff --git a/Include/bytesobject.h b/Include/bytesobject.h
index 5062d8d123a..39c241a2dcf 100644
--- a/Include/bytesobject.h
+++ b/Include/bytesobject.h
@@ -1,5 +1,5 @@
 
-/* Bytes (String) object interface */
+/* Bytes object interface */
 
 #ifndef Py_BYTESOBJECT_H
 #define Py_BYTESOBJECT_H
@@ -10,23 +10,20 @@ extern "C" {
 #include <stdarg.h>
 
 /*
-Type PyBytesObject represents a character string.  An extra zero byte is
+Type PyBytesObject represents a byte string.  An extra zero byte is
 reserved at the end to ensure it is zero-terminated, but a size is
 present so strings with null bytes in them can be represented.  This
 is an immutable object type.
 
-There are functions to create new string objects, to test
-an object for string-ness, and to get the
-string value.  The latter function returns a null pointer
+There are functions to create new bytes objects, to test
+an object for bytes-ness, and to get the
+byte string value.  The latter function returns a null pointer
 if the object is not of the proper type.
 There is a variant that takes an explicit size as well as a
 variant that assumes a zero-terminated string.  Note that none of the
-functions should be applied to nil objects.
+functions should be applied to NULL pointer.
 */
 
-/* Caching the hash (ob_shash) saves recalculation of a string's hash value.
-   This significantly speeds up dict lookups. */
-
 PyAPI_DATA(PyTypeObject) PyBytes_Type;
 PyAPI_DATA(PyTypeObject) PyBytesIter_Type;
 
@@ -50,26 +47,16 @@ PyAPI_FUNC(PyObject *) PyBytes_DecodeEscape(const char *, Py_ssize_t,
                                             const char *, Py_ssize_t,
                                             const char *);
 
-/* Provides access to the internal data buffer and size of a string
-   object or the default encoded version of a Unicode object. Passing
-   NULL as *len parameter will force the string buffer to be
-   0-terminated (passing a string with embedded NULL characters will
+/* Provides access to the internal data buffer and size of a bytes object.
+   Passing NULL as len parameter will force the string buffer to be
+   0-terminated (passing a string with embedded NUL characters will
    cause an exception).  */
 PyAPI_FUNC(int) PyBytes_AsStringAndSize(
-    PyObject *obj,      /* string or Unicode object */
+    PyObject *obj,      /* bytes object */
     char **s,           /* pointer to buffer variable */
-    Py_ssize_t *len     /* pointer to length variable or NULL
-                           (only possible for 0-terminated
-                           strings) */
+    Py_ssize_t *len     /* pointer to length variable or NULL */
     );
 
-/* Flags used by string formatting */
-#define F_LJUST (1<<0)
-#define F_SIGN  (1<<1)
-#define F_BLANK (1<<2)
-#define F_ALT   (1<<3)
-#define F_ZERO  (1<<4)
-
 #ifndef Py_LIMITED_API
 #  define Py_CPYTHON_BYTESOBJECT_H
 #  include  "cpython/bytesobject.h"
diff --git a/Include/cpython/bytesobject.h b/Include/cpython/bytesobject.h
index f284c5835df..6b3f55224fc 100644
--- a/Include/cpython/bytesobject.h
+++ b/Include/cpython/bytesobject.h
@@ -10,7 +10,7 @@ typedef struct {
     /* Invariants:
      *     ob_sval contains space for 'ob_size+1' elements.
      *     ob_sval[ob_size] == 0.
-     *     ob_shash is the hash of the string or -1 if not computed yet.
+     *     ob_shash is the hash of the byte string or -1 if not computed yet.
      */
 } PyBytesObject;
 
diff --git a/Include/internal/pycore_format.h b/Include/internal/pycore_format.h
new file mode 100644
index 00000000000..1b8d57539ca
--- /dev/null
+++ b/Include/internal/pycore_format.h
@@ -0,0 +1,27 @@
+#ifndef Py_INTERNAL_FORMAT_H
+#define Py_INTERNAL_FORMAT_H
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifndef Py_BUILD_CORE
+#  error "this header requires Py_BUILD_CORE define"
+#endif
+
+/* Format codes
+ * F_LJUST      '-'
+ * F_SIGN       '+'
+ * F_BLANK      ' '
+ * F_ALT        '#'
+ * F_ZERO       '0'
+ */
+#define F_LJUST (1<<0)
+#define F_SIGN  (1<<1)
+#define F_BLANK (1<<2)
+#define F_ALT   (1<<3)
+#define F_ZERO  (1<<4)
+
+#ifdef __cplusplus
+}
+#endif
+#endif /* !Py_INTERNAL_FORMAT_H */