Sage Developer's Guide - Mirrors

More documents

Recommendations

Info

Sage Developer’s Guide, Release 6.1.1• Use all lowercase function names with words separated by underscores. For example, you are encouraged towrite Python functions using the naming convention:def set_some_value():return 1Note, however, that some functions do have uppercase letters where it makes sense. For instance, the functionfor lattice reduction by the LLL algorithm is called Matrix_integer_dense.LLL.• Use CamelCase for class names:class SomeValue(object):def __init__(self, x):self._x = 1and factory functions that mimic object constructors, for example PolynomialRing or:def SomeIdentityValue(x):return SomeValue(1)4.1.2 Files and Directory StructureRoughly, the Sage directory tree is layout like this. Note that we use SAGE_ROOT in the following as a shortcut forthe (arbitrary) name of the directory containing the Sage sources:SAGE_ROOT/sage# the Sage launcherMakefile # top level Makefilebuild/ # sage’s build systemdepsinstall...pkgs/ # install, patch, and metadata from spkgssrc/setup.pymodule_list.py...sage/ # sage library (formerly devel/sage-main/sage)ext/ # extra sage resources (formerly devel/ext-main)mac-app/ # would no longer have to awkwardly be in extcodebin/ # the scripts in local/bin that are trackedupstream/ # tarballs of upstream sourceslocal/ # installed binariesPython Sage library code goes into src/ and uses the following conventions. Directory names may be plural(e.g. rings) and file names are almost always singular (e.g. polynomial_ring.py). Note that the filepolynomial_ring.py might still contain definitions of several different types of polynomial rings.Note: You are encouraged to include miscellaneous notes, emails, design discussions, etc., in your package.Make these plain text files (with extension .txt) in a subdirectory called notes. For example, seeSAGE_ROOT/src/sage/ext/notes/.If you want to create a new directory in the Sage library SAGE_ROOT/src/sage (say, measure_theory), thatdirectory should contain a file __init__.py that contains the single line import all in addition to whatever filesyou want to add (say, borel_measure.py and banach_tarski.py), and also a file all.py listing importsfrom that directory that are important enough to be in the Sage’s global namespace at startup. The file all.py mightlook like this:20 Chapter 4. Writing Code for Sage
Sage Developer’s Guide, Release 6.1.1from borel_measure import BorelMeasurefrom banach_tarski import BanachTarskiParadoxbut it is generally better to use the lazy import framework:from sage.misc.lazy_import import lazy_importlazy_import(’sage.measure_theory.borel_measue’, ’BorelMeasure’)lazy_import(’sage.measure_theory.banach_tarski’, ’BanachTarskiParadox’)Then in the file SAGE_ROOT/src/sage/all.py, add a linefrom sage.measure_theory.all import *4.1.3 An Example Is Worth a Thousand WordsFor all of the conventions discussed here, you can find many examples in the Sage library. Browsing through thecode is helpful, but so is searching: the functions search_src, search_def, and search_doc are worth knowingabout. Briefly, from the “sage:” prompt, search_src(string) searches Sage library code for the stringstring. The command search_def(string) does a similar search, but restricted to function definitions, whilesearch_doc(string) searches the Sage documentation. See their docstrings for more information and moreoptions.4.1.4 Headings of Sage Library Code FilesThe top of each Sage code file should follow this format:r"""AUTHORS:- YOUR NAME (2005-01-03): initial version- person (date in ISO year-month-day format): short descEXAMPLES::"""#*****************************************************************************# Copyright (C) 2013 YOUR NAME ## This program is free software: you can redistribute it and/or modify# it under the terms of the GNU General Public License as published by# the Free Software Foundation, either version 3 of the License, or# (at your option) any later version.# http://www.gnu.org/licenses/#*****************************************************************************As an example, see SAGE_ROOT/src/sage/rings/integer.pyx which contains the implementation for Z.The AUTHORS: section is redundant, the authoritative log for who wrote what is always the git repository (see theoutput of git blame). Nevertheless, it is sometimes useful to have a very rough overview over the history, especiallyif a lot of people have been working on that source file.4.1. General Conventions 21
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 74 and 75:
Sage Developer’s Guide, Release 6
Page 76 and 77:
Page 78 and 79:
Page 80 and 81:
Page 82 and 83:
Page 84 and 85:
Page 86 and 87:
Page 88 and 89:
Page 90 and 91:
Page 92 and 93:
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

You also want an ePaper? Increase the reach of your titles

Delete template?

Save as template?