DKE Python — Language Reference

4.1 The base types

Beyond the base types there are four constructed type formers — values a program builds, which exist only while it runs and are never stored: list<T> (an ordered sequence, §6.7), tuple<T1, …, TN> (a fixed-length heterogeneous sequence, §6.8), dict<K, V> (a mapping from a hashable key — a scalar or a tuple of hashables — to a value, kept in insertion order, §6.9), and set<T> (a collection of unique hashable elements — a scalar or a tuple of hashables — presented sorted, §6.10). A list<T> is produced by a list literal, a comprehension, s.split(...), and a list slice; the other three by their own literals (§6.8–§6.10) and comprehensions (§6.11) — none by a read verb. Each shares the read surface it can support (index, .length, for … in, membership) with per-type refinements, and all render in print / +. None is one of the base types — they are type formers over them. A fifth, iterator<T>, is what zip, enumerate, reversed and iter return: a one-pass reader over a collection, with no length and no position (§6.12). Three more, dict_keys<K>, dict_values<V> and dict_items<K, V>, are the views a dict’s .keys(), .values() and .items() return, which read the dict as it stands whenever they are read (§6.9).

This table is the type vocabulary. empty has a row because you write it in a match arm, and it is not one of the types: it names the absent arm of an active_claim, and the compiler refuses it as an annotation in exactly those words.

Listing order is part of the contract. Each finite collection has a defined order, and claim_list has two — a read within one cell and a read spanning several answer different questions:

Ascending name order is the order sorted() gives — codepoint order, not locale collation — the same sorted order a constructed set is presented in. So xs == sorted(list(xs)) holds for every row that says ascending, and sorting such a read again is dead code. This fixes what the order is, not only that it does not change between runs: the two structural rows bind just as tightly, so a proof_tree always leads with its conclusion and a diagnosis always reads top to bottom as written.

Three groupings drive the static rules:

• Primitives — string, int, bool.
• Finite collections — claim_list, string_list, subject_set, result_type_set, proof_tree (all store-derived), and diagnosis, the explanation why_not and what_needs give of an absence, plus the client-built list<T>. These, together with a constructed dict (walked over its keys) and set (walked in sorted order), are the types a for … in may iterate (§7.7); every one also has a .length (§11). claim_list and proof_tree yield active_claim elements; the other three store-derived collections and diagnosis yield string; a list<T> yields T. A proof_tree additionally offers a .root accessor (§11.2). (A tuple joins them when its elements have one type to bind — always for a variadic tuple, and for a fixed one whose positions share a type, are all scalars or are all class instances; a fixed tuple holding a collection beside a value of another type is not a for … in iterand, §6.8.)
• Discriminators — active_claim (+ its empty case) and verify_result. Consumed by a match, alongside the value union.
• The value union — the stored content of a claim (active_claim.value), one of these classes: int, bool, string, datetime, duration, real, null, blob, scientific or complex. All but one are write-producible — int, bool, string, datetime, duration, real, blob, scientific, complex (a program writes one and reads it back at that class). The remaining class, null (an explicit absent value), is read-only: it is asserted via assert (§5.1), no value literal produces it, but a claim carrying one is discriminable on read. Consume the union with a value match (§7.8) or an isinstance test (§8.11) to recover the typed content, or render it directly.
• datetime — a UTC instant written with the datetime("…Z") literal (e.g. datetime("2026-01-02T03:04:05Z"), RFC 3339 with a required Z and optional 1–9 fractional-second digits). A write verb stores it typed and it reads back as the datetime class of value; it renders as its RFC 3339 text.
• duration — a length of time written with the duration("…") literal (e.g. duration("PT1H30M"), an ISO 8601 duration PnDTnHnMnS; calendar years and months are not accepted). The lowest-order term may carry a decimal fraction of up to nine digits, so durations are exact to the nanosecond (duration("PT0.5S")); only the last term may be fractional, and a span must fit within about ±292 years. A write verb stores it typed and it reads back as the duration class of value; it renders as ISO 8601 in a canonical form with trailing fractional zeros removed, so duration("PT90M") reads back as PT1H30M and duration("PT1.500S") as PT1.5S.
• real — a fractional number written as a decimal literal 3.5, a leading-dot .5 (== 0.5), or a trailing-dot 5. (== 5.0); _ may separate digits as in 1_000.5. A lone . with no adjacent digit is the field operator, so .name is a field access, and 5.name is the real 5.0 then name (a parse error), not a field on an integer. A literal may also carry an exponent 1e5, 1.5e-3, 2E10, .5e2 (e/E, optional sign, digits — a real even without a point; 1e with no digit stays an integer 1). A write verb stores it typed and it reads back as the real class of value. It renders exactly as CPython repr(float): shortest round-trip, fixed-point for a decimal exponent in [-4, 15] (trailing zeros dropped — 3.50 → 3.5, 5.0 → 5.0), scientific (1e+20, 1.5e-08) beyond that, -0.0 for negative zero, and inf, -inf and nan for the two infinities and a NaN — the same text on the wire, on write-through, and on read-back: a cell holds every real exactly, -0.0, the infinities and a NaN included. An exponent past the top of the finite range is the infinity, 1e400 being inf, as in Python; one past the bottom (1e-400) underflows to 0.0. There is no NaN literal: math.nan and float("nan") make one, and math.inf an infinity (§6.14). A result past the largest real is inf or -inf, and an operation with an infinite or NaN operand answers IEEE 754’s value (§6.3, Infinity and NaN). A case real as r: arm binds r : real. Reals compute: + - * / and the ordered comparisons accept them and promote int → real; / is always true division and always yields a real (§6.3).
• blob — an opaque byte string written as a hex literal blob("48656C6C6F") (an even count of hex digits) or a base64 literal blob_b64("SGVsbG8=") (RFC 4648; the same bytes) — two input spellings for one byte space; the empty blob("") / blob_b64("") is a valid zero-byte blob. A write verb stores it typed and it reads back as the blob class of value in a single canonical uppercase-hex form regardless of the input spelling (a value written blob_b64("SGVsbG8=") reads back 48656C6C6F); it renders as that hex text whichever spelling produced it, and the two spellings and a read of the same bytes are one value, equal by their bytes wherever blobs compare (blob_b64("AQI=") == blob("0102") is True, and a set or dict holds them as one element or key). A blob indexes, slices and joins as Python’s bytes do (§6.5). A case blob as b: arm binds b : blob. There is no bytes literal: b"abc" is refused naming the blob it denotes, blob("616263") (Python Specification §3.5.8).
• scientific — a number carrying its significant figures, written with the scientific("…") factory (e.g. scientific("6.022e23")) — a mantissa and a required exponent. A write verb stores it typed and it reads back as the scientific class of value, in a canonical form with the mantissa normalized to one leading digit and the significant figures preserved, so scientific("60.220e21") reads back 6.0220e22. The figures are part of the value: scientific("6.022e23") (four figures) and scientific("6.0220e23") (five) are the same magnitude but distinct values — the property a real cannot hold. A case scientific as s: arm binds s : scientific.
• complex — a number with a real part and an imaginary part. An imaginary literal is a decimal number followed by j (4j, 1.5j, 1e3j), and a complex with a real part is written as the sum it is, 3 + 4j, as in Python. It renders as CPython does: 4j when the real part is a positive zero, otherwise both parts in parentheses, (3+4j). .real and .imag read the two parts, each a real, and z.conjugate() is the conjugate. It computes under + - * / beside a complex or a number (§6.3), compares with == and != (1 + 0j == 1 is True), and has no order: < and its kin refuse one, as in Python, and so do sorted, min and max. A write verb stores it typed and it reads back as the complex class of value; a cell holds zero without a sign, so -0j reads back 0j. A case complex as z: arm binds z : complex. A declared complex takes a number too and keeps its class (z: complex = 1 prints 1), and so does a collection: [1, 2j] is a list<complex> whose elements keep their classes, so sum([1, 2j]) is (1+2j), and it still refuses sorted. Every number answers .real, .imag and .conjugate() too, as in Python (§11.2): it is its own real part and its own conjugate, a bool the int it is, and its imaginary part is a zero of its class. A real also answers .is_integer() and .hex(); an int or a bool answers .bit_length() and .bit_count() and has .numerator and .denominator; and each answers .as_integer_ratio(), which refuses a ratio past the signed 64-bit range.

There is no None: every name holds one type, and no type means “a value or nothing”. To assert that a stored value is known to be absent, use assert(K.s.a, src) (§5.1), which carries no value; a parameter that may be omitted takes a default of its own type; a script with no result ends with a bare return. null is written only as an open bound of a validity window and as the case null: arm that matches one, and None only as a whole argument of slice(...), where it leaves that bound open (§6.5). Both words are reserved: neither can be bound as a name, and reading either where a value goes is refused with this lesson. A type is written in four places — a parameter, a binding annotation, a collection’s element type, and a script’s or value method’s return — and the same names are valid in all four. They are any of the value-class scalars (string, int, bool, datetime, duration, real, blob, scientific, complex), a read-result type (claim_list, active_claim, …, for calls between procedures), a collection type (list<int>, dict<string, int>, …), or a declared class (§8), which stands for an instance of that class. CPython’s spellings are read too: str is string, float is real, list[int] is list<int> and dict[str, int] is dict<string, int>. A return annotation of None alone, -> None:, says what no annotation says. A class name is a type wherever any other is, so list<Animal> names a list of animals and -> Animal a script that answers one; which instances fit such a name is §8. A value-class-scalar parameter supplied over the wire is passed as its canonical text (a datetime as RFC 3339 UTC, a duration as ISO 8601, a real as a decimal with a point, a blob as hex) and refuses if malformed. A class field (§8) is typed by a value-class scalar only — a field holds one stored value. Neither empty nor null is a type — both name absence; value arises only from .value field access.

4.2 Handler bindings

The except refuse as <var> / except engine_error as <var> handlers of a try (§7.9) each bind a value whose fields are all string and always present — a field with nothing to say holds "", since the language has no absent value. A refuse binds .reason, .teaching_hint, and .discriminator; an engine error binds .reason and .code. The fields are listed in §11.2. These types cannot be written as parameter types.

.reason is written for a reader and is what a program should report. The .discriminator of a refuse and the .code of an engine error play the same role for a program that must branch rather than report: each is a short tag naming which failure this is. Two kinds of .discriminator are part of this contract. A refusal you raised yourself with raise <ExcType>(…) (§7.15) carries the exception name your own source wrote. A refusal the store raises because a call cannot succeed as written carries the code the MCP Reference publishes for it as refuse_reason, such as conflicting_write, pinned_address or invalid_value, and a program may branch on those codes as a client of the service does. Every other tag is not part of this contract and is not enumerated here — branch on the tags you have observed and keep a fallback arm.

.teaching_hint suggests how to correct the call, and is empty when there is no suggestion. It is an aid to a human reader — never a second reason, and never something to branch on.

5.1 Write verbs (statement position)

remember(K.s.color, "orange", "op1")     # string
remember(K.s.count, 42, "op1")           # int — reads back as int
remember(K.s.rate, "3.0", "src", datetime("2019-01-01T00:00:00Z"), datetime("2021-01-01T00:00:00Z"))  # valid 2019–2021
remember(K.s.plan, "active", "ops", datetime("2024-01-01T00:00:00Z"), null)  # valid 2024 onward, open end

remember(Rate.vat.pct, 25, "2026 finance act")
remember(Rate.food.pct, 15, "https://lovdata.no/lov/2009-06-19-58")

remember(Reading.r1.temp, 21, "lab", qualifiers={"method": "observed", "confidence": 0.8})
remember(Reading.r1.temp, 23, "forecast", datetime("2026-10-01T00:00:00Z"), null,
         qualifiers={"method": "predicted"})

update(K.s.mood, "playful", "op2")
update(Rate.vat.pct, 25, "finance act", datetime("2024-01-01T00:00:00Z"), datetime("2024-12-31T00:00:00Z"))
update(Rate.vat.pct, 27, "finance act", datetime("2025-01-01T00:00:00Z"), null)  # 2024 still reads 25

forget(Project.dke.license, "MIT", "registry_one")

remember(Reading.probe.n, 5, "sensor")      # an int claim
forget(Reading.probe.n, "5", "sensor")      # refused - no text claim there
forget(Reading.probe.n, 5, "sensor")        # removes it

remember(Rate.eu.vat, 25, "tax", datetime("2020-01-01T00:00:00Z"), datetime("2020-12-31T00:00:00Z"))
remember(Rate.eu.vat, 25, "tax", datetime("2022-01-01T00:00:00Z"), datetime("2022-12-31T00:00:00Z"))
h = get(Rate.eu.vat, datetime("2022-06-01T00:00:00Z"))
forget(h[0])                                  # the 2022 claim; 2020 stays

forget(Sensor.probe.reading, datetime("2021-06-01T00:00:00Z"))   # the values in force then

forget(Sensor.probe.reading, recorded_before=datetime("2026-01-01T00:00:00Z"))
forget(Sensor.probe, recorded_before=datetime("2026-01-01T00:00:00Z"))
forget(Sensor, recorded_before=datetime("2026-01-01T00:00:00Z"))

forget(Sensor.probe.reading, recorded_before=datetime("2026-01-01T00:00:00Z"))

forget(K.s.mood)      # the cell and its full history
forget(K.s)           # the whole subject; its kind is gone
forget(K.s.mood, datetime("2024-01-01T00:00:00Z"))   # only what was true at that instant

assert(K.s.chip_id, "vet")

prefer(Sensor.r1.temp, "registry_two")

unprefer(Sensor.r1.temp)

pin(K.s.color)

unpin(K.s.color)

5.2 Read verbs (expression position)

cur = current(K.s.color)

hist = get(K.s.mood)

cav = caveats(K.s)

confs = conflicts()

vals = list_values(K.color)
then = list_values(K.color, datetime("2027-06-01T00:00:00Z"))

hits  = subjects(K.color, "orange")     # text match
warm  = subjects(K.temp, 42)            # int match — not the text "42"
five  = subjects(K.amt, 5)              # finds a stored 5 and a stored 5.0

everyone = list_subjects(K)             # every subject of the kind
coloured = list_subjects(K.color)       # only those with a colour
then     = list_subjects(K, datetime("2027-06-01T00:00:00Z"))

attrs = list_attributes(K)                             # the kind's attribute names
mine  = list_attributes(K.s)                           # this subject's, now
then  = list_attributes(K.s, datetime("2027-06-01T00:00:00Z"))  # …and at that time

cats = list_categories()        # e.g. ["Loose", "shop.Widget"]

5.3 Provenance and reasoning

pt = why(K.s.color)
n  = pt.length                     # how many claims participated
r  = pt.root                       # the queried claim
first = pt[0]                       # a participating claim → active_claim
for c in pt:                        # iterate the derivation's claims
    print("via " + str(c.source))

before = why(Order.o1.review, datetime("2024-03-01T00:00:00Z"))
after  = why(Order.o1.review, datetime("2024-09-01T00:00:00Z"))

for c in after:
    print("now rests on " + str(c.path) + " = " + str(c.value))
for c in before:
    print("then rested on " + str(c.path) + " = " + str(c.value))

d = why_not(Device.b.online)
print(d)             # rule `device_is_online` needs Device[b].checks > 0,
                     # and nothing is recorded there
win = why_not(Device.w.online)
print(win)           # rule `device_is_online` needs Device[w].checks > 0,
                     # and Device[w].checks is recorded as 2 but not in
                     # force at the time asked about
n = d.length
for line in d:
    print(line)

bed = why_not(Bed.south.water_on)
print(bed)           # rule `open_valve` needs Plant[`p`].thirsty == True
                     # and Plant[`p`].bed == "south" together: each is met
                     # on its own, but no one `p` meets all of the rule's
                     # conditions at once

d = what_needs(Device.b.online)
print(d)             # via rule `device_is_online`:
                     #   have Device[b].power
                     #   need Device[b].checks > 0 (record this)
win = what_needs(Device.w.online)
print(win)           # via rule `device_is_online`:
                     #   have Device[w].power
                     #   need Device[w].checks > 0 (recorded, but not in
                     #     force at the time asked about)

bed = what_needs(Bed.south.water_on)
print(bed)           # via rule `open_valve`:
                     #   need Plant[`p`].thirsty == True (met on its own,
                     #     but not together with the rule's other conditions)
                     #   need Plant[`p`].bed == "south" (met on its own,
                     #     but not together with the rule's other conditions)

one = what_needs(Crate.c1.ok)
print(one)           # via rule `ok_when_clear`:
                     #   have Crate[c1].x
                     #   need Crate[c1].blocked to be absent (it is present
                     #     — remove it, or narrow its window)
                     #   have Crate[c1].jammed absent
two = what_needs(Crate.c2.ok)
print(two)           # via rule `ok_when_clear`:
                     #   have Crate[c2].x
                     #   have Crate[c2].blocked absent
                     #   need Crate[c2].jammed to be absent (it is present,
                     #     and a rule concludes it — `why` shows what it
                     #     rests on)

v = verify(K.s.color, "orange")
if v.match:
    print("confirmed")

orange = agreement(K.s.color, "orange")   # e.g. 2

n = would_forget(Sensor.probe.reading, recorded_before=datetime("2026-01-01T00:00:00Z"))
if n > 100:
    print("that would drop a lot of history")
else:
    forget(Sensor.probe.reading, recorded_before=datetime("2026-01-01T00:00:00Z"))

a = agreement(K.s.color, "orange")   # 2 — two sources cited
w = writers(K.s.color, "orange")     # 1 — but one key wrote both

base = get(K.s.a)
for c in base:
    deps = dependents(c)
    for d in deps:
        print("derived cell = " + str(d.path))     # .path is the dependent's K.s.a
    below = dependents(c, transitive=True)         # everything resting on c

t = current(Order.o1.total)                  # total: int = price * qty
print(t.derived_by)                          # Order.total
ps = premises(t)
print(str([p.path for p in ps]))             # ['Order.o1.price', 'Order.o1.qty']

5.4 Reading as of a time

Six read verbs accept an optional trailing datetime (§4.1) naming the time the read is answered as of:

Omitting the argument reads the present, so a bare call and its anchored form differ only where a validity window (§5.1) is in play — a fact written without one is valid at every time, and reads the same either way.

The time may be future as well as past. A commitment written for later — a release date, a scheduled rate change, a contract that starts next quarter — is not part of the present, so nothing at the present reports it. The anchor is what reads it back, and on the three enumerations it is what finds it at all: without one, a store can hold a fact that no traversal reaches.

remember(Release.v2.ships, "2027-03-01", "roadmap",
         datetime("2027-01-01T00:00:00Z"), datetime("2027-12-31T00:00:00Z"))

when = datetime("2027-06-01T00:00:00Z")
list_subjects(Release, when)        # ["v2"]
list_attributes(Release.v2, when)   # ["ships"]
list_values(Release.ships, when)    # the claim
current(Release.v2.ships, when)     # "2027-03-01"

list_attributes(K) and list_categories() take no as-of time. The first gives the attribute names recorded for a kind, the second the kinds recorded in the store. Both describe what the store holds rather than what is true at a moment, so each already covers every time and an anchor could only narrow a complete answer. This is why list_attributes takes one in its K.s form and not in its K form — the first reads a subject’s claims, the second a kind’s vocabulary. Offering a time where none is accepted is a compile error naming the form that takes one.

Reading as of what the store knew. The same six reads take one keyword argument, known_at=, a datetime on the other time axis: not when a fact was true of the world, but what the store had been told by then. A claim written later is not among the answer. A claim revised or replaced later is, with the standing it had then, so a disagreement the store held at that moment reads as one, and current refuses over it as it would over a disagreement now.

remember(Price.widget.eur, 10, "list")      # written in January
update(Price.widget.eur, 12, "list")        # written in March

feb = datetime("2026-02-01T00:00:00Z")
current(Price.widget.eur, known_at=feb)     # 10 — what the store held then
current(Price.widget.eur)                   # 12

The two times are independent and may be given together: current(K.s.a, datetime("T1"), known_at=datetime("T2")) is the value the store, as of T2, held to be in force at T1. Without known_at= a read answers over everything the store holds now, and a known_at= later than every write answers the same way.

forget is retroactive: what was forgotten was never known, as far as any read can tell.

A conclusion is answered as it stood at that moment: what the rules, as they read then, concluded from what the store had been told by then. That includes a conclusion withdrawn since, and leaves out any that only a rule written later concluded. A conclusion in such an answer may carry an empty .created_at, since when it was recorded is not kept once what it rests on has changed. A known_at= read refuses catchably in three cases:

known_at= is a keyword, never a position, and is given at most once. Only these six reads accept it — on any other verb, forget included, it is a compile error — and its value must be a datetime.

5.5 Result-type introspection

rts = list_result_types()
# active_claim, claim_list, diagnosis, empty, proof_tree,
# result_type_set, string_list, subject_set, verify_result

5.6 Script-data reads (in-language)

Read-only, so they run inside a program.

names = list_scripts()

5.7 Wire-only verbs (not callable in a program)

Callable at the dke.langsyn.net wire surface but rejected in a program body — they mutate the script set or answer administrative provenance. Each row is an MCP tool call, with the tool’s own argument names. The table is a selection: the tools that change or describe your modules and rules. MCP Reference §2 lists every tool the wire serves.

The in-language import <module> statement (§7.11) loads a stored module inside a program body and so is not listed here.

