Niclas van Eyk

Diy

Sun, 07 Apr 2024 00:00:00 GMT

I really like the Laravel Service Container. diy is my attempt at recreating something in Python. After working with FastAPI, I notices some shortcomings in their DI system. Other solutions in the Python ecosystem also did not satisfy me. Most of the issues I had are described in the guiding principles section of diys documentation, though no libraries are explicitly mentioned.

Quickstart

There are two important parts in diy. Specifications contain explicit instructions about how to resolve function parameters, construct types or map protocols/interfaces to a concrete implementation.

import diy

spec = diy.Specification()

This is our example class, which only takes one parameter

class ApiClient:
  def __init__(self, token: str):
    self.token = token

  def get(self, url: str):
    # imagine an actual implementation here using the token

This teaches our container how to build an ApiClient

import os

@spec.builders.decorate
def build_api_client() -> ApiClient:
  return ApiClient(token=os.environ["API_TOKEN"])

The container retrieves a spec, and uses the contained instructions to construct types

container = diy.RuntimeContainer(spec)

This is how you get an instance

api_client = diy.resolve(ApiClient)

You can also call functions by letting their parameters be resolved from the container

def get_data(api: ApiClient):
  return api.imaginary_method("")
result = diy.call(get_data)

Notes

focus on good error messages
dependency visualization
autowiring
validation

Pytest GitLab Code Quality

Thu, 28 Mar 2024 00:00:00 GMT

Collects warnings while testing and generates a GitLab Code Quality Report.

Auto-Dark-Mode for Fish Shell

Wed, 28 Feb 2024 00:00:00 GMT

I prefer using light mode in bright environments and dark mode in darker ones. To me, this just makes sense. I don't want to be blinded by a screen when looking at my phone after waking up. Similarly, I also don't want to have a hard time reading white text on a dark background during the day.

This is why I typically setup my computers to schedule dark mode around sunset and use light mode again after sunrise. Most applications, such as apps, websites, etc. automatically adjust their theme to match the one of the operating system. However, as a developer, one notable exception is the terminal.

The Problem With Terminal Color Themes

Terminals used bright text on a dark background even before operating system dark mode was a thing. This is also why a lot of tools just assume dark mode, making.

There are terminals that can automatically change their color theme based on the system dark mode setting. One example is WezTerm, where you configure the terminal using Lua scripts and can adjust your color theme using the get_appearance function.

This fixes part of the problem for some terminals, but simply changing the terminal colors, does not automatically make everything readable.

Hardcoded Colors. Hopefully these are ANSI colors. Then the program specifies, that e.g. a portion of text should be red, and your terminal color scheme then determines the specific shade of red. However, this might be a concrete RGB value, in which case your out of luck.
Inferred Colors. There are nonstandard ways for programs to detect, whether you use a light or dark terminal color scheme (e.g. have a look at the terminal-light Rust crate, which links to a few nice sources in its code). Based on this, the program can adjust its output and use light text on a dark background or vice verca.
Adjustable Colors. Some programs allow the user to control how it renders its output. Examples include bat, difft, and most programs using Charms Glow / Lip Gloss libraries for highlighting text, such as GitHubs gh.

Ideally the program infers the color scheme, but lets you override the theme yourself. This way, you can still adjust the color scheme to your liking. Why this is still useful can be seen in the following image, displaying the output of the previously mentioned bat program, which, amongst others things, can output the contents of a file with syntax highlighting:

On the left, you see inferred colors from my terminal color scheme, which is Visual Studios Dark+ Theme for the Kitty terminal emulator. On the right you see the output when setting the color scheme to a Dark+ Theme specifically created for bat. As can be seen, the right one highlights closer to how the color scheme would look in VS Code itself. While the one on the left also uses colors from the general palette of the theme, the right one uses green for comments, just as VS Code would, leading to a more familiar and uniform look.

How Fish Can Help

The Fish shell has some nice features compared to Bash or Zsh. Out of the box it includes autocompletion, syntax highlighting, and (in my opinion) more sensible defaults in general.

For this post, we want to focus on its ability to define universal variables and reacting to variable changes using event handlers. In short, the former is a variable that all shell instances share. These can also be exported, which means that they are available as an environment variable. The latter allows us to respond to changes of variables. Together, these two features enable us to configure the color scheme of our CLI programs based on a single value.

A Concrete Example

Lets say we want to configure the color scheme of both Diffastic and Bat. We also want to have a single source of truth for whether we are in dark or light mode.

First, lets define this single value using a universal and exported fish variable. Fish can be configured by placing any *.fish file inside your configuration directory, which is usually ~/.config/fish/conf.d/. So lets create auto_dark_mode.fish:

# ~/.config/fish/conf.d/auto_dark_mode.fish

# We default to dark. It is better to be surprised by a dark theme in a light 
# environment, than a bright screen in a dark one.
set -Ux COLOR_MODE dark

This now gives us a variable we can change in any shell and it will sync to all other instances:

Now, lets create a separate configuration file for bat:

# ~/.config/fish/conf.d/bat.fish

# This environment variable gets read by bat and configures its theme.
set -Ux BAT_THEME 'Visual Studio Dark+'

# This function will be automatically called, whenever COLOR_MODE is changed.
function update_bat_theme --on-variable COLOR_MODE
    # Based on the new value of COLOR_MODE, we either configure
    # bat to use our preferred light or dark color scheme.
    if [ $COLOR_MODE = light ]
        set BAT_THEME 'Solarized (light)'
    else
        set BAT_THEME 'Visual Studio Dark+'
    end
end

We can configure difftastic in a similar way:

# ~/.config/fish/conf.d/difftastic.fish

# Difftastic automatically sets colors, but we need to explicitly tell it 
# whether we have a light or a dark terminal theme.
set -Ux DFT_BACKGROUND dark

function update_difftastic_background --on-variable COLOR_MODE
    # You could also directly assign the value of COLOR_MODE here, but this
    # way it is clear that this is the same pattern as before.
    if [ $COLOR_MODE = light ]
        set DFT_BACKGROUND light
    else
        set DFT_BACKGROUND dark
    end
end

Automation

By now we can manually run set COLOR_MODE = dark in our shell to explicitly tell our command line applications to adjust to dark mode. This works, but is a bit cumbersome to do every time you pick up your laptop in the evening or early morning. Since it is dark outside your OS automatically adjusted, but our shell still kept the state it was in last time, which might be light mode.

A simple solution is just ask the OS what mode we are in every time we start a new shell. Thanks the universal variables, starting a new shell would also update all the others. TODO A bit more text here.

A better, but maybe slightly more complex solution is to somehow get notified when the OS dark mode changes and react to this. We can achieve this using Dark Mode Daemon, which can be easily installed and launched at login via Homebrew.

To be honest, I searched for a solution to this problem for MacOS, but every article or forum post I did find told me to write my own Swift program and juggle with .plist entries. This is not something I could easily put in my dotfiles, so I decided to automate this, leading to the creation of Dark Mode Daemon. It still is a swift program, but you don't need to adjust it or maintain it.

So what does it do? Basically, you place an executable script in ~/.config/dark-mode-daemon/scripts and it will called when dark mode changes, you initially log in, and when your computer wakes up from sleep mode. It sets the DMD_COLOR_MODE to either light or dark when running the scripts, so we can very easily automate syncing our universal fish variable:

# ~/.config/dark-mode-daemon/scripts/fish-color-mode.fish

#!/usr/bin/fish

set COLOR_MODE $DMD_COLOR_MODE

And that's it!

<details> <summary>Bonus: Automate changing your terminal color scheme</summary>

If you are not using one of the previously mentioned terminals that can sync their color scheme, you might want to utilize Dark Mode Daemon. This is what I have done to have my terminal, Kitty, to sync its color scheme with the operation system one.

# ~/.config/dark-mode-daemon/scripts/update-kitty-theme.sh

#!/usr/bin/env bash

# Link light.theme.conf or dark.theme.conf to current.theme.conf
ln -s -f "$HOME/.config/kitty/$DMD_COLOR_MODE.theme.conf" "$HOME/.config/kitty/current.theme.conf"

# Tell all running kitty instances that the color mode has changed and that they should reload their config.
kill -SIGUSR1 $(pgrep -a kitty)

To make the above script work, we need to add the following to our kitty configuration file:

include current.theme.conf

and then create ~/.config/kitty/dark.theme.conf and ~/.config/kitty/light.theme.conf, which contain our chosen theme files. The script will then link current.theme.conf to the theme based on the OS color scheme. Themes files can be retrieved from the kitty-themes repository on GitHub or by using the kitty +kitten themes command. </details>

Conclusion

Dark Mode Daemon

Wed, 28 Feb 2024 00:00:00 GMT

Run scripts when the system color scheme changes between light and dark.

Web Framework Field Guide

Tue, 03 Oct 2023 00:00:00 GMT

Documents, compares and explains implementations of common web framework patterns.

Chers

Wed, 20 Sep 2023 00:00:00 GMT

This project primarily originated from the urge to play with technologies. I like to play chess from time to time, so why not recreate it from scratch? At first, it was an excuse to learn the Rust programming language. Then it turned more into an excuse to learn more about rendering in a terminal environment. Turns out you can compile Rust to WebAssembly, so the logical next step was to do just that so everything can run in the browser. That however, required to also build a web UI in addition to the terminal one.

The implementation is definitely not complete though. While all movement patterns, detecting checks and check mates, and even some more exotic rules like en passant do work, castling and e.g. proper movement clocks do not. I'd also like to implement peer to peer matches via sockets.

Keepac

Fri, 19 May 2023 00:00:00 GMT

Named after the first few letters of keepachangelog.com.

The Keep a Changelog best practises provide a solid foundation when writing changelogs. This way, you can concentrate on writing the changelog itself.

Keepac helps you work with changelogs following these conventions. Its binary, changelog, makes all commands feel natural.

Example workflow

Let's walk through common software development steps to show how Keepac can help us documenting the user-facing changes. The command line blocks show the commands and their respective output. Below the commands you also see the diff of the CHANGELOG.md file.

Creating The Changelog File

Now imagine you have already created your project using something like cargo new, npm create, or something else. Since we are very disciplined developers, we start documenting our changes right away.

$ changelog init

Initialized empty changelog at /tmp/keepac-demo/CHANGELOG.md:

   Changelog                                                                       
                                                                                   
  All notable changes to this project will be documented in this file.             
                                                                                   
  The format is based on Keep a Changelog https://keepachangelog.com/en/1.1.0/, and
  this project adheres to Semantic Versioning https://semver.org/spec/v2.0.0.html. 
                                                                                   
  ## [Unreleased]

<br>


+ # Changelog
+
+ All notable changes to this project will be documented in this file.
+
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+ ## [Unreleased]

That was easy! We did not even have to open our IDE or text editor.

If you use git on the command line, this workflow feels very similar to git init. This is on purpose. While the git CLI is not known for being intuitive, it has some nice features that inspired changelog.

Documenting Changes

Now imagine we have implement a new feature. The details are not important, just imagine we added a new API that our users should know about. Again, we use changelog for this, directly from our terminal.

$ changelog add "A shiny new feature"

  ### Added                                                                        
                                                                                   
  • A shiny new feature

<br>

  # Changelog

  All notable changes to this project will be documented in this file.

  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

  ## [Unreleased]
+
+ ### Added
+
+ - A shiny new feature

Similar to git, if you omit the message, your $EDITOR would open and you could provide more detail.

Removing, Changing, Or Deprecating Features

In our fictional example, it won't really make sense to document the removal of features. However, the Keep a Changelog guidelines list several types of changes, such as bug fixes, deprecations or general changes in behavior of the software. Let's document the removal of an old feature that we no longer want to support, just to see how that would work.

$ changelog rm "A boring old feature"

  ### Removed                                                                      
                                                                                   
  • A boring old feature

<br>

  # Changelog

  All notable changes to this project will be documented in this file.

  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

  ## [Unreleased]

  ### Added

  - A shiny new feature

+ ### Removed
+
+ - A boring old feature

Instead of using the shortcuts (add, change, deprecate, ...), you may also run the generic changelog insert and pass one of the following flags

--added
--changed
--deprecated
--fixed
--removed
--security

You can run changelog insert --help to see a complete list of the supported change types, including their shortcuts and aliases.

Releasing

Up until now, all our changes are documented under the [Unreleased] section. Now we are going to change that. First, we check what's contained in our next release.

$ changelog show next

  ## [Unreleased]                                                                  
                                                                                   
  ### Added                                                                        
                                                                                   
  • A shiny new feature                                                            
                                                                                   
  ### Removed                                                                      
                                                                                   
  • A boring old feature

Just as we expect, it only consists of our two changes. To be fair, this command is much more helpful when you have a long list of historic releases that you don't want to look at every time.

Now we choose, whether we want to increment the major, minor, or patch version and run the release command.

$ changelog release --minor

  ## [0.1.0] - 2024-03-05                                                          
                                                                                   
  ### Added                                                                        
                                                                                   
  • A shiny new feature                                                            
                                                                                   
  ### Removed                                                                      
                                                                                   
  • A boring old feature

<br>

  # Changelog

  All notable changes to this project will be documented in this file.

  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

- ## [Unreleased]
+ ## [0.1.0] - 2024-03-05

  ### Added

  - A shiny new feature

  ### Removed

  - A boring old feature

We chose to explicitly pass the --minor flag here, but you can also pass no flag to the release command to interactively choose the next version.

Closing Notes

And now we are done! The steps in the example are roughly the workflows that motivated the creation of Keepac. I grew tired of looking up the exact headings that Keep a Changelog uses, inserting them manually, or manually looking up todays date for a release. Every one of these steps does not sound that inconvenient, but I found implementing them using changelog much more convenient!

There is more to explore. You can run changelog --help to explore everything. Here are some examples:

generate the text for a GitHub release using changelog show --plain $VERSION (example from Keepacs own release workflow)
open up CHANGELOG.md from anywhere in your project using changelog edit
view the changes of multiple releases combined using changelog diff --merged 0.2.0 0.2.8
search for strings in changelogs (like grep) and see the resulting within context (version, changetype, unlike grep)

If you want to try it out and you run Linux or MacOS, just run

brew install niclasvaneyk/keepac/keepac

To learn more, such as how to compile it from scratch for Windows support, is visit the project on GitHub.

Initializer for Laravel

Fri, 25 Jun 2021 00:00:00 GMT

A visual approach to creating a new Laravel application.

Make for Laravel

Mon, 06 Jul 2020 00:00:00 GMT

A set of integration points that connect your Laravel application to PhpStorm.