Skip to content

gh-135676: lexical analysis: Improve section on Numeric literals - #134850

Merged
encukou merged 7 commits into
python:mainfrom
encukou:lex-analysis-numbers
Jun 18, 2025
Merged

gh-135676: lexical analysis: Improve section on Numeric literals#134850
encukou merged 7 commits into
python:mainfrom
encukou:lex-analysis-numbers

Conversation

@encukou

@encukouencukou commented May 28, 2025•
edited
Loading

Copy link
Copy Markdown
Member

Each section is expanded, and now progresses from simple cases and examples to more involved ones, ending with the formal grammar.

This uses meta-syntax that I want to add to the introduction in #134443. I'm marking it as draft until that's merged.

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

@encukou
encukou marked this pull request as draft May 28, 2025 15:42
@bedevere-appbedevere-appBot added docs Documentation in the Doc dir skip news labels May 28, 2025
@bedevere-appbedevere-appBot mentioned this pull request May 28, 2025
Open
skirpichev
skirpichev reviewed May 29, 2025
View reviewed changes
Comment threadDoc/reference/lexical_analysis.rst Outdated
Comment on lines +1090 to +1094
Instead, :ref:`complex numbers <typesnumeric>` can be written
as adding the complex number's real part and imaginary part.

.. productionlist:: python-grammar
imagnumber: (`floatnumber` | `digitpart`) ("j" | "J")
For example, the imaginary number 3.1+4\ *i* can be written as adding the
real number 3.1 to the imaginary number 4\ *i*.

@skirpichevskirpichevMay 29, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, but this is a wrong picture.

The CPython has no pure-imaginary numbers and above decomposition is invalid in general. Simple counterexample:

>>> -0.0+0j
0j
>>> complex(-0.0, 0)
(-0+0j)

Previous description was valid: "An imaginary literal yields a complex number with a real part of 0.0."

@AA-TurnerAA-TurnerMay 29, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The key point is this is lexical analysis. Python indeed has no imaginary literals, but the tokeniser does -- 4+16j is three tokens.

@AA-TurnerAA-TurnerMay 29, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think L1093 should say 'the complex number ...', though.

@skirpichevskirpichevMay 29, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, but 16j is not an imaginary number. It's a complex number with a real part +0.0. And complex number in the Python currently can't be "written as adding the complex number's real part and imaginary part."

@encukouencukouMay 30, 2025

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

16j is not an imaginary number; but 16i is :)

I agree that this could be clearer. Will update. (Not sure when, as I recently volunteered to focus on f-strings first.)

@skirpichevskirpichevMay 30, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

16j is not an imaginary number; but 16i is :)

But you are talking not about mathematics, but Python's complex numbers.

@encukouencukouJun 11, 2025

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've reworded the intro for Imaginary literals. Is this clearer?

@encukou
encukou marked this pull request as ready for review June 11, 2025 14:17
@skirpichev
skirpichev self-requested a review June 11, 2025 14:50
skirpichev
skirpichev reviewed Jun 11, 2025
View reviewed changes

@skirpichevskirpichev left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This pr mix

  1. change productlist directive to grammar-snippet, that solves referenced issue
  2. substantial rewrite of sections about literals.

I don't see which issue solves 2). But, maybe it's better to do in a separate pr?

@encukou

encukou commented Jun 12, 2025

Copy link
Copy Markdown
MemberAuthor

This PR is about the rewrite; changing the directives is a minor part of that.

Perhaps I could use more granular issues -- have one for adding the grammar-snippet directive itself, and another for rewriting Lexical analysis, and a different one for the Language Reference. I'm not sure if that would make things clearer, though.

@encukouencukou changed the title gh-127833: lexical analysis: Improve section on Numeric literalsgh-135676: lexical analysis: Improve section on Numeric literalsJun 18, 2025
@bedevere-appbedevere-appBot mentioned this pull request Jun 18, 2025
Open
@encukou

encukou commented Jun 18, 2025

Copy link
Copy Markdown
MemberAuthor

I've opened #135676 for rewording Lexical analysis, and attached this PR to that.

ryan-duve
ryan-duve approved these changes Jun 18, 2025
View reviewed changes

@ryan-duveryan-duve left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed online with @encukou.

@encukou

encukou commented Jun 18, 2025

Copy link
Copy Markdown
MemberAuthor

Merging; please note any follow-ups on the issue :)

@encukou
encukou merged commit 21f3d15 into python:mainJun 18, 2025
@github-project-automationgithub-project-automationBot moved this from Todo to Done in Docs PRsJun 18, 2025
@encukou
encukou deleted the lex-analysis-numbers branch June 18, 2025 14:34
@encukouencukou added the needs backport to 3.14 bugs and security fixes label Jun 18, 2025
@miss-islington-app

miss-islington-appBot commented Jun 18, 2025

Copy link
Copy Markdown

Thanks @encukou for the PR 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jun 18, 2025
@encukou@miss-islington
pythongh-135676: lexical analysis: Improve section on Numeric literals (
c8065a9
pythonGH-134850)
(cherry picked from commit 21f3d15)
Co-authored-by: Petr Viktorin <encukou@gmail.com>
@bedevere-app

bedevere-appBot commented Jun 18, 2025

Copy link
Copy Markdown

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

@bedevere-appbedevere-appBot removed the needs backport to 3.14 bugs and security fixes label Jun 18, 2025
encukou added a commit that referenced this pull request Jun 18, 2025
@miss-islington@encukou
[3.14]gh-135676: lexical analysis: Improve section on Numeric litera…
bb99270
…ls (GH-134850) (GH-135677)
gh-135676: lexical analysis: Improve section on Numeric literals (GH-134850)
(cherry picked from commit 21f3d15)
Co-authored-by: Petr Viktorin <encukou@gmail.com>
lkollar pushed a commit to lkollar/cpython that referenced this pull request Jun 19, 2025
@encukou@lkollar
pythongh-135676: lexical analysis: Improve section on Numeric literals (
bcfb5f7
pythonGH-134850)
StanFromIreland
StanFromIreland reviewed Jul 7, 2025
View reviewed changes
Comment threadDoc/reference/lexical_analysis.rst
Pranjal095 pushed a commit to Pranjal095/cpython that referenced this pull request Jul 12, 2025
@encukou@Pranjal095
pythongh-135676: lexical analysis: Improve section on Numeric literals (
d99a682
pythonGH-134850)
taegyunkim pushed a commit to taegyunkim/cpython that referenced this pull request Aug 4, 2025
@encukou@taegyunkim
pythongh-135676: lexical analysis: Improve section on Numeric literals (
3e0a74a
pythonGH-134850)
Agent-Hellboy pushed a commit to Agent-Hellboy/cpython that referenced this pull request Aug 19, 2025
@encukou@Agent-Hellboy
pythongh-135676: lexical analysis: Improve section on Numeric literals (
02787e9
pythonGH-134850)
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@skirpichevskirpichevskirpichev left review comments
@StanFromIrelandStanFromIrelandStanFromIreland left review comments
@ryan-duveryan-duveryan-duve approved these changes
@willingcwillingcAwaiting requested review from willingcwillingc is a code owner
@AA-TurnerAA-TurnerAwaiting requested review from AA-TurnerAA-Turner is a code owner

Assignees

No one assigned

Labels

docsDocumentation in the Doc dirskip news

Projects

Docs PRs
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@encukou@skirpichev@ryan-duve@AA-Turner@StanFromIreland