Skip to content

Consistent spacing is a pre-requisite to consistently good writing. #136637

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Doc/c-api/abstract.rst
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Abstract Objects Layer

The functions in this chapter interact with Python objects regardless of their
type, or with wide classes of object types (e.g. all numerical types, or all
sequence types). When used on object types for which they do not apply, they
sequence types). When used on object types for which they do not apply, they
will raise a Python exception.

It is not possible to use these functions on objects that are not properly
Expand Down
24 changes: 12 additions & 12 deletions Doc/c-api/allocation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,10 @@ Allocating Objects on the Heap
.. c:function:: PyObject* PyObject_Init(PyObject *op, PyTypeObject *type)

Initialize a newly allocated object *op* with its type and initial
reference. Returns the initialized object. Other fields of the object are
not initialized. Despite its name, this function is unrelated to the
reference. Returns the initialized object. Other fields of the object are
not initialized. Despite its name, this function is unrelated to the
object's :meth:`~object.__init__` method (:c:member:`~PyTypeObject.tp_init`
slot). Specifically, this function does **not** call the object's
slot). Specifically, this function does **not** call the object's
:meth:`!__init__` method.

In general, consider this function to be a low-level routine. Use
Expand All @@ -29,7 +29,7 @@ Allocating Objects on the Heap
.. note::

This function only initializes the object's memory corresponding to the
initial :c:type:`PyObject` structure. It does not zero the rest.
initial :c:type:`PyObject` structure. It does not zero the rest.


.. c:function:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
Expand All @@ -39,7 +39,7 @@ Allocating Objects on the Heap

.. note::

This function only initializes some of the object's memory. It does not
This function only initializes some of the object's memory. It does not
zero the rest.


Expand All @@ -48,7 +48,7 @@ Allocating Objects on the Heap
Allocates a new Python object using the C structure type *TYPE* and the
Python type object *typeobj* (``PyTypeObject*``) by calling
:c:func:`PyObject_Malloc` to allocate memory and initializing it like
:c:func:`PyObject_Init`. The caller will own the only reference to the
:c:func:`PyObject_Init`. The caller will own the only reference to the
object (i.e. its reference count will be one).

Avoid calling this directly to allocate memory for an object; call the type's
Expand Down Expand Up @@ -77,8 +77,8 @@ Allocating Objects on the Heap

This macro does not construct a fully initialized object of the given
type; it merely allocates memory and prepares it for further
initialization by :c:member:`~PyTypeObject.tp_init`. To construct a
fully initialized object, call *typeobj* instead. For example::
initialization by :c:member:`~PyTypeObject.tp_init`. To construct a
fully initialized object, call *typeobj* instead. For example::

PyObject *foo = PyObject_CallNoArgs((PyObject *)&PyFoo_Type);

Expand All @@ -100,7 +100,7 @@ Allocating Objects on the Heap
* The memory is initialized like :c:func:`PyObject_InitVar`.

This is useful for implementing objects like tuples, which are able to
determine their size at construction time. Embedding the array of fields
determine their size at construction time. Embedding the array of fields
into the same allocation decreases the number of allocations, improving the
memory management efficiency.

Expand All @@ -127,8 +127,8 @@ Allocating Objects on the Heap

This macro does not construct a fully initialized object of the given
type; it merely allocates memory and prepares it for further
initialization by :c:member:`~PyTypeObject.tp_init`. To construct a
fully initialized object, call *typeobj* instead. For example::
initialization by :c:member:`~PyTypeObject.tp_init`. To construct a
fully initialized object, call *typeobj* instead. For example::

PyObject *list_instance = PyObject_CallNoArgs((PyObject *)&PyList_Type);

Expand All @@ -146,7 +146,7 @@ Allocating Objects on the Heap

.. c:var:: PyObject _Py_NoneStruct

Object which is visible in Python as ``None``. This should only be accessed
Object which is visible in Python as ``None``. This should only be accessed
using the :c:macro:`Py_None` macro, which evaluates to a pointer to this
object.

Expand Down
126 changes: 63 additions & 63 deletions Doc/c-api/arg.rst

Large diffs are not rendered by default.

12 changes: 6 additions & 6 deletions Doc/c-api/bool.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@
Boolean Objects
---------------

Booleans in Python are implemented as a subclass of integers. There are only
two booleans, :c:data:`Py_False` and :c:data:`Py_True`. As such, the normal
creation and deletion functions don't apply to booleans. The following macros
Booleans in Python are implemented as a subclass of integers. There are only
two booleans, :c:data:`Py_False` and :c:data:`Py_True`. As such, the normal
creation and deletion functions don't apply to booleans. The following macros
are available, however.


Expand All @@ -19,13 +19,13 @@ are available, however.

.. c:function:: int PyBool_Check(PyObject *o)

Return true if *o* is of type :c:data:`PyBool_Type`. This function always
Return true if *o* is of type :c:data:`PyBool_Type`. This function always
succeeds.


.. c:var:: PyObject* Py_False

The Python ``False`` object. This object has no methods and is
The Python ``False`` object. This object has no methods and is
:term:`immortal`.

.. versionchanged:: 3.12
Expand All @@ -34,7 +34,7 @@ are available, however.

.. c:var:: PyObject* Py_True

The Python ``True`` object. This object has no methods and is
The Python ``True`` object. This object has no methods and is
:term:`immortal`.

.. versionchanged:: 3.12
Expand Down
34 changes: 17 additions & 17 deletions Doc/c-api/buffer.rst
Original file line number Diff line number Diff line change
Expand Up @@ -16,18 +16,18 @@ Buffer Protocol


Certain objects available in Python wrap access to an underlying memory
array or *buffer*. Such objects include the built-in :class:`bytes` and
array or *buffer*. Such objects include the built-in :class:`bytes` and
:class:`bytearray`, and some extension types like :class:`array.array`.
Third-party libraries may define their own types for special purposes, such
as image processing or numeric analysis.

While each of these types have their own semantics, they share the common
characteristic of being backed by a possibly large memory buffer. It is
characteristic of being backed by a possibly large memory buffer. It is
then desirable, in some situations, to access that buffer directly and
without intermediate copying.

Python provides such a facility at the C and Python level in the form of the
:ref:`buffer protocol <bufferobjects>`. This protocol has two sides:
:ref:`buffer protocol <bufferobjects>`. This protocol has two sides:

.. index:: single: PyBufferProcs (C type)

Expand All @@ -41,15 +41,15 @@ Python provides such a facility at the C and Python level in the form of the
Python see :class:`memoryview`.

Simple objects such as :class:`bytes` and :class:`bytearray` expose their
underlying buffer in byte-oriented form. Other forms are possible; for example,
underlying buffer in byte-oriented form. Other forms are possible; for example,
the elements exposed by an :class:`array.array` can be multi-byte values.

An example consumer of the buffer interface is the :meth:`~io.BufferedIOBase.write`
method of file objects: any object that can export a series of bytes through
the buffer interface can be written to a file. While :meth:`!write` only
the buffer interface can be written to a file. While :meth:`!write` only
needs read-only access to the internal contents of the object passed to it,
other methods such as :meth:`~io.BufferedIOBase.readinto` need write access
to the contents of their argument. The buffer interface allows objects to
to the contents of their argument. The buffer interface allows objects to
selectively allow or reject exporting of read-write and read-only buffers.

There are two ways for a consumer of the buffer interface to acquire a buffer
Expand All @@ -61,7 +61,7 @@ over a target object:
``y*``, ``w*`` or ``s*`` :ref:`format codes <arg-parsing>`.

In both cases, :c:func:`PyBuffer_Release` must be called when the buffer
isn't needed anymore. Failure to do so could lead to various issues such as
isn't needed anymore. Failure to do so could lead to various issues such as
resource leaks.

.. versionadded:: 3.12
Expand All @@ -75,17 +75,17 @@ Buffer structure
================

Buffer structures (or simply "buffers") are useful as a way to expose the
binary data from another object to the Python programmer. They can also be
used as a zero-copy slicing mechanism. Using their ability to reference a
binary data from another object to the Python programmer. They can also be
used as a zero-copy slicing mechanism. Using their ability to reference a
block of memory, it is possible to expose any data to the Python programmer
quite easily. The memory could be a large, constant array in a C extension,
quite easily. The memory could be a large, constant array in a C extension,
it could be a raw block of memory for manipulation before passing to an
operating system library, or it could be used to pass around structured data
in its native, in-memory format.

Contrary to most data types exposed by the Python interpreter, buffers
are not :c:type:`PyObject` pointers but rather simple C structures. This
allows them to be created and copied very simply. When a generic wrapper
are not :c:type:`PyObject` pointers but rather simple C structures. This
allows them to be created and copied very simply. When a generic wrapper
around a buffer is needed, a :ref:`memoryview <memoryview-objects>` object
can be created.

Expand Down Expand Up @@ -142,7 +142,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.

Important exception: If a consumer requests a buffer without the
:c:macro:`PyBUF_FORMAT` flag, :c:member:`~Py_buffer.format` will
be set to ``NULL``, but :c:member:`~Py_buffer.itemsize` still has
be set to ``NULL``, but :c:member:`~Py_buffer.itemsize` still has
the value for the original format.

If :c:member:`~Py_buffer.shape` is present, the equality
Expand Down Expand Up @@ -446,14 +446,14 @@ Buffer-related functions

.. c:function:: int PyObject_CheckBuffer(PyObject *obj)

Return ``1`` if *obj* supports the buffer interface otherwise ``0``. When ``1`` is
Return ``1`` if *obj* supports the buffer interface otherwise ``0``. When ``1`` is
returned, it doesn't guarantee that :c:func:`PyObject_GetBuffer` will
succeed. This function always succeeds.
succeed. This function always succeeds.


.. c:function:: int PyObject_GetBuffer(PyObject *exporter, Py_buffer *view, int flags)

Send a request to *exporter* to fill in *view* as specified by *flags*.
Send a request to *exporter* to fill in *view* as specified by *flags*.
If the exporter cannot provide a buffer of the exact type, it MUST raise
:exc:`BufferError`, set ``view->obj`` to ``NULL`` and
return ``-1``.
Expand Down Expand Up @@ -492,7 +492,7 @@ Buffer-related functions

Return ``1`` if the memory defined by the *view* is C-style (*order* is
``'C'``) or Fortran-style (*order* is ``'F'``) :term:`contiguous` or either one
(*order* is ``'A'``). Return ``0`` otherwise. This function always succeeds.
(*order* is ``'A'``). Return ``0`` otherwise. This function always succeeds.


.. c:function:: void* PyBuffer_GetPointer(const Py_buffer *view, const Py_ssize_t *indices)
Expand Down
6 changes: 3 additions & 3 deletions Doc/c-api/bytearray.rst
Original file line number Diff line number Diff line change
Expand Up @@ -25,13 +25,13 @@ Type check macros
.. c:function:: int PyByteArray_Check(PyObject *o)

Return true if the object *o* is a bytearray object or an instance of a
subtype of the bytearray type. This function always succeeds.
subtype of the bytearray type. This function always succeeds.


.. c:function:: int PyByteArray_CheckExact(PyObject *o)

Return true if the object *o* is a bytearray object, but not an instance of a
subtype of the bytearray type. This function always succeeds.
subtype of the bytearray type. This function always succeeds.


Direct API functions
Expand Down Expand Up @@ -67,7 +67,7 @@ Direct API functions
.. c:function:: char* PyByteArray_AsString(PyObject *bytearray)

Return the contents of *bytearray* as a char array after checking for a
``NULL`` pointer. The returned array always has an extra
``NULL`` pointer. The returned array always has an extra
null byte appended.


Expand Down
34 changes: 17 additions & 17 deletions Doc/c-api/bytes.rst
Original file line number Diff line number Diff line change
Expand Up @@ -25,36 +25,36 @@ called with a non-bytes parameter.
.. c:function:: int PyBytes_Check(PyObject *o)

Return true if the object *o* is a bytes object or an instance of a subtype
of the bytes type. This function always succeeds.
of the bytes type. This function always succeeds.


.. c:function:: int PyBytes_CheckExact(PyObject *o)

