General Conventions#

There are many ways to contribute to Sage, including sharing scripts and Jupyter notebooks that implement new functionality using Sage, improving to the Sage library, or to working on the many underlying libraries distributed with Sage, see Packages and Features. This guide focuses on editing the Sage library itself.

Sage is not just about gathering together functionality. It is about providing a clear, systematic and consistent way to access a large number of algorithms, in a coherent framework that makes sense mathematically. In the design of Sage, the semantics of objects, the definitions, etc., are informed by how the corresponding objects are used in everyday mathematics.

To meet the goal of making Sage easy to read, maintain, and improve, all Python/Cython code that is included with Sage should adhere to the style conventions discussed in this chapter.

Python code style#

Follow the standard Python formatting rules when writing code for Sage, as explained at the following URLs:

In particular,

Use 4 spaces for indentation levels. Do not use tabs as they can result in indentation confusion. Most editors have a feature that will insert 4 spaces when the Tab key is hit. Also, many editors will automatically search/replace leading tabs with 4 spaces.
Whitespace before and after assignment and binary operator of the lowest priority in the expression:
```
i = i + 1
c = (a+b) * (a-b)
```
No whitespace before or after the = sign if it is used for keyword arguments:
```
def complex(real, imag=0.0):
    return magic(r=real, i=imag)
```
No whitespace immediately inside parenthesis, brackets, and braces:
```
spam(ham[1], {eggs: 2})
[i^2 for i in range(3)]
```
Use all lowercase function names with words separated by underscores. For example, you are encouraged to write Python functions using the naming convention:
```
def set_some_value():
    return 1
```
Note, however, that some functions do have uppercase letters where it makes sense. For instance, the function for lattice reduction by the LLL algorithm is called Matrix_integer_dense.LLL.

Use CamelCase for class names:

class SomeValue():
    def __init__(self, x):
    self._x  = 1

and factory functions that mimic object constructors, for example PolynomialRing or:

def SomeIdentityValue(x):
    return SomeValue(1)

Files and directory structure#

Roughly, the Sage directory tree is laid out like this. Note that we use SAGE_ROOT in the following as a shortcut for the name of the directory containing the Sage sources:

SAGE_ROOT/
    sage          # the Sage launcher
    Makefile      # top level Makefile
    build/        # Sage's build system
        pkgs/     # install, patch, and metadata from spkgs
    src/
        setup.py
        ...
        sage/            # Sage library
            ext_data/    # extra Sage resources (legacy)
        bin/             # the scripts in local/bin that are tracked
    upstream/            # tarballs of upstream sources
    local/               # installed binaries

Python Sage library code goes into src/sage/ 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 file polynomial_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.

If you want to create a new directory (package) in the Sage library SAGE_ROOT/src/sage (say, measure_theory), that directory will usually contain an empty file __init__.py, which marks the directory as an ordinary package (see Ordinary packages vs. implicit namespace packages), and also a file all.py, listing imports from this package that are user-facing and important enough to be in the global namespace of Sage at startup. The file all.py might look like this:

from .borel_measure import BorelMeasure
from .banach_tarski import BanachTarskiParadox

but it is generally better to use the lazy_import framework:

from sage.misc.lazy_import import lazy_import
lazy_import('sage.measure_theory.borel_measure', 'BorelMeasure')
lazy_import('sage.measure_theory.banach_tarski', 'BanachTarskiParadox')

Then in the file SAGE_ROOT/src/sage/all.py, add a line

from sage.measure_theory.all import *

Adding new top-level packages below sage should be done sparingly. It is often better to create subpackages of existing packages.

Non-Python Sage source code and small supporting files can be included in one of the following places:

In the directory of the Python code that uses that file. When the Sage library is installed, the file will be installed in the same location as the Python code. This is referred to as “package data”.

The preferred way to access the data from Python is using the importlib.resources API, in particular the function importlib.resources.files(). Using it, you can:
- open a resource for text reading: fd = files(package).joinpath(resource).open('rt')
- open a resource for binary reading: fd = files(package).joinpath(resource).open('rb')
- read a resource as text: text = files(package).joinpath(resource).read_text()
- read a resource as bytes: bytes = files(package).joinpath(resource).read_bytes()
- open an xz-compressed resource for text reading: fd = lzma.open(files(package).joinpath(resource).open('rb'), 'rt')
- open an xz-compressed resource for binary reading: fd = lzma.open(files(package).joinpath(resource).open('rb'), 'rb')
If the file needs to be used outside of Python, then the preferred way is using the context manager importlib.resources.as_file(). It should be imported in the same way as shown above.
Older code in the Sage library accesses the package data in more direct ways. For example, SAGE_ROOT/src/sage/interfaces/maxima.py uses the file SAGE_ROOT/src/sage/interfaces/maxima.lisp at runtime, so it refers to it as:
```
os.path.join(os.path.dirname(__file__), 'sage-maxima.lisp')
```
In an appropriate subdirectory of SAGE_ROOT/src/sage/ext_data/. (At runtime, it is then available in the directory indicated by SAGE_EXTCODE). For example, if file is placed in SAGE_ROOT/src/sage/ext_data/directory/ it can be accessed with
```
from sage.env import SAGE_EXTCODE
file = os.path.join(SAGE_EXTCODE, 'directory', 'file')
```
This practice is deprecated, see Issue #33037.

In all cases, the files must be listed (explicitly or via wildcards) in the section options.package_data of the file SAGE_ROOT/pkgs/sagemath-standard/setup.cfg.m4 (or the corresponding file of another distribution).

Large data files should not be added to the Sage source tree. Instead, it is proposed to do the following:

create a separate git repository and upload them there [2],
add metadata to the repository that make it a pip-installable package (distribution package), as explained for example in the Python Packaging User Guide,
upload it to PyPI,
create metadata in SAGE_ROOT/build/pkgs that make your new pip-installable package known to Sage; see Packaging Third-Party Code for Sage.

For guiding examples of external repositories that host large data files, see https://github.com/sagemath/conway-polynomials, and https://github.com/gmou3/matroid-database.

Learn by copy/paste#

For all of the conventions discussed here, you can find many examples in the Sage library. Browsing through the code is helpful, but so is searching: the functions search_src, search_def, and search_doc are worth knowing about. Briefly, from the “sage:” prompt, search_src(string) searches Sage library code for the string string. The command search_def(string) does a similar search, but restricted to function definitions, while search_doc(string) searches the Sage documentation. See their docstrings for more information and more options.

Headings of Sage library code files#

The top of each Sage code file should follow this format:

r"""
<Short one-line summary that ends with no period>

<Paragraph description>

EXAMPLES::

<Lots and lots of examples>

AUTHORS:

- Your Name (2024-01-13): initial version
- Alice Liddell (2024-05-31): added a method; cleaned docstrings
- Full name (YYYY-MM-DD): short description

"""

# ****************************************************************************
#       Copyright (C) 2024 Your Name <your email>
#
# 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 2 of the License, or
# (at your option) any later version.
#                  https://www.gnu.org/licenses/
# ****************************************************************************

As an example, see SAGE_ROOT/src/sage/rings/integer.pyx, which contains the implementation for \(\ZZ\). The names of the people who made major contributions to the file appear in the AUTHORS section. You can add your name to the list if you belong to the people, but refrain from being verbose in the description. The AUTHORS section shows very rough overview of the history, especially if a lot of people have been working on that source file. The authoritative log for who wrote what is always the git repository (see the output of git blame).

All code included with Sage must be licensed under the GPLv2+ or a compatible, that is, less restrictive license (e.g. the BSD license).

Running automated doctests#

This section describes Sage’s automated testing of test files of the following types: .py, .pyx, .sage, .rst. Briefly, use sage -t <file> to test that the examples in <file> behave exactly as claimed. See the following subsections for more details. See also Documentation strings for a discussion on how to include examples in documentation strings and what conventions to follow. The chapter Running Sage’s Doctests contains a tutorial on doctesting modules in the Sage library.

Testing .py, .pyx and .sage files#

Run sage -t <filename.py> to test all code examples in filename.py. Similar remarks apply to .sage and .pyx files:

