gh-123858: Improve Doc: SyntaxWarning is emitted during bytecode generation

[bebound]

I'm working on eliminating the SyntaxWarning. It's strange that this error only shows up once. After some research, I found that:

A SyntaxWarning is emitted when the compiler compiles Python sources to bytecode. (Ref: #79031 (comment))

However, this isn't mentioned in the documentation. I noticed other warnings have descriptions like "ignored by default." Adding this information could help reduce confusion.

---

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

• Issue: Improve document for SyntaxWarning #123858

[cpython-cla-bot]

All commit authors signed the Contributor License Agreement.

[bebound]

Could someone please help review this PR? Thank you.

[iritkatriel]

I think this is too strong - we probably don't want to commit to only using this exception type in the compilation process. You can write an application that raises these exceptions if you want.

[bebound]

How about this?
By default, the Python interpreter emits the SyntaxWarning during bytecode compilation.

[iritkatriel]

That's not in the language spec either.

[bebound]

I can't find a suitable word to describe the current behavior.

[iritkatriel]

That's the thing, we don't document "current behaviour". We document what we guarantee will not change without a deprecation process.

The point of your PR is to alert people that compilation errors don't show up when the code is not being compiled. This may be worth mentioning in one of the tutorials (I'm not sure which), but I don't think the SyntaxError documentation is the right place for this.

[bebound]

I understand your concern that this document introduces some unofficially committed behavior for SyntaxWarning. I'm okay with leaving it here and waiting for more comments.

I searched the repository and found the following:

SyntaxWarning are only emitted once, and only when a Python file is parsed: when a cached PYC file is used, not warning is emitted -------#99011 (comment)

The problem is the warnings are only shown once, when the file is compiled.

Things would probably be improved if the warnings were always shown, as at least then devs will see the error once (although most will probably be confused when the warning doesn't repeat). --#77093 (comment)