Return true if the object *o* is a bytes object, but not an instance of a
subtype of the bytes type. This function always succeeds.
subtype of the bytes type. This function always succeeds.


.. c:function:: PyObject* PyBytes_FromString(const char *v)

Return a new bytes object with a copy of the string *v* as value on success,
and ``NULL`` on failure. The parameter *v* must not be ``NULL``; it will not be
and ``NULL`` on failure. The parameter *v* must not be ``NULL``; it will not be
checked.


.. c:function:: PyObject* PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)

Return a new bytes object with a copy of the string *v* as value and length
*len* on success, and ``NULL`` on failure. If *v* is ``NULL``, the contents of
*len* on success, and ``NULL`` on failure. If *v* is ``NULL``, the contents of
the bytes object are uninitialized.


.. c:function:: PyObject* PyBytes_FromFormat(const char *format, ...)

Take a C :c:func:`printf`\ -style *format* string and a variable number of
arguments, calculate the size of the resulting Python bytes object and return
a bytes object with the values formatted into it. The variable arguments
a bytes object with the values formatted into it. The variable arguments
must be C types and must correspond exactly to the format characters in the
*format* string. The following format characters are allowed:
*format* string. The following format characters are allowed:

.. % XXX: This should be exactly the same as the table in PyErr_Format.
.. % One should just refer to the other.
Expand Down Expand Up @@ -136,12 +136,12 @@ called with a non-bytes parameter.

.. c:function:: char* PyBytes_AsString(PyObject *o)

Return a pointer to the contents of *o*. The pointer
Return a pointer to the contents of *o*. The pointer
refers to the internal buffer of *o*, which consists of ``len(o) + 1``
bytes. The last byte in the buffer is always null, regardless of
whether there are any other null bytes. The data must not be
bytes. The last byte in the buffer is always null, regardless of
whether there are any other null bytes. The data must not be
modified in any way, unless the object was just created using
``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If
``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If
*o* is not a bytes object at all, :c:func:`PyBytes_AsString` returns ``NULL``
and raises :exc:`TypeError`.

Expand All @@ -162,9 +162,9 @@ called with a non-bytes parameter.
if it does, the function returns ``-1`` and a :exc:`ValueError` is raised.

The buffer refers to an internal buffer of *obj*, which includes an
additional null byte at the end (not counted in *length*). The data
additional null byte at the end (not counted in *length*). The data
must not be modified in any way, unless the object was just created using
``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If
``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If
*obj* is not a bytes object at all, :c:func:`PyBytes_AsStringAndSize`
returns ``-1`` and raises :exc:`TypeError`.

Expand All @@ -176,16 +176,16 @@ called with a non-bytes parameter.
.. c:function:: void PyBytes_Concat(PyObject **bytes, PyObject *newpart)

Create a new bytes object in *\*bytes* containing the contents of *newpart*
appended to *bytes*; the caller will own the new reference. The reference to
the old value of *bytes* will be stolen. If the new object cannot be
appended to *bytes*; the caller will own the new reference. The reference to
the old value of *bytes* will be stolen. If the new object cannot be
created, the old reference to *bytes* will still be discarded and the value
of *\*bytes* will be set to ``NULL``; the appropriate exception will be set.


.. c:function:: void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)

Create a new bytes object in *\*bytes* containing the contents of *newpart*
appended to *bytes*. This version releases the :term:`strong reference`
appended to *bytes*. This version releases the :term:`strong reference`
to *newpart* (i.e. decrements its reference count).


Expand Down Expand Up @@ -214,8 +214,8 @@ called with a non-bytes parameter.
one, only more efficiently.
Pass the address of an
existing bytes object as an lvalue (it may be written into), and the new size
desired. On success, *\*bytes* holds the resized bytes object and ``0`` is
returned; the address in *\*bytes* may differ from its input value. If the
desired. On success, *\*bytes* holds the resized bytes object and ``0`` is
returned; the address in *\*bytes* may differ from its input value. If the
reallocation fails, the original bytes object at *\*bytes* is deallocated,
*\*bytes* is set to ``NULL``, :exc:`MemoryError` is set, and ``-1`` is
returned.
Loading
Loading
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy