Forem: k38f

How I Built a Static Analyzer for Python Env Variables in ~700 Lines

k38f — Fri, 17 Apr 2026 17:00:53 +0000

I keep forgetting to add new env vars to .env.production before deploying. A few times it was harmless, a few times it was not. At some point it was easier to write a tool than to fix myself.

The tool is envsleuth. It reads your Python source, finds every os.getenv() / os.environ[] / os.environ.get(), and compares that list with your .env file. Pretty boring on the outside, but building it was a nice excuse to dig into the ast module. That's what this post is about.

What grep gets you

The first version wasn't a tool, it was just:

grep -rn "os.getenv" src/

This gets you through maybe a week. Then you notice it misses os.environ["X"]. And os.environ.get("X"). And it matches methods on unrelated classes that happen to be called getenv. And it has no way to tell os.getenv("X") apart from os.getenv("X", "fallback"), which matters because the second one is optional.

At that point you either write a smarter regex (don't) or start looking at ast.

What ast actually is

ast.parse(source) takes Python code and gives you back a tree. Every line of your program becomes a nested structure of nodes: Module, FunctionDef, Call, Attribute, Name, Constant, and so on.

For os.getenv("DATABASE_URL") you get roughly:

Call(
  func=Attribute(
    value=Name(id='os'),
    attr='getenv'),
  args=[Constant(value='DATABASE_URL')])

Once you see it in this shape, the matching logic writes itself. "Is this a Call? Is the function an Attribute called getenv? Is it an attribute of a Name called os? Yes? Take args[0]."

import ast

class EnvVisitor(ast.NodeVisitor):
    def __init__(self):
        self.names = []

    def visit_Call(self, node):
        if (isinstance(node.func, ast.Attribute)
                and node.func.attr == "getenv"
                and isinstance(node.func.value, ast.Name)
                and node.func.value.id == "os"):
            if node.args and isinstance(node.args[0], ast.Constant):
                self.names.append(node.args[0].value)
        self.generic_visit(node)

That last line, generic_visit, is the one I forgot on the first try. Without it the visitor only sees top-level nodes and misses everything nested in functions. A whole project returned zero results before I figured that out.

Three patterns

Python has three idiomatic ways to read env vars:

os.getenv("X")        # Call on Attribute
os.environ["X"]       # Subscript
os.environ.get("X")   # Call on nested Attribute

Each is a different AST shape, so each needs its own matcher. The nested one (os.environ.get) is the most fun — it's a Call whose func is an Attribute whose value is another Attribute. Nesting levels matter.

def _is_environ_get(self, node):
    func = node.func
    if not isinstance(func, ast.Attribute) or func.attr != "get":
        return False
    inner = func.value
    return (isinstance(inner, ast.Attribute)
            and inner.attr == "environ"
            and isinstance(inner.value, ast.Name)
            and inner.value.id == "os")

For the Subscript case (os.environ["X"]) you override visit_Subscript instead of visit_Call. Same idea, different node type.

Aliases

This is where the naive version breaks in practice. All four of these mean the same thing:

import os
os.getenv("X")

import os as sys_env
sys_env.getenv("X")

from os import getenv
getenv("X")

from os import getenv as ge
ge("X")

If you hardcode "os" in your matcher, you only catch the first one. Real codebases have the other three all the time.

The fix is a first pass that collects import bindings, then the matcher checks membership:

def visit_Import(self, node):
    for alias in node.names:
        if alias.name == "os":
            self._os_aliases.add(alias.asname or "os")
    self.generic_visit(node)

def visit_ImportFrom(self, node):
    if node.module == "os":
        for alias in node.names:
            bound = alias.asname or alias.name
            if alias.name == "getenv":
                self._getenv_aliases.add(bound)
            elif alias.name == "environ":
                self._environ_aliases.add(bound)

Now _is_getenv_call asks "is the thing we're calling in the _os_aliases set", not "is it literally the string os".

There's a nice side effect: this also cuts out false positives. If somebody has a class with a getenv method, the name "getenv" exists in the code but it's never bound via import os — so it's correctly ignored. A grep-based tool would flag it.

The thing ast can't solve

os.getenv(f"FEATURE_{name.upper()}")
os.getenv(some_variable)

These variable names are computed at runtime. Static analysis fundamentally can't know what they are without running the program. You have three choices:

Skip them silently — user never knows they exist
Refuse to handle the file — annoying
Report them separately as "dynamic usages, check manually"

I went with 3. The tool prints them under a separate warning section with the file and line number, so at least you know something's there. Pretending to solve a problem you can't solve is worse than admitting the limit.

What else is in the box

The scanner is ~200 lines. The rest of the project is:

A .env reader (via python-dotenv, no point rewriting that)
A comparison module that knows about .envignore for things you want to exclude
ANSI terminal output (I did not pull in rich for colouring five lines)
A click-based CLI
A generate command that turns a scan result into a .env.example with comments pointing at where each variable is used

Total ~700 lines, 49 tests, MIT licensed.

Try it

pip install envsleuth
envsleuth scan --path ./src
envsleuth generate              # writes .env.example from your code
envsleuth scan --strict         # exit 1 if anything's missing, for CI

Source: github.com/k38f/envsleuth

If you find a case it doesn't handle (Django settings modules, pydantic-settings integration, anything else), open an issue or a PR. Curious to see what breaks on real codebases.

How I built a progress bar library in 300 lines of Python

k38f — Thu, 16 Apr 2026 14:20:37 +0000

I wanted a pretty progress bar for my scripts without pulling in a big library. So I built one from scratch. Here's everything I learned about ANSI escape codes, ETA math, terminal tricks, and threading — all in ~300 lines.

The full source is flashbar on GitHub. You can read the entire thing in one coffee break.

The core trick: carriage return

A progress bar isn't magic. It's just one line that keeps rewriting itself. The secret is \r — carriage return. It moves the cursor back to the start of the line without creating a new one:

import sys
import time

for i in range(101):
    sys.stderr.write(f"\r{i}%")
    sys.stderr.flush()
    time.sleep(0.02)

Run this and you'll see "0%" turn into "1%", then "2%", all on the same line. That's the entire foundation of every terminal progress bar.

Two details matter here:

Why stderr? Because stdout is often piped to files or other programs. If your script does python myscript.py > output.txt, you don't want progress bars in the file. stderr stays on screen.

Why flush()? Python buffers stderr output. Without flush(), your updates might batch together and the bar won't look smooth.

Drawing the bar

Now let's make it look like an actual bar. We need filled and empty characters:

def draw_bar(current, total, width=40):
    pct = current / total
    filled = int(width * pct)
    bar = "█" * filled + "░" * (width - filled)
    return f"[{bar}] {int(pct * 100):3d}%"

█ (U+2588) is a full block, ░ (U+2591) is a light shade. Most modern terminals render these fine. The :3d format keeps the percentage right-aligned so "1%" and "100%" don't make the line jump around.

Adding color with ANSI escape codes

Terminals understand special sequences that change text color. They all start with \033[ (the escape character) and end with m:

BLUE  = "\033[94m"
GREEN = "\033[92m"
RED   = "\033[91m"
RESET = "\033[0m"

# Usage
print(f"{BLUE}This is blue{RESET} and this is normal")

The numbers map to colors: 91=red, 92=green, 93=yellow, 94=blue, 95=magenta, 96=cyan, 97=white. These are "bright" variants — the basic ones (31-37) are dimmer.

For hex colors like #FF5733, terminals support 24-bit color:

def hex_to_ansi(hex_color):
    r = int(hex_color[1:3], 16)
    g = int(hex_color[3:5], 16)
    b = int(hex_color[5:7], 16)
    return f"\033[38;2;{r};{g};{b}m"

38;2;R;G;B sets the foreground color to any RGB value. Not every terminal supports this, but most modern ones (Windows Terminal, iTerm2, GNOME Terminal) do.

In flashbar, I wrapped this into a resolve_color() function that handles both named colors and hex:

def resolve_color(color):
    if color in NAMED_COLORS:
        return NAMED_COLORS[color]
    if color.startswith("#") and len(color) == 7:
        r, g, b = int(color[1:3], 16), int(color[3:5], 16), int(color[5:7], 16)
        return f"\033[38;2;{r};{g};{b}m"
    return NAMED_COLORS["blue"]  # safe fallback

No crash on bad input — just falls back to blue.

Calculating ETA

ETA is surprisingly simple math. If you've done 40 out of 100 items in 8 seconds:

Speed: 40 items / 8 seconds = 5 items/sec
Remaining: 100 - 40 = 60 items
ETA: 60 / 5 = 12 seconds

In code:

elapsed = time.monotonic() - start_time
if current > 0:
    eta = (elapsed / current) * (total - current)

Why time.monotonic() instead of time.time()? Because time.time() can jump backward if the system clock adjusts (NTP sync, daylight saving, manual change). time.monotonic() only goes forward, so your ETA will never go negative from a clock adjustment.

Formatting the result:

def _format_time(seconds):
    if seconds < 0:
        return "--:--"
    seconds = int(seconds)
    if seconds < 3600:
        return f"{seconds // 60:02d}:{seconds % 60:02d}"
    h = seconds // 3600
    m = (seconds % 3600) // 60
    s = seconds % 60
    return f"{h}:{m:02d}:{s:02d}"

The theme system

Instead of hardcoding characters, I used a dict of themes:

THEMES = {
    "default": {"fill": "█", "empty": "░", "color": "\033[94m"},
    "retro":   {"fill": "#", "empty": ".", "color": "\033[93m"},
    "dots":    {"fill": "●", "empty": "○", "color": "\033[95m"},
    "arrow":   {"fill": "▸", "empty": "▹", "color": "\033[94m"},
    # ... more themes
}

Then the Bar class picks from this dict and allows overrides:

base = THEMES.get(theme, THEMES["default"])
self.color = resolve_color(color) if color else base["color"]
self.fill  = fill  or base["fill"]
self.empty = empty or base["empty"]

This means you can use a theme as a starting point and override just the color, or just the characters. Simple but flexible.

Terminal width: don't wrap

If your bar is wider than the terminal, it wraps to the next line and everything breaks. The fix:

import shutil

term_w = shutil.get_terminal_size().columns

Then truncate your output if it's too wide:

import re

visible = re.sub(r"\033\[[0-9;]*m", "", line)  # strip ANSI codes
if len(visible) > term_w:
    line = line[:term_w]

The regex strips ANSI codes before measuring, because \033[94m is 5 characters but displays as zero width. You need the visible length, not the raw string length.

Also, \033[K at the end of the line clears everything to the right — so if your new line is shorter than the previous one, you won't see leftover characters:

sys.stderr.write(f"\r{line}\033[K")

Building a spinner with threading

A spinner is different from a progress bar — it animates continuously while your code does something else. That means it needs to run in a separate thread:

import threading

class Spinner:
    def __init__(self, label, style="dots"):
        self.label = label
        self.frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧"]
        self._running = False
        self._thread = None

    def start(self):
        self._running = True
        self._thread = threading.Thread(target=self._animate, daemon=True)
        self._thread.start()

    def stop(self, final_text=None):
        self._running = False
        self._thread.join()
        sys.stderr.write(f"\r\033[K")  # clear line
        if final_text:
            sys.stderr.write(f"{final_text}\n")

    def _animate(self):
        idx = 0
        while self._running:
            frame = self.frames[idx % len(self.frames)]
            sys.stderr.write(f"\r{frame} {self.label}")
            sys.stderr.flush()
            idx += 1
            time.sleep(0.08)

Key decisions:

daemon=True — if your main program crashes or exits, the spinner thread dies automatically. Without this, the thread would keep your process alive.

self._running as a simple bool — technically, reading a bool from one thread while another writes it is a race condition. In CPython, the GIL makes this safe in practice, but a threading.Event would be more correct.

Adding a context manager makes it clean to use:

def __enter__(self):
    self.start()
    return self

def __exit__(self, exc_type, *_):
    if exc_type is None:
        self.stop(f"✓ {self.label}")
    else:
        self.stop(f"✗ {self.label} (failed)")
    return False

Now you get ✓ on success and ✗ on exception — automatically.

The `track()` wrapper

The most popular feature is the simplest. track() wraps any iterable with a progress bar:

def track(iterable, label="Progress", total=None, **kwargs):
    if total is None:
        if hasattr(iterable, "__len__"):
            total = len(iterable)
        else:
            raise TypeError(
                "iterable has no len(). Pass total= explicitly."
            )

    bar = Bar(total, label=label, **kwargs)
    for item in iterable:
        yield item
        bar.update()

It's a generator — yield item gives each element to the caller, then bar.update() advances the bar. For generators that don't have __len__, you pass total= manually.

The entire function is 12 lines, but it's the one people use 90% of the time.

What I'd do differently

TTY detection. Right now, flashbar always outputs ANSI codes. If someone pipes the output (python script.py 2> log.txt), the log file gets filled with escape characters. The fix is sys.stderr.isatty() — check if we're in an actual terminal, and disable colors/animation if not.

Thread safety in the spinner. The bool flag works, but threading.Event is the proper way. It's atomic and doesn't rely on CPython's GIL.

Time formatting for short tasks. int(0.8) becomes 0, so quick tasks show 00:00 for ETA. Should show 0.8s instead.

The full picture

Here's how it all fits together:

bar.py (~170 lines): Bar class, track() generator, themes, colors, time formatting
spinner.py (~60 lines): Spinner class with threading
__init__.py (~10 lines): exports

That's it. No metaclasses, no abstract base classes, no plugin systems. Just functions, one class per file, and standard library only.

The source is at github.com/k38f/flashbar. Install with pip install flashbar. Read the whole thing in one sitting — I promise it won't take long.