DEV Community: MEROLINE LIZLENT

PyScript

MEROLINE LIZLENT — Tue, 08 Sep 2026 08:49:43 +0000

For decades, JavaScript has had an iron grip on the browser. You could have it running on a server, you could have it running on a Raspberry Pi, you could have it running pretty much anywhere, but as soon as a user opened a tab, you needed JS. That's changing.
Running Python directly in an HTML page, complete with the Python ecosystem and the DOM and browser APIs. No server, no backend, no transpilation. Among Python, in the browser, in real.
The article covers everything from what PyScript is, how it works, what it can do now, and where it's headed.

What is PyScript?

PyScript is an open-source platform developed by Anaconda, Inc. and first unveiled by CEO Peter Wang at PyCon US 2022. It lets you embed Python code in HTML pages using standard <script> tags, and that code runs natively in the browser.

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://pyscript.net/releases/2025.11.1/core.css" />
  <script type="module" src="https://pyscript.net/releases/2025.11.1/core.js"></script>
</head>
<body>
  <h1>Hello from Python</h1>
  <script type="py">
    from pyscript import display
    display("Python is running in your browser!")
  </script>
</body>
</html>

That's it. No build step. No npm install. No Webpack. Drop two tags in your <head> and start writing Python.

How does it actually work?

This is the part that makes PyScript genuinely interesting, it's not a gimmick or a transpiler. It's real Python, running through WebAssembly (WASM).

PyScript ships with two Python interpreters, both compiled to WebAssembly:

1. Pyodide, Full CPython in the browser

Pyodide is the original CPython interpreter compiled to WebAssembly. This is the actual CPython runtime that Python developers use on their machines, ported to run entirely inside a browser sandbox.

What this means in practice:

The full Python standard library is available
Most pure-Python packages from PyPI work out of the box
Scientific computing packages (NumPy, Pandas, Matplotlib, Scikit-learn) ship with pre-compiled WASM binaries

<script type="py">
  import numpy as np
  import matplotlib.pyplot as plt
  from pyscript import display

  x = np.linspace(0, 2 * np.pi, 100)
  y = np.sin(x)

  fig, ax = plt.subplots()
  ax.plot(x, y)
  display(fig, target="chart")
</script>

2. MicroPython, Lean and mobile-friendly

MicroPython is a lightweight reimplementation of Python 3. Its WASM build is just ~170KB, dramatically smaller than Pyodide. This makes it the right choice for:

Mobile and tablet browsers with constrained resources
Fast initial page loads where startup time matters
Simpler apps that don't need the full CPython stdlib

<!-- Use type="mpy" for MicroPython instead of Pyodide -->
<script type="mpy">
  from pyscript import display
  display("Running MicroPython, tiny and fast!")
</script>

Both interpreters implement the same FFI (Foreign Function Interface), so switching between them is mostly a matter of swapping type="py" for type="mpy".

DOM access and the FFI

The Foreign Function Interface (FFI) is PyScript's superpower. It creates a bi-directional bridge between Python and the browser's JavaScript environment, meaning Python can call JavaScript APIs, and JavaScript can call Python.

Manipulating the DOM from Python

<button id="my-btn">Click me</button>
<p id="output"></p>

<script type="py">
  from pyscript import document

  def on_click(event):
      output = document.getElementById("output")
      output.textContent = "Button clicked! Python handled it."

  btn = document.getElementById("my-btn")
  btn.addEventListener("click", on_click)
</script>

Using the `pyscript.web` API (higher-level)

PyScript ships a Pythonic wrapper around DOM manipulation so you don't have to think in JavaScript at all:

from pyscript import when, display
from pyscript.web import page

@when("click", "#my-btn")
def handle_click(event):
    display("Clicked!", target="#output")

Calling JavaScript from Python

The FFI lets you reach into the browser's native JS APIs:

from pyscript import window

# Call browser's built-in JS APIs directly
window.alert("Hello from Python!")
window.console.log("Logged from Python")

# Access localStorage
window.localStorage.setItem("key", "value")

Calling Python from JavaScript

It's bi-directional — JS code can call Python functions too:

// In a <script> tag
const result = await pyscript.interpreter.run("2 + 2");
console.log(result); // 4

Web Workers: non-blocking Python

One of PyScript's most practical features is first-class support for Web Workers. By default, Python runs on the browser's main thread. If you do anything CPU-intensive (think data crunching, image processing, ML inference), the UI freezes.

Workers move expensive computation off the main thread:

<!-- worker="true" runs this in a Web Worker -->
<script type="py" worker>
  import time

  # This heavy computation won't block the UI
  total = sum(i * i for i in range(10_000_000))

  from pyscript import display
  display(f"Result: {total}")
</script>

Workers are isolated, each one gets its own Python interpreter. They can communicate back to the main thread via PyScript's messaging API, enabling patterns like streaming results to the UI as computation progresses.

Installing packages

PyScript supports installing packages from PyPI using a simple configuration block:

<script type="py" config='{"packages": ["pandas", "requests", "pillow"]}'>
  import pandas as pd
  import requests

  # These are real PyPI packages, running in your browser
  df = pd.DataFrame({"x": [1, 2, 3], "y": [4, 5, 6]})
  from pyscript import display
  display(df)
</script>

Or use a separate <py-config> tag for cleaner HTML:

<py-config>
packages = ["numpy", "matplotlib", "scikit-learn"]
</py-config>

For MicroPython, the mip package manager handles package installation in a way suited to MicroPython's smaller runtime.

The built-in terminal and editor

PyScript ships two interactive components out of the box.

Python Terminal

Add terminal to your script tag to get an interactive REPL embedded in your page:

<script type="py" terminal>
  # This renders a full interactive Python terminal on the page
  # Users can type Python directly into it
</script>

Python Editor

The editor component gives users a full code editor (powered by CodeMirror) with a run button:

<py-editor>
import math
print(math.pi)
</py-editor>

Both are ready for embedding into documentation, tutorials, or educational tools, no backend required.

Plugins

PyScript is built on a lean core called PolyScript. Most of its functionality is layered on top through a plugin system, which means the core stays small and efficient while the feature set can grow through community contributions.

Writing a PyScript plugin looks like this:

# my_plugin.py
from pyscript import Plugin

plugin = Plugin("my-plugin")

@plugin.setup
def setup():
    print("Plugin initialized!")

This architecture keeps PyScript extensible without bloating the core, a clean separation of concerns.

PyScript vs. alternatives

	PyScript	Transcrypt	Brython	WASM (raw)
Real Python	Yes	No (transpiles)	Yes	No
PyPI packages	Yes (Pyodide)	No	Limited	No
DOM access	Yes	Yes	Yes	Manual
Mobile-friendly	Yes (MicroPython)	Yes	Moderate	—
No build step	Yes	No	Yes	No
Maturity	Growing fast	Stable	Stable	Raw

The key differentiator is that PyScript runs actual Python not a Python-to-JS transpiler that emulates Python behaviour, and not a limited subset. You get real CPython semantics.

What can you build with PyScript today?

Interactive data dashboards -render Pandas DataFrames, Matplotlib charts, and Plotly visuals directly in the browser, shareable as a single HTML file.

Educational tools - interactive Python tutorials where learners run code in the browser without installing anything. Ideal for courses, workshops, and documentation.

Scientific notebooks - think lighter-weight Jupyter-in-the-browser experiences, without spinning up a Jupyter server.

Developer tools - embed Python-powered utilities (formatters, calculators, converters) into documentation sites.

Lightweight apps - with MicroPython, build simple Python apps that load instantly on mobile with a tiny footprint.

Honest limitations

PyScript is genuinely exciting, but a fair assessment includes its current constraints.

Initial load time. Pyodide's WASM bundle is several megabytes. First load can take a few seconds on slower connections. MicroPython's 170KB helps for lightweight use cases, but Pyodide's startup cost is a real UX concern for consumer-facing pages.

Not all packages work. Packages with C extensions that haven't been compiled to WASM won't install. The list of supported packages grows with each Pyodide release, but it's not PyPI-complete.

Browser sandbox limits. Python running in WASM is sandboxed by the browser, no filesystem access, no sockets, no subprocess. Some stdlib modules work differently or not at all.

Still maturing. PyScript is improving rapidly (releases almost monthly), but APIs do change between versions. Check the changelog before upgrading.

Getting started in 5 minutes

Create an index.html, paste this, open it in a browser:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <title>My First PyScript App</title>
  <link rel="stylesheet" href="https://pyscript.net/releases/2025.11.1/core.css" />
  <script type="module" src="https://pyscript.net/releases/2025.11.1/core.js"></script>
  <style>
    body { font-family: sans-serif; max-width: 600px; margin: 2rem auto; }
    button { padding: 0.5rem 1rem; font-size: 1rem; cursor: pointer; }
  </style>
</head>
<body>
  <h1>PyScript Demo</h1>
  <button id="btn">Run Python</button>
  <div id="output" style="margin-top: 1rem;"></div>

  <script type="py">
    from pyscript import when, display
    import random

    @when("click", "#btn")
    def on_click(event):
        number = random.randint(1, 100)
        display(f"Python picked a random number: {number}", target="#output")
  </script>
</body>
</html>

No npm. No build step. Just a file. Open it. Python runs.

For a richer sandbox, try pyscript.com, the official online editor with sharing and examples built in.

The bottom line

PyScript isn't trying to replace JavaScript. It's doing something more interesting: it's giving the 8+ million Python developers in the world a path to the browser without abandoning the language and ecosystem they already know.

For data scientists who want to share interactive work without a Jupyter server. For educators who want students to run code without installing anything. For developers who want to embed Python-powered tools into a docs site. PyScript is already viable for these use cases today, and getting better fast.

The browser just got a new language.

Resources

Have you tried PyScript? What did you build with it? Drop your experience in the comments, especially curious about anyone who used it for data science or education projects.

The Architecture Behind Software That Never Stops Running

MEROLINE LIZLENT — Wed, 26 Aug 2026 10:43:47 +0000

"Never stops running" is a lie in the literal sense , i.e. all hardware fails, all software runs out of memory, every deploy changes running code with different code. Failure is expected, it's being dealt with and it doesn't slow down, or "never stops running" as it is put. The design is not a failure prevention one. Failure is a normal, survivable, boring event not an outage!

Redundancy is not the same as availability

The naive version of high availability is "run two of everything." That's necessary but not sufficient, and teams that stop there get burned by split-brain: two nodes, each convinced it's the only one alive, both accepting writes, producing two divergent versions of the truth that someone has to reconcile by hand at 4 a.m.

What is needed is a consensus layer that sets 'who is in charge right now' on a fact the whole system agrees on, as opposed to a local fact set by each of the nodes. There are raft and Paxos-family protocols made specially for this purpose, and etcd, Consul and most managed database failover systems are based on one of them. The real guarantee you need is: At any time at least one node thinks that it's the leader. Failure of a single node is better than failure of multiple nodes; if a single node fails loudly, it's recoverable, but if multiple nodes agree quietly, it is data corruption before anyone notices.

// A leader-check that actually matters: verify leadership
// immediately before a write, not just at startup.
func (n *Node) Write(ctx context.Context, key, val string) error {
    if !n.raft.IsLeader() {
        return ErrNotLeader
    }
    // Leadership can be lost between this check and the write
    // completing — always route the actual write through the
    // consensus log, never write directly to local state here.
    return n.raft.Apply(ctx, Command{Key: key, Value: val})
}

Graceful degradation beats heroic uptime

If a system is up, but delivering errors for all its requests, that's not a system, it's just a technically running one. True resilience is the ability to agree, before the event, what the system should do if it is unable to access a dependency and making that action a conscious one, not the action that falls out of an unhandled exception.

This entails providing an answer to "what happens if this doesn't come back in time" other than "the request hangs forever". The standard tool is your circuit breaker: If a dependency fails repeatedly over a period of time, do not call it anymore and fail fast instead, to not tie up all of the threads in your process waiting for it to come back.

type CircuitBreaker struct {
    mu          sync.Mutex
    failures    int
    threshold   int
    state       string // "closed", "open", "half-open"
    lastFailure time.Time
    cooldown    time.Duration
}

func (cb *CircuitBreaker) Call(fn func() error) error {
    cb.mu.Lock()
    if cb.state == "open" {
        if time.Since(cb.lastFailure) < cb.cooldown {
            cb.mu.Unlock()
            return ErrCircuitOpen
        }
        cb.state = "half-open"
    }
    cb.mu.Unlock()

    err := fn()
    cb.mu.Lock()
    defer cb.mu.Unlock()
    if err != nil {
        cb.failures++
        cb.lastFailure = time.Now()
        if cb.failures >= cb.threshold {
            cb.state = "open"
        }
        return err
    }
    cb.failures = 0
    cb.state = "closed"
    return nil
}

The real point isn't the "circuit breaker pattern" itself, it's the design habit it's a part of: Figure out what the user will see if this particular dependency is down, and make that a design decision, not an incident retro.

Zero-downtime deploys are a data problem, not a process problem

The solution to process side is rolling deploys — creating new instances to replace old ones, rather than taking down the entire fleet. The more difficult challenge is deploying old and new code on the same data during rollout time, since for any deployment that takes more than a few seconds on a fleet, there is a period where old and new code live together on the same data.

That's why schema changes should be backward compatible both ways during migration: new code has to be able to handle the old schema, and old code (which will be serving some traffic during the migration) has to be able to deal with the new schema. The basic pattern is to split one migration into a number of deploys: insert the new column as nullable, deploy code that writes to both the old and new column, backfill, deploy code that reads only from the new column, and finally drop the old column in a later deploy when there is no reference to it. A single glance at the "rename column and redeploy" step is all it takes to transform a normal deploy into an incident, as during a rollout, some percentage of your fleet will be using code that depends on a column that is no longer present.

Self-healing means detecting and correcting without a human in the loop

Health checks that only respond to "is the process alive" see crashes but don't see the common failure: process is alive, it's accepting connections, it just hung on a dependency, it's leaking memory, it will reach an OOM kill, but hasn't yet. A liveness check should return something other than 200.

func (s *Server) HealthCheck(w http.ResponseWriter, r *http.Request) {
    ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
    defer cancel()

    if err := s.db.PingContext(ctx); err != nil {
        http.Error(w, "db unreachable", http.StatusServiceUnavailable)
        return
    }
    if s.queueDepth.Load() > s.queueDepthAlarmThreshold {
        http.Error(w, "queue backed up", http.StatusServiceUnavailable)
        return
    }
    w.WriteHeader(http.StatusOK)
}

Combine that with an orchestrator that actually takes action on this indicator (restart or remove node from rotation) and it becomes "a node is quietly degraded" to "a node is automatically replaced" and no one is paged for a problem the system could solve itself.

The actual architecture is organizational as much as technical

If the team's incentive is to pretend the above has not happened, or to cover up any degradation that is seen, none of these works. The “never stop running” systems are, at their core, systems constructed in a way where failure is a matter of fact and not a matter of code that will be executed after failure. So the uptime is a consequence of that assumption being executed to the hilt on every layer and not an add-on after the system is finished.

Building Performance Budgets Into Git

MEROLINE LIZLENT — Wed, 26 Aug 2026 10:10:58 +0000

Performance gets worse and worse as patches are added. None of the specific PRs contribute 200ms of latency, one contributes 3ms, another 5ms, and one 8ms, as someone implemented a "quick" N+1 query behind a feature flag that then became the default. Six months later you're 150ms slower than before, nobody can point to the commit that made you so slow, and a complete profiling investigation is the only way to determine where you are going. Don't fix it when you profile it, fix it when you regress it.

Treat perf budgets like any other CI gate

A performance budget is a number that your team agrees that a code path will not exceed, such as endpoint latency at p99, memory footprint of a service, bundle size of a frontend build. As with the point tests and lint, the budget should be applied pre-merge, in the CI environment and to a number which is tracked in version control along with the code rather than in a dashboard that no one checks until it turns red.

# .github/workflows/perf-budget.yml
name: perf-budget
on: [pull_request]
jobs:
  bench:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: go test -bench=. -benchtime=3x -run=^$ ./... > current.txt
      - run: git show origin/main:bench-baseline.txt > baseline.txt
      - run: benchstat baseline.txt current.txt
      - name: fail on regression over budget
        run: |
          python3 scripts/check_budget.py \
            --baseline baseline.txt --current current.txt \
            --max-regression-pct 5

The statistical comparison is done by the benchstat, part of Go's golang.org/x/perf suite of tools, which takes into account noise so you are not failing builds on a 1.2% fluctuation. The budget check script is the script that you create yourself, and it should fail loudly with the name of the specific benchmark, and the percentage regression.

Store the baseline in the repo, not in a dashboard

The big design decision is to place bench-baseline.txt (or equivalent) into the repository and only update it purposefully, as a step taken as a deliberate and reviewed action (usually in conjunction with a PR that deliberately sacrifices performance for some other gain, such as a feature that's worth it). This makes performance budget changes an accountable, reviewable change like any other code change:

# When a PR legitimately needs to update the budget:
go test -bench=. -benchtime=5x -run=^$ ./... > bench-baseline.txt
git add bench-baseline.txt
git commit -m "perf: raise checkout latency budget 12ms -> 18ms for fraud check v2

Trading latency for the new fraud detection pass. Approved in
#4021 — expected fraud loss reduction outweighs the latency cost.
See perf/2026-08-fraud-check-budget.md for the analysis."

Now if you type in git blame bench-baseline.txt, you get a real history of all the deliberate performance compromises that your team has made and the rationale for each, as documented in the commit where it was made. This is a much better place to get the truth than an 8-month-old Slack thread that nobody can find.

Scope budgets to what actually predicts user-facing pain

No, don't attempt to budget everything – you will become alert fatigued and the team will tune out the CI check – and that is not the point. For each of those few code paths with actual cost, pick it.For the handful of code paths that have actual cost, pick them: the "hot endpoints", the "critical rendering path", the necessary functions that show up wide on your production flamegraphs (see: latency archaeology). If it's an admin endpoint that you're not seeing very often, it's noise, if it's on your checkout path, or on your auth middleware, it's signal.

# scripts/check_budget.py — core logic
def check(baseline: dict, current: dict, max_pct: float) -> list[str]:
    failures = []
    for name, base_ns in baseline.items():
        if name not in current:
            continue
        cur_ns = current[name]
        pct = (cur_ns - base_ns) / base_ns * 100
        if pct > max_pct:
            failures.append(
                f"{name}: {base_ns}ns -> {cur_ns}ns (+{pct:.1f}%, budget {max_pct}%)"
            )
    return failures

Make the regression PR-blocking, not merge-blocking after the fact

The whole point of this is that this error is caught at the commit that introduced it, as the author still had all the context and can resolve it in 5 minutes instead of 5 hours, next quarter, doing a lot of archaeological work. If a nightly job recovers the same regression a week after the three subsequent PRs, it has already lost most of its value, you've got bisect to do again. Instead, perform the budget check as a status check that is required to be run on the PR itself, not as a separate scheduled job.

This is a real cost; there are costs to benchmarks for them to be stable enough not to flake, and there are costs to having someone with the updating budgets when they need to move. The other choice is the kind of situation that most teams are in right now: performance gradually sneaks up on them for months, then one person spends a week doing "latency archaeology" to discover it was 6 totally unrelated commits, all of which were individually justifiable, and it all added up to the problem no one signed off on.

Learning YAML From Scratch: What I Wish I Knew Before My First GitHub Actions Workflow published: true

MEROLINE LIZLENT — Tue, 11 Aug 2026 08:04:26 +0000

I thought that the hard part of learning CI/CD was understanding pipelines, build stages and deployment strategies. It was much simpler than that, it was a .yaml file. Specifically, it was when one of the spaces in a GitHub Actions workflow is missing that it breaks silently and there is no error message that tells you what the real problem is. After I "got" YAML, all of the rest of CI/CD started making sense and I wanted to write the introduction I wished I'd had.

What YAML actually is

YAML stands for "YAML Ain't Markup Language," and that name is a clue to what makes it different from something like XML or JSON. There are no angle brackets, no closing tags, and almost no punctuation. Structure comes entirely from indentation and line breaks, which is what makes YAML so readable and also what makes it so easy to break if you're not paying attention.

GitHub Actions uses YAML for every workflow file, stored under .github/workflows/ in a repository. Once you understand how YAML represents data, reading and writing these workflows stops feeling like guesswork.

Key-value pairs: the foundation

The simplest thing YAML does is store a value under a name, separated by a colon and a space:

name: Build and Test

That's it. No quotes required unless the value contains special characters like a colon or a hash symbol. In a GitHub Actions workflow, this line just gives the workflow a human-readable name that shows up in the Actions tab.

Indentation defines structure

This is the part that took me the longest to internalize: in YAML, whitespace isn't decoration, it's syntax. Two lines at the same indentation level are siblings. A line indented further than the one above it is nested inside it.

on:
  push:
    branches:
      - main

Here, on has a child called push, which has a child called branches, which holds a list. Every level is indented by exactly two spaces GitHub Actions files conventionally use two spaces, not tabs, and mixing tabs and spaces is one of the fastest ways to produce a parsing error that gives you almost no useful information about where things went wrong.

Lists: the dash syntax

YAML represents lists using a hyphen followed by a space:

branches:
  - main
  - develop

This says the value of branches is a list containing two items. You'll see this pattern constantly in workflow files for branches to trigger on, for steps in a job, for strategy matrices.

Mappings inside lists

Where YAML started to feel genuinely powerful to me was realizing that list items can themselves be mappings (key-value groups), not just plain strings. This is exactly how GitHub Actions defines steps:

steps:
  - name: Checkout code
    uses: actions/checkout@v4
  - name: Set up Python
    uses: actions/setup-python@v5
    with:
      python-version: "3.12"

Each hyphen starts a new step, and everything indented under that hyphen name, uses, with, belongs to that one step. Once I saw this pattern, an entire real-world workflow file went from looking like an alien script to looking like a straightforward nested outline.

A minimal, complete workflow

Putting the pieces together, here's a small but functional GitHub Actions workflow that runs on every push to main and executes a Python test suite:

name: Run Tests

on:
  push:
    branches:
      - main

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install dependencies
        run: pip install -r requirements.txt
      - name: Run tests
        run: pytest

Reading this top to bottom: the workflow is named Run Tests, it triggers on pushes to main, and it defines one job called test that runs on an Ubuntu runner and executes four steps in order. There is nothing here that isn't one of the four patterns above, key-value pairs, indentation, lists, and mappings inside lists.

Mistakes that cost me time

A few things caused most of my early frustration, and knowing about them in advance will save you the same trouble:

Mixing tabs and spaces is invalid YAML, even though many editors visually display them as equivalent. Configure your editor to insert spaces when you press Tab.

Inconsistent indentation within the same list breaks parsing. If one step is indented two spaces and the next is indented four, YAML will either misinterpret the structure or reject the file outright.

Forgetting the space after a colon turns a key-value pair into plain text. name:Run Tests is not the same as name: Run Tests YAML requires that space to recognize the colon as a separator.

Unquoted values that look like other types can be misread. A version number like 3.10 can be interpreted as the number 3.1 rather than the string "3.10", which is why you'll often see version numbers wrapped in quotes in real workflow files.

Why this was worth learning properly

Once YAML stopped being a mystery, reading other people's GitHub Actions workflows and debugging my own became dramatically easier. CI/CD pipelines are, underneath all the tooling, just structured configuration describing a sequence of steps. Learning to read that structure fluently is a small investment that pays off every time you touch a .yml file, whether that's in GitHub Actions, GitLab CI, or any other tool built on the same format.

If you're just starting out with CI/CD, I'd genuinely recommend spending an afternoon with nothing but YAML syntax before diving into pipeline concepts. It made everything downstream click faster for me than jumping straight into workflow documentation did.

Why Documentation Is Architecture

MEROLINE LIZLENT — Sun, 02 Aug 2026 15:54:03 +0000

Most of the engineers consider documentation as an after-thought; a README on a finished system written in the final 20 minutes before a PR gets merged. That's the wrong way to do this relationship. Documentation is not a description of architecture. It is part of the architecture, and marking it as separate is the cause of so many rotting systems, which still pass all tests.

The compiler doesn't care, your team does

It could be a consistent codebase and yet it be undocumented garbage from the point of view of anybody who didn't write it. Only one sort of correctness is enforced by the compiler (or interpreter): does this code perform the operation that the instructions say it performs. It doesn't weigh in on why a specific table contains a deleted_at column, versus a hard delete, or why a service tries 3 times with exponential back-off, versus 5 times with a fixed interval. Those decisions include constraints that are not apparent in the diff, regulatory, historical, or performance. If these are only in the mind of the programmer who wrote them, the actual architecture is partially undocumented, and these constraints will be breached as soon as someone else messes with the code when it is under a tight deadline.

Architecture is not only the shape of your services and schemas, it's the set of decisions and constraints that shape stayed within. Undocumented constraints are like walls that we don't see, or know about. They are walked through without anyone knowing they exist, and one of the assumed conditions is broken at a time.

Documentation as a design artifact, not a report

Good documentation should be done prior to and/or in the midst of implementation, not after. When writing a design doc that explicitly states the problem, the options you considered, the one you selected, and the tradeoffs you made, you are actually doing real design work, you are making mistakes in your thinking process that would only become apparent during production. There have been more times I've trapped myself in bad assumptions when I'm drafting a “why not X” section of a design doc than I have been in writing code reviews. Code review typically is done to see if the implementation is as per the design; it is not usually done to validate whether the design was correct, but by the time there's a PR, the investment and effort in the implementation make it hard for the reviewers to question the approach.

This implies that design docs should be considered to be an essential piece of any nontrivial change; rather than an optional feature. The doc should include the invariant being introduced or preserved (e.g., for a new Go service, or an idempotent contract change in the FastAPI endpoint) rather than just a description of the code. This endpoint is idempotent for retries since it is based on the key of request_id which the client must provide for each logical operation. The endpoint is not: This endpoint handles POST requests to /orders.

Decision records outlive the decision-makers

The reason that Architecture Decision Records (ADRs) work is that it documents the shape of the reasoning, not only the results. 18 months later the question was always asked, "why didn't we just do the obvious thing?" A short ADR, context, decision, consequences, maybe three paragraphs, answers that question. If it wasn't for that history, the logic that seems like god's own work is tried, something that nobody remembers was structurally important gets broken, and the change is reverted at 2am. It makes the next engineer read 3 paragraphs and either realize the constraint is no longer true and move on; or realize why the constraint is still true and not waste a sprint to discover it the hard way.

This is particularly apparent when it comes to smaller teams and solo projects, where no one is around to ask. When you're the only maintainer in a project and you're away for 6 months, you'll only have the ADRs as your teammates when you're back. I've just reopened my own repos relating to Bitcoin/lightning and discovered that the commit messages give me the information about what changed but not why a specific timelock value or fee-bumping approach was taken over the other alternatives, and that took real time that a 3 paragraph doc could have saved all together.

Where documentation actively prevents bad architecture

There is a more strong version of the above statement to be made, and that is that documentation does not only document architecture, it enhances it. One of the best methods to review a design if you don't have the context is to explain to an imaginary reader who doesn't. This is free and is one of the best design-review techniques available. When it's hard to explain why a service owns certain data, it's probably not ownership, it's a wrong boundary. It is hard to explain the API without resorting to three exceptions and a footnote and if you need to do that, then the contract of the API is probably not consistent, it is just under documented. Documentation debt and architectural debt are often the same debt in other clothes, and paying off one debt will often result in paying off the other debt.

Practical shape, not process theater

This doesn't involve any heavy weight process. For a small team or solo project, a good document practice is: a one-page ADR for any decision that would be expensive if it was reversed, a set of in-line comments which explain why it is not wrong on the first glance, and a living Architecture document that gets a five-minute update whenever the responsibility of any major component changes. It isn't that it isn't enough to document, it's that it's missing where it could be most important, a pretty formatting wiki that nobody ever updates after the schema changes twice is worse.

Consider documentation a first-class design tool, and the architecture benefits as a by-product. As if it were some paperwork and the architecture slowly disintegrates without anyone ever realizing that it was an unnecessary loss to begin with.

SQL Patterns Hidden Inside Social Networks

MEROLINE LIZLENT — Sun, 02 Aug 2026 15:52:50 +0000

From the outside, social features seem like something straightforward: follow a user, like a post, see a feed, but when you attempt to implement them at any real scale you find that every single one is something you've got to be aware of, a pattern, a well-documented query pattern with all its failure modes. Here's a step-by-step look at four of them: adjacency list, fan-out feed, mutual-friends join, and some graph traversal that SQL wasn't really designed for.

The adjacency list and why "who do I follow" isn't free

A follow relationship is usually modeled as a plain adjacency table: follows(follower_id, followee_id, created_at). That's the whole schema, and it's deceptively adequate for a long time. The first place it breaks is when you need "who do I follow that also follows them", mutual connections, because that's a self-join against the same table:

SELECT f2.followee_id
FROM follows f1
JOIN follows f2 ON f1.followee_id = f2.follower_id
WHERE f1.follower_id = :user_id
  AND f2.followee_id != :user_id;

This query is ok if the fan-out is low. It feels like it's no longer fine when a few accounts have a few hundred thousand joins, because join now needs to walk a correspondingly large intermediate result set per request. The typical solution isn't a better query, it's a better index and a cap.
composite indexes on (follower_id, followee_id) and (followee_id, follower_id) so both directions of the join hit an index-only scan, plus a LIMIT applied early so the planner doesn't materialize more rows than the response will ever use.

The fan-out feed problem

The “social systems” hard problem is the timeline: display to me my feed of what people I follow posted recently, in order. There are two ways to construct it and they are both right - anything else and outages happen.

Fan-out on write means that when a user posts, you insert a row into every follower's feed table immediately. Reads are then a trivial SELECT * FROM feed WHERE user_id = :id ORDER BY created_at DESC LIMIT 50, fast and simple, because the expensive work happened once at write time. This collapses the moment an account with a very large follower count posts, because that single write turns into millions of feed-table inserts.

Fan-out on read flips it: the feed table doesn't exist, and instead a read does the equivalent of the mutual-join query above merged against a posts table, unioned across everyone you follow, sorted, and limited. This is cheap for the poster and expensive for the reader, and it gets more expensive as the number of accounts someone follows grows, because you're merging N sorted streams per page load.

Real systems use both: fan-out on write for the common case, with a fallback to fan-out on read specifically for high-follower accounts, merged at serve time. The SQL pattern worth internalizing here is the k-way merge via UNION ALL plus a bounded sort, which is exactly what a database's merge-join does internally, you're just doing it explicitly at the point where fan-out-on-write would be too expensive.

Mutual connections as a bitset problem

“People you may know” and “mutual friends” are graph problems disguised as SQL statements, and the naive self-join above doesn't work well, because SQL doesn't provide a native way to define a set intersection of rows. The pattern that actually scales better is to, instead, represent each user's follow list in a compact format (a sorted array or a bitset), and then intersect the lists outside the join machinery, either in application code or with a database extension designed for this use (Postgres's "roaring bitmap"-style extensions, or a materialized intarray intersection). The lesson generalizes: If a relational query's cost is mostly for set intersection instead of row filtering, then typically the solution is to change the way that the data is represented, not to add another index to the same schema.

Recursive CTEs and the two-hop wall

SQL does have a native tool for graph traversal, the recursive common table expression, and it's worth knowing exactly where it's appropriate and where it isn't:

WITH RECURSIVE network AS (
  SELECT followee_id AS user_id, 1 AS depth
  FROM follows WHERE follower_id = :user_id
  UNION
  SELECT f.followee_id, n.depth + 1
  FROM follows f
  JOIN network n ON f.follower_id = n.user_id
  WHERE n.depth < 3
)
SELECT DISTINCT user_id, MIN(depth) FROM network GROUP BY user_id;

This returns everyone within 3 hops of a user, and is clean to traverse a moderately sized graph for a limited depth. It fails for the same reason that all recursive CTEs fail to return results on a dense graph: If you're on the 2nd or 3rd level in a social network then you might end up getting close to all the nodes in the table, and now you're getting close to the size of the table in the recursive step that is scanning and deduplicating your nodes. That's when the right answer is not “a better query,” but rather “a different storage engine”, the dedicated graph database or the precomputed reachability index that is refreshed asynchronously, because the relational engine's per-row execution model just doesn't make for the right cost model for dense multi-hop traversal.

The general pattern

All of these problems have the same pattern: a correct and efficient query at low numbers of rows becomes an inefficient query at a certain graph density, which is fixed not by the "add an index and move on" solution, but by changing either the write path (fan-out), the data representation (bitsets instead of joined rows), or the engine (graph store instead of recursive CTE). Most of the real knowledge and expertise of building a social feature on top of a relational database is in knowing which wall you're approaching before you hit it in production.

Inside the AI/ML Community at Zone01 Kisumu: How Peer-to-Peer Learning Is Building Machine Learning Skills Without a Single Lecture

MEROLINE LIZLENT — Fri, 17 Jul 2026 08:12:54 +0000

The model that scares most first time apprentices is Zone01 Kisumu, where there are no teachers, no lectures and no answer key. You receive a project brief, a piscine (coded in a controlled, intense trial for one month) and a room of colleagues who, on day one, are just as lost as you are. This model is borrowed from 42 and the 01-edu network, and is a bit awkward at first. Then it's what makes people learn quicker than they thought they would.

Within that structure, there has been another community that has self organized, the AI/ML community. It's not a track, not a graded module, it's not one teacher's track. It's a group of apprentices who thought that coming together to form a community that helps them learn more on machine learning and artificial intelligence from fellow peers. It's a good sign of why p2p learning works best in a field such as AI/ML, where the terrain is constantly changing under everyone's feet.

Why AI/ML Needed Its Own Peer Group

At the heart of Zone01's programming curriculum are the basics of software such as Go, algorithms, networking, web development, cloud devOps, the stuff that makes you a good engineer. AI/ML is also part of that fundamental track and as such, if someone wants to dive deep into it, they are encouraged to do so independently and also from peer to peer. The group discusses what matters, as they go, based on what they're actually running into a badly overfitted model, a fintech idea that's close to the Lightning, a piece of research that just landed but no one knows much about it yet.

That flexibility is important in ML, if not more so than anywhere else in software. It's possible to keep a web development curriculum fresh for years. There are whole classes of techniques missing from an already outdated ML curriculum, which was devised eighteen months ago. A peer group group that meets regularly, and has its agenda driven by what they are working on and reading in the group, remains current in a way an “old” curriculum cannot.

How the Group Actually Coordinates

Mechanics is easy and designed to be easy. The group meets regularly, face-to-face at the Kisumu campus of the Zone01, and also has a chat channel where they post documents, dataset links, reports and half written ideas between their meeting. No one has to be enrolled in the group and no one is required to attend, the group operates on the same premise as all the other groups in Zone01, you show up because you want to show up, not because someone is checking a box.

Sessions may have one of a variety of structures:

Project show and tell A person who has been "heads-down" on a model or pipeline explains what he/she built, what was broken, and what would he/she do differently. This is frequently the most worthwhile week's time slot, since the failures are more instructive than the successes. The room is given a better education about vectors and matrices when a member who took a week to pick up the pieces after a week-long ordeal with dimension-mismatch errors while building out the linear algebra behind a model walks through why 3 reshaping attempts failed, than any tutorial on reshaping them. When someone shows you an error that arose from a transpose you can't remember, or a matrix multiplied in the wrong order, the math in that situation makes sense that no notation can ever make sense.

Document/Concept break down. One person reads them a document on a technique or something, or a concept, whatever it is, and talks to them in plain English about it, and then leaves it open for questions. It's a much more effective kind of test of comprehension to explain a concept to peers who will immediately say "wait, why does that work?".

Sometimes the most beneficial thing that the group does is to sit in the same room, but on different projects, with the same open build time. It saves hours of time doing your own Googling if you can see the problem and have someone look and tell you what the issue is in ninety seconds.

The only way this doesn't turn into an informal gathering is due to a natural turnover of participants. Each member on a rotating basis proposes a topic, conducts a session or introduces a resource. There is no permanent leader, thus preventing the group from relying on one person for availability and allowing all group members to practice the more difficult skill of teaching; not just learning.

What Peer-to-Peer Learning Actually Buys You in ML

Of course, it pays to be explicit in justifying the choice of this format, rather than simply saying that it is good.

Books and courses can explain gradient descent, but they don't explain why the gradient descends. They're far worse at describing what it looks like when your loss curve does something strange at 2am and you're not sure if it's a problem with your loss function, a data leakage problem or a bug in your preprocessing. Peers who have encountered that same barrier one week prior to you can save you the two days of flailing.

When you explain something, the quickest way to see that you don't understand it is to explain it. When the apprentice decides to take the group on a tour of backprop(an algorithm neural networks use to learn from their mistakes), he or she typically comes out of that session with a better grasp of backprop, thanks to the questions that are fired off by other apprentices which the passive audience wouldn't ask. This is the same as what makes Zone01's principle of core piscines effective, you don't know an algorithm until you have needed to explain to someone why it is correct.

It brings together theory and application that is relevant to the local context. You can't learn how to create a credit scoring model for a market where most of the credit history data is thin, or how to deal with a dataset that is primarily in Swahili and Sheng, by taking a generic online course. When you have a bunch of Kenyan apprentices in a room with Kenyan issues, those constraints will come to the surface, because somebody in that room is hitting them.

Unlike it, structured ML bootcamps and specialization courses aren't for free, and even the free ones require fast, constant internet and hours and hours of screen time. Personal face-to-face and shared computing, notes, and debugging reduces the barrier of entry for others who would otherwise not be able to afford it.

It establishes the norm of teaching, a skill that would be very useful on the job. Each apprentice sharing a concept to the group is doing the same skill they will be required to do at a later date when they are the senior engineer on a team, writing documentation, or mentoring someone younger. At this point, Zone01 apprentices are pretty good at this, since the whole curriculum is structured around apprentices learning from each other, and now extends this to an area that evolves more quickly than any other part of the curriculum.

What the Group Has Worked Through

The topics the group has undertaken are more indicative of what is of interest to the group in that particular month than any set agenda. The linear algebra foundations (vectors, matrices, and the operations that appear all over the place when you start building models) have been discussed as well as linear regression and logistic regression as the gateway to supervised learning, and how to get a model from a notebook into something that will run reliably outside the notebook. Members have introduced their own projects, such as fintech recommendation logic, small prediction models, or initial projects with classification; and leverage the group as a sounding board and a debugging partner.

This project-first bias is on purpose, albeit no one has explicitly stated it as a rule. A group that is based on the finished, working code is honest, a group that is based on slide decks isn't. When the request is "show me it running" rather than "explain the concept" it will be more difficult to pretend to understand.

The Honest Challenges

All of this is not a no-friction process. The most difficult thing isn't the material, it's bandwidth. The majority of the members are executing multiple core curriculum projects and modules simultaneously, each with their own deadline, not to mention the AI/ML group who is operating outside of all of the above graded work. The fact that everyone has to attend regularly means that there are months where attendance and momentum will increase and decrease according to how crammed the other classes are throughout the month. No one is paid to create sessions, either, so what a given week looks like will vary depending upon who has the bandwidth to contribute.

The same thing that keeps it running more generally at Zone01 is the people in the room really getting something out of it, from session to session; that's more of a motivating factor than any attendance policy.

Why This Model Is Worth Copying

Zone01 Kisumu was not about to develop an ML program. Instead it created a collective that was peer driven, project first, teacherless, a better model for a subject that is more advanced than any curriculum designed to teach it. The pedagogical training of ML needs to be delayed until after it's actual use. A peer group that's self-organized is not that laggy, for the group's curriculum is simply what they're currently constructing, destructing, and reconstructing.

If you are one of those who wonder how to educate an AI/ML community without employing a dedicated teacher-machine learning expert, the Zone01 Kisumu AI/ML community is proof enough: provide a group of motivated people a space, a time, and the unspoken rule that everyone will teach as much as they learn, and the program self-organizes.

Blocks, the Blockchain, and Nodes: How Bitcoin Actually Agrees on Anything

MEROLINE LIZLENT — Fri, 03 Jul 2026 12:29:30 +0000

What Bitcoin's technology is not as important as cryptography, that's where signatures and hashing come in. The real innovation is that thousands of strangers, not organized by the central, concur that they share one history. In this post, we will go through the process of how that occurs: from a transaction in a mempool, to a validated block, to thousands of nodes coming together on the same chain.

From mempool to block

Each node keeps a personal mempool a holding area for transactions that it has received and validated, but not yet confirmed. A mining node periodically polls the mempool and attempts to assemble a block that can be added to the chain, and includes a special coinbase transaction that rewards the miner with the block reward (plus any fees attached to the transactions in the block). The vast majority of the nodes are not miners, but validators and relayers.

What's actually inside a block header

The header is designed to be small (only 80 bytes) so that it gets hashed over and over while being mined, and because it is what every other node has to check on a regular basis.

Field	Size	Purpose
version	4 bytes	signals which consensus rules this block follows
hashPrevBlock	32 bytes	hash of the parent block — this is the actual "chain" link
hashMerkleRoot	32 bytes	single hash representing every transaction in the block
timestamp	4 bytes	seconds since and includes a special coinbase transaction that rewards the and includes a special coinbase transaction that rewards the the Unix epoch
bits (target)	4 bytes	the difficulty target this block's hash must beat
nonce	4 bytes	the number miners increment while searching for a valid hash

The merkle root: proving inclusion cheaply

If each transaction was hashed directly into the header, it would be difficult to verify the headers and they would be large. Rather, transaction hashes are paired together, re-hashed, re-paired and re-hashed again and again and again, until a single 32-byte merkle root is left. That root is the hash of all the transactions in the block, but only a few hashes of intermediate transactions are necessary to prove that a particular transaction is part of the block (a "merkle proof"). This is how lightweight clients can verify a transaction is in the blockchain without having to download gigabytes of data.

hashPrevBlock: the actual chain

The one field that is 32 bytes long is what chains a pile of otherwise independent blocks together. Modify any value within a previous block, even one bit in one previous transaction, and they all have to be updated in subsequent blocks from the previous block, because the hash of the previous block will change. You don't have to do the "hard" thing when re-writing history, it's "the astronomical thing": you must redo the proof-of-work of that block, and basically redo the proof-of-work of the next block on top of it and all the subsequent blocks on top of that one.

Mining and proof-of-work

The "double-SHA256" hash of the block header is only valid if it is lower than the network-wide target. Its output is essentially a random number, so it takes a long time to find a hash that is less than the target, but once you find one it only takes one to verify it. That asymmetry – hard to create, easy to validate – is at the heart of it, and it makes it costly to send junk blocks through the network, while validating is cheap for everyone else.

The target adjusts automatically, every 2016 blocks (about 2 weeks at the intended 10 minutes/block rate), depending on the actual rate at which the blocks are being found. The more the number of participants (more hash power), the lower the target (harder), and the less the number of participants (less hash power), the higher the target (easier). This ensures constant production of blocks, even if miners log in or out.

The easiest possible target the network ever allowed divided by the present target is a common shorthand used here: difficulty. The starting point of difficulty 1 was the genesis difficulty; it's now many orders of magnitude greater, meaning that much more hashing power now is competing for each block.

How nodes agree without talking to a referee: Nakamoto consensus

Let's get to the pretty part. Every node constructs its own chain of blocks, simply based on the following rule: Always take the chain that has the longest valid chain with the most Proof-of-Work.

