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.

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

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

Merged
merged 6 commits into from
Feb 19, 2023

Conversation

erlend-aasland
Copy link
Contributor

@erlend-aasland erlend-aasland commented Feb 16, 2023

@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
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

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
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.

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 deleted the fixup-exc-docs branch February 19, 2023 20:22
erlend-aasland added a commit to erlend-aasland/cpython that referenced this pull request Feb 19, 2023
jaraco pushed a commit to jaraco/cpython that referenced this pull request Feb 20, 2023
…1962)

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
carljm added a commit to carljm/cpython that referenced this pull request Feb 20, 2023
* 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
* 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
Labels
docs Documentation in the Doc dir skip news
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants