gh-141004: Document Py_ARRAY_LENGTH macro #141601

Yashp002 · 2025-11-15T20:28:21Z

This PR adds documentation for the Py_ARRAY_LENGTH macro to the C API documentation, addressing issue #141004.

The documentation is placed in the "Useful macros" section of Doc/c-api/intro.rst and includes:

A description of the macro's purpose (computing array length at compile time)
A warning that it must be used with C arrays, not pointers
An explanation that it's equivalent to sizeof(array) / sizeof((array)[0])

This macro has existed since Python 2.7 but was previously undocumented in the official C API documentation.

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

Issue: Document the entire C API #141004

Added documentation for the Py_ARRAY_LENGTH macro, explaining its usage and requirements.

StanFromIreland · 2025-11-15T20:34:42Z

Our CI does not like it when the branch the PR is opened from is called "main" IIRC and that is why some extra tests are running.

Doc/c-api/intro.rst

Co-authored-by: Stan Ulbrych <[email protected]>

Yashp002 · 2025-11-15T20:41:20Z

Also, is it a generally good practice to break off a branch from the main while working on it myself then?

Doc/c-api/intro.rst

Co-authored-by: Stan Ulbrych <[email protected]>

picnixz · 2025-11-16T10:00:30Z

Doc/c-api/intro.rst

+   compilation error, otherwise, using this macro with a pointer will
+   produce incorrect results.
+
+   This is generally equivalent to::


I don't like the use of "generally" equivalent because it may indicate that it's equivalent to something else. So I would remove the "This is generally equivalent to:: + code"

I disagree, it's helpful to have something rather than nothing, even if it's not 100% true. This is a good example of a lie-to-children.

If you're against "generally", how about saying "this is semantically equivalent to ..."?

"generally" is inaccurate; if you want to lie a bit, you should say "roughly equivalent to" (which is what we do in academia or in itertools btw). "Generally" means that this would always be the case (at least to me when used like that), but the macro expansion is different.

If you want to use "generally" as a synonym of "usually", "roughly" is better.

"semantically equivalent" is too verbose IMO.

"roughly equivalent to" is fine with me.

Removed redundant explanation of array size calculation.

Doc/c-api/intro.rst

Co-authored-by: Bénédikt Tran <[email protected]>

ZeroIntensity

Happy to see a new contributor :)

ZeroIntensity · 2025-11-17T13:57:14Z

Doc/c-api/intro.rst


+.. c:macro:: Py_ARRAY_LENGTH(array)
+
+   Compute the length (number of elements) of a statically allocated C array at


I think it's generally well known that the length is the number of elements.

ZeroIntensity · 2025-11-17T14:00:45Z

Doc/c-api/intro.rst

+   The *array* argument must be a C array with a size known at compile time,
+   not a pointer. On supported compilers, passing a pointer will result in a


All arrays can be represented as a pointer, statically allocated or not. Let's instead say something like "heap-allocated array" instead of "pointer".

Doc/c-api/intro.rst

Co-authored-by: Peter Bierma <[email protected]>

Yashp002 · 2025-11-17T17:39:15Z

Happy to see a new contributor :)

Thanks, I've been hoping to contribute to python since the longest time tbh 😄

ZeroIntensity · 2025-11-19T19:57:57Z

Please address my comments and then I'll merge this.

I realize that VLAs also don't have a known size at compile-time.

ZeroIntensity

LGTM.

vstinner

LGTM

miss-islington-app · 2025-11-24T13:34:41Z

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

(cherry picked from commit e0773ea) Co-authored-by: Yashraj <[email protected]> Co-authored-by: Stan Ulbrych <[email protected]> Co-authored-by: Bénédikt Tran <[email protected]> Co-authored-by: Peter Bierma <[email protected]>

bedevere-app · 2025-11-24T13:34:50Z

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

(cherry picked from commit e0773ea) Co-authored-by: Yashraj <[email protected]> Co-authored-by: Stan Ulbrych <[email protected]> Co-authored-by: Bénédikt Tran <[email protected]> Co-authored-by: Peter Bierma <[email protected]>

bedevere-app · 2025-11-24T13:34:59Z

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

ZeroIntensity · 2025-11-24T13:38:21Z

Congrats on your first contribution @Yashp002 :)

gh-141004: Document `Py_ARRAY_LENGTH` (GH-141601) (cherry picked from commit e0773ea) Co-authored-by: Yashraj <[email protected]> Co-authored-by: Stan Ulbrych <[email protected]> Co-authored-by: Bénédikt Tran <[email protected]> Co-authored-by: Peter Bierma <[email protected]>

Co-authored-by: Stan Ulbrych <[email protected]> Co-authored-by: Bénédikt Tran <[email protected]> Co-authored-by: Peter Bierma <[email protected]>

Document Py_ARRAY_LENGTH macro in intro.rst

7c24a14

Added documentation for the Py_ARRAY_LENGTH macro, explaining its usage and requirements.

bedevere-app bot added awaiting review docs Documentation in the Doc dir skip news labels Nov 15, 2025

github-project-automation bot added this to Docs PRs Nov 15, 2025

github-project-automation bot moved this to Todo in Docs PRs Nov 15, 2025

Merge branch 'main' into main

3813ae8

StanFromIreland changed the title ~~Document Py_ARRAY_LENGTH macro in intro.rst~~ gh-141004: Document Py_ARRAY_LENGTH macro in intro.rst Nov 15, 2025

bedevere-app bot mentioned this pull request Nov 15, 2025

Document the entire C API #141004

Open

StanFromIreland reviewed Nov 15, 2025

View reviewed changes

Doc/c-api/intro.rst Show resolved Hide resolved

Doc/c-api/intro.rst Outdated Show resolved Hide resolved

Yashp002 and others added 3 commits November 16, 2025 02:09

Update Doc/c-api/intro.rst

40acd8f

Co-authored-by: Stan Ulbrych <[email protected]>

Update Doc/c-api/intro.rst

4234c8b

Co-authored-by: Stan Ulbrych <[email protected]>

Update Doc/c-api/intro.rst

8191b69

Co-authored-by: Stan Ulbrych <[email protected]>

StanFromIreland reviewed Nov 16, 2025

View reviewed changes

Doc/c-api/intro.rst Outdated Show resolved Hide resolved

Update Doc/c-api/intro.rst

f3a7fb7

Co-authored-by: Stan Ulbrych <[email protected]>

picnixz reviewed Nov 16, 2025

View reviewed changes

picnixz changed the title ~~gh-141004: Document Py_ARRAY_LENGTH macro in intro.rst~~ gh-141004: Document Py_ARRAY_LENGTH macro Nov 16, 2025

Remove “generally equivalent” phrasing as per review feedback

0301587

Removed redundant explanation of array size calculation.

picnixz reviewed Nov 16, 2025

View reviewed changes

Doc/c-api/intro.rst Outdated Show resolved Hide resolved

Update Doc/c-api/intro.rst

7f64d0b

Co-authored-by: Bénédikt Tran <[email protected]>

ZeroIntensity reviewed Nov 17, 2025

View reviewed changes

Update Doc/c-api/intro.rst

7962258

Co-authored-by: Peter Bierma <[email protected]>

Yashp002 and others added 3 commits November 20, 2025 23:50

Merge branch 'python:main' into main

f27366a

Address my own comments.

8a9fc39

Use better terminology

2aadd23

I realize that VLAs also don't have a known size at compile-time.

ZeroIntensity approved these changes Nov 24, 2025

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting review labels Nov 24, 2025

ZeroIntensity enabled auto-merge (squash) November 24, 2025 13:30

ZeroIntensity added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Nov 24, 2025

vstinner approved these changes Nov 24, 2025

View reviewed changes

ZeroIntensity merged commit e0773ea into python:main Nov 24, 2025
36 checks passed

github-project-automation bot moved this from Todo to Done in Docs PRs Nov 24, 2025

bedevere-app bot removed the awaiting merge label Nov 24, 2025

bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label Nov 24, 2025

bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label Nov 24, 2025


		.. c:macro:: Py_ARRAY_LENGTH(array)

		Compute the length (number of elements) of a statically allocated C array at

		The array argument must be a C array with a size known at compile time,
		not a pointer. On supported compilers, passing a pointer will result in a

Uh oh!

gh-141004: Document Py_ARRAY_LENGTH macro #141601

gh-141004: Document Py_ARRAY_LENGTH macro #141601

Uh oh!

Conversation

Yashp002 commented Nov 15, 2025 • edited by bedevere-app bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

StanFromIreland commented Nov 15, 2025

Uh oh!

Uh oh!

Uh oh!

Yashp002 commented Nov 15, 2025

Uh oh!

Uh oh!

picnixz Nov 16, 2025

Choose a reason for hiding this comment

Uh oh!

ZeroIntensity Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

picnixz Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ZeroIntensity Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ZeroIntensity left a comment

Choose a reason for hiding this comment

Uh oh!

ZeroIntensity Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

ZeroIntensity Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Yashp002 commented Nov 17, 2025

Uh oh!

ZeroIntensity commented Nov 19, 2025

Uh oh!

ZeroIntensity left a comment

Choose a reason for hiding this comment

Uh oh!

vstinner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

miss-islington-app bot commented Nov 24, 2025

Uh oh!

bedevere-app bot commented Nov 24, 2025

Uh oh!

bedevere-app bot commented Nov 24, 2025

Uh oh!

ZeroIntensity commented Nov 24, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Yashp002 commented Nov 15, 2025 •

edited by bedevere-app bot

Loading

picnixz Nov 19, 2025 •

edited

Loading