Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Merged
merged 6 commits into from
Feb 19, 2023
Merged

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

merged 6 commits into from
Feb 19, 2023

Conversation

erlend-aasland
Copy link
Contributor

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

@bedevere-bot bedevere-bot mentioned this pull request Feb 16, 2023
Closed
@erlend-aasland
Copy link
Contributor Author

  • 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)

@CAM-Gerlach CAM-Gerlach added the docs Documentation in the Doc dir label Feb 17, 2023
CAM-Gerlach
CAM-Gerlach reviewed Feb 17, 2023
View reviewed changes
Copy link
Member

@CAM-Gerlach CAM-Gerlach left a comment

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.

Doc/c-api/exceptions.rst Outdated Show resolved Hide resolved
Doc/c-api/exceptions.rst Outdated Show resolved Hide resolved
Doc/c-api/exceptions.rst Outdated Show resolved Hide resolved
Doc/c-api/exceptions.rst Outdated Show resolved Hide resolved
Doc/c-api/exceptions.rst Outdated Show resolved Hide resolved
@erlend-aasland
Copy link
Contributor Author

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
Copy link
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
Copy link
Member

@CAM-Gerlach CAM-Gerlach left a comment

Choose a reason for hiding this comment

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

A couple followup suggestions

Doc/c-api/exceptions.rst Outdated Show resolved Hide resolved
Doc/c-api/exceptions.rst Outdated Show resolved Hide resolved
Doc/c-api/exceptions.rst Outdated Show resolved Hide resolved
CAM-Gerlach
CAM-Gerlach approved these changes Feb 17, 2023
View reviewed changes
Copy link
Member

@CAM-Gerlach CAM-Gerlach left a comment

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
Copy link
Contributor Author

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

@erlend-aasland @CAM-Gerlach
Update Doc/c-api/exceptions.rst
fd94dd8 
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
@erlend-aasland
Copy link
Contributor Author

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:main Feb 19, 2023
@erlend-aasland erlend-aasland deleted the fixup-exc-docs branch February 19, 2023 20:22
@erlend-aasland erlend-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>
@jaraco jaraco 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 free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@CAM-Gerlach CAM-Gerlach CAM-Gerlach approved these changes

@iritkatriel iritkatriel iritkatriel left review comments

@markshannon markshannon Awaiting requested review from markshannon

Assignees
No one assigned
Labels
docs Documentation in the Doc dir skip 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