Sage Developer's Guide - Mirrors

More documents

Recommendations

Info

Sage Developer’s Guide, Release 6.1.1To summarize, only catch specific exceptions as in the following example:try:return self.__coordinate_ringexcept (AttributeError, OtherExceptions) as msg:more_code_to_compute_something()# goodNote that the syntax in except is to list all the exceptions that are caught as a tuple, followed by an error message.4.2.8 ImportingWe mention two issues with importing: circular imports and importing large third-party modules.First, you must avoid circular imports. For example, suppose that the fileSAGE_ROOT/src/sage/algebras/steenrod_algebra.py started with a line:from sage.sage.algebras.steenrod_algebra_bases import *and that the file SAGE_ROOT/src/sage/algebras/steenrod_algebra_bases.py started with a line:from sage.sage.algebras.steenrod_algebra import SteenrodAlgebraThis sets up a loop: loading one of these files requires the other, which then requires the first, etc.With this set-up, running Sage will produce an error:Exception exceptions.ImportError: ’cannot import name SteenrodAlgebra’in ’sage.rings.polynomial.polynomial_element.Polynomial_generic_dense.__normalize’ ignored-------------------------------------------------------------------ImportErrorTraceback (most recent call last)...ImportError: cannot import name SteenrodAlgebraInstead, you might replace the import * line at the top of the file by more specific imports where they are neededin the code. For example, the basis method for the class SteenrodAlgebra might look like this (omitting thedocumentation string):def basis(self, n):from steenrod_algebra_bases import steenrod_algebra_basisreturn steenrod_algebra_basis(n, basis=self._basis_name, p=self.prime)Second, do not import at the top level of your module a third-party module that will take a long time to initialize (e.g.matplotlib). As above, you might instead import specific components of the module when they are needed, rather thanat the top level of your file.It is important to try to make from sage.all import * as fast as possible, since this is what dominatesthe Sage startup time, and controlling the top-level imports helps to do this. One important mechanism in Sageare lazy imports, which don’t actually perform the import but delay it until the object is actually used. Seesage.misc.lazy_import for more details of lazy imports, and Files and Directory Structure for an exampleusing lazy imports for a new module.4.2.9 DeprecationSooner or later you will find places in the Sage library that are, in hindsight, not designed as well as they could be. Ofcourse you want to improve the overall state, but at the same time we don’t want to pull out the carpet under our users’feet. The process of removing old code is called deprecation.38 Chapter 4. Writing Code for Sage
Sage Developer’s Guide, Release 6.1.1Note: Before removing any functionality, you should keep a deprecation warning in place for at least one year (ifpossible). The deprecation must include the trac ticket number where it was introduced.For example, let’s say you run across the following while working on a module in the Sage library:class Foo(SageObject):def terrible_idea(self):return 1def bad_name(self):return 1def f(self, weird_keyword=True):return self._f_implementation(weird_keyword=weird_keyword)def _f_implementation(self, weird_keyword=True):return 1You note that the terrible_idea() method does not make any sense, and should be removed altogether. Youopen the trac ticket number 3333 (say), and replace the code with:def terrible_idea(self):from sage.misc.superseded import deprecationdeprecation(3333, ’You can just call f() instead’)return 1Later, you come up with a much better name for the second method. You open the trac ticket number 4444, and replaceit with:def much_better_name(self):return 1bad_name = deprecated_function_alias(4444, much_better_name)Finally, you like the f() method name but you don’t like the weird_keyword name. You fix this by opening thetrac ticket 5555, and replacing it with:@rename_keyword(deprecation=5555, weird_keyword=’nice_keyword’)def f(self, nice_keyword=True):return self._f_implementation(nice_keyword=nice_keyword)def _f_implementation(self, nice_keyword=True):return 1Note that the underscore-method _f_implementation is, by convention, not something that ought to be used byothers. So we do not need to deprecate anything when we change it.Now, any user that still relies on the deprecated functionality will be informed that this is about to change, yet thedeprecated commands still work. With all necessary imports, the final result looks like this:sage: from sage.misc.superseded import deprecation, deprecated_function_aliassage: from sage.misc.decorators import rename_keywordsage: class Foo(SageObject):....:....: def terrible_idea(self):....: deprecation(3333, ’You can just call f() instead’)....: return 1....:....: def much_better_name(self):....: return 1....:4.2. Coding in Python for Sage 39
Page 1: Sage Developer’s GuideRelease 6.1
Page 4 and 5: 7 Indices and tables 129Bibliograph
Page 6 and 7: Sage Developer’s Guide, Release 6
Page 92 and 93:
Sage Developer’s Guide, Release 6
Page 94 and 95:
Page 96 and 97:
Page 98 and 99:
Page 100 and 101:
Page 102 and 103:
Page 104 and 105:
Page 106 and 107:
Page 108 and 109:
Page 110 and 111:
Page 112 and 113:
Page 114 and 115:
Page 116 and 117:
Page 118 and 119:
Page 120 and 121:
Page 122 and 123:
Page 124 and 125:
Page 126 and 127:
Page 128 and 129:
Page 130 and 131:
Page 132 and 133:
Page 134 and 135:
Page 136 and 137:
show all

Sage Developer's Guide - Mirrors

Create successful ePaper yourself

Delete template?

Save as template?