Skip to content

gh-101578: Amend PyErr_{Set,Get}RaisedException docs - #101962

Merged
erlend-aasland merged 6 commits into
python:mainfrom
erlend-aasland:fixup-exc-docs
Feb 19, 2023
Merged

gh-101578: Amend PyErr_{Set,Get}RaisedException docs#101962
erlend-aasland merged 6 commits into
python:mainfrom
erlend-aasland:fixup-exc-docs

Conversation

@erlend-aasland

@erlend-aaslanderlend-aasland commented Feb 16, 2023•
edited
Loading

Copy link
Copy Markdown
Contributor

@bedevere-botbedevere-bot mentioned this pull request Feb 16, 2023
Closed
@erlend-aasland

erlend-aasland commented Feb 16, 2023

Copy link
Copy Markdown
ContributorAuthor
  • I removed the duplicate example; it should be sufficient to provide a single example.
  • Use note:: to put emphasis on non-standard reference count semantics in the set function.
  • Mark the getter as returning a borrowed reference.
  • Apply Diátaxis: be succinct and to the point (and hopefully also clearer)

erlend-aasland
erlend-aasland commented Feb 16, 2023
View reviewed changes
Comment threadDoc/c-api/exceptions.rst Outdated
@CAM-GerlachCAM-Gerlach added the docs Documentation in the Doc dir label Feb 17, 2023
CAM-Gerlach
CAM-Gerlach reviewed Feb 17, 2023
View reviewed changes

@CAM-GerlachCAM-Gerlach 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.

Thanks @erlend-aasland ; this is a substantial improvement to the previous docs.

Perhaps its worth fixing the other couple remaining similar docs defects also introduced in PR #101607 , namely in the descriptions of the newly documented functions PyException_GetArgs and PyException_SetArgs (that could use a similar (if much simpler) treatment as here), and the deprecation notices added to PyErr_Fetch, PyErr_Restore and PyErr_NormalizeException not being added to, and particularly duplicating, the .. deprecated directive.

Comment threadDoc/c-api/exceptions.rst Outdated
Comment threadDoc/c-api/exceptions.rst Outdated
Comment threadDoc/c-api/exceptions.rst Outdated
Comment threadDoc/c-api/exceptions.rst Outdated
Comment threadDoc/c-api/exceptions.rst Outdated
@erlend-aasland

erlend-aasland commented Feb 17, 2023

Copy link
Copy Markdown
ContributorAuthor

Thanks @erlend-aasland ; this is a substantial improvement to the previous docs.

Thanks, and thanks for the review!

Perhaps its worth fixing the other couple remaining similar docs defects also introduced in PR #101607 , namely in the descriptions of the newly documented functions PyException_GetArgs and PyException_SetArgs (that could use a similar (if much simpler) treatment as here), and the deprecation notices added to PyErr_Fetch, PyErr_Restore and PyErr_NormalizeException not being added to, and particularly duplicating, the .. deprecated directive.

Definitely; perhaps as a follow-up PR?

@CAM-Gerlach

CAM-Gerlach commented Feb 17, 2023

Copy link
Copy Markdown
Member

Definitely; perhaps as a follow-up PR?

Yeah certainly could be; up to you, of course

CAM-Gerlach
CAM-Gerlach reviewed Feb 17, 2023
View reviewed changes

@CAM-GerlachCAM-Gerlach 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.

A couple followup suggestions

Comment threadDoc/c-api/exceptions.rst Outdated
Comment threadDoc/c-api/exceptions.rst Outdated
Comment threadDoc/c-api/exceptions.rst Outdated
CAM-Gerlach
CAM-Gerlach approved these changes Feb 17, 2023
View reviewed changes

@CAM-GerlachCAM-Gerlach 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.

LGTM from me; thanks @erlend-aasland !

@erlend-aasland

erlend-aasland commented Feb 17, 2023

Copy link
Copy Markdown
ContributorAuthor

Thanks for the review, CAM; highly appreciated. I'll wait for @iritkatriel's or @markshannon's approval before landing.

iritkatriel
iritkatriel reviewed Feb 17, 2023
View reviewed changes
Comment threadDoc/c-api/exceptions.rst Outdated
iritkatriel
iritkatriel reviewed Feb 18, 2023
View reviewed changes
Comment threadDoc/c-api/exceptions.rst Outdated
@erlend-aasland@CAM-Gerlach
Update Doc/c-api/exceptions.rst
fd94dd8
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
@erlend-aasland

erlend-aasland commented Feb 19, 2023

Copy link
Copy Markdown
ContributorAuthor

Thanks for the reviews, Irit and CAM; highly appreciated. I'll create a follow-up PR Any Time Soon™.

@erlend-aasland
erlend-aasland merged commit 60bbed7 into python:mainFeb 19, 2023
@erlend-aasland
erlend-aasland deleted the fixup-exc-docs branch February 19, 2023 20:22
@erlend-aaslanderlend-aasland mentioned this pull request Feb 19, 2023
Merged
erlend-aasland added a commit to erlend-aasland/cpython that referenced this pull request Feb 19, 2023
@erlend-aasland
pythongh-101578: Amend exception docs
3a4a570
Follow-up to pythongh-101962
jaraco pushed a commit to jaraco/cpython that referenced this pull request Feb 20, 2023
@erlend-aasland@CAM-Gerlach@jaraco
pythongh-101578: Amend PyErr_{Set,Get}RaisedException docs (python#10…
a0004e1
…1962)
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
@jaracojaraco mentioned this pull request Feb 20, 2023
Closed
carljm added a commit to carljm/cpython that referenced this pull request Feb 20, 2023
@carljm
Merge branch 'main' into inlinecomp2
9f0fc5b
* main: (60 commits)
pythongh-102056: Fix a few bugs in error handling of exception printing code (python#102078)
pythongh-102011: use sys.exception() instead of sys.exc_info() in docs where possible (python#102012)
pythongh-101566: Sync with zipp 3.14. (pythonGH-102018)
pythonGH-99818: improve the documentation for zipfile.Path and Traversable (pythonGH-101589)
pythongh-88233: zipfile: handle extras after a zip64 extra (pythonGH-96161)
pythongh-101981: Apply HOMEBREW related environment variables (pythongh-102074)
pythongh-101907: Stop using `_Py_OPCODE` and `_Py_OPARG` macros (pythonGH-101912)
pythongh-101819: Adapt _io types to heap types, batch 1 (pythonGH-101949)
pythongh-101981: Build macOS as recommended by the devguide (pythonGH-102070)
pythongh-97786: Fix compiler warnings in pytime.c (python#101826)
pythongh-101578: Amend PyErr_{Set,Get}RaisedException docs (python#101962)
Misc improvements to the float tutorial (pythonGH-102052)
pythongh-85417: Clarify behaviour on branch cuts in cmath module (python#102046)
pythongh-100425: Update tutorial docs related to sum() accuracy (FH-101854)
Add missing 'is' to `cmath.log()` docstring (python#102049)
pythongh-100210: Correct the comment link for unescaping HTML (python#100212)
pythongh-97930: Also include subdirectory in makefile. (python#102030)
pythongh-99735: Use required=True in argparse subparsers example (python#100927)
Fix incorrectly documented attribute in csv docs (python#101250)
pythonGH-84783: Make the slice object hashable (pythonGH-101264)
...
carljm added a commit to carljm/cpython that referenced this pull request Feb 22, 2023
@carljm
Merge branch 'main' into inlinecomp
544b30c
* main: (225 commits)
pythongh-102056: Fix a few bugs in error handling of exception printing code (python#102078)
pythongh-102011: use sys.exception() instead of sys.exc_info() in docs where possible (python#102012)
pythongh-101566: Sync with zipp 3.14. (pythonGH-102018)
pythonGH-99818: improve the documentation for zipfile.Path and Traversable (pythonGH-101589)
pythongh-88233: zipfile: handle extras after a zip64 extra (pythonGH-96161)
pythongh-101981: Apply HOMEBREW related environment variables (pythongh-102074)
pythongh-101907: Stop using `_Py_OPCODE` and `_Py_OPARG` macros (pythonGH-101912)
pythongh-101819: Adapt _io types to heap types, batch 1 (pythonGH-101949)
pythongh-101981: Build macOS as recommended by the devguide (pythonGH-102070)
pythongh-97786: Fix compiler warnings in pytime.c (python#101826)
pythongh-101578: Amend PyErr_{Set,Get}RaisedException docs (python#101962)
Misc improvements to the float tutorial (pythonGH-102052)
pythongh-85417: Clarify behaviour on branch cuts in cmath module (python#102046)
pythongh-100425: Update tutorial docs related to sum() accuracy (FH-101854)
Add missing 'is' to `cmath.log()` docstring (python#102049)
pythongh-100210: Correct the comment link for unescaping HTML (python#100212)
pythongh-97930: Also include subdirectory in makefile. (python#102030)
pythongh-99735: Use required=True in argparse subparsers example (python#100927)
Fix incorrectly documented attribute in csv docs (python#101250)
pythonGH-84783: Make the slice object hashable (pythonGH-101264)
...
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@iritkatrieliritkatrieliritkatriel left review comments
@CAM-GerlachCAM-GerlachCAM-Gerlach approved these changes
@markshannonmarkshannonAwaiting requested review from markshannon

Assignees

No one assigned

Labels

docsDocumentation in the Doc dirskip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@erlend-aasland@CAM-Gerlach@iritkatriel@bedevere-bot