Getting oriented
This chapter gets you from a fresh clone to a working change: setting up, finding your way around the code, and the rules the project follows. Those rules are collected here on purpose. They are the same ones enforced by Ruff, Pyright and the tests, and writing them down means you can follow them without remembering them.
Set up
You need Python 3.11 or newer. Alto supports every Python version that has not reached end of life (see the matrix in
.github/workflows/tests.yml), so do not use syntax newer than 3.11.
git clone https://github.com/altosaurus/alto.git
cd alto
python -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pre-commit install
.venv/bin/python -m alto # run the app
.venv/bin/pytest # run every test and every docstring example
On Windows the programs are in .venv\Scripts\ instead of .venv/bin/.
Three things in that list deserve a sentence each.
-e(editable install). Python installs the project as a link to the folder you are working in, not a copy, so edits take effect without reinstalling. It also makesimport altowork from anywhere, which the tests and scripts rely on.pip install -ereadspyproject.toml, which is where the dependencies, the entry point (alto = "alto.__main__:main") and the tool settings live.[dev]is an optional dependency group inpyproject.toml: pytest, coverage, Ruff, Pyright and pre-commit.pre-commit installinstalls two Git hooks: quick checks on every commit, and the full test suite and type check on every push. Nothing reaches the remote with a failing test.
If the program starts but the notation looks odd, see Rendering music notation. The default style, Finale Maestro, and the other SMuFL styles use fonts bundled with the program. Only the “Noto Music” style needs a font from your system.
Running without a screen
All the tests, and the screenshot script, run on Qt’s offscreen platform, which draws into memory. Set
QT_QPA_PLATFORM=offscreen and nothing opens on screen. The test configuration sets it for you. It is how continuous
integration runs the tests on a machine with no display, and it is how you can draw a widget to a PNG in a script.
A tour of the repository
alto/ the program
__main__.py starts the app: python -m alto
audio.py samples, pitch shifting, the piano synthesiser, playback
instrument_info.py facts about each instrument's recordings
settings.py the user's choices as plain objects (no saving)
theory/ notes, intervals, scales, chords
exercises/ Exercise and Question, and the eight exercises
learning/ profiles, SQLite, the scheduler, the statistics
ui/ everything that needs Qt
assets/ fonts, instrument recordings, icons (ship with the package)
tests/ the tests, one file per area
docs/ this website (Jekyll, published to GitHub Pages)
api/ generated API reference (do not edit by hand)
guide/ this guide
scripts/ screenshots.py, api_docs.py, typecheck.sh, check-docs.sh, run-tests.sh
ARCHITECTURE.md a one-page map of how the pieces fit
pyproject.toml dependencies, entry point, pytest, Ruff, Pyright and coverage settings
.pre-commit-config.yaml the checks run on commit and on push
.github/workflows/ continuous integration: tests, Pyright, coverage
alto/ui/ is large because drawing is verbose. The biggest files are settings_panel.py (the sliding settings panes for
every exercise), charts.py, pictures.py (the small illustrations in the settings), staff.py, keyboard.py and
exercise_view.py. You will rarely need to read any of them from top to bottom. Read one class, and use its docstring.
The files to read first
If you read only five files, read these, in this order.
alto/exercises/base.py:Question,Exerciseandregister. Everything revolves around them.alto/exercises/library.py: one real exercise,NoteNames, to see how aQuestionis made.alto/learning/scheduler.py: forty lines of arithmetic that decide what is asked next.alto/learning/learner.py: how a question is chosen and an answer recorded.alto/ui/exercise_view.py:next_question,submitand_record, the loop the user lives in.
Learn the code by running it
Every docstring has an Examples section, and pytest runs it. That makes the docstrings a guided tour you can execute:
.venv/bin/python
>>> from alto.theory.pitch import Note, Interval
>>> Note.parse("C4").transpose(Interval.parse("M3"))
The examples in alto/ui/ create real widgets, because the root conftest.py gives every example a QApplication called
app. Copy one into a script, add widget.show() and app.exec() and you have a window. To draw a widget to a file:
import os
os.environ["QT_QPA_PLATFORM"] = "offscreen"
from PySide6.QtWidgets import QApplication
from alto.ui.staff import StaffWidget
app = QApplication([])
staff = StaffWidget()
staff.resize(400, 200)
staff.grab().save("/tmp/staff.png") # grab() renders the widget into a pixmap
This is the quickest feedback loop for drawing work: change a number, save the picture, look at it.
The rules
These are enforced by tools wherever a tool can do it. Where none can, they are marked.
Layout
- Lines are at most 130 characters. Strings use double quotes.
- Anything with several elements that does not fit on a line (a list, dictionary, tuple, call or signature) goes one element per line with a trailing comma. A trailing comma you write yourself keeps even a short list exploded; that is how you ask for one-per-line. Function definitions with two or more parameters, and calls, collections and tuples with four or more elements, are written one per line. Short calls stay on one line.
- Run the formatter and then the linter, in this order:
ruff format .thenruff check --fix .. The formatter splits long lines, and the linter adds the trailing commas it leaves out. In the other order they fight each other.
Arguments
- Only the first parameter of a function may be positional. The rest are keyword-only (written after a bare
*), and every call names them:Note(3, letter=1), notNote(3, 1). Ruff enforces it (PLR0917). Calls then read as sentences, and adding a parameter later cannot silently change what an existing call means. - Tests that stand in for Qt functions, which Qt calls positionally, may need
# noqa: PLR0917with a reason. Test functions receive pytest fixtures as plain parameters, which is allowed.
Imports
- Absolute only.
from alto.ui.store import store, neverfrom .store import store(TID252). - All at the top of the file. None inside a function (
PLC0415). The>>>lines of a docstring example are the one exception, because an example has to import what it uses. When two modules need each other, do not import one lazily: move the shared thing, or have one register a callback with the other.alto/ui/notation.pyandalto/ui/staff.pydo this withon_redraw. - Sorted like isort, with
altoas its own section after the third-party packages (I). -
Two or more names from one module: one per line, in parentheses, with a trailing comma. Ruff cannot enforce this; it only keeps an import that is already written this way:
from alto.learning.database import ( Database, ItemRecord, Profile, ) - In the two
conftest.pyfiles the imports that come after the environment setup carry# noqa: E402, on the first line of the statement. The setup must run before anything from Alto is imported.
Docstrings and types
- Every module, class, function, method, nested function and test has a NumPy-style docstring. The text starts on the line
after the opening
""". - Describe every parameter with its type, every return and yield, and, with
Raises, every error the function raises. Add anExamplessection that runs as a doctest. Tests are exempt fromExamples.tests/test_docstrings.pychecks all of this for every file, including private and nested functions that Ruff skips. - Every signature is fully annotated, and
Anyis not used: write the real type. Pyright runs in basic mode as if on Python 3.11 (sh scripts/typecheck.sh). - Use a raw docstring (
r""") if it contains a backslash.
No warnings
There must be no warnings from Ruff, Pyright or PyCharm. Where a tool is wrong, silence it narrowly and say why: # pyright:
ignore[ruleName], # noqa: CODE, or # noinspection InspectionName for PyCharm (in a doctest, a line >>> # noinspection
InspectionName covers the next statement). For developers lists the PyCharm settings a
fresh clone needs.
Before you commit
.venv/bin/ruff format .
.venv/bin/ruff check --fix .
sh scripts/typecheck.sh
.venv/bin/pytest
If you changed a docstring or a public signature: python scripts/api_docs.py. If you changed anything visible:
python scripts/screenshots.py and look at the pictures before committing them (fonts render slightly differently on every
machine, so regenerate on the machine you normally use).
Git
- Work on a branch. Open a pull request into
main; CI runs the tests on every supported Python version, Pyright, and coverage. - Commits are yours. Write the message as a short summary line, a blank line, and a paragraph on why.
pre-commitmay change files and stop the commit. Look at the change,git addthe files, and commit again.
What to read next
If you are going to add an exercise, read Building an exercise. If you are about to touch the user interface, read Qt and PySide6 first. It will save you from the traps that are hard to see.
Further reading
- Python Packaging User Guide, packaging.python.org (the Python Packaging Authority):
pyproject.toml, editable installs and virtual environments, from the people who maintain the tools. - Python Software Foundation, The Python Tutorial and The Python Standard Library, docs.python.org.
- Pro Git, Scott Chacon and Ben Straub (Apress, 2014; free at git-scm.com/book): the standard book on Git.
- Brian Okken, Python Testing with pytest, 2nd ed. (Pragmatic Bookshelf, 2022).
- The Ruff documentation, docs.astral.sh/ruff, for what each rule code means. A rule code such as
PLR0917is looked up there. - PEP 8, Style Guide for Python Code, and PEP 257, Docstring Conventions, at peps.python.org.