serif

Python in, Python out. Allowed to raise, not allowed to lie.

Serif is typed vectors and tables for Python, built around two promises: touching your data should feel like ordinary Python, and ambiguous operations should fail loudly.

Values stay Python values — int, float, str, date, None — so there is nothing to convert, unwrap, or remember. And serif does not silently coerce, mutate, or guess. When an operation has no clear meaning, it raises.

Vector provides the foundation. Table is the primary interface for exploration, modeling, and analysis.

30-Second Example

from serif import Table

t = Table({
    "price ($)": [10, 20, 30],
    "quantity":  [4, 5, 6]
})

t >>= {'total': t.price * t.quantity}
t >>= {'tax': t.total * 0.1}

t
# 'price ($)'   quantity   total      tax
#      .price  .quantity  .total     .tax
#       [int]      [int]   [int]  [float]
#          10          4      40      4.0
#          20          5     100     10.0
#          30          6     180     18.0
#
# 3×4 table <int, float>

Installation

pip install serif

Serif has no required runtime dependencies. Its pure-Python implementation defines the semantics; optional accelerators improve performance without changing behavior.

NumPy and PyArrow are used when available, but only when they preserve the same Python values and behavior. Otherwise, Serif falls back to pure Python.

pip install "serif[numpy]"
pip install "serif[pyarrow]"
pip install "serif[numpy,pyarrow]"

Quickstart

Vectors

from serif import Vector

a = Vector([1, 2, 3, 4, 5])

a * 2         # 2, 4, 6, 8, 10
a > 3         # False, False, False, True, True
a[a > 3]      # 4, 5 — boolean masks filter
a.sum()       # 15 — a plain Python int

Tables

from serif import Table

t = Table({
    "first name": ["ann", "bo", "cy"],
    "price ($)":  [10, 20, 30],
})

t.price * 2                    # names sanitize for dot access
t >>= {'total': t.price * 2}   # add a column
t[t.price > 15]                # masks filter rows

t._                            # what do I have again?
# .first_name   str   'first name'
# .price        int   'price ($)'
# .total        int

None means missing

Element-wise, unknown in is unknown out. Aggregates summarize what you know.

v = Vector([10, None, 30])

v + 1        # 11, None, 31
v > 15       # False, None, True
v.sum()      # 40
len(v)       # 3

Joins and aggregation

customers = Table({'id': [1, 2, 3], 'name': ['Ann', 'Bo', 'Cy']})
scores    = Table({'id': [2, 3, 4], 'score': [85, 90, 95]})

customers.inner_join(scores, left_on='id', right_on='id')
# id, name, score — matched key columns are not duplicated

sales = Table({'customer': ['A', 'B', 'A'], 'amount': [100, 200, 150]})

sales.aggregate(
    groupby=sales.customer,
    aggregations={'total': sales.amount.sum, 'n': len},
)
# customer  total      n
# [str]     [int]  [int]
# A           250      2
# B           200      1
#
# 2×3 table <int, str>

CSV and Parquet

from serif import read_csv, read_parquet

t = read_csv("sales.csv")        # types inferred, headers sanitized for dot access
t.to_parquet("sales.parquet")    # ints, dates, and nulls arrive intact
u = read_parquet("sales.parquet")
recent = u[u.date >= cutoff]      # remaining columns load through this mask

read_parquet reads the footer first and materializes columns only when they are touched. Boolean filtering stays ordinary Serif filtering: the concrete mask is carried into columns that have not been read yet, so the first fully materialized table can be the filtered one. Keep the source file readable and unchanged until the table has materialized.

Documentation

• Design Philosophy — the principles everything else answers to
• Serif vs Python — the few intentional departures
• Table Model — the column-major table
• Indexing — slicing, masking, and selection rules
• Null Semantics — None, three-valued logic, verdicts
• Joins & Aggregations — detailed examples and patterns
• Naming — column names and sanitization
• Repr — what the display shows and why
• Invariants — the promises the internals keep
• Exceptions — error types and when they raise
• Aliasing — copy-on-write
• Performance — complexity of the core operations
• Gotchas — sharp edges worth knowing up front
• Development — running tests, project structure

License

MIT

Contributing

See CONTRIBUTING.md and CODE_OF_CONDUCT.md.