Skip to content

Commit 0e819af

Browse files
author
Release Manager
committed
gh-37311: Add tips for choosing an exception in developer guide <!-- ^^^^^ Please provide a concise, informative and self-explanatory title. Don't put issue numbers in there, do this in the PR body below. For example, instead of "Fixes #1234" use "Introduce new method to calculate 1+1" --> <!-- Describe your changes here in detail --> as discussed in https://groups.google.com/g/sage- devel/c/xzp0sxinCW8/m/RLZ4vGdPAAAJ <!-- Why is this change required? What problem does it solve? --> <!-- If this PR resolves an open issue, please link to it here. For example "Fixes #12345". --> <!-- If your change requires a documentation PR, please link it appropriately. --> ### 📝 Checklist <!-- Put an `x` in all the boxes that apply. --> <!-- If your change requires a documentation PR, please link it appropriately --> <!-- If you're unsure about any of these, don't hesitate to ask. We're here to help! --> <!-- Feel free to remove irrelevant items. --> - [x] The title is concise, informative, and self-explanatory. - [x] The description explains in detail what this PR is about. - [x] I have linked a relevant issue or discussion. - [ ] I have created tests covering the changes. - [ ] I have updated the documentation accordingly. ### ⌛ Dependencies <!-- List all open PRs that this PR logically depends on - #12345: short description why this is a dependency - #34567: ... --> <!-- If you're unsure about any of these, don't hesitate to ask. We're here to help! --> URL: #37311 Reported by: Kwankyu Lee Reviewer(s): grhkm21, Kwankyu Lee, Martin Rubey, Matthias Köppe
2 parents c3e76e1 + e546f92 commit 0e819af

File tree

1 file changed

+33
-5
lines changed

1 file changed

+33
-5
lines changed

src/doc/en/developer/coding_in_python.rst

Lines changed: 33 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ scratch. Try to figure out how your code should fit in with other Sage
6464
code, and design it accordingly.
6565

6666

67-
Special sage functions
67+
Special Sage functions
6868
======================
6969

7070
Functions with leading and trailing double underscores ``__XXX__`` are
@@ -103,8 +103,8 @@ You should implement the ``_latex_`` and ``_repr_`` method for every
103103
object. The other methods depend on the nature of the object.
104104

105105

106-
LaTeX Representation
107-
--------------------
106+
LaTeX representation
107+
====================
108108

109109
Every object ``x`` in Sage should support the command ``latex(x)``, so
110110
that any Sage object can be easily and accurately displayed via
@@ -158,7 +158,7 @@ typeset version of this.
158158

159159

160160
Print representation
161-
--------------------
161+
====================
162162

163163
The standard Python printing method is ``__repr__(self)``. In Sage,
164164
that is for objects that derive from ``SageObject`` (which is
@@ -194,7 +194,7 @@ Here is an example of the ``_latex_`` and ``_repr_`` functions for the
194194
195195
196196
Matrix or vector from object
197-
----------------------------
197+
============================
198198

199199
Provide a ``_matrix_`` method for an object that can be coerced to a
200200
matrix over a ring `R`. Then the Sage function ``matrix`` will work
@@ -473,6 +473,34 @@ example:
473473
Note that the syntax in ``except`` is to list all the exceptions that
474474
are caught as a tuple, followed by an error message.
475475

476+
A method or a function accepts input described in the ``INPUT`` block of
477+
:ref:`the docstring <section-docstring-function>`. If the input cannot be
478+
handled by the code, then it may raise an exception. The following aims to
479+
guide you in choosing from the most relevant exceptions to Sage. Raise
480+
481+
- :class:`TypeError`: if the input belongs to a class of objects that is not
482+
supported by the method. For example, a method works only with monic
483+
polynomials over a finite field, but a polynomial over rationals was given.
484+
485+
- :class:`ValueError`: if the input has a value not supported by the method.
486+
For example, the above method was given a non-monic polynomial.
487+
488+
- :class:`ArithmeticError`: if the method performs an arithmetic operation
489+
(sum, product, quotient, and the like) but the input is not appropriate.
490+
491+
- :class:`ZeroDivisionError`: if the method performs division but the input is
492+
zero. Note that for non-invertible input values, :class:`ArithmeticError` is
493+
more appropriate. As derived from :class:`ArithmeticError`,
494+
:class:`ZeroDivisionError` can be caught as :class:`ArithmeticError`.
495+
496+
- :class:`NotImplementedError`: if the input is for a feature not yet
497+
implemented by the method. Note that this exception is derived from
498+
:class:`RuntimeError`.
499+
500+
If no specific error seems to apply for your situation, :class:`RuntimeError`
501+
can be used. In all cases, the string associated with the exception should
502+
describe the details of what went wrong.
503+
476504

477505
Integer return values
478506
=====================

0 commit comments

Comments
 (0)