alto.circle_schemes
The colour schemes of the circle of fifths: the presets, and the schemes a user makes.
A scheme says what colour each of the 24 cells of the circle is when it is quiet and when it is lit, and whether its wedges
are light, with dark names. The circle blends between the two as a cell brightens. The disc in the middle is not part of a
scheme: it takes the colours of the app’s theme. Nothing here needs Qt, so the schemes can be tested, saved and shown anywhere;
alto.ui.circle turns them into pictures.
A colour is a hue (0 to 360), a saturation and a lightness (both 0 to 1).
Examples
>>> scheme = preset("cyan-indigo")
>>> scheme.name, scheme.light
('Cyan to indigo', False)
>>> round(scheme.colour("outer", place=0, lift=1.0)[2], 2) > round(scheme.colour("outer", place=0, lift=0.0)[2], 2)
True
CellMaker
class CellMaker(Protocol)
A function that gives the cell at a place on a ring its quiet and lit colours.
CustomRecord
class CustomRecord(TypedDict)
A scheme of the user’s own, as it is saved.
Attributes
id(str): Its key, such as “custom-1”.name(str): What the user called it.mode(str): How its colours are made: a key ofMODES.colours(list of str): The colours the mode takes, as “#rrggbb”: what a cell looks like when it is lit.light(bool): Whether the wedges are light, with dark names.
Scheme
Scheme(
key: str,
name: str,
description: str,
light: bool,
cells: dict[str, tuple[Cell, ...]],
)
A colour scheme for the circle.
Attributes
key(str): Its identifier, used to save the choice.name(str): Its name, as the settings show it.description(str): A sentence about it.light(bool): Whether the wedges are light, with dark names, instead of dark with white names.cells(dict of str to tuple of (tuple of float, tuple of float)): For each ring (“outer” and “inner”), the 12 cells’ quiet and lit colours, clockwise from the top.
Scheme.colour
def colour(
ring: str,
*,
place: int,
lift: float,
) -> tuple[float, float, float]
Return the colour of a cell as it is lit.
Parameters
ring(str): “outer” or “inner”.place(int): The cell’s place, clockwise from the top. Keyword-only.lift(float): How lit it is, from 0 (quiet) to 1 (fully lit). Keyword-only.
Returns
- tuple of float: Its red, green and blue, each from 0 to 1.
Examples
>>> red, green, blue = preset("spectrum").colour("outer", place=0, lift=1.0)
>>> red > green and red > blue
True
>>> preset("spectrum").colour("outer", place=6, lift=0.0)[0] < 0.2
True
Scheme.names
def names() -> dict[str, str]
Return the colours of the names written on the wedges.
Returns
- dict of str to str: “ink” (a key’s name) and “muted” (its other name and its numeral), as “#rrggbb”.
Examples
>>> preset("paper").names()["ink"], preset("spectrum").names()["ink"]
('#1b2030', '#f5f5f5')
rgb_of
def rgb_of(
colour: Hsl,
*,
capped: bool,
) -> tuple[float, float, float]
Turn a colour into red, green and blue, keeping a dark circle’s cells from getting too bright.
Yellows and greens look far brighter than blues of the same lightness, so on dark wedges a colour that is brighter than white names can stand is brought down to the limit.
Parameters
colour(tuple of float): The hue, saturation and lightness.capped(bool): Whether to bring a too bright colour down. Keyword-only.
Returns
- tuple of float: Red, green and blue, each from 0 to 1.
Examples
>>> r, g, b = rgb_of((60.0, 0.9, 0.5), capped=True)
>>> 0.299 * r + 0.587 * g + 0.114 * b <= MAX_BRIGHTNESS + 1e-9
True
>>> rgb_of((0.0, 0.0, 1.0), capped=False)
(1.0, 1.0, 1.0)
hex_of
def hex_of(rgb: tuple[float, float, float]) -> str
Write a colour as “#rrggbb”.
Parameters
rgb(tuple of float): Red, green and blue, each from 0 to 1.
Returns
- str: The colour as hexadecimal.
Examples
>>> hex_of((1.0, 0.5, 0.0))
'#ff8000'
hsl_of
def hsl_of(text: str) -> Hsl
Read a colour written as “#rrggbb”.
Parameters
text(str): The colour.
Returns
- tuple of float: Its hue (0 to 360), saturation and lightness.
Examples
>>> hsl_of("#ff0000")
(0.0, 1.0, 0.5)
signature_of
def signature_of(place: int) -> int
Return how far a place is from C, with flats as negative: the key signature of the major key there.
Parameters
place(int): The place clockwise from the top, 0 to 11.
Returns
- int: From -5 (five flats) to 6 (six sharps).
Examples
>>> [signature_of(at) for at in (0, 1, 6, 7, 11)]
[0, 1, 6, -5, -1]
preset
def preset(key: str) -> Scheme
Return a preset by its key.
Parameters
key(str): A key ofPRESETS.
Returns
- Scheme: The preset.
Raises
- KeyError: If there is no such preset.
Examples
>>> preset("midnight").name
'Midnight'
>>> len(PRESETS)
14
record_of
def record_of(
key: str,
*,
name: str,
mode: str,
colours: list[str],
light: bool = False,
) -> CustomRecord
Make the record of a scheme of the user’s own.
Parameters
key(str): Its key, such as “custom-1”.name(str): Its name. Keyword-only.mode(str): How its colours are made: a key ofMODES. Keyword-only.colours(list of str): The colours the mode takes, as “#rrggbb”. Keyword-only.light(bool, default False): Whether the wedges are light. Keyword-only.
Returns
- CustomRecord: The record. Nothing is checked:
clean_recorddoes that.
Examples
>>> record_of("custom-1", name="Mine", mode="single", colours=["#2f6bd0"])["light"]
False
clean_record
def clean_record(raw: object) -> CustomRecord | None
Check one saved scheme of the user’s own, and tidy it.
Parameters
raw(object): What was read back from the saved data.
Returns
- CustomRecord or None: The record, with a name of at most 40 characters, or None if anything in it is missing or wrong: an unknown mode, a colour that is not “#rrggbb”, or the wrong number of colours for the mode.
Examples
>>> good = record_of("custom-1", name="Mine", mode="rings", colours=["#2f6bd0", "#18a0c0"])
>>> clean_record(good) == good
True
>>> few = record_of("custom-1", name="Mine", mode="rings", colours=["#2f6bd0"])
>>> unknown = record_of("custom-1", name="Mine", mode="nope", colours=["#2f6bd0", "#18a0c0"])
>>> clean_record(few) is None, clean_record(unknown) is None
(True, True)
>>> clean_record("not a record") is None
True
custom_scheme
def custom_scheme(record: CustomRecord) -> Scheme
Make a scheme from one of the user’s own records.
The colours in a record are what a cell looks like when lit; the quiet cells are the same hue, calmer and darker (or, on a light wedges, paler).
Parameters
record(CustomRecord): A record thatclean_recordaccepted.
Returns
- Scheme: The scheme, with the key and name of the record.
Examples
>>> scheme = custom_scheme(record_of("custom-1", name="Mine", mode="rings", colours=["#2f6bd0", "#18a0c0"]))
>>> scheme.key, scheme.name, scheme.light
('custom-1', 'Mine', False)
>>> scheme.cells["outer"][0][1][0] != scheme.cells["inner"][0][1][0] # two rings, two hues
True
dump_customs
def dump_customs(records: list[CustomRecord]) -> str
Write the user’s own schemes as text to save.
Parameters
records(list of CustomRecord): The schemes.
Returns
- str: JSON.
Examples
>>> dump_customs([])
'[]'
load_customs
def load_customs(text: str) -> list[CustomRecord]
Read the user’s own schemes back, leaving out any that are not valid and any beyond the limit.
Parameters
text(str): Whatdump_customswrote.
Returns
- list of CustomRecord: The valid schemes, each with its own key.
Examples
>>> load_customs("not json"), load_customs("[1, 2]")
([], [])
>>> one = record_of("custom-1", name="A", mode="single", colours=["#2f6bd0"])
>>> [r["id"] for r in load_customs(dump_customs([one, one]))] # a repeated key is dropped
['custom-1']
resolve
def resolve(
key: str,
*,
customs: list[CustomRecord],
) -> Scheme
Find a scheme by its key, among the presets and the user’s own, falling back to the default.
Parameters
key(str): The saved choice.customs(list of CustomRecord): The user’s own schemes. Keyword-only.
Returns
- Scheme: The scheme, or the default one if the key is unknown (for instance after the scheme was deleted).
Examples
>>> resolve("midnight", customs=[]).name, resolve("gone", customs=[]).key
('Midnight', 'cyan-indigo')
next_custom_key
def next_custom_key(customs: list[CustomRecord]) -> str
Return a key that none of the user’s schemes has.
Parameters
customs(list of CustomRecord): The user’s own schemes.
Returns
- str: “custom-“ and the smallest number that is free.
Examples
>>> taken = [record_of("custom-1", name="", mode="single", colours=[])]
>>> next_custom_key([]), next_custom_key(taken)
('custom-1', 'custom-2')