gh-92788: Add docs for ast.Module, ast.Expression, and others

[sobolevn]

• Issue: No documentation for ast.Module class and others. #92788

[CAM-Gerlach]

Higher-level comments:

• Since this is formally documenting new module classes, IMO it would probably be worth adding a NEWS entry under the Documentation category (and perhaps even a What's New entry?), and perhaps also adding a version-added directive.

  Alternatively, if this is considered fixing a documentation defect to properly document nodes that always were de-facto considered public, and thus doesn't deserve a What's New or NEWS entry, then it might be worth backporting to earlier versions, assuming they also have the same nodes (and if they don't, then an appropriate version-added directive should be added accordingly).

• You should at least briefly but explictly document the parameters to each class constructor (type and value), as my comment does for body and as the other node classes generally do.

• You'll need to add a ast-statements ref target label above the Statements section, i.e.

  .. _ast-statements:
  
  Statements
  ^^^^^^^^^^

[sobolevn]

Wow, what a great feedback! 👍
Thank you! I've applied one of your proposed changes, so you also get a credit for this PR (it was easier for me to fix others in a proper IDE, than here).

Alternatively, if this is considered fixing a documentation defect to properly document nodes that always were de-facto considered public, and thus doesn't deserve a What's New or NEWS entry, then it might be worth backporting to earlier versions, assuming they also have the same nodes

Yeah, I think that this is the case. These nodes are public since day one, they are also supported by python3.6 and earlier (except FunctionType which was added in python3.8)

[CAM-Gerlach]

Wow, great work—thanks @sobolevn ! I've left some additional minor comments as suggestions; otherwise I think this is ready for core dev/subject matter expert review (@isidentical ?)

[CAM-Gerlach]

LGTM now; there's just one remaining top-level comment from the previous review.

Since this is formally documenting stdlib module classes, IMO it would make sense to do one of the following:

• If it's considered to be formally documenting these classes for the first time, and they are not considered public in previous Python versions, then it seems certainly worth adding a NEWS entry under the Documentation category (and perhaps even a What's New entry?), and perhaps also adding a version-added directive.

• Alternatively, if this is considered fixing a documentation defect to properly document nodes that were already de-facto considered public, and thus doesn't deserve a What's New entry or versionchanged, then it would presumably be worth backporting to earlier versions, assuming they also have the same nodes (and if they don't, then an appropriate version-added directive should be added accordingly). It might still be worth a Documentation-category NEWS entry, though.

From a Docs team perspective, I would prefer the second option, barring a strong enough reason, but I'm not the subject matter expert on ast here. @isidentical , what do you think?

[ajoino]

I've been working a lot with the ast module the last weeks (code generation) and this documentation will be helpful.

However, it's still lacking an explanation of how to use the types_ignore field of ast.Module. The new docs suggest to look at ast.parse but I cannot find anything there, and all examples in the docs leave the field as an empty list. It would be nice if, maybe not in this PR, some examples on how to use types_ignore field was added.

[sobolevn]

@ajoino yes, I think this is the ast.parse's job. Because it has the magic switch.

[CAM-Gerlach]

Added an explicit mention to each class description of it's connection with the ast.parse mode, per @isidentical 's suggestions. Also, added cross-references to the relevant section for each in the Top-Level Components page of the Language Reference, for readers interested in the technical details (as found through the discussion above viz. interactive input).

[sobolevn]

@CAM-Gerlach @isidentical done!

[CAM-Gerlach]

LGTM now from my end 👍

[sobolevn]

@pablogsal @lysnikolaou maybe you would have time to take a look? :)
Seems like this PR is highly related to your field.

[miss-islington]

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

[miss-islington]

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

[bedevere-bot]

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

[bedevere-bot]

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