gh-141004: Document PyBUF_WRITEABLE

[ZeroIntensity]

• Issue: Document the entire C API #141004

---

📚 Documentation preview 📚: https://cpython-previews--141255.org.readthedocs.build/en/141255/c-api/buffer.html#c.PyBUF_WRITEABLE

[StanFromIreland]

Suggested change

	.. c:macro:: PyBUF_WRITEABLE
	This is a :term:`soft deprecated` alias to :c:macro:`PyBUF_WRITABLE`.
	.. c:namespace:: NULL
	.. c:macro:: PyBUF_WRITEABLE
	This is a :term:`soft deprecated` alias to :c:macro:`PyBUF_WRITABLE`.

I see this was recently done for a different alias, i.e., it is put under what it is aliased to:

cpython/Doc/c-api/long.rst

Lines 196 to 205 in be1c72a

	.. c:namespace:: NULL
	.. c:function:: long PyLong_AS_LONG(PyObject *obj)
	A :term:`soft deprecated` alias.
	Exactly equivalent to the preferred ``PyLong_AsLong``. In particular,
	it can fail with :exc:`OverflowError` or another exception.
	.. deprecated:: 3.14
	The function is soft deprecated.

IMO it also makes sense to add a .. deprecated:: 3.15.

[ZeroIntensity]

I really don't think we should be backporting deprecations. It implies that it's valid to use up until that version, which we don't want people to think.

In general, it's very uncommon to backport deprecations. This is the second time someone has pointed to that as precedent, but I would have disagreed there too.

[StanFromIreland]

I removed it from the suggestion, but why not keep it here and just edit Miss Islington's backports to remove it? I volunteer to do it if you want.

[ZeroIntensity]

We need C API WG approval in order to do a deprecation, and that can take months. I'd like to do deprecations after we've gotten everything documented so we're not blocked by them.

[ZeroIntensity]

Also, what does .. c:namespace:: NULL do? I don't see a difference in the output.

[StanFromIreland]

Also, what does .. c:namespace:: NULL do? I don't see a difference in the output.

It allows for cross referencing as the macro name IIUC, per the docs:

Using NULL ... as the scope will change to global scope.

[ZeroIntensity]

Huh, I don't follow. This should be in the global namespace already. I think that only applies if you're using something like namespace-push, right?

[StanFromIreland]

I simply copied what Petr had done, I've not tested it yet.

[StanFromIreland]

Testing it, it is not in the global namespace, and I need to use :c:macro:`PyBUF_WRITABLE.PyBUF_WRITEABLE` to get a link.

[ZeroIntensity]

Hmm... I just tested it too, using :c:macro:`PyBUF_WRITEABLE` works just fine on my end.

[StanFromIreland]

LGTM, I don't feel strongly about the indentation.

[miss-islington-app]

Thanks @ZeroIntensity for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

[miss-islington-app]

Thanks @ZeroIntensity for the PR 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

[bedevere-app]

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

[bedevere-app]

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