compile and run are the two ways to submit a source, and they differ in one respect: compile stores the compilation (the module’s defs become callable by name, its rules stand); an inline run executes it once and stores nothing — data it remembers persists, but no script is left for later instructions to call or for list to report. Neither needs a def: bare top-level statements are a complete program, which is the shortest form for a one-off question (such a program takes no arguments — a def is what gives it parameters). Any number of procedures run (they may call one another; the last top-level def is the entry); a source that defines standing rules (a @rule or a computed field) cannot take effect in a run and is refused — such a source is compiled to activate its rules. Both report what the module body did — its output and its store effects — since both run it, and compile additionally states what it installed. → §9.3, MCP Reference §4.1, §4.2

5.8 Aggregate query functions

A read-only fold over a whole attribute — one attribute across every subject of a kind — returning a value (§4.1). Bind it to a name on its own line, then use it, or return it whole (return avg(Reading.value)); an aggregate may not be a bare argument to another call.

n     = count(Reading.value)          # single-attribute fold
p90   = percentile(Reading.value, 90)  # ranked fold, rank 0–100
slope_xy = slope(Point.x, Point.y)     # two-attribute fold (both attributes of one kind)
mean  = avg(Reading.value)            # bind first, then use `mean`

• Single-attribute fn(K.attr) — count, sum, product; avg, median, midpoint, mode, geomean, harmmean, rms; min, max, span, variance, stdev, iqr, mad, cv; skewness, kurtosis, entropy.
• Identity / positional fn(K.attr) — distinct (how many distinct values, counting equal numbers once as a Python set does: 1, 1.0 and True are one value), argmin / argmax (which subject holds the min / max value), first / last (the earliest- / latest-recorded current value).
• Ranked percentile(K.attr, <int>) — the <int>-th percentile (rank 0–100). The rank is an integer literal or the name of an int, resolved at runtime; outside 0–100 it is refused, at compile time for a literal and at runtime for a name. An expression is bound to a name first.
• Two-attribute fn(K.x, K.y) (both attributes of one kind) — covariance, correlation, slope, intercept, rsquared.

Anything after a single-attribute fold’s attribute is refused at the fold’s name, which gives its form, and so is a two-attribute fold’s second operand that is not an attribute, such as x + 1. A keyword argument is refused at the keyword, since an aggregate query takes none; key= and default= on min and max, and start= on sum, are named as what those names take over a list.

Which definition each name denotes. Some of these names mean a different number in different systems, so the choice is stated rather than left to the reader: variance and stdev are the population figures (divide by n); skewness is the population g1; kurtosis is excess kurtosis (0 for a normal distribution); mad is the median absolute deviation about the median; entropy is in nats; percentile and iqr interpolate linearly between the two nearest ranks; and covariance is the population covariance, where Python’s statistics.covariance is the sample one.

stdev is worth a second look if you come from CPython. There, statistics.stdev is the SAMPLE standard deviation and pstdev is the population one; here stdev is the population figure. Over [2, 4, 4, 4, 5, 5, 7, 9] this answers 2.0 where statistics.stdev answers 2.138090 — both correct for their own definition, which is why the name alone does not tell you which you have.

Rounding over real values. A fold has no order to add its values in, so it does not add them as a loop over a list does. sum is the exactly rounded sum, Python’s math.fsum over reals, with an int entering as itself; avg is the exact mean rounded once, and rms the exact root mean square rounded once, where statistics.fmean and math.sqrt(statistics.fmean([x * x for x in xs])) round along the way and can differ in the last place. product, geomean and harmmean are their exact values rounded once too, in no order: over ten values of 0.1, geomean is 0.1, where statistics.geometric_mean gives 0.10000000000000002, and sum is 1.0, as sum([0.1] * 10) is. variance, stdev, cv, skewness, kurtosis and the two-attribute folds are their exact values rounded once as well: variance and stdev answer what statistics.pvariance and statistics.pstdev give. min, max, median, midpoint and span select a member or combine two exactly, and percentile, iqr and mad are their exact values rounded once as well: neither the rank nor the interpolation rounds, where the same formulas in reals round at each step. entropy is its exact value rounded once too, where a Python computation can differ in the last place (Python Specification §7.1.1). Where the Python computation passes the largest real on the way and the fold’s value does not, the fold answers its value: over 1e308 and 1.5e308, avg yields 1.25e+308, where statistics.fmean raises. A value past the largest real yields inf or -inf. A fold that yields a duration or a datetime is its exact value rounded once to a nanosecond, half away from zero: over PT0S and PT15638400.000000001S, avg, median and stdev are each P90DT12H0.000000001S.

