8000 gh-69011: `ctypes.create_*_buffer` clarify NUL termination character inclusion by StanFromIreland · Pull Request #132858 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

gh-69011: ctypes.create_*_buffer clarify NUL termination character inclusion #132858

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

Jump to bottom
Merged
merged 5 commits into from
May 29, 2025
Merged

gh-69011: ctypes.create_*_buffer clarify NUL termination character inclusion #132858

merged 5 commits into from
May 29, 2025

Conversation

StanFromIreland
Copy link
Member
@StanFromIreland StanFromIreland commented Apr 23, 2025 •
edited
Loading

There was little support for raising errors so a docs note is probably the best thing to do -- atleast for now

📚 Documentation preview 📚: https://cpython-previews--132858.org.readthedocs.build/

@bedevere-app bedevere-app bot added awaiting review docs Documentation in the Doc dir skip news labels Apr 23, 2025
@github-project-automation github-project-automation bot moved this to Todo in Docs PRs Apr 23, 2025
@bedevere-app bedevere-app bot mentioned this pull request Apr 23, 2025
Closed
ZeroIntensity
ZeroIntensity reviewed Apr 24, 2025
View reviewed changes
ZeroIntensity
ZeroIntensity approved these changes Apr 24, 2025
View reviewed changes
Copy link
Member
@ZeroIntensity ZeroIntensity left a comment

Choose a reason for hiding this comment

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

This looks fine. I'll tag @encukou as the current ctypes expert, but be aware he's currently on leave.

@ZeroIntensity ZeroIntensity added the needs backport to 3.13 bugs and security fixes label Apr 24, 2025
@encukou
Copy link
Member
encukou commented Apr 28, 2025 •
edited
Loading

I'd write it like this, to also mention what happens if size is too large:

.. function:: create_string_buffer(init, size=None)
              create_string_buffer(size)

   Create a mutable character buffer. The returned object is a
   ctypes array of :class:`c_char`.

   If *size* is given (and not None), it must be an :cls:`int.
   It specifies the size of the returned array.

   If the *init* argument is given, it must be :cls:`bytes`. It is used
   to initialize the array items. Bytes not initialized this way are
   set to zero (NUL).

   If *size* is not given (or if it is None), the buffer is made one byte
   larger than *init*, effectively adding a NUL termination byte.

   If both arguments are given, *size* must not be less than ``len(init)``.

   .. warning::

      If *size* is equal to ``len(init)``, a NUL terminator is
      not added. Do not treat such a buffer as a C string.

   For example::

      >>> bytes(create_string_buffer(2))
      b'\x00\x00'

      >>> bytes(create_string_buffer(b'ab'))
      b'ab\x00'

      >>> bytes(create_string_buffer(b'ab', 2))
      b'ab'

      >>> bytes(create_string_buffer(b'ab', 4))
      b'ab\x00\x00'

      >>> bytes(create_string_buffer(b'abcdef', 2))
      Traceb
8000
ack (most recent call last):
         ...
      ValueError: byte string too long

@StanFromIreland
Petr's suggestion
23a91c1 
# Conflicts:
#	Doc/library/ctypes.rst
@StanFromIreland
Copy link
Member Author

@encukou I have applied your suggested format.

@serhiy-storchaka serhiy-storchaka added the needs backport to 3.14 bugs and security fixes label May 8, 2025
@StanFromIreland
Copy link
Member Author

@encukou Friendly ping :-)

encukou
encukou reviewed May 17, 2025
View reviewed changes
Copy link
Member
@encukou encukou left a comment

Choose a reason for hiding this comment

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

Oops, I left my comments in the “pending” state. Sorry for the delay!

@StanFromIreland StanFromIreland requested a review from encukou May 18, 2025 07:45
@encukou
Copy link
Member
encukou commented May 29, 2025

Looks great now. Thank you!

@encukou encukou merged commit b783e17 into python:main May 29, 2025
24 checks passed
@github-project-automation github-project-automation bot moved this from Todo to Done in Docs PRs May 29, 2025
@miss-islington-app
Copy link

Thanks @StanFromIreland for the PR, and @encukou for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request May 29, 2025
@StanFromIreland @miss-islington
pythongh-69011: : clarify & deduplicate ctypes.create_*_buffer docs (…
9b10f11 
…pythonGH-132858)

This adds a warning about the possibly-missing NUL terminator, but in a way
that doesn't make it sound like a bug/wart.
(cherry picked from commit b783e17)

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request May 29, 2025
@StanFromIreland @miss-islington
pythongh-69011: : clarify & deduplicate ctypes.create_*_buffer docs (…
778d63b 
…pythonGH-132858)

This adds a warning about the possibly-missing NUL terminator, but in a way
that doesn't make it sound like a bug/wart.
(cherry picked from commit b783e17)

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
@bedevere-app
Copy link
bedevere-app bot commented May 29, 2025

GH-134881 is a backport of this pull request to the 3.14 branch.

@bedevere-app bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label May 29, 2025
@bedevere-app
Copy link
bedevere-app bot commented May 29, 2025

GH-134882 is a backport of this pull request to the 3.13 branch.

@bedevere-app bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label May 29, 2025
@StanFromIreland StanFromIreland deleted the ctypes-note branch May 29, 2025 13:17
encukou pushed a commit that referenced this pull request May 29, 2025
@miss-islington @StanFromIreland
[3.13] gh-69011: : clarify & deduplicate ctypes.create_*_buffer docs (
aebb4ea 
GH-132858) (GH-134882)

This adds a warning about the possibly-missing NUL terminator, but in a way
that doesn't make it sound like a bug/wart.
(cherry picked from commit b783e17)

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
encukou pushed a commit that referenced this pull request May 29, 2025
@miss-islington @StanFromIreland
[3.14] gh-69011: clarify & deduplicate ctypes.create_*_buffer docs (G…
da4f375 
…H-132858) (GH-134881)

This adds a warning about the possibly-missing NUL terminator, but in a way
that doesn't make it sound like a bug/wart.
(cherry picked from commit b783e17)

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ZeroIntensity ZeroIntensity ZeroIntensity approved these changes

@encukou encukou Awaiting requested review from encukou

Assignees
No one assigned
Labels
docs Documentation in the Doc dir skip news topic-ctypes
Projects
Docs PRs
Status: Done
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@StanFromIreland @encukou @ZeroIntensity @serhiy-storchaka
0