Skip to content

gh-101100: Fix sphinx warnings in Doc/c-api/memoryview.rst #114669

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

Merged
merged 1 commit into from
Jan 29, 2024

Conversation

sobolevn
Copy link
Member

@sobolevn sobolevn commented Jan 28, 2024

It used to be:

/Users/sobolev/Desktop/cpython2/Doc/c-api/memoryview.rst:25: WARNING: c:macro reference target not found: PyBUF_READ
/Users/sobolev/Desktop/cpython2/Doc/c-api/memoryview.rst:25: WARNING: c:macro reference target not found: PyBUF_WRITE

I documented these values there, because they are primarily used in memoryview. Grep:

Misc/stable_abi.toml
2336:[const.PyBUF_READ]
2338:[const.PyBUF_WRITE]

Python/import.c
3506:        data = PyMemoryView_FromMemory((char *)info.data, info.size, PyBUF_READ);
3547:        if (PyObject_GetBuffer(dataobj, &buf, PyBUF_READ) != 0) {

Include/pybuffer.h
113:#define PyBUF_WRITEABLE PyBUF_WRITABLE
137:#define PyBUF_READ  0x100
138:#define PyBUF_WRITE 0x200

Objects/memoryobject.c
740:   PyBUF_READ or PyBUF_WRITE. view->format is set to "B" (unsigned bytes).
750:    assert(flags == PyBUF_READ || flags == PyBUF_WRITE);
756:    readonly = (flags == PyBUF_WRITE) ? 0 : 1;
952:   buffertype={PyBUF_READ, PyBUF_WRITE} and order={'C', 'F'ortran, or 'A'ny}.
957:   As usual, if buffertype=PyBUF_WRITE, the exporter's buffer must be writable,
963:   Otherwise, if the buffertype is PyBUF_READ, the memoryview will be
974:    assert(buffertype == PyBUF_READ || buffertype == PyBUF_WRITE);
982:    if (buffertype == PyBUF_WRITE && view->readonly) {
992:    if (buffertype == PyBUF_WRITE) {
2095:    x->mview = PyMemoryView_FromMemory(x->item, itemsize, PyBUF_WRITE);

Lib/test/test_buffer.py
888:                    contig = get_contiguous(result, PyBUF_READ, order)
1278:        self.assertRaises(TypeError, get_contiguous, nd, PyBUF_READ, 961)
1279:        self.assertRaises(UnicodeEncodeError, get_contiguous, nd, PyBUF_READ,
1281:        self.assertRaises(ValueError, get_contiguous, nd, PyBUF_READ, 'Z')
2487:        self.assertRaises(ValueError, get_contiguous, nd, PyBUF_READ, 'C')
2488:        self.assertRaises(ValueError, get_contiguous, nd, PyBUF_READ, 'F')
2489:        self.assertRaises(ValueError, get_contiguous, nd[::-1], PyBUF_READ, 'C')
3981:        self.assertRaises(TypeError, get_contiguous, {}, PyBUF_READ, 'F')
3984:        self.assertRaises(BufferError, get_contiguous, b'x', PyBUF_WRITE, 'C')
3988:        self.assertRaises(BufferError, get_contiguous, nd, PyBUF_WRITE, 'A')
3993:            m = get_contiguous(nd, PyBUF_READ, order)
4000:            m = get_contiguous(nd, PyBUF_READ, order)
4007:            m = get_contiguous(nd, PyBUF_WRITE, order)
4018:            m = get_contiguous(nd, PyBUF_READ, order)
4026:            m = get_contiguous(nd, PyBUF_READ, order)
4032:            m = get_contiguous(nd, PyBUF_WRITE, order)
4038:            m = get_contiguous(nd, PyBUF_WRITE, order)
4045:            m = get_contiguous(nd, PyBUF_READ, order)
4054:            m = get_contiguous(nd, PyBUF_READ, order)
4064:            m = get_contiguous(nd, PyBUF_WRITE, order)
4067:        self.assertRaises(BufferError, get_contiguous, nd, PyBUF_WRITE, 'F')
4068:        m = get_contiguous(nd, PyBUF_READ, order)
4074:            m = get_contiguous(nd, PyBUF_WRITE, order)
4077:        self.assertRaises(BufferError, get_contiguous, nd, PyBUF_WRITE, 'C')
4078:        m = get_contiguous(nd, PyBUF_READ, order)
4084:            self.assertRaises(BufferError, get_contiguous, nd, PyBUF_WRITE,
4086:            m = get_contiguous(nd, PyBUF_READ, order)
4091:        m = get_contiguous(nd, PyBUF_READ, 'C')

Modules/_pickle.c
1403:    PyObject *buf_obj = PyMemoryView_FromMemory(buf, n, PyBUF_WRITE);

Modules/_testbuffer.c
413:    mview = PyMemoryView_FromMemory(ptr, itemsize, PyBUF_WRITE);
582:    mview = PyMemoryView_FromMemory(ptr, itemsize, PyBUF_READ);
711:    mview = PyMemoryView_FromMemory(item, base->itemsize, PyBUF_WRITE);
2399:            "buffertype must be PyBUF_READ or PyBUF_WRITE");
2407:    if (type != PyBUF_READ && type != PyBUF_WRITE) {
2878:    PyModule_AddIntMacro(m, PyBUF_READ);
2879:    PyModule_AddIntMacro(m, PyBUF_WRITE);

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

Copy link
Member

@serhiy-storchaka serhiy-storchaka left a comment

Choose a reason for hiding this comment

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

LGTM. Agree that it is the right place. It is unfortunate that these constants share a suffix with other PyBUF_* constants.

@serhiy-storchaka
Copy link
Member

I have a suspicion that the use of PyBUF_READ in PyObject_GetBuffer(dataobj, &buf, PyBUF_READ) is incorrect.

@miss-islington-app
Copy link

Thanks @sobolevn for the PR, and @serhiy-storchaka for merging it 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12.
🐍🍒⛏🤖

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jan 29, 2024
…ythonGH-114669)

(cherry picked from commit 97fb248)

Co-authored-by: Nikita Sobolev <mail@sobolevn.me>
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jan 29, 2024
…ythonGH-114669)

(cherry picked from commit 97fb248)

Co-authored-by: Nikita Sobolev <mail@sobolevn.me>
@bedevere-app
Copy link

bedevere-app bot commented Jan 29, 2024

GH-114704 is a backport of this pull request to the 3.12 branch.

@bedevere-app bedevere-app bot removed the needs backport to 3.12 only security fixes label Jan 29, 2024
@bedevere-app
Copy link

bedevere-app bot commented Jan 29, 2024

GH-114705 is a backport of this pull request to the 3.11 branch.

@bedevere-app bedevere-app bot removed the needs backport to 3.11 only security fixes label Jan 29, 2024
serhiy-storchaka pushed a commit that referenced this pull request Jan 29, 2024
…H-114669) (GH-114704)

(cherry picked from commit 97fb248)

Co-authored-by: Nikita Sobolev <mail@sobolevn.me>
serhiy-storchaka pushed a commit that referenced this pull request Jan 29, 2024
…H-114669) (GH-114705)

(cherry picked from commit 97fb248)

Co-authored-by: Nikita Sobolev <mail@sobolevn.me>
aisk pushed a commit to aisk/cpython that referenced this pull request Feb 11, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir skip news
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants