Dev Notes

Understanding uv sync and dependency conflicts

2026-04-07T23:00:00+00:00

If you're switching to uv sync, keep in mind that it behaves differently than the standard uv pip workflow. Here is a quick breakdown of what to expect and how to fix common issues.

The Trap: uv sync Resolves Everything

Unlike uv pip compile, which only looks at what you ask for, uv sync attempts to resolve every dependency in your project, including all optional "extras."

Even if you only request specific extras (e.g., uv sync --extra api), uv still checks if the rest of your extras (like deploy) are compatible with your environment. If they conflict, the command will fail.

The Solution: Declaring Conflicts

If you have optional dependencies that are fundamentally incompatible—meaning they aren't meant to be installed together—you can tell uv to ignore those conflicts during the sync process.

Add a conflicts section to your pyproject.toml:

[tool.uv]
conflicts = [
  [
    { extra = "ai" },
    { extra = "deploy" },
  ],
]

The Result

By explicitly declaring that ai and deploy are mutually exclusive, uv sync --extra api --extra ai will now work perfectly. It effectively tells the resolver, "I know these two don't get along; just focus on the ones I actually requested."

Originally published as GitHub Gist #51837dab7bb02c9b5b1c9509693c7d92

licence-normaliser: Taming licence chaos in Python

2026-04-04T14:00:00+00:00

Hey, ever tried cleaning up messy license strings — like CC BY-NC-ND 4.0 or MIT License — and getting them into something tidy and machine-readable? That's exactly what licence-normaliser does, and honestly, it's a lifesaver for anyone dealing with open-source compliance or metadata.

Check out the repo here: licence-normaliser. It's a lightweight Python library that turns chaos into order using a neat three-level system: family → licence → version. Think cc → cc-by-nc-nd → cc-by-nc-nd-4.0.

Here's a quick demo — imagine you're scraping papers or repos and licenses come in every flavor:

from licence_normaliser import normalise_licence

result = normalise_licence("CC BY-NC-ND 4.0")
print(result.key)           # → cc-by-nc-nd-4.0
print(result.licence)       # → cc-by-nc-nd
print(result.licence.family)  # → cc

Super clean, right? It handles SPDX codes (Apache-2.0), full URLs, even sloppy prose like "creative commons attribution non-commercial no derivatives". And for Creative Commons fans — yes, it knows all the variants, including the weird IGO ones.

Look at these badges to see what it normalizes:

Or the compatibility chart if you're remixing stuff:

What makes it robust? Everything's file-driven — aliases, patterns, URLs live in JSON, so you add new synonyms without touching code. Want strictness? Pass strict=True and it'll raise an error if it can't match. Debugging? Use --explain or trace=True to see the whole resolution path.

Install's dead simple:

pip install licence-normaliser

(or uv pip install if you're fancy).

CLI's handy too:

licence-normaliser normalise "MIT"          # → mit
licence-normaliser batch "Apache-2.0" "CC BY 4.0"

It's got only two stars right now — probably because it's niche — but if you're building anything with license detection (think ScanCode integration, repo crawlers, academic tools), this quietly solves a headache. It gets updated via CLI data pulls from SPDX, OSI, Creative Commons... no manual hassle.

Bottom line: if licenses are your mess, normalise them. This tool just works.

Originally published as GitHub Gist #93cafc05616758479eed6377f6593246

Log4Brains images support

2026-04-03T14:00:00+00:00

https://github.com/thomvaill/log4brains

Directory structure

docs
├── adr
│   ├── 20240416-architecture-v2.md
│   ├── 20240916-llm-choice.md
│   ├── 20240916-rag-framework-choice.md
│   ├── index.md
│   └── template.md
└── l4b-static
    └── images
        ├── favicon-16x16.png
        └── favicon-32x32.png

Makefile

Filename: Makefile

add-adr:
    docker run --rm -ti -v $$(pwd):/workdir -p 4004:4004 thomvaill/log4brains adr new $(ARGS)

preview:
    docker run --rm -ti -v $$(pwd):/workdir -p 4004:4004 thomvaill/log4brains preview $(ARGS)

build:
    docker run --rm -ti -v $$(pwd):/workdir -p 4004:4004 thomvaill/log4brains build $(ARGS)
    cp -R docs/l4b-static/* .log4brains/out/l4b-static/

# Serve the built docs on port 5002
serve:
    cd .log4brains/out && python3 -m http.server 5002

GitHub Action

Filename: .github/workflows/publish-log4brains.yml

name: Publish Log4brains
on:
  push:
    branches:
      - main
  workflow_dispatch: {}

jobs:
  pre-commit:
    runs-on: ubuntu-latest
    if: ${{ !github.event.pull_request.draft }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - uses: pre-commit/action@v3.0.0

  build-and-publish:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          persist-credentials: false # required by JamesIves/github-pages-deploy-action
          fetch-depth: 0 # required by Log4brains to work correctly (needs the whole Git history)
      - name: Install Node
        uses: actions/setup-node@v3
        with:
          node-version: "16"
      - name: Install and Build Log4brains
        run: |
          npm install -g log4brains
          log4brains build
          cp -R docs/l4b-static/* .log4brains/out/l4b-static/

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: .log4brains/out

Usage example

Filename: docs/adr/index.md

# Architecture knowledge base

Welcome 👋 to the architecture knowledge base of Project ![Project](/l4b-static/images/favicon-16x16.png).
You will find here all the Architecture Decision Records (ADR) of the project.

Originally published as GitHub Gist #f041a013db9a730d2f2889663d1956f6

Make scrollbars always visible in Vivaldi browser using Stylus

2026-04-03T01:42:00+00:00

Steps

Install Stylus Extension:
- Go to the Chrome Web Store and search for Stylus.
- Install the Stylus extension.

Create a New Style in Stylus:

Click on the Stylus icon in your browser toolbar.
Click on Manage > Write new style.

Add the following CSS code to make scrollbars always visible:

/* Always show vertical scrollbar */
html, body {
    overflow-y: scroll !important;
}

/* Always show horizontal scrollbar */
html, body {
    overflow-x: scroll !important;
}

/* Force scrollbar visibility for all elements */
*::-webkit-scrollbar {
    width: 16px;  /* Set the width for vertical scrollbars */
    height: 16px; /* Set the height for horizontal scrollbars */
    -webkit-appearance: none;
}

*::-webkit-scrollbar-thumb {
    background-color: rgba(0, 0, 0, 0.5); /* Customize the color of the scrollbar thumb */
    border-radius: 8px; /* Customize the radius */
    border: 3px solid rgba(0, 0, 0, 0); /* Adjust border if needed */
}

*::-webkit-scrollbar-track {
    background-color: rgba(0, 0, 0, 0.1); /* Customize the background of the scrollbar track */
}

Save and Apply the Style:
- Give your style a name, for example, Always Show Scrollbars.
- Save and enable the style.

Originally published as GitHub Gist #b957e6e87d2f544054f402957d03bf7a

CudaText installation and config for SublimeText users

2026-04-03T01:08:00+00:00

https://github.com/Alexey-T/CudaText

macOS releases

Go for aarch64 releases

https://github.com/Alexey-T/CudaText/discussions/5590#discussioncomment-15352982

Tweaks

Post-installation

xattr -cr /Applications/CudaText.app

.zshrc

# ----------------------------------------------------------------------------
# CudaText
# ----------------------------------------------------------------------------
alias cudatext="/Applications/CudaText.app/Contents/MacOS/cudatext"

Plugins list

https://github.com/halfbrained/cudatext_plugins_list

CudaExt
CudaLint
Differ
Favorites
Find in Files 4
Highlight Occurrences
Encode
Spell Checker
Case Converter
CSV Helper
Python IntelliSense
SQL Tools
Text Statistics
Markdown Preview
reStructuredText Preview

user.json

{
  "ui_theme": "ebony",
  "ui_theme_syntax": "ebony",
  "ui_toolbar_show": false,
  "ruler_show": true,
  "minimap_show": true,
  "margin_string": "80 120",
  "minimap_sel_always": true,
  "minimap_sel_border": false,
  "tab_size": 4,
  "tab_spaces": true,
  "caret_blink_en": true
}

Originally published as GitHub Gist #65bd6a58ce5f2fda89594c2f4fac812a

Useful plugins for VSCode

2026-04-03T01:02:00+00:00

Sort lines: Sort lines of text for VS Code
PyCharm Theme: PyCharm Theme for VS Code
MarkdownLint: Markdown/CommonMark linting and style checking for VS Code
Makefile Tools: Enhancing Makefile development in VS Code
Pylance: A performant, feature-rich language server for Python in VS Code
Even better TOML: A TOML language support for VS Code
reStructuredText Syntax highlighting: Syntax highlighting and non-intrusive section navigation for reStructuredText.

Originally published as GitHub Gist #cd525950b1cc849dc79306251db183fe

open-webui setup on macOS

2026-04-03T00:21:00+00:00

Here’s how to set up Open WebUI as a launchd service on macOS.

Prerequisites

First, install Open WebUI via uv if you haven’t already:

uv tool install open-webui

1. Create the plist file

cat > ~/Library/LaunchAgents/com.user.openwebui.plist << EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
  <key>Label</key><string>com.user.openwebui</string>
  <key>ProgramArguments</key><array>
    <string>$HOME/.local/share/uv/tools/open-webui/bin/open-webui</string>
    <string>serve</string>
    <string>--port</string>
    <string>8081</string>
  </array>
  <key>WorkingDirectory</key><string>$HOME</string>
  <key>EnvironmentVariables</key><dict>
    <key>HOME</key><string>$HOME</string>
    <key>WEBUI_SECRET_KEY_FILE</key><string>$HOME/.webui_secret_key</string>
  </dict>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>$HOME/Library/Logs/openwebui.log</string>
  <key>StandardErrorPath</key><string>$HOME/Library/Logs/openwebui.err</string>
</dict></plist>
EOF

Save the plist to ~/Library/LaunchAgents/com.user.openwebui.plist. Before doing so, verify the binary path matches your actual installation:

which open-webui
# or
ls ~/.local/share/uv/tools/open-webui/bin/open-webui

If the path differs, update the ProgramArguments string in the plist accordingly.

2. Set the secret key (optional but recommended)

The plist references a secret key file. Create it:

openssl rand -hex 32 > ~/.webui_secret_key
chmod 600 ~/.webui_secret_key

If you don’t want to use a secret key file, remove the WEBUI_SECRET_KEY_FILE entry from EnvironmentVariables in the plist.

3. Load the service

launchctl load ~/Library/LaunchAgents/com.user.openwebui.plist

This registers the service and starts it immediately (because RunAtLoad is true). It will also restart automatically on crash (KeepAlive is true) and run on every login.

4. Verify it's running

# Check the process is up
launchctl list | grep openwebui

# Tail the logs
tail -f ~/Library/Logs/openwebui.log
tail -f ~/Library/Logs/openwebui.err

Then visit http://localhost:8081 in your browser.

5. Common management commands

Action	Command
Stop the service	`launchctl unload ~/Library/LaunchAgents/com.user.openwebui.plist`
Start it again	`launchctl load ~/Library/LaunchAgents/com.user.openwebui.plist`
Restart	unload, then load
Disable autostart	unload + delete the plist file

6. After editing the plist

If you ever modify the plist, you must reload it for changes to take effect:

launchctl unload ~/Library/LaunchAgents/com.user.openwebui.plist
launchctl load ~/Library/LaunchAgents/com.user.openwebui.plist

That’s it — after step 3, Open WebUI will start automatically on every login without any further action needed.

7. Web-app

Open your browser and navigate to http://localhost:8081/.
Firefox and Chromium-based browsers (like Chrome or Edge) support Progressive Web Apps. Click the Install icon in the address bar to run Open WebUI as a standalone application.

Originally published as GitHub Gist #916b8911e29ba9e5ee9b14916834d031

Hide *.py,cover files from IDE

2026-04-02T14:00:00+00:00

VSCode

Settings -> Text Editor -> Files -> Add Pattern: Add **/*.py,cover

PyCharm

Editor -> File Types -> Ignored Files and Folders : Add *.py,cover

Originally published as GitHub Gist #2e36de0a8b64198ed98e748a0a7b7f15

Safezip - zero-dependency wrapper for secure ZIP extraction

2026-02-25T13:00:00+00:00

I wrote a small, zero-dependency wrapper for secure ZIP extraction.

https://github.com/barseghyanartur/safezip

What My Project Does

safezip is a zero-dependency wrapper around Python’s zipfile module that makes secure ZIP extraction the default. It protects against:

ZipSlip protection: Blocks relative paths, absolute paths, Windows UNC paths, Unicode lookalike attacks, and null bytes in filenames.
ZIP bomb prevention: Enforces per-member and cumulative decompression ratio limits at stream time — not based on untrusted header values.
ZIP64 consistency checks: Crafted archives with inconsistent ZIP64 extra fields are rejected before decompression begins.
Symlink policy — configurable: REJECT (default), IGNORE, or RESOLVE_INTERNAL.
Atomic writes: Extracts to a temp file first and only moves it to the destination if all checks pass. If something fails, you don’t end up with half-extracted junk on your disk.
Environment variable overrides: All numeric limits can be set via SAFEZIP_* environment variables for containerised deployments.

It’s meant to be an almost drop-in replacement. You can just do:

from safezip import safe_extract

safe_extract("path/to/file.zip", "/var/files/extracted/")

If you need more control, there’s a SafeZipFile context manager that lets you tweak limits or monitor security events.

from safezip import SafeZipFile

with SafeZipFile("path/to/file.zip") as zf:
    print(zf.namelist())
    zf.extractall("/var/files/extracted/")

Target Audience

If you’re handling user uploads or processing ZIP files from untrusted sources, this might save you some headache. It’s production-oriented but currently in beta, so feedback and edge cases are very welcome.

Comparison

The standard library’s zipfile module historically wasn’t safe to use on untrusted files. Even the official docs warn against extractall() because of ZipSlip risks, and it doesn’t do much to stop ZIP bombs from eating up your disk or memory. Python 3.12 did address some of this — extractall() now strips path components that would escape the target directory — but it still leaves meaningful gaps: no ZIP bomb protection, no stream-time size enforcement, no symlink policy, no ZIP64 consistency checks, and no atomic writes. safezip fills all of those. I got tired of writing the same boilerplate every time, so I packaged it up.

-—

Documentation: https://safezip.readthedocs.io/en/latest/

Originally published as GitHub Gist #160a1cd9c12448447882f12b16e14d35

PyData Amsterdam 2025 notes

2025-09-26T22:02:00+00:00

Prompts

Use DSpy https://dspy.ai/ for automatic prompt optimisation.
Microsoft's attempt to fix the prompt management: https://github.com/microsoft/prompty. Supported by LangChain.

Zero-copy

Use DLPack https://dmlc.github.io/dlpack/latest/ for zero-data-copy of tensor data between between different libs (PyTorch, NumPy, etc.).
Use Apache Arrow https://arrow.apache.org/ for zero-data-copy of tabular data between different libs (Pandas, Polars, DuckDB, etc.).

End-to-end GPU processing

If you're using NVIDIA GPUs, use cuDF-cu12 https://docs.rapids.ai/api/cudf/stable/

Vector DBs

Qdrant https://github.com/qdrant/qdrant is generally loved by many as a vector DB.

Face-recognition

ArcFace https://github.com/deepinsight/insightface and SigLip2 https://huggingface.co/blog/siglip2 are your best friends here.

Notebooks

Marimo is emerging as a Jupyter notebook replacement.

LLMs

Some suggest to use universal LLM proxies for corporate use. LiteLLM https://docs.litellm.ai/ is one of such. Same folks suggest using Open WebUI as a generally available tool for corporate use.
MCP gets tremendous amount of attention.
Proper (optimal) implementation of RAGs get a lot of attention too. Make sure you're familiar with pre, mid, and post optimisations.
Agents get tremendous amount of attention. New frameworks like Dapr https://github.com/dapr/dapr emerge.
Dutch local governance is actively integrating LLMs into their processes.
Some suggest to use outlines https://github.com/dottxt-ai/outlines for structured output.
Some suggest SmolLM https://github.com/huggingface/smollm or https://ollama.com/library/smollm for development/testing, as it's extremely small and fast. There's SmolVLM too, if you need a multimodal version.

Engineering

Some suggest to use DuckDB https://duckdb.org/why_duckdb.html for querying extremely large datasets.
Docling is generally loved by many for format conversion. Check docling-langchain https://github.com/docling-project/docling-langchain/ for better LangChain integration.

Originally published as GitHub Gist #2d4cdb080895d58846427c5e8eec5331

Why is Vivaldi browser a great companion?

2025-03-12T14:03:00+00:00

TL;DR

Vivaldi browser has 1 killing feature, that no other browser has implemented. It can turn any website into a progressive web app.

Ever wanted to have Google Translate or GMail as a web app? No problem! From this point, you could jump directly to How to section.

Background

I have many browsers installed on the systems I use. I use most of them simultaneously.

Firefox for strictly work related private web sites (such as company portal, knowledge base) only. With a minimal set of trusted plugins.
Brave as a primary browser for personal use and main browser for everything else, which isn't company private. Brave's out of the box security is great.
Edge as a secondary browser next to Brave. I use it primarily for Microsoft CoPilot and ChatGPT.
Google Chrome for installing progressive web apps (such as WhatsApp, Google Meet or RegEx101).
Opera for anonymous browsing. I never log into sites using Opera.
Chromium for automated frontend testing. Occasionally.

Vivaldi joined the group recently and immediately climbed to same shelf as Google Chrome. I primarily use Vivaldi for web apps that aren't yet progressive (such as JSONFormatter, JSONDiff or Google Translate.

Why is Vivaldi great?

My use case

I use many browsers. In these browsers I have many tabs. I like it that way. There are many things I want to come back to later on. Some things I check occasionally. I don't like to use favourites.

I use JSONFormatter a lot. JSONDiff too. Google Translate helps me from time to time. I simply want to switch to them quickly. I don't want to have it in a browser.

How to

It's ridiculously simple — no extensions, no extra setup, and it works for any website, even the ones that aren't proper PWAs yet.

Here's exactly what I do:

Open Vivaldi and navigate to the site you want (e.g. JSONFormatter, JSONDiff, Google Translate, whatever).
Right-click the tab on the tab bar.
From the context menu choose Install [website name] (if the site supports full PWA) or Create a shortcut (for everything else — this is the killer part).
Click Install in the tiny confirmation popup.

Done.

The site now lives as its own standalone window, just like WhatsApp or Google Meet do in Chrome. No browser chrome, no stray tabs, no digging through bookmarks or favourites. You can pin it to your taskbar/start menu/dock, launch it with one click, and it feels exactly like a real app.

That's it. That single right-click is why Vivaldi instantly earned the same spot in my workflow as Chrome. Every utility site I use regularly now has its own clean little window, and I can keep my main browsers for actual browsing instead of permanent tab graveyards.

Originally published as GitHub Gist #7fc4de46270ba1ced2f46dc654c21add

How to uninstall Progressive Web App installed with Vivaldi

2024-10-30T19:00:00+00:00

Open the progresssive-web-app/shortcut.
Navigate to the top-right menu, expand the menu and click on "Uninstall {app-name}".

Originally published as GitHub Gist #b48103b4e8091150654373280e09ac90

How to debug Python applications

2022-06-21T11:00:00+00:00

Introduction

In software development, testing is an essential part of ensuring that code works as intended. One critical aspect of testing is debugging, which involves finding and fixing errors or bugs in a program. In this article, we’ll explore how to debug Python applications and highlight some of the most commonly used methods for debugging Python code.

Debugging options

When it comes to debugging Python, there are multiple options available, and you should consider which one suits your needs best. Two popular options are IDE debugging tools and package debugging tools.

IDE Debugging Tools

IDEs like PyCharm and VSCode offer debugging tools that allow you to set breakpoints in your code and run it in debug mode. This allows you to step through your code line by line, inspect variables, and evaluate expressions. Here are some resources for learning how to use the debugging tools in PyCharm and VSCode:

Package Debugging Tools

Links:

Python also offers built-in debugging tools, such as the pdb module, which allow you to set breakpoints and step through your code in a console-based debugger. Additionally, there are alternative packages like ipdb, which is based on the IPython tool and provides a more powerful debugger. Here is an example of how to use the pdb module in your code:

my_module.py

def something(val: str) -> int:
    val += " world"
    import pdb; pdb.set_trace()  # set a breakpoint
    # If you want a more powerful debugger, use `ipdb`.
    # Note, that this requires installation of `ipdb`
    #     $ pip install ipdb
    # Then, comment out the `mport pdb; ...` and
    # uncomment the following line:
    # import ipdb; ipdb.set_trace()

my_str = "Hello"

print(something(my_str))

In the example code above, we set a breakpoint in the something() function using the pdb.set_trace() function. When the code reaches this point, it will pause execution and drop into the debugger, allowing you to inspect variables and step through the code.

Run it

python my_module.py

What would you see

$ python my_module.py
--Return--
> /home/artur.local/repos/tryouts/debug/my_module.py(3)something()->None
-> import pdb; pdb.set_trace()  # set a breakpoint
(Pdb) locals()
{'val': 'Hello world', 'pdb': <module 'pdb' from '/usr/lib64/python3.11/pdb.py'>, '__return__': None}
(Pdb) val
'Hello world'
(Pdb)

Study pdb documentation for more.

Good to know

It works similarly with your web views (like, FastAPI/Flask/Django).

def your_view(request):
   # ...
   import pdb; pdb.set_trace()

Best Practices for Debugging Python

While debugging is an essential part of the development process, there are some best practices to keep in mind to ensure that your code remains clean and maintainable.

Don’t commit your debug code!

Links:

One critical practice is to avoid committing your debug code to your code repository. Debug code can clutter your codebase and make it more challenging to maintain. To avoid committing debug code, use a tool like pre-commit and linters like ruff to catch and prevent it from being committed.

Debugging in Docker

If you use Docker for development, you need to configure your docker-compose.yml to allow debugging. You can do this by setting the stdin_open and tty options for your service:

version: '3'

services:
  api:
    # Other configuration
    stdin_open: true
    tty: true

After configuring your Docker environment, assuming that you have it running already, you can find the container ID (CONTAINER ID) for your service (in the example above - api service) using docker ps and attach to it with the docker attach (docker attach {CONTAINER ID}) command to start debugging. Note, that you will need to run the docker attach command in a separate shell/terminal tab and that’s where the debug prompt will appear.

Conclusion

Debugging Python is an essential skill for any developer, and it’s crucial to understand the available options and best practices. In this article, we explored two popular options for debugging Python: IDE debugging tools and package debugging tools. We also highlighted some best practices for debugging in Python, including avoiding committing debug code and configuring Docker for debugging. With this knowledge, you’ll be better equipped to debug Python applications and write clean, maintainable code.

Originally published as GitHub Gist #27c2f93e772330a4798fa7269a5ddb9b