If two miners discover the same block at almost the same time, the network temporarily bifurcates, with some nodes discovering block A before block B, and mining on top of that, while the others discover block B before block A, and begin mining on top of block B. This is not a crisis as it will sort itself out when one of the two competing tips is extended by any miner. Each node then reevaluates, realizes that one chain is longer and moves to it, removing ("orphaning") the transactions from the losing chain back into its mempool for later re-evaluation.

A reorg of this kind occurs regularly (with the single-block reorgs, less than once per month) and is a normal and healthy process in how the network self-corrects. The more a transaction is buried in the subsequent blocks, the more computational effort an attacker would have to work to break the transaction — that's what “confirmations” represent. One confirmation means one block is added above the transaction, and six confirmations means six blocks are added above the transaction, placing a big barrier between the attacker and the ability to change the transaction.

This is also the theoretical basis behind the "51% attack" (which is largely theoretical, and economically self-defeating): in theory, if they have more than 50% of the network's hash power, they could be mining their own history while honest miners are on the other. The amount of hardware it would take to acquire and maintain that alone is why it is firmly in the "theoretically possible, but practically irrational" category.

Soft-forks and hard-forks, quickly

Upgrading a decentralized network without a central "update now" button requires care. The two failure modes:

Soft-fork — new rules are a subset of the old rules. Old nodes still accept the new, stricter blocks (they just don't understand some of the extra restrictions), so the network stays in sync as long as enough hashing power adopts the change. Segregated Witness shipped this way, with considerable engineering effort to make a fairly invasive change backward-compatible.
Hard-fork — new rules accept blocks the old rules would have rejected. Old and new nodes can no longer agree, and the network permanently splits into two unless everyone upgrades together.

Because hard-forks are disruptive and contentious, the Bitcoin community has strongly favored soft-forks for protocol changes, even when a hard-fork would have been the technically simpler path.

Types of nodes you'll encounter

A "full node" isn't one fixed thing — it's a bundle of optional roles:

Routing/relay — propagates transactions and blocks to peers (almost every node does this).
Archival — stores the entire blockchain from the genesis block forward. Some nodes opt to prune older block data to save disk space once it's been validated.
Wallet — manages keys and lets the node's owner send/receive funds (optional; can be disabled).
Mining — actually competes to produce new blocks. A small minority of nodes do this; the rest validate and relay what miners produce.

Summarizing

Remove the jargon and the consensus mechanism of bitcoin is summarized as follows: hash link blocks together, so blocks can be detected if they are tampered with, new blocks are expensive to create, making spam impractical, and each node independently agrees to follow the chain of blocks that has the most work put into it. No voting, no central authority; it is just a simple rule mechanically enforced by everyone who runs the software, and it is followed by everyone.

Bitcoin Keys and Addresses

MEROLINE LIZLENT — Wed, 01 Jul 2026 14:41:42 +0000

Have you ever looked at one of these Bitcoin addresses, such as bc1q... or 1A1zP1... and wondered what it meant, or what was happening? We will go over how a private key becomes a public key, and how that public key becomes the address you use to send the money.

You can't access this feature without having a private key.

A Bitcoin private key is not magical; rather, it is a 256-bit random number. That's it. 32 bytes, 64 hex characters, selected preferably from an cryptographically-secure random number generator.

The Elliptic Curve Digital Signature Algorithm (ECDSA) is used on a curve that is known as secp256k1. Any integer k, such that 1 <= k < n, where n is the order of the curve (which is a value just smaller than 2^256), is a valid private key. In practice, this means that just about any 256-bit number will do, but not every number; the numbers which are either equal to or greater than n will be considered invalid and rejected.
This is why key generation should work this way: Generate a random 256-bit number, and if it is not in [1, n-1] then reject it and repeat the process; do not simply reduce it mod n because it gives a slight bias towards the lower end of the range and that's an error you don't want in a game where you are putting real money at risk. Well vetted libraries do this for you, but it's good to know about if you're ever tempted to roll your own key generation.

The downside: the security of your money is dependent on the randomness of that number. If your key is based on something that you can guess, such as your birthday, a memorable phrase, a weak PRNG, etc., then there are programs that can easily discover the key in mere seconds and your coins are lost. Bitcoin doesn't offer you a "forgot password" link, there's no second chance.

With ECDSA, it is possible to derive the public key from the private key, which means that the address is derived from the public key and that the possession of the private key is sufficient to get the address.

Displaying a Private key: WIF and WIF-compressed

A raw 32-byte number isn't fun to copy around, so Wallets show private keys as Wallet Import Format (WIF). WIF is simply Base58Check encoding (Base58 + version byte + 4-byte checksum) of the key bytes.

The compressed variant, WIF-C, puts an additional 0x01 byte in front of the encoding to indicate the public key is to be compressed (more on that below). Most modern wallets default to WIF-C as that is what helps maintain a smaller blockchain.

	Mainnet prefix	Testnet prefix
WIF	starts with `5`	starts with `9`
WIF-Compressed	starts with `K` or `L`	starts with `c`

Using a Python library such as bitcoinutils, generating both forms from the same secret exponent looks roughly like this:

from bitcoinutils.setup import setup
from bitcoinutils.keys import PrivateKey

setup('testnet')

priv = PrivateKey(secret_exponent=0x1a2b3c...)  # your 256-bit int
print(priv.to_wif(compressed=False))
print(priv.to_wif(compressed=True))

From private key to public key

Elliptic curve math allows you to easily convert from private to public, but not public to private (which would involve brute forcing the curve, a task that's too hard to do in the real world). The public key is obtained by multiplying the private key by a fixed point on the curve, G (the generator point):

P = k * G

P is a point on the curve with coordinates (x, y), each 32 bytes. Naively, that's 64 bytes for a public key, plus a 0x04 prefix to mark it as "uncompressed", 65 bytes total.

Because the curve is symmetric about the x-axis, for any given x there are only two possible y values (even or odd). So instead of storing the full y, we can store just a single bit indicating which one it is. That gives us the compressed public key: 33 bytes, prefixed with 0x02 (even y) or 0x03 (odd y).

pub = priv.get_public_key()
print(pub.to_hex())                  # compressed, 33 bytes
print(pub.to_hex(compressed=False))  # uncompressed, 65 bytes

Compressed keys are the default these days they're shorter, and Segregated Witness actually requires them.

From public key to address

One of the things that comes as a surprise to some new to Bitcoin is that you do not have to share your public key in order to receive funds. Address is a hash of the public key, which you share. There are some good reasons for this:

Addresses are shorter than public keys. The public key remains private until it's actually used to spend from that address, giving another (controversial, but true) degree of security against future cryptographic attacks.

The key to creating a legacy address:

publicKeyHash = RIPEMD160( SHA256( publicKey ) )
data = networkPrefix + publicKeyHash
checksum = first 4 bytes of SHA256( SHA256( data ) )
address = Base58CheckEncode( data + checksum )

That RIPEMD160(SHA256(x)) combo even has its own nickname: HASH160. You'll see it constantly when reading Bitcoin source code.

Type	Mainnet prefix	Testnet prefix
P2PKH (legacy)	`1`	`m` / `n`
P2SH	`3`	`2`
Native segwit (bech32)	`bc1`	`tb1`

addr = pub.get_address()
print(addr.to_string())

Because the hash of a compressed key differs from the hash of an uncompressed key, the same private key produces two different legacy addresses depending on which public-key form you hashed. Worth remembering if an old wallet ever "loses" a balance check the other form.

Segwit addresses: same idea, new encoding

Since the Segregated Witness upgrade, the recommended address format is native segwit, encoded with Bech32 instead of Base58Check. P2WPKH (witness pubkey hash) addresses on mainnet start with bc1, and tb1 on testnet. Under the hood it's still essentially "hash of the public key" just packaged differently, and cheaper to spend from thanks to the witness discount we'll get into in a later post.

There's also a "nested" variant, a segwit script wrapped inside a P2SH address created so older, segwit-unaware wallets could still send funds to segwit users. It looks just like a normal P2SH address (prefix 3 / 2) from the sender's point of view.

A quick word on wallets

Wallets generally fall into two camps:

Non-deterministic — a pile of independently generated random keys. Simple, but every new key means a fresh backup.
Deterministic (HD) — a single seed deterministically generates an entire tree of keys. Back up the seed once, and you can always regenerate every address you've ever used. This is what virtually every modern wallet does (BIP-32/39/44).

Vanity addresses, briefly

It's possible to grind random keys until the resulting address starts with a chosen string (1Kostas, for example). Each extra character multiplies the search space by roughly 58 (the size of the Base58 alphabet), so long vanity prefixes get expensive fast which is why dedicated vanity-mining pools exist, using clever elliptic-curve key addition so they never learn your final private key.

Wrapping up

The whole chain: random number - private key - public key via curve multiplication - address via hashing is what makes Bitcoin ownership verifiable without any central authority knowing who you are. Next time you generate an address in code, you'll know exactly what's happening at each step.

Go: The Language That Just Works

MEROLINE LIZLENT — Wed, 03 Jun 2026 11:46:23 +0000

Three engineers at Google, Robert Griesemer, Rob Pike, and Ken Thompson were tired in 2007. Annoyed with waiting for C++ code to compile. Frustrated with the messiness that seeped into big code bases. Frustrated by the limitations of languages on their size and concurrency requirements of today's infrastructure.

So they built their own.

This is the bold idea that was born of Go: What if there was a language as fast as C, as readable as Python, and as concurrent as possible from the ground up? It was released as open source in 2009 and version 1.0 came in 2012 and has become one of the most impactful programming languages of the last 20 years.

Go's goal is to "provide for something that is easy to program but also efficient and safe like a statically typed, compiled language.

Go by the numbers

#8 on the TIOBE Index (2024), up from #14 in 2020
According to the Stack Overflow 2023 Developer Report, 13% of developers use Go on a regular basis.
Average salary is 70% higher than average Go developer salary.Median salary is 70% higher than the average Go developer's salary.

What makes Go genuinely different

Go is not just another C-family language. It involves a series of conscious and subjective decisions all of which are required to create something unusual: a language that can be used for small projects as well as infrastructure for the planet and remains the same in your head.

1. Concurrency as a first-class citizen

The Go runtime manages lightweight threads called goroutines. Conventional OS threads take 1MB+ per thread. Goroutines are born small, at just 2-8 KB — and can be started as needed; 100,000s can run on a single machine concurrently.

package main

import (
    "fmt"
    "sync"
)

// Fan-out: distribute work across goroutines
func processJobs(jobs <-chan string, wg *sync.WaitGroup) {
    defer wg.Done()
    for job := range jobs {
        fmt.Printf("Processing: %s\n", job)
    }
}

func main() {
    jobs := make(chan string, 100)
    var wg sync.WaitGroup

    // Spin up 10 workers — goroutines are cheap
    for i := 0; i < 10; i++ {
        wg.Add(1)
        go processJobs(jobs, &wg)
    }

    jobs <- "build Docker image"
    jobs <- "run test suite"
    jobs <- "deploy to staging"
    close(jobs)

    wg.Wait()
}

Concurrent programs are easier to reason about and are much less prone to race conditions with the CSP (Communicating Sequential Processes) model, which is the model in which goroutines communicate through channels and not memory.

2. Blazing fast compilation

Go can take seconds to compile large codebases, instead of minutes. This isn't just a little convenience, this actually alters the way development feels. You have a very close feedback loop, no matter what the scale is. A Go build with over a thousand files, and it takes 3 seconds, is something of a miracle.

3. Static typing with type inference

The static type is able to detect bugs at compile-time, while the shorthand syntax := and interfaces make the code feel light.

// Explicit type declaration
var name string = "Gopher"

// Type inference — Go figures it out
name := "Gopher"

// Interfaces are satisfied implicitly (no 'implements' keyword)
type Writer interface {
    Write(p []byte) (n int, err error)
}

4. Garbage collected with low latency

Go's GC is optimized for latency operations. Modern versions are able to deliver sub-millisecond GC pauses (i.e. makes Java real-time systems feasible where it would have been a deal-breaker).

5. Batteries-included standard library

Go ships with an exceptionally rich standard library covering:

HTTP servers and clients (net/http)
JSON encoding/decoding (encoding/json)
Cryptography (crypto/tls, crypto/sha256)
Testing framework (testing)
Database interfaces (database/sql)
Templating (html/template, text/template)

All production-quality.
All without installing anything.

6. Single static binary output

Write-once-run-anywhere. Go generates a single binary file that can be executed without relying on any external runtimes. The deployment is just a copy of one file. The images of the containers shrink from gigabytes to megabytes.

# Cross-compile for Linux from macOS
GOOS=linux GOARCH=amd64 go build -o ./bin/myapp .

# Your entire app: one file
scp ./bin/myapp user@server:/opt/myapp

7. Enforced formatting

Your code is automatically formatted by gofmt. There is one style for all Go code, everywhere, all the time. No bikeshedding in PRs, no tab vs space debates, no style guide debates. The point of code reviews is logic and not looks.

8. Explicit error handling

Go treats errors as values, not exceptions. Every function returns an error that you must consciously handle.

file, err := os.Open("data.json")
if err != nil {
    return fmt.Errorf("opening data file: %w", err)
}
defer file.Close()

This is an interesting experience for developers coming from Python or JavaScript. It will be useful over time; in Go code bases, the failure modes will always be obvious in code. No unexpected path which catches you off guard in production.

Where Go dominates today

Go has not attempted to be all things to all people. It made deep inroads in certain areas of specialization and those areas happen to be the backbone of modern computing.

Go is the home of cloud infrastructure. The tools that power the internet are filled overwhelmingly with Go.The tools that power the internet Docker, Kubernetes, Terraform, Prometheus, etcd, CockroachDB, Caddy, Traefik, they are all written in Go. It's not a coincidence. Go's performance, binaries and concurrency are perfect for infrastructure software.

Another sweet spot is the use of Microservices and APIs. Go's net/http package is production-ready and its frameworks such as Gin, Echo, and Fiber simplify the creation of REST or gRPC applications quickly and efficiently. Handling 100K+ requests per second with regular hardware is nothing new for a Go HTTP server.

Go produces a single binary, it is ideal for distributing command-line tools. Install Go CLI: copy a file. No runtime requirements, no conflicts with other versions. This is why there are tons of DevOps tools that ship Go binaries.

Go vs. the competition

Go vs. Python

Go is 10-100 times faster in CPU-centric tasks and much more efficient in terms of memory and CPU resources. While Python is the go to language for data science and scripting, if it's services that must deal with heavy load, then Go will be a better option. Go's type system will also catch entire classes of bugs that Python will allow to enter production.

Go vs. Rust

Rust provides high degree of control and performance, but requires a very steep learning curve (borrow checker) and slower development velocity. When the performance of 95% of Rust is required with less than 10% of the learning curve, Go is the pragmatic option. Both are good — Go is the "get it shipped" language.

Go vs. Java / Node.js

It requires less memory than Java (no JVM overhead) and loads up in milliseconds, which is important for serverless and containerized deployments. Go's event-driven roots are shared by Node.js, which has difficulty with CPU-intensive tasks. Go is efficient with I/O and computation, without callbacks and async/await complexity.

Why Go is accelerating

The industry now has firmly moved into the containerized, distributed, cloud-native architecture. All the large cloud providers have had a lot of fun with Go. Major companies such as Google, Cloudflare, Uber, Twitch, Dropbox and Stripe have large Go code bases.

There's a flywheel effect with the language:

More infrastructure is written in Go
More engineers need to learn Go
More companies hire Go engineers
Even more infrastructure gets written in Go

Generics were introduced in Go 1.18 (2022) to address the longest-standing complaint in Go, and to start a new wave of library development. The system of modules developed. The toolchain sped up. Go in 2024 is a meaningful improvement not a complete overhaul of Go in 2018, and still retains all the original features.

The simplicity is not a weakness, it is the strength of Go. Better code by any person who can read it than by any genius that can write it, in large groups.

Who should learn Go?

Not all the tasks can be accomplished with Go. However, if your project involves any of these aspects, it is definitely worth considering:

Backend / API engineers building services that need to be fast, reliable, and maintainable by a team
DevOps / Platform engineers building tooling, CLIs, or anything touching Kubernetes or cloud infrastructure
Python developers hitting performance walls — Go is the natural next step when your service can't keep up with traffic
Anyone building distributed systems — Go's concurrency primitives and ecosystem are ideal for this domain

Where Go still falls short

Honestly addressing limits is important to a fair assessment.

A frequent criticism is the return of err if it is not nil dozens of times in a function. The explicitness is real useful, but there have been proposals for cleaner syntax for years.
Generics are not yet fully developed. Not all of them have been accepted into the standard library, and some patterns are not idiomatic in Go.
Go is not competitive in areas that demand maximum low-level control (embedded systems, OS kernels), vast mathematical computation (ML training) or rich GUI applications. Python is for data science, Rust is for bare metal and Go is for the middle layer.

Getting started

Go's onboarding is genuinely good. The official tour at go.dev/tour is interactive and covers the essentials in a few hours.

# Install Go (macOS with Homebrew)
brew install go

# Or download from go.dev/dl

# Create a new module
mkdir myapp && cd myapp
go mod init github.com/you/myapp

# Write your first program, then:
go run main.go        # run directly
go build -o ./bin/app # compile to binary
go test ./...         # run all tests

# Your binary: one file, zero dependencies
./bin/app

The Go community is friendly and the simplicity of the language makes other people's Go code really a fun to read. Begin with the tour and then read an article from a source you used for a project – Caddy or Prometheus are good sources.

The bottom line

In 2009, Go wagered that simplicity, speed and pragmatism would be more important than expressiveness. So, that gamble paid off big time 15 years ago. The language of the cloud-native revolution, and Docker and Kubernetes, is not going away… it's moving faster.

If you haven't taken a closer look at Go, you should now! It's easy to learn, it's got a great job market, and it's an ever more integral part of software development, solving problems that are increasingly relevant.

GitPython

MEROLINE LIZLENT — Wed, 13 May 2026 11:27:35 +0000

Have you ever written a deployment script with subprocess.run(["git", "pull"]) and felt like there just must be a better way? There is! GitPython provides you with a real Python API for doing anything Git can do: clone, commit, create branches, diffs, read history, etc.

Installation

pip install gitpython

GitPython assumes you have git installed on your system. It uses shelling out to git behind the scenes, translating into Python objects as cleanly as possible.

Opening a Repository

from git import Repo, InvalidGitRepositoryError

# Open an existing repo
repo = Repo("/path/to/your/project")

# Open the repo at the current working directory
repo = Repo(".")

# Open from any subdirectory (search_parent_directories=True)
repo = Repo(".", search_parent_directories=True)

# Safe opening with error handling
try:
    repo = Repo("/some/path")
except InvalidGitRepositoryError:
    print("Not a git repository")

Repository Basics

from git import Repo

repo = Repo(".")

# Basic info
print(repo.working_dir)       # /home/user/myproject
print(repo.git_dir)           # /home/user/myproject/.git
print(repo.is_dirty())        # True if there are uncommitted changes
print(repo.untracked_files)   # ['new_file.py', 'notes.txt']
print(repo.active_branch.name)  # main

# Check if repo has any commits
print(repo.head.is_valid())   # False if repo is empty

Cloning a Repository

from git import Repo

# Clone a public repo
repo = Repo.clone_from(
    "https://github.com/user/myproject.git",
    "/tmp/myproject"
)

# Clone a specific branch
repo = Repo.clone_from(
    "https://github.com/user/myproject.git",
    "/tmp/myproject",
    branch="develop"
)

# Clone with depth (shallow clone — faster for CI)
repo = Repo.clone_from(
    "https://github.com/user/myproject.git",
    "/tmp/myproject",
    depth=1
)

# Clone with SSH
repo = Repo.clone_from(
    "git@github.com:user/myproject.git",
    "/tmp/myproject"
)

Staging and Committing

from git import Repo
import os

repo = Repo(".")

# Stage specific files
repo.index.add(["README.md", "src/main.py"])

# Stage all changes (like `git add .`)
repo.git.add(A=True)

# Or using the index directly
changed_files = [item.a_path for item in repo.index.diff(None)]
untracked = repo.untracked_files
repo.index.add(changed_files + untracked)

# Commit
commit = repo.index.commit(
    "feat: add user authentication module",
    author_date="2024-01-15T10:00:00",
    commit_date="2024-01-15T10:00:00",
)
print(f"Committed: {commit.hexsha[:7]} — {commit.message.strip()}")

Commit with Custom Author

from git import Repo, Actor

repo = Repo(".")

author = Actor("Alice", "alice@example.com")
committer = Actor("CI Bot", "ci@example.com")

repo.index.add(["deploy.yaml"])
repo.index.commit(
    "chore: update deployment config",
    author=author,
    committer=committer,
)

Branches

from git import Repo

repo = Repo(".")

# List all branches
for branch in repo.branches:
    print(branch.name)

# List remote branches
for ref in repo.remotes.origin.refs:
    print(ref.name)

# Create a new branch
new_branch = repo.create_head("feature/login")

# Switch to a branch (checkout)
new_branch.checkout()

# Or one-liner
repo.git.checkout("-b", "feature/signup")

# Delete a branch
repo.delete_head("feature/old-stuff", force=True)

# Check current branch
print(repo.active_branch.name)  # feature/login

Working with Remotes

from git import Repo

repo = Repo(".")

# List remotes
for remote in repo.remotes:
    print(f"{remote.name}: {remote.url}")

# Fetch
repo.remotes.origin.fetch()

# Pull
repo.remotes.origin.pull()

# Push
repo.remotes.origin.push()

# Push a specific branch
repo.remotes.origin.push(refspec="feature/login:feature/login")

# Add a new remote
repo.create_remote("upstream", "https://github.com/original/repo.git")

# Remove a remote
repo.delete_remote("upstream")

Reading Commit History

from git import Repo

repo = Repo(".")

# Iterate over commit history
for commit in repo.iter_commits("main", max_count=10):
    print(f"{commit.hexsha[:7]}  {commit.authored_datetime}  {commit.author.name}")
    print(f"  {commit.message.strip()}")
    print()

a3f1c22  2024-01-15 10:30:00  Alice
  feat: add payment gateway

7b2d891  2024-01-14 16:45:00  Bob
  fix: correct validation logic

Filter by Author, Path, or Date

from datetime import datetime

# Commits by a specific author
for commit in repo.iter_commits("main", author="Alice"):
    print(commit.message.strip())

# Commits touching a specific file
for commit in repo.iter_commits("main", paths="src/auth.py"):
    print(f"{commit.hexsha[:7]} {commit.message.strip()}")

# Commits since a date
since = datetime(2024, 1, 1)
for commit in repo.iter_commits("main"):
    if commit.authored_datetime.replace(tzinfo=None) < since:
        break
    print(commit.message.strip())

Diffs: What Changed?

from git import Repo

repo = Repo(".")

# Diff between working directory and index (unstaged changes)
for diff in repo.index.diff(None):
    print(f"Modified: {diff.a_path}")

# Diff between index and HEAD (staged changes)
for diff in repo.index.diff("HEAD"):
    print(f"Staged: {diff.a_path}")

# Diff between two commits
commits = list(repo.iter_commits("main", max_count=2))
diffs = commits[1].diff(commits[0])

for diff in diffs:
    print(f"Changed: {diff.a_path}")
    if diff.diff:
        print(diff.diff.decode("utf-8"))

Reading File Contents from Git

You can read file contents from any commit without touching the filesystem:

from git import Repo

repo = Repo(".")

# Read a file at HEAD
blob = repo.head.commit.tree["README.md"]
content = blob.data_stream.read().decode("utf-8")
print(content)

# Read from a specific commit
commit = repo.commit("a3f1c22")
blob = commit.tree["src/main.py"]
print(blob.data_stream.read().decode("utf-8"))

# Navigate into subdirectories
blob = repo.head.commit.tree["src"]["auth"]["jwt.py"]
print(blob.data_stream.read().decode("utf-8"))

Submodules

from git import Repo

repo = Repo(".")

# List submodules
for submodule in repo.submodules:
    print(f"{submodule.name}: {submodule.url}")

# Add a submodule
repo.create_submodule("mylib", "libs/mylib", url="https://github.com/user/mylib.git")

# Update all submodules
for submodule in repo.submodules:
    submodule.update(init=True)

Real-World Patterns

Auto-Commit Changed Files

from git import Repo, Actor
from datetime import datetime

def auto_commit(repo_path: str, message: str = None):
    repo = Repo(repo_path)

    if not repo.is_dirty(untracked_files=True):
        print("Nothing to commit")
        return

    # Stage everything
    repo.git.add(A=True)

    msg = message or f"auto: update {datetime.now().strftime('%Y-%m-%d %H:%M')}"
    commit = repo.index.commit(msg, author=Actor("AutoBot", "bot@example.com"))
    print(f"Committed: {commit.hexsha[:7]}")
    return commit

auto_commit(".", "chore: automated sync")

Generate a Changelog

from git import Repo
from collections import defaultdict

def generate_changelog(repo_path: str, from_tag: str, to_tag: str = "HEAD") -> str:
    repo = Repo(repo_path)
    commits = list(repo.iter_commits(f"{from_tag}..{to_tag}"))

    categories = defaultdict(list)
    for commit in commits:
        msg = commit.message.strip().split("\n")[0]
        if msg.startswith("feat"):
            categories["Features"].append(msg)
        elif msg.startswith("fix"):
            categories["Bug Fixes"].append(msg)
        elif msg.startswith("chore") or msg.startswith("ci"):
            categories["Maintenance"].append(msg)
        else:
            categories["Other"].append(msg)

    lines = [f"# Changelog: {from_tag} → {to_tag}\n"]
    for category, items in categories.items():
        lines.append(f"\n## {category}")
        for item in items:
            lines.append(f"- {item}")

    return "\n".join(lines)

print(generate_changelog(".", "v1.0.0", "v1.1.0"))

Find Who Last Modified a Line (git blame)

from git import Repo

def blame_file(repo_path: str, file_path: str):
    repo = Repo(repo_path)
    blame = repo.blame("HEAD", file_path)

    for commit, lines in blame:
        for line in lines:
            print(f"{commit.hexsha[:7]}  {commit.author.name:<20}  {line.decode('utf-8')}", end="")

blame_file(".", "src/auth.py")

Check if Branch Is Behind Remote

from git import Repo

def check_sync_status(repo_path: str):
    repo = Repo(repo_path)
    origin = repo.remotes.origin
    origin.fetch()

    branch = repo.active_branch
    tracking = branch.tracking_branch()

    if tracking is None:
        print("Branch has no remote tracking")
        return

    ahead = list(repo.iter_commits(f"{tracking}..{branch}"))
    behind = list(repo.iter_commits(f"{branch}..{tracking}"))

    print(f"Branch '{branch.name}':")
    print(f"  Ahead by:  {len(ahead)} commit(s)")
    print(f"  Behind by: {len(behind)} commit(s)")

check_sync_status(".")

Using the Raw Git Interface

For executing Git commands not exposed through GitPython's API, call repo.git with any git command you want to run:

from git import Repo

repo = Repo(".")

# Any git command as a method call
output = repo.git.log("--oneline", "-5")
print(output)

# git stash
repo.git.stash("save", "work in progress")
repo.git.stash("pop")

# git cherry-pick
repo.git.cherry_pick("a3f1c22")

# git rebase
repo.git.rebase("main")

Summarizing

GitPython elevates Git from a shell-scriptable command line tool to a fully fledged Python object. Writing deployment tools, code analysis apps, changelog generators or scripts to massage repository data? GitPython has you covered. No more cutting and parsing subprocess output.

Ideally suited to automation: anything you would normally do by hand, with a series of git commands, can be turned into a neat, testable Python function.

Pydantic v2: The Data Validation Library That Makes Python Feel Type-Safe

MEROLINE LIZLENT — Wed, 13 May 2026 10:44:41 +0000

Pydantic is a full data validation, serialization, and settings management library. And with v2 which has been rewritten in Rust, is blazingly fast. This article covers everything from the basics to the advanced patterns that will change how you write Python.

What Is Pydantic?

Pydantic lets you define data schemas using Python type hints and then validates data against those schemas at runtime. When validation fails, you get clear, structured error messages not cryptic KeyError or AttributeError exceptions buried in your business logic.

pip install pydantic
pip install "pydantic[email]"  # for EmailStr and other extras

The Basics: BaseModel

from pydantic import BaseModel

class User(BaseModel):
    id: int
    name: str
    email: str
    is_active: bool = True

# Valid data
user = User(id=1, name="Alice", email="alice@example.com")
print(user.id)        # 1
print(user.is_active) # True (default)

# Pydantic converts compatible types
user2 = User(id="42", name="Bob", email="bob@example.com")
print(type(user2.id))  # <class 'int'> — "42" was coerced to 42

Type coercion is one of Pydantic's most useful behaviors. It tries to convert compatible values rather than failing immediately.

Validation

from pydantic import BaseModel, ValidationError

class Product(BaseModel):
    name: str
    price: float
    quantity: int

try:
    p = Product(name="Widget", price="not_a_number", quantity=10)
except ValidationError as e:
    print(e.json())

Output:

[
  {
    "type": "float_parsing",
    "loc": ["price"],
    "msg": "Input should be a valid number, unable to parse string as a number",
    "input": "not_a_number",
    "url": "https://errors.pydantic.dev/2.x/v/float_parsing"
  }
]

Structured, machine-readable errors with field location, error type, and the offending input.

Field: Fine-Grained Validation

The Field function lets you add constraints, defaults, aliases, and metadata to individual fields.

from pydantic import BaseModel, Field
from typing import Optional

class Article(BaseModel):
    title: "str = Field(..., min_length=3, max_length=200)"
    slug: str = Field(..., pattern=r"^[a-z0-9-]+$")
    body: str = Field(..., min_length=10)
    views: int = Field(default=0, ge=0)
    rating: float = Field(default=5.0, ge=1.0, le=5.0)
    tags: list[str] = Field(default_factory=list, max_length=10)
    author_id: Optional[int] = Field(None, description="Foreign key to users table")

... (Ellipsis) means the field is required. Common constraints:

min_length / max_length — for strings and lists
ge / le / gt / lt — numeric bounds (≥, ≤, >, <)
pattern — regex validation for strings
default_factory — callable that produces the default (use this instead of default=[])

Custom Validators

Field Validators

from pydantic import BaseModel, field_validator

class UserRegistration(BaseModel):
    username: str
    password: str
    confirm_password: str

    @field_validator("username")
    @classmethod
    def username_must_be_alphanumeric(cls, v: str) -> str:
        if not v.isalnum():
            raise ValueError("Username must contain only letters and numbers")
        return v.lower()  # normalize to lowercase

    @field_validator("password")
    @classmethod
    def password_strength(cls, v: str) -> str:
        if len(v) < 8:
            raise ValueError("Password must be at least 8 characters")
        if not any(c.isupper() for c in v):
            raise ValueError("Password must contain at least one uppercase letter")
        if not any(c.isdigit() for c in v):
            raise ValueError("Password must contain at least one digit")
        return v

Model Validators (Cross-Field Validation)

Sometimes you need to validate multiple fields together. Use @model_validator:

from pydantic import BaseModel, model_validator

class PasswordReset(BaseModel):
    password: str
    confirm_password: str

    @model_validator(mode="after")
    def passwords_must_match(self) -> "PasswordReset":
        if self.password != self.confirm_password:
            raise ValueError("Passwords do not match")
        return self

class DateRange(BaseModel):
    start_date: date
    end_date: date

    @model_validator(mode="after")
    def end_must_be_after_start(self) -> "DateRange":
        if self.end_date <= self.start_date:
            raise ValueError("end_date must be after start_date")
        return self

Types That Do the Heavy Lifting

Pydantic ships with a rich set of built-in types that handle common validation patterns:

from pydantic import BaseModel, EmailStr, HttpUrl, AnyUrl
from pydantic import IPvAnyAddress, SecretStr, PositiveInt, NegativeFloat
from datetime import datetime
from uuid import UUID

class RichModel(BaseModel):
    # Validated email address
    email: EmailStr

    # Validated URLs
    website: HttpUrl
    profile_picture: AnyUrl

    # UUID (accepts strings and UUID objects)
    user_id: UUID

    # Hides value in repr and logs — great for passwords/tokens
    api_key: SecretStr

    # Type shortcuts
    age: PositiveInt          # int > 0
    temperature: NegativeFloat  # float < 0

    # IP address (v4 or v6)
    ip_address: IPvAnyAddress

    # Datetime parsing from strings, timestamps, etc.
    created_at: datetime

data = RichModel(
    email="user@example.com",
    website="https://example.com",
    profile_picture="s3://bucket/image.png",
    user_id="550e8400-e29b-41d4-a716-446655440000",
    api_key="super-secret-key",
    age=25,
    temperature=-3.5,
    ip_address="192.168.1.1",
    created_at="2024-01-15T10:30:00Z",
)

print(data.api_key)          # **********  (hidden!)
print(data.api_key.get_secret_value())  # super-secret-key

Nested Models and Composition

Pydantic models compose naturally:

from pydantic import BaseModel
from typing import Optional

class Address(BaseModel):
    street: str
    city: str
    country: str
    postal_code: Optional[str] = None

class Company(BaseModel):
    name: str
    address: Address

class Employee(BaseModel):
    name: str
    company: Company
    work_address: Optional[Address] = None

# Nested dict input works seamlessly
data = {
    "name": "Alice",
    "company": {
        "name": "Acme Corp",
        "address": {
            "street": "123 Main St",
            "city": "Nairobi",
            "country": "Kenya"
        }
    }
}

employee = Employee(**data)
print(employee.company.address.city)  # Nairobi

Validation cascades through all nested models automatically.

Generics: Reusable Response Wrappers

One of Pydantic's most useful patterns for APIs is a generic response wrapper:

from pydantic import BaseModel
from typing import Generic, TypeVar, Optional, List

T = TypeVar("T")

class PaginatedResponse(BaseModel, Generic[T]):
    items: List[T]
    total: int
    page: int
    per_page: int
    has_next: bool

class APIResponse(BaseModel, Generic[T]):
    success: bool
    data: Optional[T] = None
    error: Optional[str] = None

class UserOut(BaseModel):
    id: int
    name: str
    email: str

# Usage
response = APIResponse[UserOut](
    success=True,
    data=UserOut(id=1, name="Alice", email="alice@example.com")
)

paginated = PaginatedResponse[UserOut](
    items=[UserOut(id=1, name="Alice", email="alice@example.com")],
    total=1,
    page=1,
    per_page=10,
    has_next=False,
)

In FastAPI, these generics show up correctly in the OpenAPI schema too.

Serialization: model_dump and model_dump_json

from pydantic import BaseModel, Field
from datetime import datetime

class Event(BaseModel):
    event_id: int = Field(alias="eventId")
    title: str
    created_at: datetime

event = Event(eventId=1, title="Conference", created_at=datetime.now())

# Convert to dict
print(event.model_dump())
# {'event_id': 1, 'title': 'Conference', 'created_at': datetime(...)}

# Use the alias in output
print(event.model_dump(by_alias=True))
# {'eventId': 1, 'title': 'Conference', 'created_at': datetime(...)}

# Exclude fields
print(event.model_dump(exclude={"created_at"}))

# Include only specific fields
print(event.model_dump(include={"title", "event_id"}))

# Serialize to JSON string (fast Rust-based serializer)
print(event.model_dump_json())

Aliases: Bridging Different Naming Conventions

APIs often use camelCase while Python uses snake_case. Pydantic handles this elegantly:

from pydantic import BaseModel, Field
from pydantic.alias_generators import to_camel

class UserProfile(BaseModel):
    model_config = {"alias_generator": to_camel, "populate_by_name": True}

    first_name: str
    last_name: str
    phone_number: str

# Accept camelCase input (from a JS frontend)
profile = UserProfile(firstName="Alice", lastName="Smith", phoneNumber="+254712345678")
print(profile.first_name)  # Alice

# Output camelCase (for a JS frontend)
print(profile.model_dump(by_alias=True))
# {'firstName': 'Meroline', 'lastName': 'Lizlent', 'phoneNumber': '+254712345678'}

Model Config: Customizing Behavior

model_config controls how your model behaves:

from pydantic import BaseModel, ConfigDict

class StrictUser(BaseModel):
    model_config = ConfigDict(
        # Reject extra fields instead of ignoring them
        extra="forbid",

        # Don't coerce types — "42" won't become 42
        strict=True,

        # Validate default values too
        validate_default=True,

        # Allow population by field name even when alias is set
        populate_by_name=True,

        # Freeze the model (make it immutable/hashable)
        frozen=True,
    )

    id: int
    name: str

Common extra options:

"ignore" (default) — silently discard extra fields
"forbid" — raise a validation error if extra fields are present
"allow" — keep extra fields in the model

Pydantic Settings: Managing Configuration

One of Pydantic's killer features for production apps: pydantic-settings for environment variable management.

pip install pydantic-settings

from pydantic import Field
from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        case_sensitive=False,
    )

    # Required — will raise error if not set
    database_url: str
    secret_key: str

    # Optional with defaults
    debug: bool = False
    allowed_hosts: list[str] = ["localhost"]
    max_connections: int = Field(default=10, ge=1, le=100)
    app_name: str = "My App"

# Loads from environment variables and .env file automatically
settings = Settings()
print(settings.database_url)

Your .env:

DATABASE_URL=postgresql://user:pass@localhost/mydb
SECRET_KEY=your-secret-key-here
DEBUG=true
MAX_CONNECTIONS=20

Use it with a singleton pattern in FastAPI:

from functools import lru_cache

@lru_cache
def get_settings() -> Settings:
    return Settings()

# In your FastAPI routes
from fastapi import Depends

@app.get("/info")
def app_info(settings: Settings = Depends(get_settings)):
    return {"app": settings.app_name, "debug": settings.debug}

Computed Fields

Need a field derived from other fields?

from pydantic import BaseModel, computed_field

class Rectangle(BaseModel):
    width: float
    height: float

    @computed_field
    @property
    def area(self) -> float:
        return self.width * self.height

    @computed_field
    @property
    def perimeter(self) -> float:
        return 2 * (self.width + self.height)

r = Rectangle(width=5.0, height=3.0)
print(r.area)       # 15.0
print(r.model_dump())  # includes 'area' and 'perimeter'

Discriminated Unions: Polymorphic Models

When you have multiple model types that share a field used to distinguish them:

from pydantic import BaseModel
from typing import Literal, Union, Annotated
from pydantic import Field

class CreditCardPayment(BaseModel):
    payment_type: Literal["credit_card"]
    card_number: str
    expiry: str
    cvv: str

class BankTransferPayment(BaseModel):
    payment_type: Literal["bank_transfer"]
    account_number: str
    routing_number: str

class MpesaPayment(BaseModel):
    payment_type: Literal["mpesa"]
    phone_number: str
    transaction_id: str

Payment = Annotated[
    Union[CreditCardPayment, BankTransferPayment, MpesaPayment],
    Field(discriminator="payment_type")
]

class Order(BaseModel):
    order_id: int
    amount: float
    payment: Payment

# Pydantic knows exactly which model to use based on payment_type
order = Order(
    order_id=1,
    amount=99.99,
    payment={"payment_type": "mpesa", "phone_number": "+254712345678", "transaction_id": "MPX123"}
)
print(type(order.payment))  # <class 'MpesaPayment'>

Performance: Pydantic v2 Is Fast

Pydantic v2 was rewritten in Rust and is dramatically faster than v1:

Operation	v1	v2
Model validation	baseline	~5-50x faster
JSON serialization	baseline	~10x faster
Schema generation	baseline	~2-5x faster

For high-throughput APIs handling thousands of requests per second, this matters.

You can also pre-compile validators for repeated use:

from pydantic import TypeAdapter

# Validate a list of items without defining a full model
adapter = TypeAdapter(list[int])
result = adapter.validate_python(["1", "2", "3"])
print(result)  # [1, 2, 3]

# Or validate JSON directly (fast path)
result = adapter.validate_json("[1, 2, 3]")

Common Pitfalls

Mutable defaults

# BAD — shared mutable default (classic Python bug)
class Model(BaseModel):
    tags: list = []  # all instances share the same list!

# GOOD
class Model(BaseModel):
    tags: list[str] = Field(default_factory=list)

Modifying a model directly

user = User(id=1, name="Alice")
user.name = "Bob"  # This works but bypasses validation in some contexts

# For truly immutable models:
class User(BaseModel):
    model_config = ConfigDict(frozen=True)
    id: int
    name: str

The dict returned by model_dump() contains the same objects. If you need a deep copy, use model.model_copy(deep=True).

Summary

Pydantic is one of those libraries that, once you learn it properly, changes how you think about data in Python. It brings structure, validation, and type safety to a language that's historically been loose about all three.

The patterns covered here; Field constraints, custom validators, generics, discriminated unions, Settings management are production patterns used in real systems.

DEV Community: MEROLINE LIZLENT

PyScript

What is PyScript?

How does it actually work?

1. Pyodide, Full CPython in the browser

2. MicroPython, Lean and mobile-friendly

DOM access and the FFI

Manipulating the DOM from Python

Using the pyscript.web API (higher-level)

Calling JavaScript from Python

Calling Python from JavaScript

Web Workers: non-blocking Python

Installing packages

The built-in terminal and editor

Python Terminal

Python Editor

Plugins

PyScript vs. alternatives

What can you build with PyScript today?

Honest limitations

Getting started in 5 minutes

The bottom line

Resources

The Architecture Behind Software That Never Stops Running

Redundancy is not the same as availability

Graceful degradation beats heroic uptime

Zero-downtime deploys are a data problem, not a process problem

Self-healing means detecting and correcting without a human in the loop

The actual architecture is organizational as much as technical

Building Performance Budgets Into Git

Treat perf budgets like any other CI gate

Store the baseline in the repo, not in a dashboard

Scope budgets to what actually predicts user-facing pain

Make the regression PR-blocking, not merge-blocking after the fact

Learning YAML From Scratch: What I Wish I Knew Before My First GitHub Actions Workflow published: true

What YAML actually is

Key-value pairs: the foundation

Indentation defines structure

Lists: the dash syntax

Mappings inside lists

A minimal, complete workflow

Mistakes that cost me time

Why this was worth learning properly

Why Documentation Is Architecture

The compiler doesn't care, your team does

Documentation as a design artifact, not a report

Decision records outlive the decision-makers

Where documentation actively prevents bad architecture

Practical shape, not process theater

SQL Patterns Hidden Inside Social Networks

The adjacency list and why "who do I follow" isn't free

The fan-out feed problem

Mutual connections as a bitset problem

Recursive CTEs and the two-hop wall

The general pattern

Inside the AI/ML Community at Zone01 Kisumu: How Peer-to-Peer Learning Is Building Machine Learning Skills Without a Single Lecture

Why AI/ML Needed Its Own Peer Group

How the Group Actually Coordinates

What Peer-to-Peer Learning Actually Buys You in ML

What the Group Has Worked Through

The Honest Challenges

Why This Model Is Worth Copying

Blocks, the Blockchain, and Nodes: How Bitcoin Actually Agrees on Anything

From mempool to block

What's actually inside a block header

The merkle root: proving inclusion cheaply

hashPrevBlock: the actual chain

Mining and proof-of-work

How nodes agree without talking to a referee: Nakamoto consensus

Soft-forks and hard-forks, quickly

Types of nodes you'll encounter

Summarizing

Bitcoin Keys and Addresses

From private key to public key

From public key to address

Segwit addresses: same idea, new encoding

A quick word on wallets

Vanity addresses, briefly

Wrapping up

Go: The Language That Just Works

Using the `pyscript.web` API (higher-level)