Skip to content

gh-68168: Improve the docs for format units starting with 'e' #19610

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.

Sign up for GitHub

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

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

gh-68168: Improve the docs for format units starting with 'e' #19610

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a56f2ae
bpo-23980: Improve the docs for format units starting with 'e'
ZackerySpytz Apr 19, 2020
d9c3c9b
Merge branch 'main' into bpo-23980-format-units-e-docs
erlend-aasland Jan 5, 2024
107ede9
Fix merge
erlend-aasland Jan 5, 2024
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
8 changes: 4 additions & 4 deletions Doc/c-api/arg.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,7 +163,7 @@ There are three ways strings and buffers can be converted to C:
The buffer may contain embedded null bytes. The caller have to call
:c:func:`PyBuffer_Release` when it is done with the buffer.

``es`` (:class:`str`) [const char \*encoding, char \*\*buffer]
``es`` (:class:`str`) [*encoding*, char \*buffer]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do you remove "const char*" type on encoding: the type is correct, no?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suspect that this is following Martin's comment on the issue.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, but Martin's comment also says:

The text description should explain what encoding is, but it appears it may already do that well enough.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@erlend-aasland: Do you want to address this issue?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, I can take care of that later today.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe the arguments are explained pretty good already:

This format requires two arguments. The first is only used as input, and
must be a :c:expr:const char* which points to the name of an encoding as a
NUL-terminated string, or NULL, in which case 'utf-8' encoding is used.
An exception is raised if the named encoding is not known to Python. The
second argument must be a :c:expr:char**; the value of the pointer it
references will be set to a buffer with the contents of the argument text.
The text will be encoded in the encoding specified by the first argument.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But, I find it strange that the type is removed. Passing a NULL argument to a const char * parameter is perfectly allowed in C.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reading again the OP by Larry, I'm not so sure he meant the data types to be removed: #68168 (comment)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See also the description of the table at the top of arg.rst:

In the following description, the quoted form is the format
unit; the entry in (round) parentheses is the Python object type that matches
the format unit; and the entry in [square] brackets is the type of the C
variable(s) whose address should be passed.

This variant on ``s`` is used for encoding Unicode into a character buffer.
It only works for encoded data without embedded NUL bytes.

Expand All @@ -180,12 +180,12 @@ There are three ways strings and buffers can be converted to C:
allocated storage. The caller is responsible for calling :c:func:`PyMem_Free` to
free the allocated buffer after use.

``et`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char \*encoding, char \*\*buffer]
``et`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [*encoding*, char \*buffer]
Same as ``es`` except that byte string objects are passed through without
recoding them. Instead, the implementation assumes that the byte string object uses
the encoding passed in as parameter.

``es#`` (:class:`str`) [const char \*encoding, char \*\*buffer, :c:type:`Py_ssize_t` \*buffer_length]
``es#`` (:class:`str`) [*encoding*, char \*\*buffer, :c:type:`Py_ssize_t` \*buffer_length]
This variant on ``s#`` is used for encoding Unicode into a character buffer.
Unlike the ``es`` format, this variant allows input data which contains NUL
characters.
Expand Down Expand Up @@ -216,7 +216,7 @@ There are three ways strings and buffers can be converted to C:
In both cases, *\*buffer_length* is set to the length of the encoded data
without the trailing NUL byte.

``et#`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char \*encoding, char \*\*buffer, :c:type:`Py_ssize_t` \*buffer_length]
``et#`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [*encoding*, char \*\*buffer, :c:type:`Py_ssize_t` \*buffer_length]
Same as ``es#`` except that byte string objects are passed through without recoding
them. Instead, the implementation assumes that the byte string object uses the
encoding passed in as parameter.
Expand Down