$ sage -t [--verbose] [--optional]  [files and directories ... ]

The Sage doctesting framework is based on the standard Python doctest module, but with many additional features (such as parallel testing, timeouts, optional tests). The Sage doctester recognizes sage: prompts as well as >>> prompts. It also preparses the doctests, just like in interactive Sage sessions.

Your file passes the tests if the code in it will run when entered at the sage: prompt with no extra imports. Thus users are guaranteed to be able to exactly copy code out of the examples you write for the documentation and have them work.

For more information, see Running Sage’s Doctests.

Testing reST documentation#

Run sage -t <filename.rst> to test the examples in verbatim environments in reST documentation.

Of course in reST files, one often inserts explanatory texts between different verbatim environments. To link together verbatim environments, use the .. link comment. For example:

EXAMPLES::

        sage: a = 1

Next we add 1 to ``a``.

.. link::

        sage: 1 + a
        2

If you want to link all the verbatim environments together, you can put .. linkall anywhere in the file, on a line by itself. (For clarity, it might be best to put it near the top of the file.) Then sage -t will act as if there were a .. link before each verbatim environment. The file SAGE_ROOT/src/doc/en/tutorial/interfaces.rst contains a .. linkall directive, for example.

You can also put .. skip right before a verbatim environment to have that example skipped when testing the file. This goes in the same place as the .. link in the previous example.

See the files in SAGE_ROOT/src/doc/en/tutorial/ for many examples of how to include automated testing in reST documentation for Sage.

General coding style regarding whitespace#

Use spaces instead of tabs for indentation. The only exception is for makefiles, in which tabs have a syntactic meaning different from spaces.

Do not add trailing whitespace.

Sage provides editor configuration for Emacs, using the file .dir-locals.el, to use spaces instead of tabs. Regarding trailing whitespace, see https://www.emacswiki.org/emacs/DeletingWhitespace for various solutions.

If you use another editor, we recommend to configure it so you do not add tabs to files. See Text editors and IDEs for use with Sage.

Global options#

Global options for classes can be defined in Sage using GlobalOptions.

Miscellaneous minor things#

Some decisions are arbitrary, but common conventions make life easier.

Non-ASCII names in identifiers:
- Translate ä and ö to ae and oe, like moebius_function for Möbius function.
- Translate á to a, like lovasz_number for Lovász number.
Common function keyword arguments:

This is a list of some keyword arguments that many functions and methods take. For consistency, you should use the keywords from the list below with the meaning as explained here. Do not use a different keyword with the same meaning (for example, do not use method; use algorithm instead).
- algorithm, a string or None: choose between various implementation or algorithm. Use None as a default that selects a sensible default, which could depend on installed optional packages.
- certificate, a Boolean with False as default: whether the function should return some kind of certificate together with the result. With certificate=True the return value should be a pair \((r, c)\) where \(r\) is the result that would be given with certificate=False and \(c\) is the certificate or None if there is no meaningful certificate.
- proof, a Boolean with True as default: if True, require a mathematically proven computation. If False, a probabilistic algorithm or an algorithm relying to non-proved hypothesis like RH can be used.
- check, a Boolean: do some additional checks to verify the input parameters. This should not otherwise influence the functioning of the code: if code works with check=True, it should also work with check=False.
- coerce, a Boolean: convert the input parameters to a suitable parent. This is typically used in constructors. You can call a method with coerce=False to skip some checks if the parent is known to be correct.
- inplace, a Boolean: whether to modify the object in-place or to return a copy.

General Conventions#

Python code style#

Files and directory structure#

Learn by copy/paste#

Headings of Sage library code files#

Documentation strings#

The docstring of a function: content#

Note about Sphinx directives vs. other blocks#

Sage documentation style#

Sage’s master BIBLIOGRAPHY file#

Template#

Fine points on styles#

Private functions#

LaTeX typesetting#

Writing testable examples#

Special markup to influence doctests#

Running automated doctests#

Testing .py, .pyx and .sage files#

Testing reST documentation#

General coding style regarding whitespace#

Global options#

Miscellaneous minor things#