The result’s class follows the attribute (a numeric attribute yields a number; a datetime / duration attribute a datetime / duration) — except distinct (always an int) and argmin / argmax (always a string, the subject); first / last follow the attribute. Over values holding a real, a fold that computes yields a real, whole or not (sum over 0.5, 1.5 is 2.0). Over int and bool values alone, sum, avg, span, midpoint, variance and product yield an int when the result is whole (avg over 1, 3 is 2), and stdev, iqr, percentile, mad, cv, geomean, harmmean, rms, skewness, kurtosis, the two-attribute folds and an even-count median yield a real (stdev over 1, 3 is 1.0). A bool attribute is numeric: a fold that computes yields a number (sum over True, True, False is 2), and min, max, mode, first and last yield the stored value (max is True), the first recorded of equal values, or for last the last. Destructure with match or use it wherever a value is expressible. Fold names are soft keywords — recognised only right before (, so they stay ordinary identifiers elsewhere. An aggregate over an attribute with no data is a refuse, with the aggregate_empty discriminator, and so is a fold whose formula has no value: geomean and harmmean over a zero or a negative value, cv where the mean is zero, slope and intercept where the first attribute’s values are all equal, and correlation and rsquared where either attribute’s are. Python Specification §7.1.1 gives each fold’s formula. A value-comparing fold (sum, avg, min, max, argmin, argmax, …) over an attribute whose values are not numbers (a text attribute, or one mixing numbers with non-numeric values) is likewise a refuse — the fold declines rather than treating a non-number as zero. So is one over an attribute mixing two of the numbers, duration, datetime and scientific (a duration beside an int), as Python’s sum and max raise. The folds that don’t compare values numerically — count, mode, entropy, distinct, first, last — read how the values are distributed, or return a stored value unchanged, so a string, bool, datetime, duration, scientific or complex attribute folds under all six without refusing on that ground (a complex has no order, so the folds that compare by value, sum among them, refuse one), and an attribute mixing them folds too, each chosen value in its own class. A blob value is the exception: count folds an attribute holding one, and the other five refuse over it — a blob is opaque, so there is nothing in it to group by, to tell apart, or to hand back as a result.

5.9 Worlds

A world is a named alternative to the store, kept until it is merged or discarded. It holds everything the store holds, and what is written in it is seen only there. A program writes in a world and reads it inside a with world(...) block (§7.18), and a later program can enter the same world again, so one alternative can be built up and read over as many runs as it takes. A world’s name is a string and follows the rule a branch’s name does (§7.10).

d = compare_worlds("wet", "dry")
for c in d:
    print(c.path, c.value, c.source)

6.1 Comparison

== != over any two values. Values of different types are unequal, as in Python — "7" == 7 is False and "7" != 7 is True, and nothing is converted to be compared. Numbers compare by value across int, real and bool, or an element of a list mixing them (§6.7): 1 == 1.0 is True, and a bool is the int it is, so True == 1 is True, matching the ordered comparisons and Python. A value compares with any value as the class it holds (§4.1), and two discriminators compare .kind. Two constructed lists compare element-wise at any depth — [1] == [1.0] is True, [1] == ["a"] is False, and an empty list compares with any list (§6.7). The same rule holds wherever a value is looked for: in, .index, .count, .remove, a dict key read, set inclusion and is (below). Two operands are refused: a class instance, and an answer read from the store (a claim, a proof) against anything but its own type. < > <= >= over numeric operands (int, real, bool or scientific, or an element of a list mixing them, §6.7; mixed allowed — compared numerically) or two strings. A scientific orders by its magnitude, the real nearest the number it writes, against any number or another scientific, as a rule premise orders one (§8.8): scientific("2.0e4") > 100 is True. Its figures take no part, so scientific("6.022e23") and scientific("6.0220e23") are neither < nor > each other, while == still tells them apart, and tells scientific("1.0e0") from 1. A complex equals another when both parts are equal, and equals a number exactly when its imaginary part is zero and its real part equals that number (1 + 0j == 1 is True). It has no order: < > <= >= with a complex on either side is a type error in Python’s words ('<' not supported between instances of 'complex' and 'int'), and so are sorted, min and max over one. Order by a part or by the magnitude instead: sorted(zs, key=abs). A string comparison is lexicographic by Unicode codepoint, so "apple" < "banana" and (uppercase first) "Z" < "a", matching Python; a shorter string that is a prefix orders first ("a" < "ab"). A string compared against a number is a type error. < > <= >= also order two datetimes (chronologically — the earlier instant first) or two durations (by length — the shorter first). Both compare by value, not spelling: duration("PT90M") < duration("PT1H30M") is False, and so is >, since the two are the same length; a datetime written with fractional seconds orders against one written without them by the instants they denote. A datetime compared against a duration, a number, or a string is a type error. datetime and duration also COMPUTE together: datetime + duration (either order) and datetime - duration shift an instant, datetime - datetime gives the length between two instants, and duration + duration / duration - duration add and subtract lengths. A duration also scales: duration * <number> (either order) stretches it (duration("PT1H") * 2.5 is PT2H30M) and duration / <number> splits it (duration("PT1H") / 4 is PT15M). Dividing a duration by another duration asks how many times one fits into the other and gives a plain real — duration("PT3H") / duration("PT45M") is 4.0, not a length — while % gives the length left over (duration("PT3H10M") % duration("PT45M") is PT10M). Shifts respect the calendar (datetime("2024-02-28T12:00:00Z") + duration("P1D") is 2024-02-29T12:00:00Z). Addition, subtraction, % and scaling by an int are exact to the nanosecond; scaling by a real rounds to the nearest nanosecond, halves away from zero. Subtracting a later instant from an earlier one yields a negative duration, which renders and reads back with a leading - (duration("-PT2H")). Two datetimes have no sum, duration - datetime is meaningless, duration * duration is an area rather than a time, <number> / duration is a frequency rather than a time, and //, ** are undefined over temporal values; a span past ~±292 years, an instant outside years 0001..9999, or a division or remainder by a zero-length duration, is a catchable refuse. < > <= >= also order two lists of an orderable element type or two tuples with orderable elements, of any lengths — element-wise lexicographic: the first unequal pair decides, and a prefix orders first ([1, 2] < [1, 2, 3], (1, 2) < (1, 3), (1,) < (1, 2)). An orderable element is a number, a scientific, a string, a datetime, a duration, or a nested list/tuple whose own elements are orderable, so the rule recurses all the way down ([[1], [2]] < [[1], [3]], [[2]] < [[10]] — element 2 < 10, not a string compare). Comparisons chain: a < b < c is (a < b) and (b < c) — each adjacent pair compared, the results conjoined, with b evaluated only once.

== / != also compare two tuples of any lengths (tuples of different lengths are unequal, and so are two whose positions hold different types, as (1,) == ("a",); equal tuples agree position by position, §6.8) and two sets (element-wise and order-independent — two sets are equal when they hold the same elements, and an int, a real and a bool of equal value are the same element, so {1, 2.0} == {1.0, 2} is True, §6.10). < > <= >= on two sets compare them by inclusion (§6.10), and so do they on a dict’s keys or items view beside a set or another such view (§6.9). Two dicts also compare with == / !=, order-independent — equal when they hold the same key→value mapping regardless of insertion order (numbers of either class by value, so {1: "a"} == {1.0: "a"} is True, a value of another type is unequal, and {} == {"a": 1} is False, §6.9).

Infinity and NaN. inf and -inf order beyond every other number. A NaN compares as IEEE 754 has it: math.nan == math.nan is False and every ordered comparison with one is False. DKE Python has one NaN, and a collection finds it by value, where Python finds a NaN only when it is the very object: float("nan") in [math.nan] is True, {math.nan: 1}[float("nan")] is 1, len({math.nan, -math.nan}) is 1, and [float("nan")] == [float("nan")] is True (Python: False, KeyError, 2, False). Sorting puts a NaN after inf, so sorted([3.0, math.nan, 1.0]) is [1.0, 3.0, nan] (Python: [3.0, nan, 1.0]), and min and max answer nan when any operand is one, as IEEE 754’s minimum and maximum do (Python Specification §8.1).

Identity: is / is not. a is b is True when a and b are one list, set or dict. A collection is shared (§7.17), so a name bound to another’s list, a parameter, an element read and a loop variable each hold the collection itself, while a copy, a conversion, a comprehension and a literal each build a new one: after b = a, a is b is True and a is a.copy() is False. is not is the negation. Two collections of different kinds or element types are never one, so [1] is {1} and [1] is ["a"] are False, as in Python. Over a number or a string there is nothing to ask: whether two equal numbers or strings are the same object in Python depends on how the implementation interns them, which the language leaves undefined, so is there is a compile error that names == or !=. Over any other value, a tuple or a class instance, the error names the three kinds is takes. x is None and x is not None have no == rewrite either, since there is no None here — a rule asks whether a field has no value with absent(...) (§8.8), and over None the error names no comparison at all. The word itself is reserved, as it is in Python, so is = 3 is a parse error.

6.1a Membership

in / not in over (string, string) → bool — substring containment: sub in s is True when sub occurs anywhere in s (the empty string is in every string) — or element containment: x in xs over a constructed list<T> (§6.7), x in s over a set<T> (§6.10), k in d over a dict<K, V> (testing its keys, §6.9) and k in d.keys() the same way, x in d.values() and (k, v) in d.items() over a dict’s views (§6.9), and x in t over a tuple, each True when an element == the item. A number is found among numbers of either class by value, as 1 == 1.0 compares: 1 in [1.0] is True, and so is 2.5 in (1, 2.5). A dict finds a numeric key the same way (§6.9). An item of another type is not found — "a" in [1, 2] is False — and a record tuple is searched for any of its fields: "alice" in ("alice", 30) is True. Membership does not test a store-derived collection — to iterate one, use the for <var> in <collection>: statement (§7), whose in is the loop keyword, not this operator.

if "@" in address:      ...
if 4 in [3, 1, 4]:      ...
if "red" in tags:       ...   # set membership
if "ana" in ages:       ...   # dict key membership

6.2 Logical

and, or, not over any value that has a truth value — False / 0 / 0.0 / 0j / "" / empty constructed collections are falsy, everything else truthy. The eight store-derived read-result types have none — active_claim, claim_list, proof_tree, diagnosis, subject_set, string_list, verify_result, result_type_set — and are refused in all four condition positions: an if / elif, a comprehension if filter, the condition of a if c else b, and an operand of and / or / not. This diverges from Python on purpose. An empty store read and a read that found nothing to tell you are different answers, and one False would say both; use .length to ask about emptiness and for … in to walk. and / or are short-circuit and operand-return — a and b is a when a is falsy else b; a or b is a when a is truthy else b — so name or "anon" returns the string. Their result type joins the operands (identical → that type; int/real → real; a complex and a number → complex; two other value scalars → value), and the operand returned keeps its class, so 1 or 2.5 is 1; a non-unifiable pair is a type_error. not always yields a bool. not binds looser than comparison, so not a == b is not (a == b).

6.2a Conditional expression (ternary)

a if c else b yields a when c is truthy (any value that has a truth value, §6.2), else b. The two branches must share a type, which is the result type, be two class instances, which join under their common base as a list’s elements do, be a scalar beside a value or two scalars that are not both numbers, which join to a value holding their classes, or be two numbers: an int/real pair is typed real, and the branch selected is returned unconverted, so 2.5 if False else 1 is 1. A complex and a number join the same way, to complex: 2j if False else 1 is 1. Evaluation is short-circuit — only the selected branch runs, so an untaken branch that would refuse is never reached (safe if d == 0 else 1 / d). A name holding a value that the condition tests is read in the first branch at what the test holding leaves it, and in the second at what its failing leaves (§8.11). It binds lower than every operator and is right-associative.

grade = "pass" if score >= 60 else "fail"

6.3 Arithmetic

+ - * / // % ** over numeric operands (int, real or bool — a bool computes as the int it is, so True + True is 2); prefix - negates an int (-True is -1), and prefix + takes the same operands and changes no number (+True is 1). The numeric operators promote: int × int stays int, and any real operand yields a real: the exact value of the operation rounded once, so an int past 2**53 is not rounded first (9007199254740993 + 0.5 is 9007199254740994.0, where Python answers 9007199254740992.0), as a base or an exponent of ** too ((-1.0000000000000002) ** 9007199254740993 is -7.38905609893065, where Python answers 7.389056098930649). Nothing but arithmetic and float(x) converts: a value given to a declared real, and a selection of two numbers, keep the class they have. So a real field written with 1 + 0.0 holds 1.0, and written with a -> real script’s return 1 holds 1; the two are equal. One exception and one detail: - / is true division — it always yields a real, so int / int promotes (7 / 2 is 3.5, 8 / 2 is 4.0). The floored integer quotient is // (7 // 2 is 3, -7 // 2 is -4 — floor rounds toward −∞). - % and // are the floor pair — both take the sign of the divisor (-7 % 2 is 1, -7.5 % 2 is 0.5), so a == (a // b) * b + (a % b) holds at either operand class. A remainder of zero takes the divisor’s sign too, which only a real can show: 6.0 % -2 is -0.0.

Complex arithmetic. +, -, *, / and ** take a complex beside another complex or beside a number and answer a complex, what CPython answers for the same operands: (3 + 4j) * 2 is (6+8j), (3 + 4j) / 2 is (1.5+2j), 1 / (3 + 4j) is (0.12-0.16j), 1j ** 2 is (-1+0j). The prefix - negates both parts, so -4j renders (-0-4j). // and % do not take a complex, and neither do divmod, round, int and float; read .real or .imag for a part. A division by zero with a finite dividend refuses at run time in Python’s words, complex division by zero. A part may be infinite or a NaN, and computes as Infinity and NaN (below) says.

** is power, right-associative, binding tighter than the prefix - (-2 ** 2 is -4, 2 ** 3 ** 2 is 512): int ** non-negative int is an int (2 ** 10 is 1024); a real operand yields a real; an int base with a negative exponent is a real when the exponent is written as a literal (2 ** -1 is 0.5), and otherwise refuses at run time with a teaching hint — write the base as a real (2.0 ** n), or the exponent as a literal. Reals compute to IEEE-754-double precision and render in canonical decimal form. A power with a real operand and a complex’s abs are correctly rounded, and each part of a product, quotient or power over a complex with every part finite is its exact value rounded once: the answer is the same wherever it is computed. Python takes these functions from its platform, which rounds them correctly almost always; where it does not, Python’s last digit differs from DKE’s (Python Specification §8.3). Division / modulo by zero of finite operands and integer overflow refuse at runtime; a real result past the range is inf or -inf. Two ** shapes refuse for reasons that are not overflow: a zero base under a negative exponent (0 ** -1) is a division by zero and says so, and a negative base under a fractional exponent is a complex number, which the real a power of two numbers is typed as cannot hold. Two spellings compute it. Written with both operands as literals the power is typed complex: (-8) ** 0.5 is 2.8284271247461903j, its real part exactly zero, where Python’s is 1.7319121124709868e-16. And a complex operand makes any power a complex, so complex(x) ** 0.5 answers for a negative x. A zero raised to a negative or a complex power refuses in Python’s words, 0.0 to a negative or complex power; a base that is not zero never does. A complex power’s part past the range is inf or -inf, where Python raises OverflowError: complex exponentiation. A negative base under an integral exponent ((-8.0) ** 3.0 is -512.0) and a zero base under a non-negative one (0 ** 0 is 1) are ordinary.

Infinity and NaN. A real, and a part of a complex, may be inf, -inf or nan, and every operation takes one and answers IEEE 754’s value, as Python’s operators do: math.inf - math.inf is nan, 1 / math.inf is 0.0, and an operation with a NaN operand is nan (save math.nan ** 0, which is 1.0). A result past the largest real from finite operands is inf or -inf, as 1e308 * 10 is in Python. A zero divisor refuses only when the operands are finite. DKE Python departs from Python where Python raises instead, and at three corners where Python’s answer breaks its operator’s rule:

Each part of a complex product, quotient or power of finite operands (a power’s base not zero) is its exact value rounded once, inf only where that value is past the range; Python rounds at every step, and loses some parts to an intermediate. A part whose exact value is zero takes the sign Python gives it where Python answers a zero there, and +0 otherwise. A quotient by a complex zero answers as C99 Annex G says. Comparisons, collections, min, max and sorting treat a NaN as §6.1 says, and the math functions as §6.14 says (Python Specification §8.3).

* also does sequence repetition: a string, a constructed list or a constructed tuple repeated by an int (either order) — "ab" * 3 is "ababab", "-" * 20 a rule, [0] * 4 is [0, 0, 0, 0], [1, 2] * 3 is [1, 2, 1, 2, 1, 2], (1, 2) * 2 is (1, 2, 1, 2). A non-positive count yields the empty sequence ("x" * 0 and (1, 2) * 0 are "" and ()); the count must be an int. A tuple’s type is its position list, so its count must be written as a literal and the result may name at most 65536 positions; with a count the run supplies, repeat a list — whose length is not in its type — and convert: tuple([1, 2] * n). One rule covers that and the negative literal exponent above, and the Specification states it once: a static type may depend on an operand’s value only where the program writes that value as a literal. → Python Specification §8.3

Bitwise operators — on two integers, a bool counting as the int it is, &, | and ^ are bitwise and, or and exclusive or, << and >> shift left and right by a count of bits, and the prefix ~ inverts every bit, as in Python: 12 & 10 is 8, 12 | 10 is 14, 12 ^ 10 is 6, 1 << 4 is 16, -5 >> 1 is -3 and ~5 is -6. Two bools given &, | or ^ answer a bool (True ^ True is False); ~ and the shifts answer an int. They bind between comparison and + / -, in Python’s order — | loosest, then ^, & and the shifts — so i & 4 == 4 is (i & 4) == 4, and ~ binds as the prefix - does. &=, |=, ^=, <<= and >>= assign the result. A negative shift count refuses in Python’s words, negative shift count (value_error), and a left shift whose result leaves the int range refuses as any integer overflow does. @ and @= read, of *’s level, and no value here answers them: each is a type error naming its operands, unsupported operand type(s) for @: 'int' and 'int'. → Python Specification §8.3

abs(x) — the built-in absolute value: abs(-5) is 5, abs(-3.5) is 3.5; it keeps the argument’s numeric type and takes exactly one number (a non-number, or a different argument count, is a type error). The abs of a complex is its magnitude, a real: abs(3 + 4j) is 5.0.

round(x[, n]) — half-to-even (“banker’s”) rounding: round(0.5) and round(2.5) are 0 and 2, round(0.125, 2) is 0.12. The optional digit count n is an int (negatives allowed: round(35, -1) is 40). Result type: round(int, …) → int; round(real) (no n) → int; round(real, n) → real (a real even at n = 0, so round(2.5, 0) is 2.0). Rounding follows the stored double, so round(2.675, 2) is 2.67 (matching CPython).

sum(iterable) / min(…) / max(…) — reduce an in-memory iterable, distinct from the same-named store-aggregate folds sum(K.attr) / … (the argument shape selects: a bare K.attr path → fold; anything else → this reduce). sum adds numeric elements (all-int → int, empty → 0, any real → real, complex elements → complex, so sum([1j, 2j]) is 3j; over a list of both classes, §6.7, the class the additions give — sum([1, 2.5]) is 3.5). Where any element or the start is a real and none is a complex, the sum is the exact sum of the start and every element, rounded once: sum([0.1] * 10) is 1.0, where Python 3.11 answers 0.9999999999999999, and an int enters as the integer it is. It is refused as arithmetic_overflow only when that rounded value, or an all-int total, is out of range, and a zero sum is -0.0 only when the start and every element are. A sum holding a complex is, in each part, that part’s exact sum rounded once: sum([0.1j] * 10) is 1j, where Python 3.11, adding left to right, answers 0.9999999999999999j. A start value, sum(xs, 10) or sum(xs, start=10), is added first, as in Python: sum([1, 2], 10) is 13, an empty iterable answers it, and a real one makes the sum real. A start that is not a number takes what + adds to it: a list or tuple start concatenates (sum([[1], [2]], []) is [1, 2], and a tuple sum has a runtime length), a duration start adds lengths and a datetime start is shifted by each duration. A start + cannot keep adding the elements to is refused, and so is a string start, as Python refuses it. min/max take one iterable or two-plus scalar values → the extreme in sorted’s order (numbers by value, a scientific by its magnitude, strings lexicographically, a datetime chronologically, a duration by length; the first of two equal elements); elements/values must share an orderable type (numeric, scientific, string, datetime, duration, or a nested list/tuple of those — the comparison recurses), and a scientific shares one with any number. An int and a real compare by value and the extreme keeps its class: min([1, 2.5]) is 1. min/ max of a runtime-empty iterable is a catchable refuse (ValueError), unless a keyword-only default=<value> is supplied — min([], default=0) is 0 — which is returned only when the iterable is empty and whose type must match the element type (min(<iterable>, default=…); default= is invalid with multiple positional values).

key=<name> on min, max and sorted — compares the elements by what the named function returns for each: max(words, key=len) is the longest word, sorted(words, key=len) is shortest first. The name is a builtin taking one argument (len, abs, ord, str, …), a method of a built-in type (key=str.lower, over elements of that type), or a script — declared in the unit, imported by from, or key=m.f — called once per element, in order. Only the keys are compared, so only they must be orderable: max([{"a": 1}, {}], key=len) is {'a': 1}. Equal keys keep their order: min/max return the first of them, and sorted is stable both ways, so sorted(["bb", "a", "cc"], key=len, reverse=True) is ['bb', 'cc', 'a']. key= goes with default= or reverse= in either order. It takes a name and nothing else — a lambda, a method of a value such as d.get, a call or an expression is a parse_error (write a def that computes the key and name it), key=None is too (leave key= out), and sum and the store fold min(K.attr) take no key=. DKE Python has no lambda because a lambda is a function held as a value, and no type holds a function.

divmod(a, b) — the floored quotient and the remainder as one pair, equal to (a // b, a % b): divmod(7, 2) is (3, 1) and divmod(-7, 2) is (-4, 1) (the quotient floors toward negative infinity, the remainder takes the divisor’s sign, and q * b + r == a always holds). Both operands must be numeric, and the pair promotes together — tuple<int, int> for two ints, tuple<real, real> when either is real, never a mixed pair: divmod(7.5, 2) is (3.0, 1.5). An element of a list of both classes (§6.7) gives a pair whose one class is the element’s: divmod([1, 2.5][1], 2) is (1.0, 0.5). A zero divisor, and the most-negative int over -1, are catchable refuses.

reversed(xs) — an iterator<T> (§6.12) over the elements in the reverse of the order for walks them, so a dict contributes its keys, a set its sorted elements and a dict view what it views, backwards: "".join(reversed("abc")) is "cba", and list(reversed(xs)) is a reversed copy. An iterator is not an argument, as in CPython, since an iterator reads only forwards.

sorted(xs[, key=<name>][, reverse=<bool>]) / any(xs) / all(xs) — sorted returns a new list<T> in ascending order (descending with reverse=True; a stable sort, key= and reverse= keyword-only, a key as above); without a key the elements must be orderable — numeric, scientific, string, datetime, duration, or a nested list/tuple of those (the sort recurses lexicographically, so sorted([[10], [2], [1, 3]]) is [[1, 3], [2], [10]]). ints and reals sort by value and keep their classes (sorted([3, 2.5]) is [2.5, 3]). A keyword sorted or a list’s sort does not take is a type error in Python’s words, named for sort() as Python names it ('x' is an invalid keyword argument for sort()). any/all fold truthiness (§6.2) to a bool — any([]) is False, all([]) is True.

format(value, spec) / repr(value) — format renders a value per the Python format mini-language, with the empty spec if it is given none (format(3.14159, ".2f") → "3.14", format(42, "05") → "00042", format(255, "x") → "ff", format(1234.5, ".2") → "1.2e+03", format(65, "c") → "A"): [[fill]align][sign][z][#][0][width] [grouping][.precision][type]. The fill is any one character and align is <, >, ^ or =, which pads between a number’s sign and its digits (format(-5, "*=6") → "-****5"). An int or bool takes d x X o b c n and every type a real takes; a real takes e E f F g G n %, a string s. A precision counts decimals under e, f and %, significant digits under g, n and with no type, and characters on a string; an int takes none. A bool formats as its int once any spec is written. + and a space write a positive number’s sign (format(5, "+") → "+5"), z drops a negative zero’s, # writes a prefix or keeps a point (format(5, "#b") → "0b101"), and , and _ group digits (format(1234567, ",") → "1,234,567"), each as in Python. A type the value does not take is a catchable refuse; so are =, a sign, z or # on a string, and c of a number that is no character’s code point. A collection (a list, tuple, dict, set, a dict’s views, a slice) takes no format spec: a non-empty one is refused wherever it is written, in format, an f-string, str.format and __format__ called by name, and an empty one answers str of the value. A complex formats as in Python: format(3 + 4j, ".2f") is "3.00+4.00j", a precision alone counts significant digits in each part (format(3.14159 + 2j, ".3") is "(3.14+2j)"), it takes e E f F g G n, it is right-aligned by default, and zero padding or = is a catchable refuse. repr(x) gives the repr text (a string keeps its quotes, and a character Python would not print, such as a no-break space, is escaped: repr("a\xa0b") is "'a\\xa0b'"). Both power f-string {v:spec} / {v!r} (§6.4a).

ord(s) / chr(i) — the Unicode codepoint round-trip. ord(s) returns the integer codepoint of a one-character string (ord("A") is 65, ord("æ") is 230); a string of any other length is a catchable refuse. chr(i) returns the one-character string for a codepoint i in range(0x110000) (chr(97) is "a", chr(937) is "Ω"); an i outside that range — or a lone surrogate (U+D800..U+DFFF), which has no UTF-8 encoding — is a catchable refuse.

bin(n) / hex(n) / oct(n) / ascii(x) — text for a value, as Python writes it. bin, hex and oct write an int in base 2, 16 or 8 behind 0b, 0x or 0o, lowercase and unpadded: hex(255) is "0xff", oct(0) is "0o0", and a negative number is signed, bin(-5) being "-0b101". int(s, base) reads each back. ascii(x) is repr(x) with every character past U+007F escaped, so ascii("é") is "'\\xe9'"; with nothing to escape it equals repr. Each takes exactly one argument, and bin, hex and oct an int or a bool.

pow(base, exp[, mod]) — with two arguments, base ** exp itself: pow(2, 10) is 1024 and pow(2, -1) is 0.5, and it refuses as ** does. With a third, modular exponentiation over ints, computed below the modulus so any exponent finishes: pow(2, 10, 1000) is 24, pow(3, -1, 7) is 5 (a negative exponent raises the base’s inverse), and the answer takes the modulus’s sign, so pow(2, 3, -5) is -2. A zero modulus, and a base with no inverse, are catchable refuses (value_error). A non-integer in the three-argument form is a type error in Python’s words: a real is refused, pow() 3rd argument not allowed unless all arguments are integers, a complex complex modulo, and anything else names the three classes, unsupported operand type(s) for ** or pow(): 'int', 'str', 'int'.

Type conversions. str(x) renders any value to text (total, the +/print rendering); int(x) and float(x) convert a string / int / real / bool, or an element of a list of both number classes (§6.7), to an int / real. int(3.9) truncates toward zero (3), int(" -7 ") is -7, and _ separates digits as it does in a literal (int("1_000") is 1000, float("1_000.5") is 1000.5); a string that is not a valid number (int("abc"), int("3.5")) or an out-of-range value is a catchable refuse (Python ValueError). A decimal digit of any script reads as its value and a Unicode space pads, as in Python: int("٥5") is 55. With no argument each conversion is the zero of its type, as in Python: int() is 0, float() is 0.0, str() is "" and bool() is False. int(s, base) parses a string in an explicit radix: base is 2..36 (or 0 to auto-detect from a 0x/0o/0b prefix), a 0x/0o/0b prefix is accepted when it matches base, an optional leading sign and _ digit separators are allowed, and a digit outside the base, an out-of-range base, or a base-0 decimal with a leading zero refuses (int("ff", 16) is 255, int("0b101", 2) is 5, int("z", 36) is 35). An explicit base with a non-string value is a type error, as in Python. complex(re, im) builds a complex from two numbers, each keeping the sign of a zero, and complex(x) builds one from a single number, from a complex, or from a string holding the text a complex prints as (complex("3+4j"), complex("-2.5j")); with no argument it is 0j. Either argument of the two-argument form may itself be a complex, computed as in Python, so complex(1j, 2j) prints (-2+1j). A string that is not a complex is a catchable refuse (Python ValueError); a part spelled inf or nan, or past the range, is what float reads, as in Python: complex("inf") is (inf+0j). Arguments by name: an argument Python lets a caller name may be named here too, in any order after the positional ones — int(s, base=16), round(number=x, ndigits=2), complex(real=1, imag=2), pow(base=2, exp=10, mod=1000), str(object=x) and enumerate(iterable=xs, start=1). Each argument is evaluated where it is written, whichever position it fills, so pow(exp=xs.pop(), base=xs.pop()) pops the exponent first, as in Python. An omitted real is 0, so complex(imag=2) is 2j. The names given to dict are keys, each the string written in any language: dict(a=1) is {"a": 1}, and dict({"a": 1}, a=2, b=3) writes them over a positional argument’s entries, giving {"a": 2, "b": 3}. int’s text is positional only, as in Python, and a built-in function that takes no argument by name refuses one in Python’s words and says what to do instead: abs(x=1) is a type error beginning abs() takes no keyword arguments. A method’s names are listed with the method (§6.6, §6.9). Collection conversions: list(x) collects a finite collection’s elements (a dict view what it views, a string its characters, a tuple its elements — list((1,2,3)) → [1, 2, 3], the element type what a for over the tuple binds, §6.8) into a list; set(x) collects them into a deduped (1 and 1.0 once), sorted set (elements must be hashable — a scalar or a tuple of hashables); dict(x) builds a dict<K, V> from another dict — a new dict holding its entries — or from any other collection of pairs, read as update reads one: a list<tuple<K, V>>, a tuple of them, an iterator<tuple<K, V>> or a dict_items<K, V> — dict(zip(keys, vals)); tuple(x) collects the elements into a variadic homogeneous tuple tuple<T, ...> (runtime length, indexed by a runtime int, unpacked as a list is), and accepts a fixed tuple too — which is how a fixed tuple is widened to a variadic one. Called with no argument, each gives the empty collection, as in Python: list() → [], dict() → {}, tuple() → (), set() → set(). bool(x) returns the truthiness (§6.2) of any value as a bool (bool([]) → False, bool("x") → True).

6.4 Concatenation

+ joins two strings into a new string. A string + a non-string operand is a type error (as in Python, which raises TypeError) — convert the non-string side with str(…) ("count = " + str(xs.length)); there is no implicit string coercion. An f-string applies str(…) to each field for you (§6.4a). With two list operands + concatenates into a new list: [1, 2] + [3, 4] is [1, 2, 3, 4]. xs += ys, xs.append(v) and xs.extend(ys) change xs in place to the same concatenation (§7.17), and xs += c takes any collection, as extend does: xs = [1] then xs += (2, 3) leaves [1, 2, 3]. The result element type follows the list-literal rule (§6.7): same type → list<T>, differing scalars → list<value> ([1] + [3.5], holding numbers), an empty operand takes the other side ([] + [1]); a non-scalar mismatch is a type error. A list plus a non-list, non-string operand is a type error.

With two tuple operands + concatenates into a new immutable tuple: (1, 2) + (3,) is (1, 2, 3). A tuple is heterogeneous, so the result keeps each operand’s positions and their types rather than settling on one element type — tuple<int, string> + tuple<bool> is tuple<int, string, bool>, and a constant index into the result reads the position it names (after t = (1, "a") + (5,), t[2] is an int). The empty tuple takes the other side (() + (1,)). A tuple plus a non-tuple operand is a type error. When one side is a tuple whose length is only known at run time, the result is too, so it needs a single element type covering both sides — the same unification list concatenation uses, and element types that do not unify are a type error.

print("count = " + str(xs.length))
print("items = " + str(xs))
combined = xs + [99]              # concatenate two lists
pair = (1, "a") + (True,)         # concatenate two tuples

Either quote — a string opens with " or ' and ends at the next of the same, so 'a' and "a" are one string and the other quote is ordinary content: "it's", 'say "hi"'. A prefix u or U changes nothing. A printed collection of strings, ['a', 'b'], reads back as written.

Adjacent literals — two or more string literals separated only by whitespace are joined at compile time, with no +, so a long constant can span lines without a run-time concatenation: "one " "two" is "one two" and "a" "b" "c" is "abc". An f-string joins the run too, in either order and any mixture (f"a" "b", "a" f"{x}", f"{x}" f"{y}"), which is the idiomatic way to write a long interpolated message across lines — and the whole run is one interpolated string, costing what the single f-string it replaces costs. A typed value (datetime("…"), duration("…"), blob("…")) does not join: concatenation is for strings. Render one with str(…) and use +, or interpolate it.

Triple-quoted literals — a string delimited by """ runs until the next """, so it may span multiple lines (each newline is a literal \n) and hold lone "/"" characters without escaping: """line one … line two""". The escapes are the same as a string in one quote and the value is an ordinary string. ''' is the same with the other quote, and an f-string may be triple-quoted too.

Raw strings — an r or R prefix makes a backslash an ordinary character: it stays in the value with the character after it, so r"a\n" is three characters and r"C:\path" is the path as written. A backslash still keeps the next " from ending the literal, so a raw string cannot end in one backslash. A raw string may be triple-quoted, joins an adjacent run like any string, and combines with f as rf"…" or fr"…", where a brace still opens a field (Python Specification §3.5.1).

Escapes — a backslash inside a string begins an escape: \\ a backslash, \" a double quote, \' a single quote, \n line feed, \t tab, \r carriage return, \a bell, \b backspace, \f form feed, \v vertical tab. Three take hex digits and are written into the value as UTF-8: \xNN is a codepoint up to U+00FF from exactly two digits — so "\x85" is the same one-character string as "\u0085", as in CPython — \uNNNN one up to U+FFFF, and \UNNNNNNNN a codepoint up to U+10FFFF — the only escape that reaches above the BMP. One more names its codepoint rather than numbering it — \N{name}, below. One to three octal digits name a codepoint, so "\101" is "A", and a backslash at the end of a line continues the string on the next line. Anything else after a backslash stays in the value with the backslash, as in CPython: "\d" is two characters, the same string as "\\d". Two values are refused rather than encoded: a surrogate (U+D800..U+DFFF, written either way), and any escape that would produce a NUL — \0, \x00 and \u0000 alike — so a string never carries an interior NUL.

Named-character escape — \N{name} is the codepoint with that Unicode character name, matched case-insensitively, across every script: "\N{BULLET}" is "•", "\N{GREEK SMALL LETTER ALPHA}" is "α", and "\N{CJK UNIFIED IDEOGRAPH-4E00}" is "一". A name Unicode does not assign is a parse error.

6.4a Formatted strings (f-strings)

An f-string — a string literal with an f (or F) prefix — writes a value into text directly: each { … } field holds an expression that is evaluated and written in place. f"a{x}b" has the same value as "a" + str(x) + "b", so a field is rendered the way + renders that value (§6.4) and an f-string is always a string (even a lone field: f"{n}" is "42", not the int 42). A field holds any expression — a bound variable, arithmetic, a method call, an index or slice; a store read is bound to a name first (§7.2), as with +. Write {{ or }} for a literal brace. A field may carry a conversion and/or a format spec: {x!r} uses repr(x), {x!s} uses str(x); {x:spec} applies the format mini-language — f"{x:.2f}", f"{n:>5}", f"{s:*^8}" — and they combine ({x!r:>10}). A field may end in a self-documenting =: f"{x=}" writes the field’s source text up to the = (whitespace preserved) followed by the value, defaulting to repr — f"{x=}" is "x=5", f"{ x = }" is " x = 5", f"{s=}" is "s='hi'" — and a :spec/!conv overrides that default (f"{x=:.2f}" is "x=5.00"). A trailing ==/>=/<=/!= is a comparison, not the debug =. A spec may hold fields of its own, each replaced by its value before the spec applies: f"{x:>{w}}" pads x to the width w holds. A field may hold a string in the quote that does not enclose the f-string, as f"{d['k']}" does. Python’s two older ways to format a string read as Python’s do: "{}".format(x) and "{a}".format_map(d) (§6.6), and "%.2f" % x. A % with a string on its left takes the next element of a tuple on its right, or the one value that is not, and %(key)d looks its key up in a dict or a list. It knows s r a d i u o x X e E f F g G c, the flags, a width, a precision, * and %%. A fault in either refuses as the program runs, in Python’s words.

print(f"count = {xs.length}")
name = "Merlin"
print(f"hi {name}, first char {name[0]}, upper {name.upper()}")

6.5 Field access, indexing, and slicing

x.field (see §11) composes on any computed value — a method result, an index, or a slice — not only a bare name (text.upper().length, xs[0].value, hist[-1].source); a store read is still bound to a name first (§7.2). The builtin len(x) is an alias for x.length (a string’s character count, a blob’s byte count, or a collection’s element count). xs[i] (zero-based; index is int; out-of-range refuses). A string may also be indexed to read a single character (s[i] → a one-character string; a negative index counts from the end, so s[-1] is the last character) and sliced for a substring — s[a:b], with either bound optional (s[a:], s[:b], s[:]) and negative bounds counting from the end (s[-3:], s[:-1]), plus an optional step s[a:b:step] (a negative step reverses, so s[::-1] is s reversed and s[::2] is every other character). Slicing is total: it never refuses; bounds are clamped and an inverted range yields "" — the sole exception is a step of 0, a catchable refuse. A constructed list<T> indexes and slices by the same rules (xs[i], negative from-end permitted; xs[a:b:c] yields a new list<T>); from-end (negative) positions apply to a string and a constructed list, while a store-derived collection index is non-negative. Positions count characters (a string) or elements (a list). A tuple slices too — t[a:b] yields a tuple, the sub-tuple of the selected positions when its bounds are constant integers, and a variadic tuple of what a computed index reads when one is computed (§6.8); list(t[a:b]) converts the result to a list. An index of another type than int is refused at compile, in Python’s words over a string, a list or a tuple: list indices must be integers or slices, not str for [1]["a"].

A blob indexes, slices and joins as Python’s bytes do, over its bytes: b[i] is the byte at i as an int from 0 to 255, a negative i counting from the end; b[a:b:c] is the blob of the bytes selected, by the rules of a string’s slice, a negative step walking from the high end and a step of 0 a catchable refusal; and b1 + b2 is the blob of the bytes of b1 and then those of b2. A position past either end refuses with index out of range (index_out_of_bounds), and an index of another type than int is refused at compile, byte indices must be integers or slices, not str. Each is one operation, however long the blob, and builds no cells (Python Specification §3.5.8).

b = blob("000102030405FF")
print(b[1:4])        # 010203
print(b[::-2])       # FF040200
print(b[0], b[-1])   # 0 255
print(b[:2] + b[5:]) # 000105FF

A slice is also a value. slice(stop) or slice(start, stop[, step]) builds one. Each argument is an int, a bool or None, and None or a bound left out is open, so slice(5) is slice(None, 5, None), which is also how it prints. xs[s] selects what xs[a:b:c] with the same bounds selects, from a string, a list or a tuple, a fixed-length tuple reading it as a computed bound (§6.8). On a list, xs[s] = c, xs[s] op= c and del xs[s] change what the bracketed slice would. s.start, s.stop and s.step read the bounds back as value, an open one being the null class, which prints null where CPython prints None. s.indices(n) answers the (start, stop, step) that xs[s] selects from a sequence of length n, refusing a negative n (value_error) before a zero step (slice_step_zero). Two slices are == when their bounds are. A slice has no order and no .length, is always true, is not hashable (so it is no set element and no dict key), and is never stored.

6.6 String methods

A string carries these built-in methods (all character-counting, all total except split, the justify family, and index/rindex, noted below): - s.find(sub[, start[, end]]) → int / s.rfind(...) → int — the first / last position of sub, or -1; the optional start[, end] window searches s[start:end] and the index is into the whole s. - s.index(sub[, start[, end]]) → int / s.rindex(...) → int — like find / rfind, but a missing sub refuses (catchable, §10) instead of returning -1. - s.count(sub[, start[, end]]) → int — the number of non-overlapping occurrences of sub in the window (an empty sub yields the window’s length + 1). - s.startswith(prefix[, start[, end]]) → bool / s.endswith(suffix[, ...]) → bool — whether the window of s begins / ends with the argument (an empty argument yields True). The argument may instead be a tuple of strings — True if the window matches any of them (an empty tuple yields False). - s.replace(old, new[, count]) → string — a copy of s with each non-overlapping occurrence of old replaced by new, at most count times when given (an empty old inserts new in every gap, as in CPython: "abc".replace("", "-") → -a-b-c-). - s.upper() → string / s.lower() → string — the full Unicode case mapping. A character may expand to more than one ("straße".upper() is "STRASSE", "file".upper() is "FILE", "İ".lower() is "i̇"), so a case transform can change the length (which .length reflects). lower() also applies the Greek word-final rule ("ΟΔΟΣ".lower() is "οδος", final ς). - s.capitalize() → string — first character titlecased, the rest lowercased. - s.title() → string — the first character of each word titlecased, the rest lowercased (a word is a run of cased characters; any non-letter, including an apostrophe, starts a new word — so "they're".title() is "They'Re"). - s.swapcase() → string — each uppercase character lowercased and vice versa. (These four case transforms use the full Unicode mapping above, including the Greek word-final rule where they lowercase.) - s.casefold() → string — aggressive, context-free folding for caseless matching: like lower but more so ("STRAßE".casefold() is "strasse", "fi" folds to "fi"), and it does not apply the Greek word-final rule, so "ΟΔΟΣ".casefold() is "οδοσ" (a medial σ, unlike .lower()’s "οδος"). Use a.casefold() == b.casefold() for caseless equality. - s.zfill(width) → string — left-pad with '0' to width characters, keeping a leading +/- sign first; width ≤ s.length is a no-op. - s.ljust(width[, fill]) / s.rjust(width[, fill]) / s.center(width[, fill]) → string — justify s in a field of width characters, padding right / left / both with fill (a single character, default space). width ≤ s.length is a no-op; a fill that is not exactly one character refuses (catchable). - s.strip([chars]) / s.lstrip([chars]) / s.rstrip([chars]) → string — s with characters removed from both ends / the left / the right. With no argument they remove whitespace; with a chars argument they remove any character that occurs in the chars set. - s.removeprefix(prefix) / s.removesuffix(suffix) → string — s with a leading prefix / trailing suffix removed if present, else s unchanged (an empty suffix is a no-op). - s.expandtabs([tabsize]) → string — each tab replaced by spaces to the next tab stop (multiple of tabsize, default 8); the column counts characters and resets after \n/\r. tabsize ≤ 0 removes tabs. tabsize may be named: s.expandtabs(tabsize=4). - s.split([sep[, maxsplit]]) → list<string> — the substrings of s split at each occurrence of sep (empty pieces kept); an optional maxsplit caps the splits (≤ maxsplit + 1 pieces). With no argument, s splits on runs of whitespace, dropping empty pieces. An explicit empty separator is a catchable refuse (§10). Both arguments may be named, s.split(sep=",", maxsplit=1), and naming maxsplit alone bounds a whitespace split, keeping the rest as one piece: " a b c ".split(maxsplit=1) is ['a', 'b c ']. - s.rsplit([sep[, maxsplit]]) → list<string> — like split, but a bounded maxsplit takes its splits from the right ("a,b,c".rsplit(",", 1) is ['a,b', 'c']); with no maxsplit the result equals split. It takes the same names, and " a b c ".rsplit(maxsplit=1) is [' a b', 'c']. - sep.join(xs) → string — the strings xs yields, concatenated with sep between adjacent ones: xs is a string (its characters), or a list, tuple, set, dict (its keys) or iterator of strings, and an empty one yields "". "-".join("abc") is "a-b-c". Elements of any other type are a type error, in Python’s words: "a".join([1]) is refused with sequence item 0: expected str instance, int found, and "a".join(1) with can only join an iterable. - s.partition(sep) / s.rpartition(sep) → tuple<string, string, string> — split s once at the first / last occurrence of sep into (before, sep, after); when sep is absent, partition yields (s, "", "") and rpartition yields ("", "", s). An explicit empty separator is a catchable refuse (§10). - s.translate(table) → string — s with each character whose code point table holds replaced by what it holds for it: an int or bool is a code point, a string stands as written, and any other character stays. A dict from code points, as str.maketrans makes one (§11), finds a code point as any dict does, so 97.0 is the key 97. A list, a tuple or a string is indexed by it, and a character past its end stays. A table of any other type, a value of any other type, a code point outside range(0x110000) or a surrogate is a catchable refuse (§10), when a character reaches it. - s.format(*args, **kwargs) → string — s read as a template, as Python reads it: each {} takes the next positional argument, {0} the one at that position and {a} the keyword. After that, .x reads a field and [w] an item, !r, !s and !a convert, and :spec is what format(value, spec) takes (§6.4a). {{ and }} are a brace. .x on an instance refuses as the program runs, since the store is not read in the middle of an expression: bind the field to a name and pass that. A fault refuses in Python’s words: key_not_found for a name no argument holds, index_out_of_bounds for a position past the last, type_error or value_error for the rest. - s.format_map(m) → string — as format, every name looked up in m. - s.splitlines([keepends]) → list<string> — the lines of s, split at each of CPython’s eleven line boundaries: \n, \r\n, \r, the vertical tab, the form feed, the three C0 separators, U+0085, U+2028 and U+2029 — with the trailing-newline empty line dropped ("" yields []). With a true keepends, given by position or by name, each line keeps the boundary that ends it: "a\r\nb".splitlines(keepends=True) is ['a\r\n', 'b']. - Arguments by name: the names above are the only ones a method takes, as in Python, besides a list’s sort (key=, reverse=) and a dict’s update, whose names are keys. Any other method refuses a name in Python’s words, naming the receiver’s Python class: s.center(width=9) is a type error beginning str.center() takes no keyword arguments. - Arguments of a type a method does not take are a type error in Python’s words, which differ by method as CPython’s do: "abc".find(1) is refused with must be str, not int, "abc".replace("a", 1) with replace() argument 2 must be str, not int, "abc".split(1) with must be str or None, not int and "abc".zfill("a") with 'str' object cannot be interpreted as an integer. A search’s bounds are a slice’s: "abc".find("a", 2.5) is refused with slice indices must be integers or None or have an __index__ method, and a list’s or a tuple’s index bounds with slice indices must be integers or have an __index__ method. A list’s insert position is an integer: xs.insert("a", 2) is refused with 'str' object cannot be interpreted as an integer. An argument of a type Python has no class for, such as a claim’s value, is told which type the method takes. - The character-class predicates — each () → bool, testing every character of s against its Unicode class: s.isspace(), s.isdigit(), s.isdecimal(), s.isnumeric(), s.isalpha(), s.isalnum(), s.isupper(), s.islower(), s.istitle(), s.isascii(), s.isprintable(), s.isidentifier(). All but isascii and isprintable are False on the empty string (the whole-string rule is “non-empty and all characters match”); "".isascii() and "".isprintable() are True. isupper/islower require at least one cased character and no character of the opposite case; istitle tests the titlecase pattern. They classify by full Unicode, so "blåbær".islower() and "ÆØÅ".isalpha() are True. isprintable is False for a control, a format character, any separator but the space, and a private-use or unassigned codepoint. isidentifier asks what Python asks of a name, and reserves no keyword: "class".isidentifier() is True.

domain = email.strip()[email.find("@") + 1:]
label  = raw.replace("_", " ").upper()
paid   = invoice.endswith("PAID")
tidy   = title.strip("*_ ")
parts  = "a,b,c".split(",")          # ['a', 'b', 'c']
line   = " ".join(["a", "b", "c"])   # "a b c"
addr   = "user@host".partition("@")  # ('user', '@', 'host')
rows   = "one\ntwo".splitlines()     # ['one', 'two']
digits = code.isdigit()              # True if code is all digits
at     = path.index("/")             # position of "/", or refuses if absent

6.7 Constructed lists and comprehensions

A list literal [e1, e2, …] builds a constructed list<T> (shared, bounded, existing only while the program runs and never stored). Elements are inferred to a common type: homogeneous → list<T>, mixed scalars → list<value>, empty [] → list<unknown>; lists nest. The empty list is compatible with any list<T> — wherever two list types must agree it takes the concrete side’s type: [1, 2] if c else [], a re-binding (xs = [] then xs = [1]), an annotated binding (xs: list<int> = [], and d: dict<string, int> = {} likewise), a nested sibling ([[1, 2], []] is list<list<int>>), ",".join([]), and [] == xs. The empty set set([]) and the empty dict {} are compatible the same way with any set and any dict, so the accumulator seen = set([]) then seen |= {w} binds a set<string> when w is a string. A constructed list is indexed, sliced, measured (.length), iterated (for … in), tested for membership (x in xs), searched (xs.index(v[, start[, end]]) → the first index of v, within an optional codepoint window and refusing if absent; xs.count(v) → how many times v occurs), compared (== / !=) and copied (xs.copy() → a new list holding the same elements); it renders in print and +. A list is shared: every name holding it holds the one list, and a statement that changes it — xs.append(v), xs[i] = v, del xs[i] and the rest of §7.17 — changes it in place, so every one of them sees the change.

A list mixing only ints and reals — [1, 2.5] — holds numbers. Its type is still list<value> and each element keeps its own class ([1, 2.5][0] is 1), but arithmetic, ordering, membership, sum / min / max / sorted, abs / round / divmod and int / float take its elements as numbers: min([1, 2.5]) is 1, sum([1, 2.5]) is 3.5 and [1, 2.5][1] + 1 is 3.5, as in Python. So do a set, a dict’s values and a tuple’s positions that mix the two classes, and whatever is read from them — an index, a loop or comprehension variable, a generator expression, + of two such lists. A result is a real where a real decides it ([1, 2.5][0] + 0.5, and /), and otherwise again a value holding a number, which satisfies no int or real annotation or parameter: convert it with int(…) or float(…). Anything that could bring a non-number in removes the property — a conditional expression or or choosing between [1, 2.5] and ["a", 1], a re-binding, a nested literal. A bool is a number here, the int it is, as in Python: sum([True, 2]) is 3, True in [1, 2.5] is True, and max([True, 0]) is True, the element itself. It is an int by class too, as in Python: [True, 2] is a list<int>, a parameter, annotation or return declared int takes a bool, so do an index, a bound and a repetition count, and a case int arm over a value takes True — write case bool above it to tell the two apart. It keeps its class, so x: int = True prints True. A list<bool> is still not a list<int>, since a list is shared. Python Specification §6.4 and §8.1 state the rule.

A list mixing a scientific with numbers — [scientific("2.0e0"), 1] — holds magnitudes: its elements order by magnitude, as a scientific does (§6.1), so sorted, min and max take it and sorted([scientific("2.0e0"), 1, 2.5]) is [1, 2.0e0, 2.5]. They compute nothing, so arithmetic and sum refuse them. The same holds for a set, a dict’s keys or values and a tuple’s positions, for whatever is read from them, and for min or max of a scientific and a number. Python Specification §5.6 states the rule.

A comprehension [expr for x in xs if cond] builds a new list by bounded iteration: it binds each element of the finite source xs to x, keeps those the optional cond (truth-tested) admits, and collects expr. The loop variable is comprehension-local (it may shadow an outer name and does not leak). Over an empty source whose element type nothing supplied, a comprehension is empty, and what reads x is not checked (§7.7): [x.upper() for x in []] is list<unknown>. A clause may name a target list of two or more names, or one name and a trailing comma ([k for k, v in d.items()]), which destructures each element the way a for statement does (§7.7): the element must be a tuple of that arity or a list. Nested targets ([c for a, (b, c) in xs]) and one optional starred target ([r for a, *r in xs]) are taken here as they are everywhere else, the star making the arity a minimum. A clause’s targets are names — an element target goes in a for statement, which has a body to write it in. Multiple for clauses form the flat cartesian product ([a + b for a in xs for b in ys]) — the first clause is the outermost loop, and a later clause’s source may reference earlier loop variables ([y for row in grid for y in row]); a clause may carry several if filters (applied conjunctively, each asked only for its truth value). A comprehension whose result is itself a comprehension also nests.

nums    = [3, 1, 4, 1, 5]
evens   = [n for n in nums if n % 2 == 0]     # [4]
caps    = [w.upper() for w in "a,b".split(",")]  # ['A', 'B']
grid    = [[x for x in nums] for r in caps]   # list<list<int>>
pairs   = [a + b for a in [1, 2] for b in [10, 20]]  # [11, 21, 12, 22]
flat    = [y for row in [[1, 2], [3, 4]] for y in row]  # [1, 2, 3, 4]

A generator expression is a comprehension written in a call’s parentheses instead of brackets, sum(x for x in xs). It is accepted as the whole argument of a call that reads every element before it returns: sum, min, max, any, all, sorted, list, tuple, set, dict, a string’s join, a set’s union, intersection, difference, symmetric_difference, issubset, issuperset and isdisjoint, a list’s extend, a set’s update, difference_update, intersection_update and symmetric_difference_update, and a dict’s update. There it means the bracketed comprehension, except that any and all stop at the element that decides, and a set’s update and difference_update and a dict’s update read it one element at a time (§7.17), as Python’s do. Beside another argument it is written in its own parentheses, sorted((x for x in xs), reverse=True). Written bare beside another argument, in a call of any kind, it is a grammar error at its start, as in Python, so print(1, x for x in xs) is refused at column 10. In its own parentheses right after a *, in a call or a display, it is read the same way, since the * reads every element first: print(*(x for x in xs)), [*(x for x in xs)]. Anywhere else it would be a generator object, which DKE Python does not have: bound to a name, returned, printed, or passed to len, enumerate, zip, a method not listed here or a script, it is refused with a message naming [… for … in …].

nums    = [3, 1, 4, 1, 5]
total   = sum(n * n for n in nums)                     # 52
big     = any(n > 3 for n in nums)                     # True
ordered = sorted((n % 3 for n in nums), reverse=True)  # [2, 1, 1, 1, 0]

6.8 Tuples

A tuple literal (e1, e2, …) builds a constructed tuple<T1, …, TN> — a fixed-length, heterogeneous sequence in which each position keeps its own type (immutable, bounded, never stored). A comma makes the tuple: (e) is a grouped expression, (e,) a one-element tuple, (a, b) a two-element tuple, () the empty tuple; tuples nest (((1, 2), 3) is a tuple<tuple<int, int>, int>). After return and on the right of an assignment the parentheses may be left off, as in CPython: return 1, 2 returns (1, 2), and x = 1, binds (1,). A tuple indexed by a compile-time constant integer reads that position’s own type — t[0] the first position’s, t[-1] the last’s. A computed index reads what a for over the tuple binds, below, and is a compile-time error only over a tuple holding a collection beside a value of another type (every position stays reachable by a literal index); an index past either end refuses when it runs, catchably, as Python’s IndexError does. It is measured with .length and compared with == / != against any value — (1, 2) == (1,) is False, and so is (1,) == ("a",). A tuple is written after for … in when its positions share one type, are all scalars, which the loop variable takes as a value (§6.7, §7.7), or are all class instances, which it takes at their common base (§8.10); a tuple holding a collection beside a value of another type has no single element type to bind, so index it instead. It renders in print and + as (e1, e2, …), a one-element tuple as (e,). Two tuples concatenate with + (§6.4), the result keeping every position’s own type. A tuple is searched (t.index(v[, start[, end]]) → the first position of v, within an optional window and refusing if absent; t.count(v) → how many positions hold v) wherever v in t is allowed, comparing v with every position as == does — (1, "a").index("a") is 1, and a missing value refuses as tuple.index(x): x not in tuple. A fixed tuple whose positions all agree with T is a tuple<T, ...>, a tuple being immutable, so it fills one wherever that variadic type is declared — as a value, inside a collection literal written at the declaration (ts: list<tuple<int, ...>> = [(1, 2)]), by an element write (ds[k] = (1, 2)), and by append / insert / extend. A collection a name already holds is not widened into a second name, a list being shared.

point = (3, 4)             # tuple<int, int>
x     = point[0]           # 3      — constant index
at    = point.index(4)     # 1
mixed = (1, "ana", True)   # tuple<int, string, bool>
same  = (3, 4) == point    # True
wide  = point + (5,)       # tuple<int, int, int>

6.9 Dicts

A dict literal {k1: v1, k2: v2} builds a constructed dict<K, V> — a mapping from hashable keys (a scalar or a tuple of hashables) to values, kept in insertion order (shared as a list is, bounded, never stored). Keys are drawn from a scalar value class (string / int / bool / datetime / duration / real / blob / scientific / complex), a value, or a tuple of hashables, and are homogeneous (a mix of scalar value classes gives a value-typed key part, and any other mix, such as a tuple beside a string, is a type error naming the two types, in a literal or written by d[k] = v, since a value holds a scalar); values join as a list’s elements do: a mix of scalar value classes gives a value-typed value part, holding numbers when all are ints and reals (§6.7), collections whose elements meet are one type ({"a": [1], "b": []} is a dict<string, list<int>>), and instances of several subclasses take their common base (§8.10). The empty dict is {}. When a key is written twice the entry keeps its first position but takes the last value ({"x": 1, "x": 9} is {'x': 9}). A key matches by value, so an int and a real of equal value are one key, as in Python — {1: "a", 1.0: "b"} is {1: 'b'}, and a bool and the int it is are one key too, {True: "a", 1: "b"} is {True: 'b'} — and the keys of a dict of int and real keys hold numbers in the §6.7 sense (sum({1: "a", 2.5: "b"}) is 3.5). A **d entry gives every entry d holds at that place, so {**d, "a": 0} keeps 0 for "a", and d | e is the same merge as {**d, **e}. A list, a set or a dict cannot be a key: writing one is told unhashable type: 'list', and so is looking one up, as the program runs, whatever the dict holds ([1] in d, d.get([1], 0)). A dict is: - read by key — d[k] returns V; the key is compared with the keys as == does (a number finds a key of either class, {1: "a"}[1.0] is 'a'), and a key absent at run time, or of another type, is a catchable refuse (§10), never a silent default; - tested — k in d / k not in d over its keys (§6.1a); - measured — .length, its entry count; - walked — for k in d: binds each key in insertion order (§7.7); - viewed — d.keys() → dict_keys<K>, d.values() → dict_values<V>, and d.items() → dict_items<K, V>, each a view that reads the dict in insertion order as it stands whenever the view is read (below); - read defensively — d.get(key, default) returns the value for key, or default when the key is absent. A default is required (there is no None for a 1-argument form); the result type is the join of V and the default’s type; - copied — d.copy() or dict(d) → a new dict holding the same entries; - changed — d[k] = v, d[k] += v, del d[k], d.update(e) and d.clear() are statements that change d in place (§7.17). update also takes names, each written as a string key: d.update(a=1) sets d["a"], and d.update(e, a=1) applies e first.

It renders in print and + as {k1: v1, k2: v2} in insertion order. Two dicts compare with == / != order-independently — equal when they hold the same key→value mapping regardless of insertion order ({"a": 1, "b": 2} == {"b": 2, "a": 1} is True); its key and value types must meet, and an empty dict unifies with any dict.

ages = {"ana": 30, "bo": 25}
ages["ana"]                   # 30
"bo" in ages                  # True
names = ages.keys()           # dict_keys(['ana', 'bo'])
pairs = ages.items()          # dict_items([('ana', 30), ('bo', 25)])

Views. A view follows its dict, as Python’s does: after names = ages.keys() and ages["cy"] = 41, names holds "cy". It is walked by for and a comprehension, read by the conversions (list(v), set(v), dict(ages.items())) and by every builtin that reads a collection, has a length (len, .length) and a truth value, and takes in. It has no position: names[0] is a type_error in Python’s words, 'dict_keys' object is not subscriptable, naming list(...). A keys or items view is set-like — it equals a set holding its elements, takes & | - ^ beside any collection on either side, as Python’s does, and < <= > >= beside a set or another such view, answering a set: {"a": 1}.keys() & ["a"] is {'a'}. A number beside a view is a type_error in Python’s words, 'int' object is not iterable. Of the set methods it has isdisjoint alone. A values view equals only itself. A view prints as Python’s does and is not a key or set element. An annotation writes one dict_keys<K>, dict_values<V> or dict_items<K, V>.

6.10 Sets

A set literal {a, b, c} (no colons) builds a constructed set<T> — a collection of unique hashable elements — a scalar, a value, or a tuple of hashables (shared as a list is, bounded, never stored). A { … } with a colon is a dict (§6.9), so — because the empty braces {} are the empty dict — the empty set has no literal: write set(), as in Python, or set([]); either renders set(). Elements are homogeneous (a mix of scalar value classes gives a set<value>, holding numbers when all are ints, reals and bools, §6.7, and any other mix, such as {1, (1, 2)}, is a type error naming the two types, as a list’s is); duplicates are removed at construction, and an int, a real and a bool of equal value are duplicates, as in Python, the first written kept ({1.0, 1} is {1.0}, {True, 1} is {True}). A set renders and is walked (for x in s:) in a deterministic sorted order — a defined refinement of Python, whose set order is unspecified. It is the order sorted(s) gives: numbers rank by value, an int and a real together, so {2.5, 1, 3} renders {1, 2.5, 3} and a loop over {2, 1.5} meets 1.5 first. A set is: - tested — x in s / x not in s (§6.1a); - measured — .length; - combined — s | t (union), s & t (intersection), s - t (difference) and s ^ t (symmetric difference), or the methods s.union(t), s.intersection(t), s.difference(t) and s.symmetric_difference(t), each returning a new sorted set, where union, intersection and difference take any number of collections and with none answer a copy of s; - compared — == / !=, element-wise and order-independent; s <= t (subset), s < t (proper subset), s >= t (superset) and s > t (proper superset); and the methods s.issubset(t), s.issuperset(t) and s.isdisjoint(t); - copied — s.copy() → a new set holding the same elements; - changed — s.add(x), s.discard(x), s.remove(x), s.update(t), s.difference_update(t), s.intersection_update(t), s.symmetric_difference_update(t) and s.clear() are statements that change s in place (§7.17). update, difference_update and intersection_update take any number of collections, and with none change nothing.

An operator takes two sets, or a set and a dict’s keys or items view, which also takes any collection (§6.9). A method takes any collection set(t) would — a set, list, tuple, string, dict (its keys) or generator expression — as Python’s do. An int, a real and a bool of equal value are one element to every relation ({1} <= {1.0} is True). A relation that only compares takes any element type, since an element of another type equals nothing: {1} <= {"a"} and {1}.issubset(["a"]) are False, {1}.isdisjoint(["a"]) is True, and {1} - {"a"}, {1} & {"a"} and .difference and .intersection keep s’s element type. |, ^, .union and .symmetric_difference keep elements of both, joined as a list literal’s are: a set of ints joined with a set of strings is a set<value>, as Python builds a mixed set, and one joined with a set of tuples is a type error, since a value holds no tuple. Joined in place, by |=, ^=, .update or .add, a set<int> that would hold a string is a type error, as a name keeps its type. On two integers |, & and ^ are bitwise (§6.3), and | on two dicts merges them (§6.9), d |= e changing d in place, e being anything update reads, so d |= [("b", 2)] too. On anything else but sets they are type errors.

s |= t, s &= t, s -= t and s ^= t change s in place to the new set, as xs += ys changes a list, so another name holding the set sees the change, as in Python (§7.17). Inclusion is a partial order ({1} < {2} and {2} < {1} are both False), so a list of sets is not sortable, and min and max do not take sets.

It renders in print and + as {e1, e2, …} in sorted order.

tags   = {"red", "green", "red", "blue"}   # {'blue', 'green', 'red'}  (unique, sorted)
"red" in tags                              # True
warm   = {"red", "orange"}
shared = tags.intersection(warm)           # {'red'}
both   = tags.union(warm)                  # {'blue', 'green', 'orange', 'red'}
cool   = tags - warm                       # {'blue', 'green'}
inside = shared <= warm                    # True
apart  = warm.isdisjoint(["blue", "gray"]) # True

6.11 Dict and set comprehensions

Alongside the list comprehension (§6.7), a set comprehension {expr for x in xs if cond} builds a new set<T> — deduping and sorting, with expr hashable (a scalar or a tuple of hashables) — and a dict comprehension {key: value for x in xs if cond} builds a new dict<K, V> in insertion order, last value winning on a repeated key and key hashable on the same terms. Both iterate a finite source, bind each element to the comprehension-local x (or to a target list, §6.7), keep those the optional cond admits, and collect the result — the same bounded iteration as a list comprehension, so both terminate and store nothing. A brace form with a : in its head is a dict comprehension; without one, a set comprehension.

squares = {n: n * n for n in [1, 2, 3]}    # {1: 1, 2: 4, 3: 9}
parity  = {n % 2 for n in [1, 2, 3, 4]}     # {0, 1}   (deduped, sorted)

6.12 zip, enumerate, iter, next and range

Two builtin functions pair finite collections into tuples, each returning an iterator, as CPython’s do: - zip(a, b, …) → iterator<tuple<…>> — pairs elements position by position, up to the shortest input (zip(["a", "b"], [1, 2, 3]) gives two tuples), and zip() gives none. zip(a, b, strict=True) pairs them the same way and refuses, in CPython’s words, if the inputs differ in length: zip() argument 2 is shorter than argument 1. The refusal is a value_error, and the pairs read before it have been given. - enumerate(xs [, start]) → iterator<tuple<int, T>> — numbers each element, from 0 by default or from an optional int start (positional or the start= keyword; may be negative).

Each argument is any finite collection (a dict contributes its keys, a set its sorted elements, a dict view what it views) or an iterator. reversed (§6.3) returns one too.

iter(x) → iterator<T> makes one over any finite collection, read as for reads it, and answers an iterator with itself, so iter(e) is e. It prints as CPython’s class for it: <list_iterator object> over a list, <tuple_iterator object>, <set_iterator object>, <dict_keyiterator object> over a dict, and over a string <str_ascii_iterator object>, or <str_iterator object> when a character is not ASCII. It takes exactly one argument; CPython’s two-argument form calls a function, and no value here is one. An iterator is not a key or set element, where CPython hashes one by its identity: a key here is held by its value, and an iterator is equal only to itself (Python Specification §5.1). any, all, in, a set’s intersection, issuperset and isdisjoint stop reading an iterator once the answer is known, as CPython’s do, and leave the rest.

next(e [, default]) reads the next element of the iterator e. When none is left, next(e, default) answers default, which is evaluated before the read, and next(e) is a refuse with discriminator stop_iteration where CPython raises StopIteration. The default and the elements join as two elements of one list display do (§6.7), so a default of another scalar class gives a value (§4.1), and one that cannot join, such as a list beside an int, is a type_error. next(xs) over a list is a type_error in CPython’s words, 'list' object is not an iterator. next takes no keyword argument, and next(e) may stand alone as a statement, which skips an element (§7.4).

An iterator is read once. for, a comprehension, list, tuple, set, dict, sorted, sum, min, max, any, all, join, extend, update, zip, enumerate, next and unpacking each take the elements they read, so a second read finds only what the first left. A for reads one per pass, so break leaves the rest, and x in e reads up to the first match. Every name holding an iterator holds the same one. An iterator never reads past the length its source had when it was made; a dict or set that changes size refuses the next read in CPython’s words, dictionary changed size during iteration. A set’s update and difference_update and a dict’s update read one element at a time, so one over the collection they change refuses as soon as its size changes (§7.17).

It has no length and no position: len(e), e[0] and e[1:] are type_errors that name list(...), which reads it into a list with both. It is always truthy, equal only to itself, and prints as its class without CPython’s address — <zip object>, <enumerate object>, <list_reverseiterator object>. Printing it reads nothing. An annotation writes it iterator<T>.

paired = zip(["ana", "bo"], [90, 85])
print(paired)                             # <zip object>
print(list(paired))                       # [('ana', 90), ('bo', 85)]
print(list(paired))                       # []
print(list(enumerate(["ana", "bo"], 1)))  # [(1, 'ana'), (2, 'bo')]
e = iter([1, 2])
print(next(e), next(e))                   # 1 2
print(next(e, "done"))                    # done
for name, score in zip(names, scores):    # tuple unpacking (§7.7)
    print(name + " scored " + str(score))

range(stop), range(start, stop) and range(start, stop, step) → range: the integers from start (default 0) up to but not including stop, step apart (default 1); a negative step counts down. It is how a counting loop gets its numbers. Every argument is an int, and there are one to three of them. A zero step is a refuse with CPython’s text, range() arg 3 must not be zero (discriminator value_error).

list(range(4))           # [0, 1, 2, 3]
list(range(2, 7))        # [2, 3, 4, 5, 6]
list(range(10, 0, -3))   # [10, 7, 4, 1]
list(range(5, 2))        # []
for i in range(3):
    print(i)

A range is CPython’s: it holds its three bounds, never its integers, so a for walks it and len, an index, in, .index and .count are answered without building it. It prints as range(0, 3), equals a range denoting the same integers and nothing else, and a slice of it is a range. list(range(n)) builds its integers, and they count toward a service’s budget on how much one run builds (§10), as [0] * n’s do; so does what a run adds to a collection it holds. sum, min and max read a range from its bounds, and a generator of ints one element at a time, building nothing: sum(range(10 ** 6)) is 499999500000. A generator’s elements from its first that is not an int are held. any and all hold nothing of a generator, and stop at the element that decides.

6.13 Spreading a collection

A * before an element of a list, a tuple or a set spreads a collection into it, as in Python: its elements stand in that place, in the order for walks them.

a = [1, 2]
print([*a, 3])                 # [1, 2, 3]
print((0, *a))                 # (0, 1, 2)
print({*a, *{2, 4}})           # {1, 2, 4}
print([*"ab", *{"k": 1}])      # ['a', 'b', 'k']
t = *a, 3                      # (1, 2, 3)
for x in *a, 3:                # 1, 2, 3
    print(x)

Anything for walks may be spread (§7.7): a list, a set, a dict (its keys), a dict view, a string, a tuple and an iterator, which the spread reads to its end. Anything else is a compile-time type_error that names the spread, where Python raises Value after * must be an iterable, not int as the program runs. The elements and spreads are evaluated left to right, each once, and the result is a new collection: ys = [*xs] is a copy, and a change to ys is not seen through xs. In a subscript a spread makes the index a tuple, as a comma does: d[*k] is d[(*k,)].

The type is the one the elements would give written out. A list is a list<T> and a set a set<T>, with T joined as a list literal’s elements join (§6.7). A tuple whose spreads are all of tuples written with a fixed number of positions keeps every position’s type, so (0, *(1, "a")) is a tuple<int, int, string>. One that spreads anything else has no length in its type, so it is a tuple<T, ...>: (*xs, 3) with xs a list<int> is a tuple<int, ...>.

A starred value alone is no tuple: y = *a, return *a and for x in *a: are each a parse_error at the *, “can’t use starred expression here”, as in Python, and y = *a, is the tuple. As a comprehension’s element, [*x for x in xs], it is a parse_error, “iterable unpacking cannot be used in comprehension”. A * before an argument of print spreads the collection across print’s arguments (§7.13); so does one before an argument of a script’s call, §7.4, and one before a method’s argument, §8.4; before an argument of a verb it is not taken. One before an argument of a builtin spreads the collection across the call’s arguments, which then answers what it answers written out: max(*xs), zip(*rows), range(*bounds). A count the builtin does not take is refused in Python’s words: at compile for a tuple of fixed length or a list display, and as a refuse with discriminator type_error as the program runs for any other. A builtin whose result’s type would depend on the count is a type_error, as max(*xs) is for a list of lists. A keyword argument beside the * binds as Python binds it, written before the * or after it: int(*["ff"], base=16), round(*xs, ndigits=1), sorted(*xs, reverse=True), max(*xs, default=0), zip(*rows, strict=True). A count that does not fit the keyword is refused the same way, in Python’s words, and a name the builtin does not take is a type_error. One before an argument of a built-in method spreads the same way, "-".join(*[xs]), "abc".replace(*pair), and through a type’s name what it gives first may be the receiver, str.upper(*["a"]). A count a built-in method does not take, spread or written out, is refused in Python’s words, str.upper() takes no arguments (1 given), replace expected at least 2 arguments, got 1: at compile where the count is written or fixed, and as a refuse with discriminator type_error as the program runs for any other. A name beside the * binds as written out, once the count is known: "a b c".split(*ys, maxsplit=1), d.update(*ys, k=1), xs.sort(*ys, reverse=True), which sorts where ys gives nothing and otherwise raises sort() takes no positional arguments, in Python’s words. One before an argument of a call into math, cmath, vector or struct spreads the collection across the call’s arguments, as in a script’s call: given p = [1.0, 1.0], math.atan2(*p) answers what math.atan2(1.0, 1.0) answers. A count of arguments the function does not take is then refused as the program runs, with type_error, and math.isclose places an a or b given by name at the count the * gives: with xs holding one element, math.isclose(*xs, b=1.0) compares it with 1.0. A ** in a dict is not taken either; to merge two dicts, copy one and update it (§6.9).

6.14 math and cmath

import math
import cmath

Python’s math and cmath, provided by the language: an import of either reads nothing from your store (§9.4), and math.<name> is available from the import to the end of the unit (§9.3). from math import sqrt, pi binds the names it lists, and leaves math itself unbound, as in Python.

A math function takes an int, a real or a bool; a cmath function takes a complex too, except rect, whose two arguments are real. Anything else is a type_error; prod takes a complex too. Only isclose and prod take keyword arguments, prod’s start by name only, and hypot, gcd and lcm take any number of arguments, none included. A wrong number of arguments is a type_error in Python’s words, math.sqrt() takes exactly one argument (2 given) or math.log requires 1 to 2 arguments. A constant called (math.pi()), a function used as a value (f = math.sqrt), a name the namespace does not have, a namespace used without its import, and a call on a line of its own are each a parse_error.

import math
import cmath

print(math.sqrt(2))                      # 1.4142135623730951
print(math.log(8, 2))                    # 3.0
print(math.log(1000, 10))                # 3.0
print(math.erf(1))                       # 0.8427007929497149
print(math.gamma(5))                     # 24.0
print(math.atan2(1, 1) == math.pi / 4)   # True
print(math.degrees(math.asin(0.5)))      # 30.000000000000004
print(math.hypot(3, 4, 12))              # 13.0
print(cmath.exp(1j * math.pi / 2))       # (6.123233995736766e-17+1j)
print(cmath.sqrt(-4))                    # 2j
print(cmath.polar(3 + 4j))               # (5.0, 0.9272952180016122)

Each function follows Python’s algorithm with every power, logarithm, exponential, trigonometric step, inverse and modulus correctly rounded, as ** is (§6.3), so an answer is the same wherever it is computed and departs from Python’s only where Python’s platform rounds one of those steps wrongly (Python Specification §8.16). degrees and radians are the exact product rounded once, where Python’s rounds twice, so a last digit may differ from Python’s: math.degrees(-880.7976600675347) is -50465.9885268683, where Python answers -50465.98852686831. math.log(x, base) is rounded once too, where Python’s divides two rounded logarithms: math.log(1000, 10) is 3.0, where Python answers 2.9999999999999996. An int past 2**53 is taken as the int it is, where Python rounds it to a real first: math.sqrt(893270773857066291) is 945130030.1318684, where Python answers 945130030.1318682, and math.fmod(9007199254740993, 10.0) is 3.0, where Python answers 2.0. hypot of any number of coordinates is correctly rounded, and dist and hypot of one point never differ. fsum, prod and dist are the exact value rounded once, where Python’s round at every step: math.fsum([1e308, 1e308, -1e308]) is 1e+308, where Python raises OverflowError; math.prod([1e200, 1e200, 0.0]) is 0.0, where Python answers nan; and math.dist([-1.7, 1.6, -9.6], [2.3, 2.6, -8.8]) is 4.199999999999999, where Python answers 4.2. prod takes numbers, where Python’s multiplies whatever * takes. cmath.exp, cmath.rect and cmath.sqrt give each part, real and imaginary, as its exact value rounded once, where Python’s rounds the parts it composes and again: cmath.exp(complex(1.3, 2.7)).imag is 1.5681835703495033, where Python answers 1.5681835703495035. A call refuses where Python raises, in Python’s words: an argument outside the domain (math.sqrt(-1), math.log(0), math.asin(2), math.atanh(1), math.fmod(1, 0), or a pole of the gamma function, math.gamma(0), math.gamma(-1), math.lgamma(-3)) with value_error, math domain error; an int answer past what an int holds (math.factorial(21)) with arithmetic_overflow, integer overflow: `math.factorial` result exceeds the signed 64-bit range; an infinity or a NaN to math.floor, math.ceil or math.trunc with arithmetic_overflow, cannot convert float infinity to integer, or value_error, cannot convert float NaN to integer; math.log(x, 1) with division_by_zero, float division by zero; and a negative tolerance to isclose with value_error, tolerances must be non-negative. A result too small to represent is the nearest one that is: math.exp(-1000) is 0.0. Two departures from Python: a result past the largest real is inf or -inf (math.exp(1000), math.gamma(172), math.fsum([1e308, 1e308]), cmath.exp(800) is (inf+0j)), where Python raises OverflowError; and an infinite argument with no value is nan (math.sin(math.inf), math.sqrt(-math.inf), math.fmod(math.inf, 2.0), math.fsum([math.inf, -math.inf])), where Python raises ValueError. There is one NaN, so math.copysign(1.0, -math.nan) is 1.0, where Python answers -1.0 (Python Specification §8.16).

A constant costs nothing, as the literal it names does; each call costs one operation.

6.15 vector

import vector

A namespace the language provides, imported and reserved as math is (§6.14). Python has no module of this name. Its two functions apply a matrix to a list, and add the squares of a list, along axes, each in one call.

xs is a list of 2ⁿ numbers, and axis a is bit a of an index into it, so axis 0 is the lowest bit. axes names k different axes, and m is 2ᵏ rows of 2ᵏ numbers. The first axis named is the high bit of a row or column of m, so along [a, b] row 2 of m is the element whose bit a is 1 and whose bit b is 0, and along [1, 0] the rows of a 4 × 4 matrix follow the order of a four-element list. For each setting of the bits the axes do not name, the 2ᵏ elements the named bits reach are replaced by m times them: the element at row r becomes m[r][0] * x0 + m[r][1] * x1 + …, where xc is the element at column c. Each element keeps the class that arithmetic gives it, as in Python; one of ints is that int, and any other, its operands finite, is in each part the exact sum of the exact products rounded once, whatever order they come in. The answer is that of a Python function stated in full (Python Specification §8.17).

import vector

print(vector.apply([4.0, 8.0], [[0.75, 0.25], [0.25, 0.75]], [0]))   # [5.0, 7.0]
print(vector.apply([1, 2, 3, 4], [[1, 0], [1, 1]], [0]))             # [1, 3, 3, 7]
print(vector.apply([1, 2, 3, 4], [[1, 0], [1, 1]], [1]))             # [1, 2, 4, 6]
upto = [[1, 0, 0, 0], [1, 1, 0, 0], [1, 1, 1, 0], [1, 1, 1, 1]]
print(vector.apply([10, 20, 30, 40], upto, [1, 0]))                  # [10, 30, 60, 100]
print(vector.apply([10, 20, 30, 40], upto, [0, 1]))                  # [10, 60, 40, 100]
print(vector.apply([1.0, 2.0], [[1, 0], [1j, 1]], [0]))              # [1.0, (2+1j)]

An argument that is not a list of numbers, a matrix that is not a list of lists of numbers, and axes that are not a list of integers are each a type_error. A call refuses with value_error where the length of xs is not a power of two, an axis is outside 0 to n − 1 or named twice, or m is not 2ᵏ rows of 2ᵏ; and with arithmetic_overflow where a product or sum passes the range of its class, as * and + do (§6.3). A call costs one operation, whatever the length of xs.

vector.sumsq takes the same xs and the same axes, and answers a list of 2ᵏ reals: one sum for each pattern of the bits the axes name, listed with the first axis named as the high bit of the pattern, as the rows of m are. The sum for a pattern is the exact sum of the exact squares of z.real and z.imag of every element z = complex(x) whose bits on the axes make that pattern, rounded once, so it does not depend on the order the elements are in. Naming no axis makes one sum of every element. The answer is that of a Python function stated in full (Python Specification §8.17).

import vector

print(vector.sumsq([3, 4], []))                       # [25.0]
print(vector.sumsq([1, 2, 3, 4], [0]))                # [10.0, 20.0]
print(vector.sumsq([1, 2, 3, 4], [1]))                # [5.0, 25.0]
print(vector.sumsq([1, 2, 3, 4], [1, 0]))             # [1.0, 4.0, 9.0, 16.0]
print(vector.sumsq([1, 2, 3, 4], [0, 1]))             # [1.0, 9.0, 4.0, 16.0]
print(vector.sumsq([1.0 + 2.0j, True, -0.0, 0.0], [1]))   # [6.0, 0.0]

A vector that is not a list of numbers and axes that are not a list of integers are each a type_error. A call refuses with value_error where the length of xs is not a power of two or an axis is outside 0 to n − 1 or named twice. A square, or a sum of squares, past the range of a real is inf, where Python’s fsum may raise OverflowError, and an element with a NaN part makes its sum nan: vector.sumsq([1e200, 1.0], [0]) is [inf, 1.0]. A call costs one operation, whatever the length of xs, and builds the 2ᵏ sums alone.

6.16 struct

import struct

Python’s module of that name, provided by the language, imported and reserved as math is (§6.14). It lays numbers out as the bytes of a blob, and reads them back, by a format string, as Python’s does.

A format opens with an optional @ (native sizes, each value aligned, the default), = or < (little-endian, no padding), or > or ! (big-endian), and then has codes, each after an optional count. The integers are b, h, i, l and q, of 1, 2, 4, 4 and 8 bytes, signed, with their unsigned twins B, H, I, L and Q; l and L are 8 bytes in native layout, and n, N and P are 8-byte integers that only native layout has. ? is a bool, e, f and d are reals of 2, 4 and 8 bytes, and F and D are complex numbers of two f or two d. x is a pad byte, c a blob of one byte, and s and p one blob whose length is the count. Native layout is Python’s on a 64-bit x86 Linux host, wherever a program runs, so a format lays out the same bytes everywhere.

import struct

b = struct.pack("<hd", -2, 0.5)
print(b)                                     # FEFF000000000000E03F
print(len(b), struct.calcsize("@hd"))        # 10 16
n, x = struct.unpack("<hd", b)
print(n, x)                                  # -2 0.5
print(struct.unpack(">I", blob("0000FF01")))  # (65281,)
zs = [1j, complex(-0.0, 2.0)]
kept = struct.pack(f"<{len(zs)}D", *zs)
print(list(struct.unpack(f"<{len(kept) // 16}D", kept)))   # [1j, (-0+2j)]

unpack takes its tuple’s types from a format written in the call: a string literal gives each position the type of its code, so struct.unpack("<hd", b) is a tuple<int, real>, and an f-string whose holes are integers and whose codes all read one type gives a tuple of that type, as f"<{n}D" gives a tuple<complex, ...>. Any other format gives a tuple<value, ...>.

A call refuses where Python raises, in Python’s words: with value_error for a format it cannot read, a count of values or a length of blob the format does not lay out, a value its code does not pack, or an integer outside its code’s range, and with arithmetic_overflow for a finite real too large for e or f. A DKE int is at most 2⁶³ − 1, so unpack refuses an unsigned integer above that with arithmetic_overflow. An infinity or a NaN packs and unpacks as in Python, and there is one NaN: pack writes it as the quiet NaN with its sign bit clear (7ff8000000000000 for d), where Python writes the bits of the NaN it was given. A call costs one operation, however many values it packs or reads, and a * argument one more (§6.13). The rules in full are in Python Specification §8.18.

6.17 Special names on a built-in value

A special name is one that begins and ends with two underscores. A value holds the special names its Python class holds, and one called by name answers as the spelling it stands for, at that spelling’s cost. A reflected name takes its operands the other way round.

xs = [3, 1]
print(xs.__len__())              # 2
print((2).__rsub__(10))          # 8
print(xs.__contains__(3))        # True
xs.__setitem__(0, 5)             # xs[0] = 5
xs.__iadd__([7])                 # xs += [7]
print(xs)                        # [5, 1, 7]

A name the class does not hold, a count of arguments its method does not take, and a keyword argument are type_errors in Python’s words. So is __hash__ on a list, a dict or a set, which is None in Python: 'NoneType' object is not callable. Where Python answers something no value here holds, the call is a type_error saying so: NotImplemented, which an operator’s special name answers for an operand its class does not take; __class__, a class; a special name read with no call, a method; and the machinery behind a value, such as __sizeof__. A special name that changes its receiver, __setitem__, __delitem__ or an in-place name such as __iadd__, is a statement, as append is (§7.17), and read as a value it is a type_error. A * and a ** before any dict are read as at any method (§7.4): the names are merged and refused in Python’s words, wrapper __len__() takes no keyword arguments, before the count is, as the program runs. Beside a ** whose keys are known only as the program runs, a call whose answer no value here holds, and a change read as a value, are refused as the program runs too, after the names, and a change is made first; a value bound from one is a type_error where the unit is compiled. The rules in full are in Python Specification §8.20.

7.1 Declaration

def audit(K: string, s: string):
    <suite>
def doubled(n: int) -> int:          # value script: returns an int
    return n * 2

The def keyword, name, typed parameters (name: type), an optional -> type return type, :, indented body. A type is a scalar / read-result type (§5.5) or a parameterized collection — list<T>, set<T>, dict<K, V>, tuple<T, ...>, nestable (dict<string, list<int>>) — so a collection crosses a function boundary as an argument or return value (def total(xs: list<int>) -> int:, def doubled(xs: list<int>) -> list<int>:). A parameter may carry a default (def f(x: int, y: int = 1)) — a constant expression whose type matches the parameter; a defaulted parameter may not precede a required one. Two declarations in a unit must not share a name, whatever their kinds: a def, a @rule, a @constraint and a class share one name space, and a second declaration of a name is refused with the kind that holds it. A call may target a declaration above or below it in the unit, as long as no call leads back to its caller (compile-before-call). A module’s own statement runs where it stands, so one that reaches a def below it is told name 'g' is not defined when the unit compiles.

A parameter may be variadic — written *name: T — collecting the surplus positional arguments into a tuple<T, ...> (possibly empty): def total(label: string, *nums: int) -> int: accepts total("a", 1, 2, 3) with nums = (1, 2, 3). There may be at most one, its element type is required, it takes no default, and it cannot be passed by keyword; inside the body it is an ordinary tuple (nums[0], len(nums), for n in nums, sum(nums)). There is no **kwargs: a signature names every keyword a call may pass, so a misspelt keyword is refused where it is written. Use explicit named parameters or a dict parameter.

A / makes the parameters before it positional-only, and a bare * or a variadic makes those after it keyword-only, as in Python: def f(a: int, /, b: int, *, c: int = 3) is called f(1, 2) or f(1, b=2, c=4). Passing a by name or c by position is a type_error naming the parameter and its marker. A keyword-only parameter with no default may follow one with a default.

A script with no -> type whose body holds no return <expr> is a void script (no value); one written def name(...) -> type: is a value script — it produces a value of type and MUST return a value on every path (§7.12). With no -> type, a body holding a return <expr> is a value script of the type its returns give. Only a value script may be called as an expression (§7.4). A value script that hands on a store fold’s result declares -> value, as a value method does (§8.5), and its caller narrows it with match.

7.2 Assignment (bind a read)

hist = get(K.s.color)

A name is bound by bare assignment, name = <expr>. The right side must not be a statement-only verb (no value). Augmented assignment x += e (and -= *= /= %= //= **=) is accepted on a bare name; x <op>= e is equivalent to x = x <op> e. It does not apply to a field (obj.field += e is rejected): a field is a provenance-carrying claim, not a mutable cell, and a compound assignment names no source — update a field by reading it, then writing the new value back with remember(obj.field, <new value>, <source>). An annotated assignment x: <type> = <expr> gives the binding its type explicitly (n: int = 5, xs: list<int> = [1, 2, 3]); the annotation must agree with the initializer, and a bare x: <type> with no value is rejected (write x: <type> = <value>). An element write xs[i] = v or d[k] = v, and d[k] += v, changes the collection in place (§7.17); its value may be a bare comma-list, so ts[0] = 3, 4 writes a tuple. An element or a slice may also be one target of several, in a target list, a chained assignment or a for header, written the same way. Chained assignment a = b = <expr> binds every target to one value (evaluated once), left to right: a = xs[0] = 5 binds a and writes xs[0], and xs[a] = a = 1 writes xs at the a held before the statement. Unpacking a, b = <expr> destructures a tuple or a list into its targets, each a name, an element or a slice. A tuple must hold exactly the target count, written parenthesized ((1, 2)) or as a bare comma-list (b, a). A list, a variadic tuple<T, ...> such as a *args parameter, a string, a set, a dict (its keys), a dict’s view or an iterator gives each target its element type, and its length is checked when the statement runs, so k, v = line.split("="), x, y = args and a, b = "xy" work and a mismatch is a catchable refusal in CPython’s words — not enough values to unpack (expected 2, got 1) or too many values to unpack (expected 2), discriminator value_error. Anything else, a number included, does not unpack. The whole right side is evaluated before any target binds, so a, b = b, a swaps (§7.7), and so does xs[i], xs[j] = xs[j], xs[i]; the targets are then assigned left to right, so i, xs[i] = 1, 5 writes xs[1]. A target may itself be a parenthesized target list, so nested unpacking (a, b), c = ((1, 2), 3) (or a, (b, c) = …) destructures a tuple or list of tuples or lists, each level arity-checked independently. One target may be starred (a, *rest = (1, 2, 3) → rest = [2, 3], always a list): it absorbs the surplus elements (which must share one type), the RHS needing at least the fixed-target count. A parenthesized group may hold its own star, so a, (b, *c) = 1, (2, 3, 4) gives c = [3, 4]. The star may stand before a group or an element as well: a, *(b, c) = 1, 2, 3 unpacks what it absorbs, binding b = 2 and c = 3, and with xs = [[0]], a, *xs[0] = 1, 2 writes the list [2] to xs[0]. A target list may be written in brackets too, [a, b] = t, where one target is a list of one, [a] = t, and none is a list of none, [] = t, which asks that t hold nothing; a chained assignment’s target may be a target list, t = a, b = 1, 2. An element target may begin with a value no name holds, f(xs)[0] = v, and changes the collection that value is, so a script that returns the list it was given hands back the caller’s. A field is never a target: written as one, in any of these positions, it is refused in favour of remember(...), and so is an annotation on anything but a name, xs[0]: int = 1.

7.3 What a value prints as

print([3, 1, 2])                 # [3, 1, 2]
names = list_subjects(Cat)
print(names)                     # 2 entries [felix, tom]
proof = why(Cat.tom.old)
print(proof)                     # proof_tree(2)
age = current(Cat.felix.age)
print(age)                       # <empty>

print accepts any expressible value and writes it as its text form, the one str(x) gives. A boolean is written True / False. A constructed list<T> renders [e1, e2, …]; a tuple renders (e1, e2, …); a dict renders {k1: v1, k2: v2} in insertion order; a set renders {e1, e2, …} in sorted order (an empty set, set()) — each element rendered recursively. A read is bound to a name on its own line and the name printed (§7.2), as above.

What a read gives back is written too, each type its own way, and this is the whole list (Python Specification §8.13.1):

These are for reading, not for parsing: to take a value out of a read, iterate the collection or read the field. The call itself, with several arguments, sep, end and a * spread, is §7.13.

7.4 Script call (invocation)

audit_subject(K, s)                  # statement: run for effects, discard any value
total = summed(a, b)                 # value-call: bind what a value script returns
total = summed(*pair)                # a spread: each element of `pair` an argument

A plain call of a stored script: a script is called like any function. The call is fixed when the calling program is compiled and runs the body the callee had then (§9.6); a script cannot call itself, directly or through another. Arguments bind by position, or by keyword (greet("World", greeting="Hi")); a keyword may not precede a positional argument, and an omitted argument uses the parameter’s default (§7.1). A call that does not fit is a type_error in Python’s words and in Python’s order: summed() got an unexpected keyword argument 'z', summed() takes 2 positional arguments but 3 were given, or summed() missing 1 required positional argument: 'b'.

A positional argument written *xs spreads xs: each element is a positional argument of its own, in its place, and a variadic parameter collects what is left over. A spread may follow a keyword argument, as in Python: summed(b=2, *xs) fills a from xs. What may be spread is what for walks, and a tuple (§6.13). A tuple written with a fixed number of positions has its length in its type, so a call spreading only such tuples is checked as written: summed(*(1, 2, 3)), given two parameters, is a type_error. Any other spread has a length known only as the program runs, so the call is checked then, once every argument is evaluated, and one that does not fit is a refuse with discriminator type_error, in Python’s words: summed() takes 2 positional arguments but 3 were given, summed() missing 1 required positional argument: 'b', or summed() got multiple values for argument 'b' when a keyword names a parameter the spread reaches. Each element must suit every parameter it could fill, and so must each argument written after the spread.

An argument written **d gives each entry of the dict d as a keyword argument, as in Python: summed(**{"a": 1, "b": 2}) is summed(a=1, b=2). Its keys are known only as the program runs, so the call is checked then, and one that does not fit is a refuse with discriminator type_error, in Python’s words: summed() got an unexpected keyword argument 'z', or __main__.summed() got multiple values for keyword argument 'a'. An operand that is no dict is a type_error.

print, a builtin, a built-in type’s method, sorted, a list’s sort and a math function take a ** before a dict display whose keys are all literals, its keys given as keyword arguments: int("10", **{"base": 2}) is 2, and xs.sort(**{"reverse": True}) sorts in reverse. A display that gives nothing gives the call nothing, and a key given twice in one display keeps its later value, as in Python. A call it does not fit is a type_error where the unit is compiled, in Python’s words and order: a keyword two arguments give (print() got multiple values for keyword argument 'sep', and '1' for print(**{1: 2}, **{True: 3}), a key that is no string being one key as a dict’s are equal), then a key that is no string (keywords must be strings), then a name the callee does not take ('zz' is an invalid keyword argument for print(), len() takes no keyword arguments). Any other operand after a ** there, such as a name, is read when the call runs at print (§7.13), at a builtin that takes no name, such as len, abs, list or isinstance, and at int, round, pow, complex, str, zip, enumerate, sum, sorted, min, max and dict, at a built-in value’s method, a change among them, and at a function of math, cmath, vector or struct, and not yet anywhere else. At a builtin that takes no name it is read after the positional arguments, and a mapping that gives nothing leaves the call as written, so len(xs, **opts) is len(xs) while opts is empty. Any name it gives is a catchable refuse with discriminator type_error, len() takes no keyword arguments, after a name given twice (len() got multiple values for keyword argument 'x', or '1' where two mappings give the key 1) or, once every mapping is merged, a key that is no string (keywords must be strings), and a display written beside such a **, whose key is no string, is merged with it as the call runs: print(**{1: 2}, **n, **k) with n and k both holding "x" is print() got multiple values for keyword argument 'x'. Two displays written out that give one name are refused as the call runs too where a ** the program reads is merged before the second giving, in the order Python merges: print(**n, **{"x": 1}, **{"z": 1}, **{"z": 2}) with n holding "x" is print() got multiple values for keyword argument 'x', and the refusal is catchable; with every mapping written out it is refused where the unit is compiled. A count it does not take is refused only where the mapping gives no name, as the program runs: with opts empty, len(xs, 2, **opts) is len() takes exactly one argument (2 given). So it is at a built-in value’s method and a function of a built-in namespace that take no name, s.upper(1, **opts) and math.sqrt(x, 2, **opts), and without such a ** the count is a type_error where the unit is compiled. So is an argument it does not take, of a type or a value it refuses: with opts holding x, len(5, **opts) is len() takes no keyword arguments and s.center(1.5, **opts) is str.center() takes no keyword arguments, and with opts empty each is refused in the words it has without such a **, object of type 'int' has no len(), as the program runs. So is a change’s, such as s.add([1], **opts), and a dict’s get or setdefault of a key alone, which has no None to answer, once the names are merged. So is a change that would give its receiver a second type: after s = {1}, s.add("a", **opts) is set.add() takes no keyword arguments with opts holding x, and with opts empty the refusal a name’s one type gives, as the program runs; the statement refuses either way, so the receiver keeps its type. Beside a * whose length is known only as the program runs, it is read where what is called takes no name, a builtin, a function, a built-in value’s method or a change, after every argument and before the count the * gives: with opts holding x, len(*xs, **opts) is len() takes no keyword arguments whatever xs holds. So it is at int, round, pow, complex, str, zip, enumerate, sum and dict, which take names, over the count the * gives and in the order below: with xs empty and opts holding base, int(*xs, **opts) is int() missing string argument. So it is at sorted, min and max, which count the * before they read a name, as Python’s do: over two elements sorted(*xs, **opts) is sorted expected 1 argument, got 2 whatever opts holds. So it is at a built-in value’s method that takes names, split and its kin, and at math.isclose, over the count the * gives. So it is at a list’s sort, which counts what the * gives as arguments by position and refuses any, sort() takes no positional arguments, and at a dict’s update, which writes what the * gives and then the names, as keys. So it is through a type’s name, where the receiver is the first thing the * gives, and the names are merged before the receiver is taken, as Python merges them: with xs empty and opts holding a key that is no string, list.sort(*xs, **opts) and str.upper(*xs, **opts) are keywords must be strings, and otherwise unbound method list.sort() needs an argument and unbound method str.upper() needs an argument; where xs gives a value of another type first, descriptor 'upper' for 'str' objects doesn't apply to a 'int' object. So it is where nothing types what the * gives, as with xs = [].

At int, round, pow, complex, str, zip, enumerate, sum, sorted, min and max the names it gives are the call’s, as if written: int(s, **opts) with opts holding base is int(s, base=...). A name the callee does not take is a catchable refuse with discriminator type_error, 'x' is an invalid keyword argument for int(), after too many names in all (int() takes at most 2 arguments (3 given)) and after a name the call lacks or is given by name and by position, as in Python. Any other refusal is the one the call written out meets, as the program runs. enumerate reads the names where they stand, as Python’s does: with two arguments in all a name must be start, and with one it must be iterable, so enumerate(**opts) with opts holding start alone is refused 'start' is an invalid keyword argument for enumerate(), as enumerate(start=1) is. sorted, min and max count the names apart from the positional arguments, and sorted is refused under sort’s name, as Python’s is. A key a mapping gives is never a function, since a dict holds none, so the call refuses it, 'int' object is not callable, once there is an element to call it on, and over none is the call without it. dict takes every name as a key, after its positional argument’s entries. A call whose type would turn on the names given is a type_error where the unit is compiled: round(x, **opts) over a real gives an int without ndigits and a real with it. A call that no names its mapping could give would let run is refused as the program runs, in the words of what the mapping gives, as Python’s is: sum(**opts) is sum() takes at least 1 positional argument (0 given). At a built-in value’s method the names are the method’s, as if written: split, rsplit, splitlines and expandtabs take theirs as Python’s do, and any other method refuses any name it is given, str.upper() takes no keyword arguments. So does a method that changes its receiver: a list’s sort takes key and reverse as sorted does, a dict’s update takes every name as a key, after the entries it is given, and any other refuses any name before the collection changes, list.append() takes no keyword arguments, and a count it does not take only where the mapping gives no name. Read as a value and bound to no name, such a change is made, and only then is the value refused, as the program runs: with opts empty, print(xs.append(2, **opts)) appends 2 and is refused. A name written beside the ** is merged with the names it gives, so that with opts holding x, xs.append(5, x=1, **opts) is list.append() got multiple values for keyword argument 'x'. Through a type’s name, a receiver written of another type is refused once the names are merged, before the method reads a name: str.upper(5, **opts) is keywords must be strings where opts holds a key that is no string, and otherwise descriptor 'upper' for 'str' objects doesn't apply to a 'int' object. Without such a ** each is a type_error where the unit is compiled. Through its type a call given no positional argument, only such a **, merges the names and is then refused for its missing receiver: str.upper(**opts) is unbound method str.upper() needs an argument, after keywords must be strings or a name given twice. A name written beside such a ** at sorted, min, max or a list’s sort that the callee does not take waits for the merge too: with opts holding x, sorted(xs, x=1, **opts) is sorted() got multiple values for keyword argument 'x', and with opts empty 'x' is an invalid keyword argument for sort(). A list’s sort whose receiver is written, with a typed * after it, counts what the * gives before it names one: xs.sort(*ys, x=1) and list.sort(xs, *ys, x=1) are sort() takes no positional arguments where ys gives a value and 'x' is an invalid keyword argument for sort() where it gives none, as the program runs; where nothing types ys the second is refused where the unit is compiled. A positional argument written beside the * is counted with what the * gives, before any name: xs.sort(*ys, 5, x=1) is sort() takes at most 2 arguments (3 given) where ys gives one value, as the program runs, and where nothing types ys it is refused where the unit is compiled. A key= beside the * is applied only where the sort runs: xs.sort(*ys, key=len) over a list of ints is sort() takes no positional arguments where ys gives one value, and object of type 'int' has no len() where it gives none, each as the program runs and catchable; where nothing types ys, and where there is no *, a key the elements refuse is refused where the unit is compiled. A list’s sort through its type takes its list from the first thing every * and every positional argument gives, in order, and counts and names what follows it only after: list.sort(*xs, ys) sorts ys where xs gives nothing, list.sort(*xs, x=1) with xs giving nothing is unbound method list.sort() needs an argument, and over a tuple t, list.sort(t, 1) is descriptor 'sort' for 'list' objects doesn't apply to a 'tuple' object. At a function of a built-in namespace the names are merged under the function as Python’s call names it, math.isclose() or _struct.pack(): math.isclose takes its names as int does above, named alone, isclose() missing required argument 'b' (pos 2), and any other function refuses any name, math.sqrt() takes no keyword arguments, and math.log before it reads a key, log() takes no keyword arguments. A call of slice refuses any name before it reads a key too, slice() takes no keyword arguments. The three methods a type answers itself, dict.fromkeys, str.maketrans and float.fromhex, read a ** the same way, named with their type: with opts holding x, dict.fromkeys(xs, 0, **opts) is dict.fromkeys() takes no keyword arguments, and with opts empty dict.fromkeys(xs, 0). A value bound from such a call, where nothing types what the call would answer, is a type_error where the unit is compiled, in the call’s own words, whatever the mapping gives, since a name bound by bare assignment takes its value’s type and such a call has none: v = list.pop((1, 2), **opts) is descriptor 'pop' for 'list' objects doesn't apply to a 'tuple' object, v = chr("a", 2, **opts) is chr() takes exactly one argument (2 given), v = abs("a", **opts) is a type_error as v = abs("a") is, since abs answers the type it is given, and over xs = [], v = list.pop(*xs, **opts) is cannot infer type of binding `v` — right-hand side did not typecheck to a known type. The same call read as a statement or printed is refused as the program runs, as above, and so is a value bound from a call that fixes a type, such as str.upper(5, **opts), len(5, **opts) or s.center(1.5, **opts).

A value script (§7.1) may be called in expression position — its call yields what the script returns, and composes anywhere an expression may: y = f(x), return f(x), print(f(x)), f(a) + g(b), or nested f(g(x)) (evaluated inner-first, left-to-right). A void script called as a value is a type_error — call it as a statement instead. A call names what it calls: (…) after a value — a literal, or what an index, a call or a .name answers, xs[0](1) or f()(1) — calls that value, and is a type_error in Python’s words, 'int' object is not callable, since no value holds a function. The name of a def, a method or a module read with no call is a type_error saying so.

A builtin called as a statement, where no script has its name, runs and its value is dropped, as any expression alone is: len(xs) does nothing you can see, and next(e) (§6.12) reads an element and discards it, since the read changes e.

7.5 Verb-call statement

A write verb (§5.1) in statement position:

remember(K.s.color, "orange", "op1")

7.6 if

if <cond>:
    <suite>
elif <cond>:
    <suite>
else:
    <suite>

<cond> may be any value — it is tested for truthiness (§6.2), so if xs: / if s: / if n: branch on non-empty / non-zero as in Python; each elif and the else are optional. An elif is equivalent to an else: containing a nested if. A name first bound in both arms of an if/else, or in every arm of a chain ending in else, is readable after it; one bound in some arms only is not, and an arm ending in return, raise, break or continue need not bind it (Python Specification §6.1).

7.7 for … in

for c in hist:
    <suite>

Iterates one of the six finite collections — claim_list, string_list, subject_set, result_type_set, proof_tree and diagnosis (§4.1) — a constructed list<T> (§6.7), a range(n) (§6.12), a dict (binding each key in insertion order, §6.9) or one of its views, or a set (in sorted order, §6.10), or a string, binding each character (a one-character string, by Unicode character), or a tuple whose elements all have one type (a variadic tuple always, a fixed one when its positions share a type). Written without its brackets, as in Python, it is the same tuple: for x in 1, 2: iterates (1, 2). A fixed tuple with differing position types, and any other iterand, is a type_error. An empty [] or {} whose element type no context supplied (§6.7) iterates too, zero times, as in Python: for x in []: compiles, and the code that reads x is not type-checked, since it never runs; the rest of the body is. If an enclosing loop could give that list, set or dict elements on a later pass (xs = xs + [1] in the same outer loop), the program is refused: declare the type where it starts, xs: list<int> = [], seen: set<int> = set([]) or d: dict<string, int> = {}. The loop variable stays bound after the loop and in its else, holding the last element (an empty loop leaves it as it was), as in Python. So a for over a name that is already a variable must keep its type. After x = 1, the loop for x in ["a"]: would leave a string in an int variable, and is refused with a type_error that names it. → Python Specification §6.1, §6.3 The collection is snapshotted at entry. A comprehension (§6.7, §6.11) is the same bounded iteration in expression position. Bounded iteration is what gives DKE Python its termination guarantee.

A target list unpacks each element (a tuple or a list) into named variables — for i, x in enumerate(xs):, for a, b in zip(xs, ys):, for k, v in d.items(): — each element must be a tuple of the target arity, or a list or a variadic tuple, whose length is checked as the element is reached. A trailing comma ends the list, so for a, b, in xs: is for a, b in xs: and for a, in xs: binds a to each one-element tuple’s item. A target, alone or in a list, may be an element or a slice: for xs[0] in ys: writes xs[0] with each element before the body runs. Nested targets (for a, (b, c) in xs:) and one optional starred target (for a, *rest in xs:) are taken here as they are in an assignment, the star making the target arity a minimum. A name first bound in the body is not readable after the loop, which may run zero times. Like the single loop variable, the targets stay bound after the loop, holding the last element’s values.

Inside a for body, break stops the loop and continue skips to the next element (each resolves to the innermost enclosing loop; both may sit inside a nested if/match/try). Either outside a loop is a compile-time error, and a break/continue must be inside a loop in its own def, not merely called from one. Both only shorten the (bounded) iteration, so termination still holds.

for c in claims:
    if c.value == "":
        continue                     # skip blanks
    if c.value == stop:
        break                        # stop at a sentinel
    print(c.value)

A for may end with an else: clause: it runs once after the loop completes, but not if a break left the loop. An empty collection (zero iterations) still runs it. The loop variable is still bound in the else, holding the last element, as it is after any loop (above).

for c in hist:
    print(c.value)
else:
    print("no more history")           # runs unless a break fired above

7.8 match (discriminator dispatch)

match cur:
    case active_claim:
        print("value = " + str(cur.value))
    case empty:
        print("absent")

The scrutinee must be a discriminator (active_claim, proof_tree, verify_result). Arms exhaustively cover the discriminator’s cases. case _: is the catch-all case default: is, and may stand in any match.

(A match over a value Python has is Python’s, each arm a test and none required, §7.8; over an instance the compiler follows it is also the class match, §8.6.)

A match whose scrutinee is a value (a claim’s .value, §4.1) is a value match: the case labels are the value classes int, bool, string, datetime, duration, real, null, blob, scientific and complex. The write-producible classes (int, bool, string, datetime, duration, real, blob, scientific, complex) may bind the typed content with a named as <var> arm; the one read-only class, null, is a bare arm only — attaching as <var> to it is a type_error:

match cur.value:
    case int as n:      print("next = " + str((n + 1)))     # n : int
    case string as s:   print("text = " + str(s))
    case duration as u: print("span = " + str(u))           # u : duration
    case real as r:     print("value = " + str(r))          # r : real — renders decimal
    case blob as b:     print("bytes = " + str(b))          # b : blob — renders hex
    case null:          print("an absent value")       # bare — no `as`
    case default:       print("other class")

Arms cover every class or provide case default:; a bound as <var> is typed at the arm’s class and scoped to that arm. A bool is an int, so a case int arm takes one and covers bool, and a case bool below an unguarded case int is refused as an arm that could never run — put case bool first. case int():, Python’s class-pattern spelling, tests what case int: tests, and case str(): and case float(): are the string and real arms. When every arm naming a class writes the parentheses, and none is a bare label, the match is Python’s instead: each arm a test and none required, and case int(n): binds the value to n, as a capture binds it. Beside a bare label, a pattern inside the parentheses is not taken — bind the content with as. In an arm naming classes, a scrutinee written as a name is read at their class (§8.11), and in an arm below them at what their tests failing leave it. A label that is no class, such as null or default, takes no parentheses.

for e in [1, "a"]:
    match e:
        case int():
            print(e + 1)        # e : int
        case str():
            print(e.upper())    # e : string

Alternatives in one arm. A case label may name two or more classes separated by |, and the arm runs when the value is any one of them:

match cur.value:
    case int | real | scientific:   print("a number")
    case string:                    print("text")
    case default:                   print("something else")

case int | real: and two arms case int: / case real: with the same body mean the same thing; the alternation is a spelling, not a widening. An alternation takes no as <var> — the alternatives bind different types, so there is no single type for the name — and default may not appear in one, since it already covers everything not named. There is no AND-pattern: a value has exactly one class.

Guards. An arm may carry a condition it must also satisfy:

match cur.value:
    case int as n if n > 100:  print("big")
    case int as n if n > 0:    print("positive")
    case int:                  print("zero or negative")
    case default:              print("not an int")

Arms are tried in order and the first whose class matches and whose guard holds runs; a false guard falls through to the next arm. The as binding is in scope in the guard, which is what makes if n > 0 possible. The condition is anything with a truth value, the same rule if uses. The body reads a name its guard narrows at the narrower class (§8.11).

Two things follow, and both are compile-time errors when broken. A guarded arm does not count towards exhaustiveness — its guard may fail — so a match with no case default: must name every class in an arm with no guard; that is what guarantees an exhaustive match always runs exactly one arm. And a class may be named by several arms only while every earlier one is guarded: an unguarded case int: runs for every int, so nothing after it can. case default: may not carry a guard at all. There is no AND-pattern: a value has exactly one class.

Matching on a value. A case label can be a value pattern — Python’s own — and then the match compares rather than dispatches:

match n:
    case 0:              print("none")
    case 1 | 2:          print("a couple")
    case k if k < 0:     print("negative " + str(k))
    case _:              print("several")

A literal — a number (negative included), a text, True or False — matches when the scrutinee == it, so case 1: matches 1.0. Literals joined by | match any of them. _ matches anything and binds nothing; a name that is not a class label matches anything and binds the value to that name, and as <var> after any pattern does the same. A capture and an as over a value pattern bind like ordinary assignments — made before the guard runs, kept when the guard is false, and §7.8’s scoping note applies to them, not the arm-local rule the class arms use.

A match over a value Python has — a number, a text, a collection, a slice, a view, an iterator or an instance — takes value patterns, shape patterns and class patterns, and needs no catch-all: when no arm matches, none runs and execution continues after the match, exactly as in Python. An arm that can never be taken compiles and never runs. case int():, case Site(): and case geo.Site(): test the class, as isinstance does, at the top of an arm or inside another pattern (case [int(), Site() as s]:, case 1 | str():), and a guard and a body read the value as that class. A type that reads as itself, int, bool, float, str, list, tuple, dict or set, may hold one pattern over the same value (case int(n):); past that, and for anything inside another class’s parentheses, the test raises Python’s type_error once the class has held (int() accepts 1 positional sub-pattern (2 given)). Over a value, literals stand beside the class arms and are tried where they are written — a match naming a class is still exhaustive, and one naming none is not. A catch-all — _, an unguarded capture, or case default: beside a value pattern — must be the last arm, since nothing after it could run.

case True: takes only a bool, by identity, as in Python (case 1: over a bool does take True, since 1 == True).

What is refused, and why: a class named with no () where the compiler does not follow an instance to it (case int: over an int), which Python reads as a capture — write case int():; a keyword in a class pattern (case Site(size=1):), which would read a field while the match dispatches — read it inside the arm; a typed value (datetime("…"), duration("…"), blob("…"), scientific("…")), which reads as a class pattern, and a value class takes no sub-patterns; a capture in a match that dispatches on classes, where a misspelt class must not silently take everything; and mixing a class and a value in one arm (case 1 | int:). case 1 | n: is refused as Python refuses it — a capture cannot be one alternative — and case _ | 1: because nothing follows _. An as _ is a syntax error, since _ binds nothing, and a pattern binding one name twice is refused, as case [a, a]: is.

Matching on shape. A case label can be a shape instead of a class — a list pattern or a dict pattern — and then the match is matching the structure of a collection rather than the class of a stored value:

match parts:
    case []:                 print("nothing")
    case [only]:             print("just " + only)
    case [first, *rest]:     print(first + " and " + str(rest.length) + " more")
    case default:            print("unreachable, but required")

A name in a pattern binds whatever is at that position, and _ matches it and binds nothing; a literal tests for equality and binds nothing; a nested [...] or {...} matches a shape at that position. Alternatives separated by | can stand at a position, as in case [1 | 2, b]:, and are tried in order. Each binds the same names, so case [[1, a] | [2, a, 0]]: binds a from whichever matched. as name after a pattern at a position binds what it matched, as in case [[1, y] as z]:. Alternatives and as stand at the top of a case as well, around a shape: case [1] | [2]:, case 1 | [b, 2]:, case [1, _] as z:. A *name collects the remaining elements and must be the last element. Without a * the pattern matches a list of exactly that length; with one, of at least the fixed length.

A dict pattern names keys, each a literal — a text, a number, True or False — and each key once:

match record:
    case {"id": i, "kind": "sensor"}:  print("sensor " + i)
    case {"id": i}:                    print("something " + i)
    case default:                      print("no id")

It matches when every key it names is present, and ignores keys it does not name — it is a subset test. As with a list pattern, i binds the value and the literal "sensor" tests it.

A shape arm matches a sequence or a mapping and nothing else: over any other value it compiles and never matches, and as one alternative of several it is left out, the arm standing on the others: over x = 1, case 1 | [2]: is taken. The thing matched on may be any expression, evaluated once, and a shape match needs no catch-all. Shape arms take guards (case [a, b] if a > b:) with the pattern’s bindings in scope, and may stand beside value and class patterns in one match.

An ordinary assignment inside an arm is not arm-scoped, and the contrast is worth stating because one match has both rules in it. The as <var> binding of a CLASS arm exists only inside its arm (a value pattern’s capture and as are assignments, above); a name you assign in an arm belongs to the enclosing scope, and is readable after the match when it was bound before it or when every arm assigns it and the match has a catch-all (Python Specification §6.1), which is how a match computes a value for the code below it. Reading the arm binding after the match is a type_error, name 'n' is not defined; reading the assigned name is ordinary.

label = "none"
match cur.value:
    case int as n:  label = "int " + str(n)   # `n` lives only here
    case default:   label = "other"
print("after: " + label)                       # `label` is readable; `n` is not

7.9 try

try:
    <suite>
except refuse as r:
    <suite>
except engine_error as e:
    <suite>
else:
    <suite>            # runs only if the body raised nothing
finally:
    <suite>            # always runs, last

Python’s own except … [as …]: shape. Both handlers are optional, and so is each handler’s as <var> binding — except refuse: catches without naming the exception (omit as when the body does not use the refuse/engine_error info). A refused statement does not bind and transfers control to except refuse; an engine error to except engine_error, which takes every run-time failure the wire reports as engine_error, including those that until now passed by it (a value narrowed to a class it did not hold, a read of a method that returns nothing); a spent budget, a stopped run and an add-only refusal remain uncatchable. With no matching handler, the outcome propagates. Handlers may be written in either order, and a category may be named more than once — the first handler naming the raised category runs, as in Python, and a later handler for that same category never runs. The program still compiles, and compile and run each answer with a note naming that handler and the line of the one that runs, after the result and as a notes entry the MCP Reference describes. An optional else (allowed only alongside an except) runs when the body raised nothing; a refuse in the else is not caught here. An optional finally runs on every exit path — clean, caught, propagating, or a break/continue leaving the block — and runs last; if the finally itself raises or breaks, that supersedes. A try needs at least one except or a finally. A name first bound in the body and in every handler is readable after the try, the else reads what the body bound, and a name the finally binds is readable after it; the finally itself reads none of the body’s names, since it also runs when the body did not complete (Python Specification §6.1).

try:
    remember(Reading.probe.taken_at, "not a timestamp", "sensor")
except refuse as r:
    print(r.reason)
    if r.teaching_hint != "":
        print(r.teaching_hint)              # empty when there is no suggestion
except engine_error as e:
    print(e.reason)

Report .reason; add .teaching_hint when it is non-empty, since it says how to correct the call. Branch on .discriminator (or an engine error’s .code) only where the program must act differently — see §4.2.

7.10 branch / commit / rollback

with branch("experiment"):
    remember(K.s.color, "tigret", "audit")
    if ok:
        commit
    else:
        rollback

A with branch("<name>"): block groups writes transactionally: clean exit commits; an uncaught refuse / engine error rolls back. Leaving the block early by return, break or continue is a clean exit and commits, as reaching the end does — the line is between leaving and failing, not between leaving early and leaving at the end. To abandon the writes, say rollback. Bare commit / rollback end the branch explicitly — the branch is over at that statement, so a write in the block’s remaining lines is an ordinary, immediately durable one. Ordinary invocation is not transactional.

An update inside the block revises a claim its source recorded before the branch as it would outside one, and a remember after it is judged against the new claim:

remember(Plant.basil.min_moisture, 40, "care-guide")
with branch("bonus"):
    update(Plant.basil.min_moisture, 40, "care-guide", null, datetime("2026-10-31T23:59:59Z"))
    remember(Plant.basil.min_moisture, 25, "care-guide", datetime("2026-11-01T00:00:00Z"), null)
# October reads 40 and January reads 25, in the block and after it

What the store’s rules concluded from the claim from before the branch no longer reads inside the block either, as after a commit, while a conclusion the rules still reach from what the block reads does. A fact the block writes does the same to what the rules concluded from that fact’s absence. The claim from before the branch is not changed, and neither is what was concluded from it, so a rollback leaves the store exactly as it was. → §5.1

A branch’s name begins with a letter or _ and continues with letters, digits, _ or -; it holds no . or space and cannot be empty. Any other name is a refuse naming the character at fault, before the block runs. A branch may not take the name of a world that exists, and cannot open inside a world block (§7.18).

7.11 import (module)

import catalog                       # in a program body: load a stored module

A DKE Python file is a module (§9); import <module> loads one: it runs the module’s body once and makes its names available under the module’s namespace. import is a reserved word, as it is in Python, and begins the import statement at statement head. A module may import another module; an import cycle is rejected when the module loads. Loading a module already loaded reconciles it: only the cells whose values changed are rewritten, so re-import is safe to repeat. → §9.1, §9.3, §9.5

A module’s names are namespaced. A kind a module declares with class is addressed under the module name — catalog.Product. The module-qualified construction module.Kind(subject) is an instance of it, and you read a cell through the instance’s field, as with any class:

p = catalog.Product("widget").price    # read catalog's Product widget, field price
print("price = " + str(p.value))

You can also bind the instance first. After w = catalog.Product("widget"), w.price reads the same cell, and w can be passed to a catalog script that takes a Product. Two modules may each declare a Product without collision (catalog.Product, store.Product, distinct). A script a module declares with def is addressed the same way — module.script — and that qualified name is how the service surface names it: the name info and forget take, the name list reports, and the name instructions call once the module is imported (warehouse.restock, store.restock, distinct). A script’s own body still calls its siblings unqualified; the qualifier is the address, used from outside at the service surface. → §9.6

An import also brings the module’s kinds into scope unqualified, so after import catalog a bare Product means catalog.Product:

import catalog
def restock():
    remember(Product.widget.price, "9", "ops")   # catalog's Product

A kind the unit declares itself wins over an imported one of the same name, and if two imported modules declare the same kind the program is refused — name the module to say which you mean (catalog.Product). That rule covers a kind in a path. A class is constructed only through its module: after import catalog, a bare Product("widget") is refused, just as a bare name is after import catalog in Python. → §9.6

Provide a module from the wire. compile with a source stores a module by name and runs it (§5.7). Every module in a store arrived that way. The bare import <module> is the in-language form written in a program. → §9.3, §9.4

Data at module scope. A write verb (§5.1) written at a module’s top level — not inside a def — is a data declaration: it runs when the module is compiled or imported. A module that only declares a schema, installs a rule, or writes data defines no callable script and is loaded for its body’s effect. → §9.2, §9.7

# in a module body, at top level:
remember(Rate.vat.pct, 25, "2026-finance-act")   # runs when compiled or imported

7.12 return

def classify(n: int) -> string:
    if n > 100:
        return "big"
    else:
        return "small"                # every path returns → value script (§7.1)
def find(xs: claim_list, stop: string):
    for c in xs:
        if c.value == stop:
            return                     # bare early exit → any script
        print(c.value)

A bare return ends the current script early and is valid in a script returning no value; outside a script it is refused, as Python refuses it. A return <expr> yields a value and makes the script a value script (§7.1); the expression’s type must match the declared -> type (an int satisfies -> real), and with none, the returns give the type, the wider of two where one fills the other. A value script must return on every path — a return in its suite, or an if/else (or exhaustive match) where each branch returns; a for alone never satisfies it. Two returns of types neither of which fills the other, or a value script that can fall off its end, are a type_error. A return exits past any enclosing for/try (running a try’s finally first) and never runs a for … else.

7.13 print

print("hi", who)                 # one line: "hi <who>"
print(1, 2, 3)                   # "1 2 3"
print("a", "b", sep=", ")        # "a, b"
print("x", end="!")              # "x!"
print(*[1, 2], 3, sep="-")       # "1-2-3"
print(1, 2, sep="-" * 2)         # "1--2"
print("x", flush=True)           # "x"
print("a", "b", **{"sep": "-"})  # "a-b"
opts = {"sep": "-", "end": "!"}
print("a", "b", **opts)          # "a-b!"
print()                          # an empty line

Writes one output line. Each argument is written as its text form (§7.3) and the pieces are joined by sep (default a single space), then end (default a newline) is appended. An argument written with * spreads a collection, and each of its elements is an argument of its own (§6.13). sep and end are keyword arguments, each any expression that gives a string, read after the positional arguments in the order written. None written as the whole of either is its default, and one that gives anything else is a catchable refuse when the line is composed, “sep must be None or a string, not int”. flush is read and changes nothing, and file may be given None alone, its default. A keyword print does not take is a type error in Python’s words ('x' is an invalid keyword argument for print()), the first one written, followed by the ones it takes. A ** before a dict display gives these keywords as its keys (§7.4). A ** before any other dict, such as a name that holds one, gives them as the line is composed, merged where it was written, as Python merges a call’s keywords: a name given twice (print() got multiple values for keyword argument 'sep') is refused as it is met, and a key that is no string (keywords must be strings) once every mapping is merged, then the first name print does not take, written or given, in Python’s words alone, then the values, sep before end. Each is a catchable refuse with discriminator type_error, and a file it gives is refused in the words a written one is given. An operand that is no dict is a type error where the unit is compiled (print() argument after ** must be a mapping, not list). Output is line-oriented — each print writes exactly one line — so a trailing newline in end is that line, and end="" reads the same as the default (there is no continuing a line).

7.14 pass

if x > 0:
    print("positive")
else:
    pass                         # do nothing

A no-op statement: it does nothing and produces no output. Use it where a block would otherwise be empty.

7.15 raise

def withdraw(amount: int):
    if amount <= 0:
        raise ValueError("amount must be positive")
    remember(Account.main.pending, amount, "teller")

try:
    withdraw(x)
except refuse as r:
    print("blocked: " + str(r.reason))          # "blocked: amount must be positive"
    print("kind: " + str(r.discriminator))      # "kind: ValueError"

Raises a recoverable error — a refuse — that an enclosing try catches with except refuse as r:. Name one of the built-in exceptions (ValueError, KeyError, TypeError, RuntimeError, …); the message becomes r.reason and the exception name r.discriminator. Several arguments are held as Python holds them, and r.reason is the text of their tuple. Every exception name behaves the same — there are no custom exception types. A raise never falls through, so a branch that ends in one satisfies a value script’s “return on every path”.

raise alone raises again what is being handled, in an except or in a finally with one pending, keeping its category, reason and discriminator; with nothing being handled it is RuntimeError: No active exception to reraise. raise e raises what a handler’s e holds. raise X from e and raise X from None read as Python’s do; nothing here reads a cause back, so a cause changes nothing a program can observe, and one that is neither is a type_error, exception causes must derive from BaseException.

7.16 assert

def withdraw(amount: int):
    assert amount > 0, "amount must be positive"
    remember(Account.main.pending, amount, "teller")

assert x == 5                       # passes silently, execution continues
try:
    assert x > 100, "too small"
except refuse as r:
    print("caught: " + str(r.reason))            # "caught: too small"

Python’s assertion. assert cond evaluates the bool cond and, when it is false, raises an AssertionError — a refuse, equivalent to if not cond: raise AssertionError. assert cond, msg records msg on r.reason (evaluated only on failure); a bare assert cond gives an empty reason. A passing assertion produces no output and execution continues. A condition may begin with a bracket: assert (x) and assert (x), "m" are this statement. It is distinct from the absence-assertion verb assert(K.s.a, src) (§5.1), which records an explicit-absent claim, and which is read where the bracket ends the statement and holds a dotted name and then a comma. So assert (x.y, "m"), a tuple that never fails in Python, is the verb here.

7.17 Changing a collection

xs = [3, 1]
xs.append(2)                        # xs is [3, 1, 2]
xs.sort()                           # [1, 2, 3]
xs[0] = 10                          # [10, 2, 3]
del xs[-1]                          # [10, 2]
xs[1:] = [7, 8, 9]                  # [10, 7, 8, 9]
del xs[::2]                         # [7, 9]
tags = {"red"}
tags.add("blue")                    # {'blue', 'red'}
ages = {"ana": 30}
ages["bo"] = 25                     # {'ana': 30, 'bo': 25}
ages["ana"] += 1                    # {'ana': 31, 'bo': 25}
del ages["bo"]                      # {'ana': 31}

A list, a set and a dict are shared: b = a binds b to the list a holds, not to a copy, and a script called with a list receives that list. A statement that changes one changes it in place, so every name, parameter and container holding it sees the change, as in Python. Each answers nothing and is a statement of its own — ys = xs.append(2) is an error — save pop, setdefault and popitem, which answer a value too (below). On a list: xs.append(v), xs.extend(c) (the elements of a list, tuple, set, string or dict), xs.insert(i, v) (its position clamped, a negative one counting from the end), xs.remove(v) (the first equal element), xs.sort() with sorted’s optional key= and reverse=, xs.reverse(), xs.clear(), xs[i] = v, del xs[i], a slice write xs[i:j] = c (any collection, more or fewer elements; with a step, exactly as many as the slice selects), del xs[i:j], xs += c (any collection, as extend) and xs *= n. On a set: s.add(v), s.discard(v), s.remove(v), s.update(c), s.difference_update(c), s.intersection_update(c), s.symmetric_difference_update(c), s.clear(), and |=, &=, -= and ^=. On a dict: d[k] = v (a key already held keeps its place), d.update(e) (another dict, or (key, value) pairs, then any names as string keys: d.update(e, a=1)), d.clear() and del d[k]. An element or slice write evaluates its value before its target, and an augmented one, xs[i] += v or d[k] += v, its index or key once, as Python does. Each of these changes the collection its target reaches, so it works on an element, or on what a method answers, as on a name: m[i][j] = v, d[k].append(v), del m[i][j:] — the chain before the last step is read once. It works on a value no name holds as well, read once, f(xs).append(v), [xs][0].sort() or del f(xs)[0], and through parentheses, which are the name or element they hold: (xs).append(v) and del (xs)[0] change xs. A list of targets in parentheses is that list, so del (a, b) is refused as del a, b is. A target that is no name, attribute, element or slice, such as del f() or del xs[0] + 1, is a parse_error at that target, naming what it is, as in Python.

a = [1]
b = a
a.append(2)                         # b is [1, 2] as well
row = [0]
grid = [row, row]
row.append(1)                       # grid is [[0, 1], [0, 1]]
r = grid[0]
r.append(2)                         # grid is [[0, 1, 2], [0, 1, 2]]
grid[0][0] = 5                      # grid is [[5, 1, 2], [5, 1, 2]]
groups = {"a": []}
groups["a"].append(1)               # {'a': [1]}
c = a.copy()                        # a new list: c.append(3) leaves a as it is

A literal, a comprehension, .copy(), list(c), set(c), dict(c), sorted(c), a slice read and the operators +, *, |, &, - and ^ build a new collection, shallow as Python’s is: its elements are the ones its operands hold. To change a collection and keep the original, copy it first — xs.copy(), s.copy(), d.copy() or dict(d). x = e binds x to what e answers and changes nothing x held before; += on a number, a string or a tuple binds a new value, as in Python.

The changed collection keeps its type, so xs.append("a") on a list<int> is a type error naming the type change, as xs += ["a"] is. A collection first bound empty takes its element type from the first statement that supplies one, for every name holding it: after a = [], b = a, a.append(1), b is a list<int>, and b.append("x") is refused as b sharing its element type with a. A .get() default supplies a dict’s value type the same way: counts = {} filled by counts[w] = counts.get(w, 0) + 1 is a dict<string, int>. An operator supplies it too: counts[w] += 1 under if w in counts: makes counts a dict<string, int> (* and % supply nothing), and a read nothing supplies a type for is refused naming the annotation, d: dict<string, int> = {}. An empty collection written into a collection of collections takes their type: grid.append([]) on a list<list<int>> and d[k] = [] on a dict<string, list<int>> are accepted. A collection built from one still empty (b = a.copy(), b = list(a)) shares its element type too, since a loop could build it after the source holds elements — Python would let the two differ. A collection cannot hold itself: a.append(a) is a type error. A slice write takes any collection, typed as extend’s argument is, and a change through an element keeps the element’s type: m[0].append("a") on a list<list<int>> is refused naming m[…].

Changing and answering. pop, setdefault and popitem change the collection and answer a value, so each is an expression as well as a statement and works wherever an expression may stand. xs.pop() removes and answers a list’s last element, and xs.pop(i) the one at i, a negative i counting from the end. s.pop() removes and answers a set’s first element in its sorted order, where Python’s choice follows its hash table. d.pop(k) removes k and answers its value, and d.pop(k, default) answers the default when k is absent. d.setdefault(k, default) answers the value at k, writing the default there first when k is absent — DKE Python has no None, so the default is required. d.popitem() removes the last entry and answers it as a (key, value) tuple. A default supplies an empty dict’s value type as a .get() default does, so setdefault groups by key. As a statement the answer is discarded; within an expression the call runs where Python evaluates it.

xs = [3, 1, 2]
last = xs.pop()                     # 2; xs is [3, 1]
first = xs.pop(0)                   # 3; xs is [1]
ages = {"ana": 31, "bo": 25}
bo = ages.pop("bo")                 # 25; ages is {'ana': 31}
cy = ages.pop("cy", 0)              # 0; ages is unchanged
groups = {}
groups.setdefault("a", []).append(1)  # {'a': [1]}
k, v = ages.popitem()               # k is 'ana', v is 31; ages is {}

A change the collection cannot make is a catchable refuse (§10) in Python’s words: xs.remove(v) of an absent value is list.remove(x): x not in list (discriminator value_not_in_list); s.remove(v) of an absent element and del d[k] of an absent key give the repr of the missing value (key_not_found); a list index outside the list on a write or del is list assignment index out of range (index_out_of_bounds); a slice with a step, written with a different number of elements than it selects, is attempt to assign sequence of size N to extended slice of size M (value_error); a step of 0 is slice step cannot be zero (slice_step_zero); xs.pop() on an empty list is pop from empty list and xs.pop(i) outside the list pop index out of range (index_out_of_bounds); and s.pop() on an empty set is 'pop from an empty set', d.pop(k) of an absent key with no default the repr of the key, and d.popitem() on an empty dict 'popitem(): dictionary is empty' (key_not_found).

A loop over what its body changes. A for reads a list as it stands at each step, as Python does, so removing elements ends it sooner — but it never runs more steps than the list had when it began, so appending to the list it walks stops there, where Python would go on (the bound is what termination rests on). A list’s extend over the list itself, by an iterator or a generator expression, stops at the same bound. A for over a dict or set walks what it held at the start, and a change of its size is a catchable refuse at the next step in Python’s words — dictionary changed size during iteration or Set changed size during iteration (changed_during_iteration). Writing a value to a key already held is not a change of size. A for over a dict view (§6.9) reads the dict at each step, taking the element at the position it has reached, so it binds a value written during the loop; removing a key it has passed makes it pass over one, where Python’s does not.

One element at a time. A set’s update and difference_update, and a dict’s update, read an iterator or a generator expression one element at a time, changing the collection by each before reading the next, as Python’s do. One that reads the collection being changed finds it changed and is refused at the read after its size changes, in the same words; what was written before stays, so after s = {1, 2} a caught s.update(x + 10 for x in s) leaves {1, 2, 11}. A dict’s pair of the wrong length is refused naming its position, after the pairs before it are written. intersection_update and symmetric_difference_update read theirs whole first, as Python’s do.

Not statements. del x would unbind a name, which stays bound to the end of its script. A string and a tuple take none of these; rebuild them from slices.

7.18 world

create_world("wet")
with world("wet"):
    remember(Field.north.rain_mm, 180, "forecast")
    r = current(Field.north.rain_mm)
    print(r.value)

A with world(<name>): block runs its body inside the world named (§5.9). The name is a string expression, read once before the body. Entering brings the world up to date with the store; the body reads the store and the world together, and every write in it lands in the world. Leaving the body by any path — its end, return, break, continue, or an uncaught refuse or engine error — leaves the world, and the statements after the block run outside it. Nothing is committed or rolled back on the way out: what the body wrote stays in the world until merge_world or discard_world. A script called inside the block runs in the world.

A world block cannot open inside another world block or inside a branch block, and a branch block cannot open inside a world block. Written inside one another, these are compile-time errors; reached through a script called from inside one, each is a refuse. world is a contextual keyword, recognised only after with, and an ordinary identifier elsewhere.

7.19 Named expressions (:=)

xs = [1, 2, 3]
if (n := len(xs)) > 2:
    print(n)
print(a := 1, a)
print([y for x in xs if (y := x * 2) > 2], y)

name := value binds the name when it is evaluated and answers the value, in parentheses, as an element or an argument, and as the whole condition of an if, an elif or a case’s guard, or the whole subject of a match, as in Python. Anywhere else, as in y = a := 1, it is a parse_error at the :=. It binds as an assignment does, so the name keeps its one type, and what is evaluated before it reads the old value. In a comprehension it binds in the scope that holds the comprehension. It is a binding, so it costs no operation, and its value cannot be a read of the store (§7.2).

8.1 Class declaration

class Sensor:
    temp: string                                 # typed field (primitive)
    def record(self, v: string, src: string):    # void method (explicit self)
        remember(self.temp, v, src)
    def label(self) -> string:                    # value method
        return "sensor"

Written class <Name>:. Fields are name: type with a primitive type; names unique within the class. Declaring a class stores nothing. A class may name a single base class it extends — class Dog(Animal): — inheriting the base’s members (§8.10). A class exists from the line that declares it, as in Python: a line that runs as the module runs and names one below it is refused, name 'K' is not defined. The body of a def or a method runs when called, so it may name a class declared anywhere in the unit, and a signature may name one in a string, def f(x: "K"):. A module statement reaching such a body above the class is refused in the same words.

8.2 Instance construction and binding

s = Sensor(room)

Sensor(room) names one member of Sensor identified by the string room; bound by assignment, its type is the class name. Construction records nothing. Reading a never-written field yields empty.

A class declared by a unit you compiled earlier is constructed the same way wherever that unit’s scripts are called by their bare names (§7.4). Its fields, its methods, a parameter annotated with it and isinstance all work as they do for a class your own unit declares. Declaring a class that extends it is refused: a subclass needs the class’s body, which only the unit that declared it has. A class, script or import of the same name in your unit takes the name, and a class declared again replaces the earlier one for the units compiled after it.

8.3 Field read and write

reading = s.temp                    # read → active_claim or empty
remember(s.temp, "21", "op1")       # write value + provenance source

A read has type active_claim; consume with match or .value. Accessing a field the class does not declare is a type_error, as is calling a method it does not declare. Inside a method the explicit receiver self (the first parameter) names the instance (self.temp).

Every verb that takes a K.s.a cell takes a field written this way as that field’s cell, the one remember writes, through any name that holds an instance: current(s.temp), get(s.temp) and why(s.temp) read it, and so do verify, agreement, writers, pin, unpin, prefer, unprefer, why_not, what_needs, assert, forget and would_forget, and a hypothesis takes it as each field it supposes and as the field it reads (§8.9). The cell is that of the class the instance was constructed with, so through a parameter of a base class it is the subclass instance’s. A verb that takes a class and a subject — caveats and list_attributes — takes the instance itself as that subject, caveats(s), through any name that holds one. A verb that takes a class and one of its fields — list_values, list_subjects, subjects or a fold — is given the class, list_values(Sensor.temp). An instance’s field at either is a type_error.

A field is reached through an instance variable: a name bound by construction, a parameter of the class’s type, a call to a script declared to return the class, the loop variable of a for over a list of instances or a tuple of them, an element taken from such a list by index, a second name for one of these, a conditional expression over two instances of classes with a common base, or a binding annotated with the class. A list of instances is a display of them, a name bound to one, a list<Sensor> or *args: Sensor parameter, a call to a script declared to return list<Sensor>, a comprehension that collects its own loop variable over one, a slice of one, or two joined with +. An instance in a dict or a tuple whose type is declared, or in a dict or tuple display that holds one, is reached the same way: by key, by a literal index, by unpacking, and through values() and items(). Through a name holding an instance from anywhere else, such as the value d.get(key, default) returns, a verb reaches the field, as above, but reading the field itself through it is a type_error, as is a field read straight off such an expression (xs.pop().n); declare the name with the class first:

class Sensor:
    temp: string

def readings(rooms: dict<string, Sensor>):
    x = rooms.get("hall", Sensor("none"))
    item: Sensor = x
    reading = item.temp

A method called through such a name or straight off such an expression, and a class match over the name (§8.6), are refused the same way, naming the binding to write first. A field or a method may also be taken straight after a call or an index that reaches an instance this way, with no name written between them: reading = rooms["hall"].temp, sensors()[0].record("21", "op1"). The call or the index is evaluated once, where the expression is.

8.4 Void method

s.record("21", "op1")               # statement position; self is supplied by the receiver

def name(self, params): — no return type and no return <expr>; performs actions; called as a statement. The self argument is supplied by the receiver, not written at the call.

A method’s arguments bind as a script’s do (§7.1): by position or by keyword, an omitted one takes its default, and a parameter list may hold / and a bare *.

A method’s call takes a spread as a script’s does (§7.4): s.record(*pair). Python counts the receiver among the positional arguments, and so does a refusal: Box.record() takes 3 positional arguments but 4 were given. It names the method by the class whose body holds its def, as Python does, so a method Sub inherits from Box is Box.record. Called on a class another module declares, it is named by that class instead.

8.5 Value method

name = s.label()                    # expression position

def name(self, params) -> type: whose body is what a value script’s may be, any statements with a return of that type on every path; called in expression position. With no -> type, a body holding a return <expr> gives the method its type, as a def’s does. The return type is any a def takes, a collection included (-> list<string>). A method returning a field read declares -> active_claim, or nothing; one returning a store fold declares -> value, which its caller narrows with match, as its own body may. A method may call one written below it. Resolved from the receiver’s class — the actual class when the receiver is held at a base type (§8.10); compile-before-call; no recursion.

Called as a statement, s.label() runs and its value is discarded, as a value script’s is.

8.6 Class match (dispatch by class)

match s:
    case Sensor:
        remember(s.temp, "22", "op1")
    case Actuator:
        remember(s.state, "on", "op1")

A match whose scrutinee is a name the compiler follows to an instance may dispatch over class names. Inside case <Class>: the instance is treated as that class; a case matches that class or any subclass, first match winning (§8.10). An arm names its class as an annotation does, so a class a module declares is case geo.Site:, or case Site: after from geo import Site. Written so, the arm set is closed and exhaustive — cover every class the instance could be, or provide a catch-all, case default: or case _:, which must be the last arm — and a non-exhaustive one is a parse_error. case Site():, Python’s spelling, is the same arm and is a test, as §7.8 reads one over any value: a match with an arm written so runs no arm when none holds, and takes | between classes.

8.7 Computed fields

A class field declared with an initializer the engine derives from the class’s other fields and keeps current as they change. The customer writes only the inputs; the derived field reads back like any field, with a derived provenance in place of a source.

class Order:
    price: int
    qty: int
    total: int = price * qty        # int: an arithmetic expression (+ - * %) over earlier fields
    big: bool = total > 1000        # bool: one ordered comparison of an earlier field

An int field is arithmetic (+ - * %) over earlier fields; a real field may also use /; a complex field is arithmetic (+ - * /) over earlier fields, numbers and imaginary literals, and derives what a program computes for the same expression (§6.3); a bool field is one ordered comparison (< <= > >=), and holds neither True nor False for a subject whose input it cannot rank — a blob, which has no order, or a value of another type, such as a string recorded in an int field; why_not there says so. A complex number has no order either, and a bool field that compares a complex field is refused where it is declared. A field whose expression divides by zero holds no value for that subject. Every reference is to a field declared earlier, so a class’s computed fields form no cycle among themselves. One that would close a cycle with what the store already holds, a computed field an earlier compile installed or a rule, is refused at the compile that closes it, naming the field, when the cycle passes through a field that applies an operator (total: int = price * qty); a cycle of copies and comparisons settles and is accepted. Writing an input re-derives every field built on it. why over a computed field lists the inputs it was derived from (§5.3).

A computed field is never written. remember, update or a supposition there refuses, naming the inputs to write instead, and current goes on reading the derived value. forget there is never refused. Installing a class whose computed field already holds recorded values refuses as well, naming them: forget them, or give the computed field a name of its own.

8.8 Standing rules

A named top-level declaration — a sibling of class / def, not a class member — that derives a field automatically: its conclusion is in force exactly while its condition holds, so a derived field always reflects the current data. The @rule decorator marks the def as a rule; absent names one of its three negative premises, inside a rule block only.

@rule
def needs_review():
    for o in Order:
        if o.total > 1000 and absent(o.shipment):
            o.review = True

• for <var> in <Kind> (, <var> in <Kind>)* — the name the rule gives each subject, and the kind whose fields it reads under that name. The premises say which subjects a name ranges over. A name whose fields a comparison, a join or another ranging premise reads ranges over the subjects recorded with those fields; a name reached only through a join or a relation ranges over the subjects the join or the relation names, whether or not anything of its kind is recorded for them. So in for e in E, x in N, y in N: if e.a == x and e.b == y: Link.x.y = True, an E naming p and w concludes Link.p.w though no N named w is recorded; adding and y.name == y.name limits y to the Ns recorded with a name. Names must be distinct. The bindings are a conjunction and carry no order; a nested for is not accepted, because nesting would read as a walk and a rule states a condition over the whole store.
• if <premise> (and <premise>)* — every premise must hold: