Repository navigation
Documentation is unclear how "y*" and "y#" format units vary #74810
Description
Activity
indygreg commented
on Jun 10, 2017 indygregmannequinMannequinAuthorindygreg/python-zstandard#26 is a bug report against python-zstandard that a C API using the "y#" format unit is unable to accept a memoryview instance constructed from a bytes literal. It fails with "TypeError: argument 1 must be read-only bytes-like object, not memoryview".
I understand why the "y*" format unit and the buffer protocol are a superior API. In hindsight, I should have used the buffer protocol from the beginning in python-zstandard. However, this decision was primarily influenced because the docs aren't clear about the apparent limitations of "y#" compared to "y*" and I believed "y#" would get me what I wanted (pointer to read-only memory) without having to be burdened by the complexity of the buffer protocol in my C code.
So, docs issue #1 is that the limitations of "y#" compared to "y*" aren't immediately obvious when reading their respective sections in https://docs.python.org/3/c-api/arg.html#strings-and-buffers. To their credit, the docs for "y*" do have a bold recommendation to use it. But what's missing is the critical "why." There is also a paragraph above the format unit list explaining "bytes-like object" but this is detached from the definitions for "y#" and "y*" so it is easy to pass over.
Issue #2 (which may be an implementation bug) is why "y#" isn't accepting a memoryview constructed from bytes. The docs for "y#" say it accepts a "read-only bytes-like object," which is defined at https://docs.python.org/3/glossary.html#term-bytes-like-object. And the paragraphs there explicitly state that a memoryview of an immutable bytes is in fact a "read-only bytes-like object." So I have no clue why "y#" is refusing such an object.
I'll gladly author a documentation fix. However, I'm not sure what to say because I don't understand why "y#" isn't working in this memoryview(bytes) case and whether that issue applies to other types.
- changed the title
[-]Documentation is unclear how "y*" and "y#" formit units vary[/-][+]Documentation is unclear how "y*" and "y#" format units vary[/+]on Jun 11, 2017 skrah commented
on Jun 14, 2017 skrahmannequinMannequinOut of curiosity:
Is the 3.2 documentation clearer?
https://docs.python.org/3.2/c-api/arg.html#strings-and-buffers
Lately we have a lot of churn in the docs, not necessarily written by subject experts.
indygreg commented
on Jun 15, 2017 indygregmannequinMannequinAuthorIMO I don't find the 3.2 docs more useful. Specifically, the behavior for memoryview is still unclear.
skrah commented
on Jun 16, 2017 skrahmannequinMannequinOkay thanks, it's good to hear what others think about the docs.
So I have no clue why "y#" is refusing such an object.
"y#" is refusing memoryview(bytes) because "y#" only allows objects without a releasebufferproc and memoryview itself always has one.
I wonder if we could simply use the cleanup() solution also for "y#", but I have to look closer at this.
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
bugs.python.org fields: