From 10756b10ff8e47ece33f7fbf62c9a06f8a866fed Mon Sep 17 00:00:00 2001
From: Steve Dower <steve.dower@python.org>
Date: Mon, 12 Feb 2024 22:28:36 +0000
Subject: [PATCH] gh-111140: Minor doc fixes for PyLong_AsNativeBytes
 (GH-115375)

---
 Doc/c-api/long.rst | 24 ++++++++++++++----------
 1 file changed, 14 insertions(+), 10 deletions(-)

diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst
index c39823e5e67..f24282e76a3 100644
--- a/Doc/c-api/long.rst
+++ b/Doc/c-api/long.rst
@@ -359,13 +359,16 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    Copy the Python integer value to a native *buffer* of size *n_bytes*::
 
       int value;
-      Py_ssize_t bytes = PyLong_CopyBits(v, &value, sizeof(value), -1);
+      Py_ssize_t bytes = PyLong_AsNativeBytes(v, &value, sizeof(value), -1);
       if (bytes < 0) {
           // Error occurred
           return NULL;
       }
-      else if (bytes > sizeof(value)) {
-          // Overflow occurred, but 'value' contains as much as could fit
+      else if (bytes <= (Py_ssize_t)sizeof(value)) {
+          // Success!
+      }
+      else {
+          // Overflow occurred, but 'value' contains truncated value
       }
 
    *endianness* may be passed ``-1`` for the native endian that CPython was
@@ -379,15 +382,16 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    Unless an exception is raised, all *n_bytes* of the buffer will be written
    with as much of the value as can fit. This allows the caller to ignore all
    non-negative results if the intent is to match the typical behavior of a
-   C-style downcast.
+   C-style downcast. No exception is set for this case.
 
-   Values are always copied as twos-complement, and sufficient size will be
-   requested for a sign bit. For example, this may cause an value that fits into
-   8 bytes when treated as unsigned to request 9 bytes, even though all eight
-   bytes were copied into the buffer. What has been omitted is the zero sign
-   bit, which is redundant when the intention is to treat the value as unsigned.
+   Values are always copied as two's-complement, and sufficient buffer will be
+   requested to include a sign bit. For example, this may cause an value that
+   fits into 8 bytes when treated as unsigned to request 9 bytes, even though
+   all eight bytes were copied into the buffer. What has been omitted is the
+   zero sign bit, which is redundant when the intention is to treat the value as
+   unsigned.
 
-   Passing *n_bytes* of zero will always return the requested buffer size.
+   Passing zero to *n_bytes* will return the requested buffer size.
 
    .. note::