DEV Community: piko::tutorial

If not Python venv, then what?

piko::tutorial — Mon, 07 Sep 2026 05:00:00 +0000

For years, python -m venv .venv has been the default answer to Python dependency management and isolation. It works, it’s built into Python and almost every tutorial assumes you’ll use it.

But today, more and more developers are asking a question Do I actually need venv anymore?

And the answer is: not always. This article explores what modern alternatives exist and when they make sense.

Option 1: uv

The biggest momentum shift in Python tooling right now is probably uv. It’s a Rust-based Python package manager that aims to be extremely fast while simplifying dependency and environment management.

To install uv, invoke:

curl -LsSf https://astral.sh/uv/install.sh | sh

Now you can call:

uv init my_app
cd my_app

This creates a project folder with the following files:

.python-version - contains the Python interpreter version
main.py - a ready-to-run hello world application
pyproject.toml
README.md

You can run the generated application with:

uv run main.py

If you want to add the requests library, call:

uv add requests

At this point, uv automatically creates a .venv folder and installs the dependency there.

Option 2: Poetry

Before uv, Poetry was often considered the “modern Python workflow” tool. To install Poetry, call:

curl -LsSf https://install.python-poetry.org | python3 -

Now you can call:

poetry new myapp
cd myapp

This creates a slightly different project structure than uv:

src/myapp/__init__.py
tests/__init__.py
pyproject.toml
README.md

Notice that there is no .venv folder inside the project directory. By default, Poetry stores all virtual environments centrally in one location. On Linux, you can usually find them in ~/.cache/pypoetry/virtualenvs where every Poetry-managed project gets its own dedicated virtual environment.

If you want to add the requests library, call:

poetry add requests

To run your application, invoke:

poetry run python src/myapp/main.py

AI is powerful. Snippets are instant.

Stop prompting for the same patterns repeatedly. Get almost 100 free VS Code snippets for C++, Python, CMake and Bazel from piko::snippets GitHub repository.

Option 3: PDM

PDM originally implemented an idea based on PEP 582. Instead of creating isolated virtual environments with separate interpreter binaries, dependencies (and only Python dependencies) would simply be stored in a local __pypackages__ directory inside the project.

To install PDM, invoke:

curl -LsSf https://pdm-project.org/install-pdm.py | python3 -

Now you can call:

pdm new myapp

Unlike uv and Poetry, PDM asks several interactive questions before creating the project, for example:

what Python interpreter should be used?
what is the project name?
what is the project version?
what license should be used?
what is the author name?
what is the email address?
should a Git repository be initialized?

After answering these questions, PDM creates a structure similar to:

.venv
.pdm-python
pyproject.toml

If you want to add the requests library, call:

pdm add requests

And the dependency lands in the .venv folder. So where is the promised __pypackages__ directory?

The answer is that PEP 582 was never accepted as an official Python standard, so ecosystem tooling never fully adopted it. As a result, modern PDM versions switched to .venv as the default approach.

If you still want to use __pypackages__, you must enable it explicitly:

pdm config python.use_venv false

Now dependencies will be stored in the __pypackages__ directory instead. Running your app is no surprise at this point:

pdm run main.py

Option 4: Containers instead of environments

Some teams skip Python environments entirely and isolate applications using containers. In this approach, dependency isolation happens at the container level rather than through local virtual environments.

In such setups, having a dedicated venv becomes less important because the container itself acts as the isolation boundary.

So are these really alternatives to `venv`?

Not really.

Most of these systems still rely on virtual environments in one form or another. The biggest shift is not abandoning venv, but changing how developers think about Python projects.

Traditional venv workflows treat virtual environments as standalone entities that developers explicitly create, activate and attach to projects. Modern tooling flips that model around: the project becomes the primary unit and the environment is automatically associated with it, so instead of thinking “I need to activate this environment.”, developers think “I’m working on this project.” while the tooling quietly ensures that the correct interpreter and dependencies are available behind the scenes.

C++ AI-generated code that looks fast, but is actually slow

piko::tutorial — Mon, 31 Aug 2026 05:00:00 +0000

In this article we will cover the following cases:

std::end vs \n
branchless logic
preferring function objects over templates

`std::endl` vs `\n`

One of the most common examples of AI-generated C++ code that looks modern and professional, but is actually terrible for performance, is the overuse of std::endl. Large language models generate it constantly because it appears in countless tutorials, Stack Overflow answers, textbooks and introductory examples. It also looks more “explicit” and “system-level” than simply writing \n, which aligns with the kind of code patterns AI tends to associate with high-performance C++.

The problem is that std::endl does not only insert a newline character - it also flushes the stream buffer every time it is called. In practice this means that instead of accumulating output in memory and writing it in large efficient chunks, the program repeatedly forces the operating system to perform tiny writes. Those writes are expensive because they involve syscalls. Modern systems are optimized for throughput via buffering and std::endl completely defeats that optimization.

The performance difference can be enormous. Look at the following code which compares writing one million lines to file using std::endl versus using '\n':

#include <chrono>
#include <iostream>
#include <fstream>

constexpr unsigned int kNumberOfWrites {1000000U};

int main() {
    std::chrono::milliseconds std_endl_duration;
    std::chrono::milliseconds backslash_n_duration;

    {
        std::ofstream file("endl.txt");
        const auto start = std::chrono::high_resolution_clock::now();

        for (unsigned int i=0U; i<kNumberOfWrites; i++) {
            file << i << std::endl;
        }

        const auto end = std::chrono::high_resolution_clock::now();
        std_endl_duration = std::chrono::duration_cast<std::chrono::milliseconds>(end - start);
    }

    {
        std::ofstream file("newline.txt");

        const auto start = std::chrono::high_resolution_clock::now();

        for (unsigned int i=0U; i<kNumberOfWrites; i++) {
            file << i << '\n';
        }

        const auto end = std::chrono::high_resolution_clock::now();
        backslash_n_duration = std::chrono::duration_cast<std::chrono::milliseconds>(end - start);

    }

    std::cout << "endl: " << std_endl_duration.count() << " ms" << std::endl;
    std::cout << "\\n: " << backslash_n_duration.count() << " ms" << std::endl;
}

On my machine the result is:

std::endl: 1387 ms
\n: 47 ms

This is nearly a 30× slowdown caused entirely by unnecessary flushing.

Why I chose to write to file in this example instead of just writing to terminal? If the benchmark used std::cout, the difference would be much smaller and sometimes almost invisible. The reason is that terminals are already extremely slow and often line-buffered by default, meaning that writing '\n' may trigger a flush anyway. In that case the benchmark would mostly measure the terminal rendering speed rather than flushing overhead. Files are fully buffered by the OS, which exposes the real cost of std::endl.

Does this mean you should stop using std::endl in favor of \n? The answer is: no. In many programs the performance difference simply does not matter. If your application prints a few status messages, logs occasional errors or saves some data to file from time to time, using std::endl is completely fine and can even be desirable because the explicit flush guarantees that the output appears immediately.

AI is powerful. Snippets are instant.

Stop prompting for the same patterns repeatedly. Get almost 100 free VS Code snippets for C++, Python, CMake and Bazel from piko::snippets GitHub repository.

Branchless logic

Another excellent example of AI-generated C++ code that looks highly optimized but performs terribly in practice is unnecessary branchless programming. Large language models seem to be sometimes biased towards generating branchless code, most likely because “branchless” often appears in discussions about performance optimization, SIMD and CPU pipeline efficiency. Branches, on the other hand, are often described as expensive due to branch prediction misses. As a result, from time to time an ordinary conditional logic is being generated as an arithmetic expressions such as:

sum += condition * expensive();

instead of simply writing:

if (condition) {
    sum += expensive();
}

The problem is that this optimization completely ignores what is actually worth to skip - it suggests skipping if and leaves expensive() call being executed on every single iteration, even when the condition is false. Take a look at the following code:

#include <chrono>
#include <cmath>
#include <iostream>

constexpr unsigned int kNumberOfIterations {1000000U};

double expensive()
{
    double x {};

    for (unsigned int i=0U; i<100U; i++) {
        x += std::sqrt(i);
    }

    return x;
}

int main() {
    std::chrono::milliseconds branchless_duration;
    std::chrono::milliseconds branch_duration;

    {
        const auto start = std::chrono::high_resolution_clock::now();
        double sum {};

        for (unsigned int i=0U; i<kNumberOfIterations; i++) {
            const bool condition = ((i % 100) == 0);
            sum += static_cast<int>(condition) * expensive();
        }

        const auto end = std::chrono::high_resolution_clock::now();
        branchless_duration = std::chrono::duration_cast<std::chrono::milliseconds>(end - start);
    }

    {
        const auto start = std::chrono::high_resolution_clock::now();
        double sum {};

        for (unsigned int i=0U; i<kNumberOfIterations; i++) {
            if ((i % 100) == 0) {
                sum += expensive();
            }
        }

        const auto end = std::chrono::high_resolution_clock::now();
        branch_duration = std::chrono::duration_cast<std::chrono::milliseconds>(end - start);
    }

    std::cout << "Branchless: " << branchless_duration.count() << "ms" << std::endl;
    std::cout << "Branch: " << branch_duration.count() << "ms" << std::endl;
}

The result on my machine is:

Branchless: 406ms
Branch: 5ms

Here, it is clearily visible that the branchless version simply does 100 times more work (i.e. 100 more expensive() calls) than the branched version.

Does this mean branchless programming should never be used? Of course: no. Branchless techniques can be extremely effective when the condition itself is unpredictable (e.g. based on random data) and both execution paths are cheap. In those situations, branch mispredictions can dominate the execution time.

Preferring function objects over templates

The next common pattern in AI-generated C++ code is overusing std::function in places where templates would be significantly faster. I think this happens because large language models strongly associate std::function with “modern” and “clean” C++ design.

Consider the following code:

#include <chrono>
#include <functional>
#include <iostream>

constexpr unsigned int kNumberOfIterations {1000000U};

int square(const int x)
{
    return x * x;
}

int run_std_function(const std::function<int(int)>& callback)
{
    int sum {};

    for (unsigned int i=0U; i<kNumberOfIterations; i++) {
        sum += callback(i);
    }

    return sum;
}

template<typename CallbackType>
int run_template(CallbackType callback)
{
    int sum {};

    for (unsigned int i=0U; i<kNumberOfIterations; i++) {
        sum += callback(i);
    }

    return sum;
}

int main()
{
    std::chrono::milliseconds std_function_duration;
    std::chrono::milliseconds template_duration;

    {
        const auto start = std::chrono::high_resolution_clock::now();
        std::ignore = run_std_function(std::function<int(int)>(square));
        const auto end = std::chrono::high_resolution_clock::now();

        std_function_duration = std::chrono::duration_cast<std::chrono::milliseconds>(end - start);
    }

    {
        const auto start = std::chrono::high_resolution_clock::now();
        std::ignore = run_template(square);
        const auto end = std::chrono::high_resolution_clock::now();

        template_duration = std::chrono::duration_cast<std::chrono::milliseconds>(end - start);
    }

    std::cout << "std::function: " << std_function_duration.count() << "ms" << std::endl;
    std::cout << "template: " << template_duration.count() << "ms" << std::endl;
}

The result on my machine is:

std::function: 32ms
template: 1ms

This is a dramatic difference especially that unlike in the earlier branchless-vs-branch example, where one version actually performed more computation, here both versions execute exactly the same logical work.

The reason comes from how std::function is implemented internally. std::function uses type erasure, meaning that the concrete callable type is hidden behind a generic runtime mechanism. Take a look at the following code:

struct Functor {
    int operator()(int x) const { return x + 1; }
};

int main()
{
    auto lambda = [](int x) { return x + 1; };
    Functor functor;

    auto lambda_obj = std::function<int(int)>(lambda);
    auto functor_obj = std::function<int(int)>(functor);

    std::cout << lambda_obj(11) << std::endl;
    std::cout << functor_obj(11) << std::endl;
}

lambda and functor are completely different compile-time types and yet std::function can store both of them, but unfortuantely the mechanism allowing to do that (i.e. type erasure) comes with a runtime cost.

The template version is completely different. Since the callback type is known at compile time, the compiler can generate proper implementation and thus it comes with no runtime cost.

This example is particularly interesting because the slower version genuinely looks more advanced. In many discussions on the Internet a lot of people (and thus AI systems now) for years tended to prefer abstractions that appear architecturally elegant:

generic wrappers
runtime polymorphism
decoupled interfaces
reusable callback systems

And all this is often fine, but not when performance is critical.

Does this mean that you should never use std::function? Again: no. In many applications its overhead is completely negligible compared to the flexibility it provides. std::function becomes particularly useful when callables need to be stored, passed around dynamically or treated uniformly at runtime - something templates fundamentally cannot do on their own because every template instantiation has a different concrete type.

A very common example of such situation is storing multiple callbacks inside a container. The std::vector of std::function is often the way to go because you can throw in a lambda, a functor, a function pointer etc. and as long as their signatures match the std::function template type, everything will work.

10 VS Code snippets essential for every Python developer

piko::tutorial — Mon, 24 Aug 2026 05:00:00 +0000

Why use snippets in the era of AI agents?

Modern AI tools can generate Python code at an impressive speed. Scaffolding APIs, generating test suites, building CLI tools or spinning up entire modules - a well-written prompt can produce all of them in seconds or minutes. At first glance, that makes VS Code snippets feel almost obsolete.

In practice, they solve a completely different problem.

Most experienced Python developers spend a large part of their day handling small, repetitive implementation tasks. Things like setting up a logger, creating a dataclass, writing a context manager, adding a typed function definition or scaffolding a test case are not difficult problems. They are familiar patterns. Opening an AI assistant for every one of those tasks quickly becomes inefficient.

The issue is not generation speed. The issue is interruption.

Using AI for tiny recurring tasks often forces you out of your editor and into a mini feedback loop: describe the problem, wait for the response, inspect the code, adjust formatting and align everything with your project standards, maybe re-prompt to iterate on the solution provided by AI. Even when this process only takes a few minutes, it repeatedly breaks concentration throughout the day.

That loss of focus adds up.

Snippets keep you inside the editor and inside the problem you are solving. Instead of starting a conversation with an AI assistant, you trigger a pattern you already know you need. AI tools are extremely useful when you need:

experimentation
architecture ideas
quick prototypes
first drafts

Snippets shine when you need:

speed
consistency
repeatable structures
uninterrupted flow

The biggest advantage of snippets is predictability. They do exactly what you expect every single time - no need for reviewing generated output for subtle or inconsistencies. Just trigger, expand and continue coding.

In this article, I’ll show you 10 VS Code snippets that can noticeably improve the daily workflow of almost every Python developer. You can download all of them for free from my GitHub repository.

Constructor with the given number of inputs and checks for their types

Snippet is called dconc3 (abbreviation for: Define CONstructor with 3 arguments and Check types) and allows you to create a full class constructor definition which before assigning the variables to the class private members (called in the same fashion as the constructor input arguments), checks if their actual types match the type annotations.

Match with the given number of cases

Snippet is called pma2 (abbreviation for: Python MAtch with 2 cases) and allows you to generate a match statement with 2 cases and the default.

If/else condition

Snippet is called pife (abbreviation for: Python IF Else) and allows to ti insert standard if/else statement in which the cursor jumps: condition ---- if body ---- else body.

Iterate over dictionary items

Snippet is called pford (abbreviation for: Python FOR item in Dictionary) and allows you to generate a for loop over dictionary items with the predefined variables names (which you can change while jumping over them).

Enumerate over elements

Snippet is called pforen (abbreviation for: Python FOR ENumerate) and allows you to create a for loop which enumerates the items in the give container.

New logger creation

Snippet is called lognew (abbreviation for: LOGging create NEW logger) and allows you to insert a new logger instance together with its context name.

New dataclass definition

Snippet is called ddc (abbreviation for: Define Data*C*lass) and allows you to generate a new dataclass together with its mandatory import.

From ... import ...

Snippet is called fim (abbreviation for: From x IMport y) and allows you to import any type from the given standard or custom path.

Conditional dictionary comprehension

Snippet is called pdci (abbreviation for: Python Dictionary Comprehension If) and allows you to create a conditional dictionary comprehension.

Check if is instance

Snippet is called pifii (abbreviation for: Python IF Is InStance) and lets you insert an if statement checking for the object's type using isinstance.

Bug of the week #13

piko::tutorial — Mon, 10 Aug 2026 05:00:00 +0000

Let’s look at this C++ program:

#include <iostream>

int main() {
    int x;

    if (x == 0) {
        std::cout << "Zero";
    }
    else {
        std::cout << "Not zero";
    }
}

When you build it in Debug and in Release mode, then:

Debug build prints Not zero
Release build prints Zero

Same code. Same compiler. Different result.

What does it mean?

The bug comes from the undefined behavior of the uninitialized variable x:

int x;

x is declared, but never initialized and immediately used:

if (x == 0)

At this point, the program is reading a variable that has no defined value at all.

Why it happens

Stack memory

When you write:

int x;

on the stack, no initialization happens. The memory might contain:

leftover values from previous function calls
debug patterns inserted by the runtime
basically anything

So x is effectively "whatever bits happened to be in that memory slot”.

Debug vs Release changes memory behavior

This is where things get interesting. Debug runtimes often:

fill stack memory with known patterns (e.g. 0xCC, 0xCD)
keep extra safety checks
avoid aggressive register optimization

So x is very likely to contain a non-zero pattern, but in Release mode:

stack memory is not initialized
registers are heavily optimized
memory reuse is aggressive

So sometimesx happens to be 0, but sometimes it gets optimized into a register that defaults to zero in that execution path The C++ standard does not say that x is garbage or random or zero. It says that reading an uninitialized variable is undefined behavior what means:

compiler is allowed to assume it never happens
optimizations may remove or rewrite logic
results can differ between builds, machines or even runs

How to fix it?

The simplest fix may be limited to just adding curly braces {} after x - it will zero-initialize it, so that it has a known value (equal to 0) in both types of builds:

#include <iostream>

int main() {
    int x {};

    if (x == 0) {
        std::cout << "Zero";
    }
    else {
        std::cout << "Not zero";
    }
}

Now behavior is fully defined and consistent. I also encourage to enable compiler warnings to catch all such places:

-Wall -Wextra -Wuninitialized -Werror

git log tricks you really should know

piko::tutorial — Mon, 03 Aug 2026 05:00:00 +0000

git log is one of the most powerful and yet most underused inspection tools in Git. While many developers use it only to view basic commit history, it can be turned into a highly flexible data-extraction and data-generation tool. With the right flags and formatting options, git log becomes not just a history viewer, but an element of data pipeline for debugging, analytics and automation.

Below are several advanced usage patterns that go well beyond the default experience.

Structured output with `--pretty=format:`

One of the most powerful features is using --pretty=format: to control exactly how commit data is printed. This is especially useful when you want to process git log output further with some scripts. Instead of nice-looking and human-readable logs, you can output records that are easy to parse:

git log --pretty=format:"%H|%an|%ad|%s" --date=iso

This produces pipe-separated fields:

%H - full commit hash
%an - author name
%ad - author date
%s - commit subject
--date=iso - converts dates from Fri May 22 16:08:53 2025 to 2025-05-22 16:08:53 +0200

Now, you can easily parse it with scripts like:

import subprocess

output = subprocess.check_output([
    "git", "log",
    "--pretty=format:%H|%an|%ad|%s",
    "--date=iso"
]).decode()

for line in output.splitlines():
    commit_hash, author, date, message = line.split("|", 3)

Time-based and path-based history analysis

git log becomes significantly more powerful when you treat history like a queryable dataset:

git log --since="2025-01-01" --until="2025-12-31"

You can also use relative times:

git log --since="2 weeks ago"

Or narrow it down to a single file to inspect how that file evolved:

git log --since="2 weeks ago" -- path/to/file

A useful flag here may be also the --follow flag which tracks renames. If your boundaries are not dates, but certain hashes, you can use them as well:

git log hashA..hashB

What can be of course combined with other flags:

git log hashA..hashB --oneline -- path/to/file

Exporting logs to specific file formats

A less obvious, but powerful use case is treating git log as an export mechanism capable of handling multiple file formats. For example, you can format the git log output as if was a JSON file element and then with jq you can combine it into a valid JSON file:

git log --pretty=format:'{"hash":"%H","author":"%an","date":"%ad","msg":"%s"}' -20 | jq -s '.' > history.json

I used jq -s here to read multiple JSON objects and wrap them into a list, so I end up with a list of dictionaries where each dictionary represents a single commit properties.

AI is powerful. Snippets are instant.

Stop prompting for the same patterns repeatedly. Get almost 100 free VS Code snippets for C++, Python, CMake and Bazel from piko::snippets GitHub repository.

Visualizing history as a graph

git log --graph --oneline --decorate --all

This shows:

branching structure (--graph)
compact commits (--oneline)
branch/tag labels (--decorate)
all references (--all)

Extracting commit statistics for analytics

Another advanced pattern is using git log to compute repository-level insights. For example, if you need to map the author to the number of commits, call:

git log --pretty=format:"%an" | sort | uniq -c | sort -nr

The output can always be limited by providing the amount of past commits that are supposed to be analyzed:

git log --pretty=format:"%an" -20 | sort | uniq -c | sort -nr

Final combo

Let's now construct a final combo command which:

extracts assymetricaly changes between hashA and hashB
filters out changes older than 2 weeks
keeps easily-parsable date formats
formats commit properties into a JSON objects
builds a valid JSON list of dictionaries
saves it into a JSON file

git log hashA..hashB --since="2 weeks ago" --date=iso --pretty=format:'{"hash":"%H","author":"%an","date":"%ad","msg":"%s"}' | jq -s '.' > history.json

Surprisingly necessary explanation of Python venv

piko::tutorial — Mon, 27 Jul 2026 05:00:00 +0000

There is a strange phenomenon in the Python world. People train neural networks, automate infrastructure, write complex tools and maintain applications for years while still having very little understanding of Python virtual environments.

I'm not entirely sure why this happens. Maybe it's because Python has such a low barrier to entry that beginners skip this topic just to get their first script running and then never come back to it as they progress further, focusing on Python syntax and programming skills instead.

At later stages of learning, this leads people to ask questions like:

"How do I back up all dependencies of my Python project?"
"How do I run pip install on a machine without internet access?"
"How do I know which dependencies my application actually uses?"

All of these problems can be solved using basic virtual environment features, but many developers never develop that intuition.

What venv is NOT

A Python virtual environment is not:

a container - because it will not isolate your python process from the rest of the system
a virtual machine - because it will not emulate computer components
a true sandbox - because it will still be able to access the filesystem, network requests etc. (although some people can argue that Python-level isolation is enough to call it a sandbox for the Python software development use case)

A venv is simply a directory where your project-specific interpreter's configuration and project-specific dependencies live. Such an approach gives Python developers many useful features.

Dependency isolation (the one everybody usually knows)

Let’s start with the obvious one. Different projects require different dependencies. Sometimes the same dependencies, but in different versions. Installing everything globally in the system quickly creates chaos because some projects may start working after the dependency update and the others stop working due to the same reason.

Virtual environments solve this by giving each project its own package space:

project_a/.venv
project_b/.venv

Each environment contains independent:

installed packages
dependency versions
console scripts
package metadata

This shifts the problem from "works on my machine" to "works with this venv" which limits debugging only to the content of the used virtual environment.

No need to explicitly activate/deactivate the environment

When you run:

source .venv/bin/activate

the script mainly modifies your shell’s PATH variable so that .venv/bin appears before system directories. As a result, commands like python now resolve to executables inside the virtual environment.

Such activation is optional and when creating automations or running scripts remotely, it is actually a good idea to explicitly run the interpreter directly:

./.venv/bin/python script.py

or:

./.venv/bin/python -m pip install requests

AI is powerful. Snippets are instant.

Stop prompting for the same patterns repeatedly. Get almost 100 free VS Code snippets for C++, Python, CMake and Bazel from piko::snippets GitHub repository.

Build env on one machine and run on another

This is where things start becoming genuinely interesting. You may have already encountered the following setup:

Machine A:

you have full permissions
you can install packages with pip
has internet access

Machine B:

locked-down server
restricted permissions
no internet access

Many people assume this means that their Python tooling cannot be used on Machine B because how would they ensure proper dependencies. The answer is that you can build your dependencies as .whl packages, transfer them via internal network and install them offline on the server side. Let's say you need empy for your application to work. On machine A create the virtual environment:

python3 -m venv machine_a

And then install empty with pip:

./machine_a/bin/python -m pip install empy

After it's done, display the installed packages to make sure it's there:

./machine_a/bin/python -m pip freeze
empy==4.2.1

Now, build a wheel package:

/machine_a/bin/python -m pip wheel empy==4.2.1 -w deps

This creates a deps folder with a empy-4.2.1-py3-none-any.whl file inside. Transfer that folder to the machine B and then create there a new virtual environment:

python3 -m venv machine_b

You can now install the dependency fully offline out of the transferred .whl file:

./machine_b/bin/python -m pip install deps/empy-4.2.1-py3-none-any.whl

App delivery as a packaged virtual environment

Let's restrict the environment of the machine B from the previous paragraph even more and let's say that you can't even install dependencies with pip out of .whl packages. What can you do? You can transfer entire virtual environment folder from machine A to the machine B and run your script there.

The venv package will provide everything that your scripts need (of course, as long as both machines are sufficiently compatible - they share OS family, architecture etc.).

A dependency backup

Virtual environment folder captures your dependencies and their versions, so whenever you need to know what dependencies you actually use and in what versions, you can simply run:

./venv/bin/python -m pip freeze

If you save the output to the file (usually called requirements.txt) you can always re-create your venv by invoking:

./venv/bin/python -m pip install -r requirements.txt

It means that you can just copy your current venv folder, tweak versions of some dependencies, check if your app still works and if yes - start using these new versions. If no, you simply delete the new venv folder and use the old one.

When AI gets C++ bitmask enums almost right

piko::tutorial — Mon, 20 Jul 2026 05:00:00 +0000

Today I want to take a look at a piece of C++ code that Copilot generated for me recently. The code here will not be 1:1 the same because originally it was inserted as a part of the bigger code base - I changed the names and simplified it to focus on the key topic, but the overall idea is exactly the same.

At first glance, the generated code looked perfectly reasonable. In fact, it even compiled. The problem is that it also contained a subtle semantic trap that is very easy to miss if you don't stop and think carefully about what the code is actually meant to do.

The code started with an enum representing permissions where the values are bitmasks:

enum class Permission
{
    kNone = 0,
    kRead = 1 << 0,
    kWrite = 1 << 1,
    kExecute = 1 << 2
};

And then Copilot generated an associated stream operator to print the enum value using std::cout:

std::ostream& operator<<(std::ostream& os, const Permission p)
{
    switch (p) {
        case Permission::kNone:
            return os << "None";
        case Permission::kRead:
            return os << "Read";
        case Permission::kWrite:
            return os << "Write";
        case Permission::kExecute:
            return os << "Execute";
        default:
            return os << "UNKNOWN PERMISSION";
    }
}

So far, everything still looks fine. The next step overloads the bit or operator for the Permission enum:

Permission operator|(const Permission lhs, const Permission rhs)
{
    return static_cast<Permission>(static_cast<int>(lhs) | static_cast<int>(rhs));
}

Nothing immediately suspicious here either, but the things start to look interesting because Copilot generated also a function that, according to some complex logic, returns combinations of permissions in form of:

Permission GetPermissions()
{
    return Permission::A | Permission::B;
}

This is where things start getting tricky. The code is not obviously wrong because representing flags as bitmasks is a completely valid technique, but let's test this with a simple example:

Permission GetPermissions()
{
    return Permission::kNone | Permission::kWrite;
}

int main()
{
    const Permission p = GetPermissions();
    std::cout << "Current permissions: " << p;
}

This works perfectly fine because:

00000000 | 00000010 = 00000010

And 00000010 corresponds exactly to Permission::kWrite, so the output becomes:

Current permissions: Write

However, when the function reaches a path like this:

Permission GetPermissions()
{
    return Permission::kRead | Permission::kWrite;
}

the output suddenly changes to:

Current permissions: UNKNOWN PERMISSION

How is this possible that although all enum values of the Permission enum are covered in switch/case statement, after getting the object p of type Permission and printing it, no valid value of the enum is displayed?

The answer is: the value returned from GetPermissions() is simply not represented by any enum field. Take a look:

Permission::kRead  = 00000001
Permission::kWrite = 00000010

Their bitwise or produces:

00000011

But there is no enum field equal to 00000011 and C++ does not forbid such value from existing inside an enum object.

The key problem

This reveals a deeper conceptual conflict:

enums are designed to represent one value from a closed set
bitmasks are designed to represent combinations of values

These are fundamentally different concepts and without writing a logic which actually enforces the rules of how these 2 contradicting worlds co-exist, we end up with a subtle bug hidden behind a clean API. Of course, the solution is not to keep extending the enum with values like:

kReadWrite
kWriteExecute
kReadExecute

because this does not scale. With more flags, the number of combinations grows exponentially. Let's look at how to fix the issue properly.

AI is powerful. Snippets are instant.

Stop prompting for the same patterns repeatedly. Get almost 100 free VS Code snippets for C++, Python, CMake and Bazel from piko::snippets GitHub repository.

Don't lie with the function signature

Using enums to represent individual bitmask values is perfectly fine. It improves the usage and the readability because you no longer need to remember whether "read" permission is equal to 1, 2, or 16. But the moment you start combining those values, the result is no longer guaranteed to be a valid Permission enum value, so the API should reflect that reality.

The first step is changing the overloaded | operator - instead of pretending that the result is still a Permission, return an integer mask explicitly:

int operator|(const Permission lhs, const Permission rhs)
{
    return static_cast<int>(lhs) | static_cast<int>(rhs);
}

Now the operator no longer falsely suggests that combining two permissions produces another valid enum field. Similarly, any function returning combined permissions should return an integer mask instead of Permission:

int GetPermissions()
{
    return Permission::kRead | Permission::kWrite;
}

int main()
{
    const int p = GetPermissions();
    std::cout << "Current permissions: " << p;
}

This now produces:

Current permissions: 3

The value is no longer pretending to be a single enum value. It is simply a bitmask containing multiple flags what is clearily communicated by the API now. If you want, you can print it in a nicer form by using a helper function - here is an example of a simple one:

void PrintPermissions(const int p)
{
    if (p & static_cast<int>(Permission::kRead)) {
        std::cout << "Read";
    }

    if (p & static_cast<int>(Permission::kWrite)) {
        std::cout << "Write";
    }

    if (p & static_cast<int>(Permission::kExecute)) {
        std::cout << "Execute";
    }

    std::cout << std::endl;
}

Now the output becomes:

Current permissions: ReadWrite

10 VS Code snippets essential for every C++ engineer

piko::tutorial — Mon, 13 Jul 2026 05:00:00 +0000

Why use snippets in the era of AI agents?

AI can generate code faster than ever. A single prompt can produce entire classes, build files or test suites in minutes, so it’s fair to ask: why would any engineer still care about VS Code snippets? Because generating code is not the same thing as maintaining flow.

Assuming that you're not a vibe coder, you know that many repetitive engineering tasks are not difficult enough to justify opening an AI chat, writing a prompt, waiting for output, reviewing the result and adjusting it to match your project conventions. Ironically, for small but frequent tasks, AI often introduces the exact thing engineers try to avoid most: context switching.

And context switching is expensive.

Every time you stop coding to ask an AI assistant how to write a constructor, scaffold a test, remember a target_link_libraries signature or recreate a logging macro, you temporarily break concentration. Individually, these interruptions feel insignificant, but across an entire day, they quietly fragment momentum and slow down deep technical work.

Snippets solve a different problem than AI. AI is excellent for exploration:

learning unfamiliar concepts
making PoCs
generating drafts
explaining APIs

Snippets excel at execution:

known patterns
repeated workflows
reliability
muscle-memory

A good snippet system removes friction without requiring a conversation. No prompting and no waiting for the code that may or may not match your expectations. You type a few characters, press Tab and continue thinking. That immediacy matters more than ever.

This article covers 10 VS Code snippets that I consider essential for every C++ developer. You can download all of them for free from my GitHub repository.

Including path copied to the clipboard

Snippet is called incb (abbreviation for: INclude Clip*B*oard) and lets you insert the include directive with whatever you have currently copied to the clipboard. If you work in Bazel environment and all your include paths are relative to the project root, then you can just click RMB on a file, choose "Copy relative path" and type incb.

Declaring new interface class

Snippet is called dif2 (abbreviation for: Declare Inter*Face with **2* method) and lets you declare a new interface class with the number of pure virtual methods specified by the trailing number (in this case 2).

If/else

Snippet is called cife (abbreviation for: C++ IF Else) and lets you insert one of the most frequently typed blocks of code.

Switch-case statements

Snippet is called cswi2 (abbreviation for: C++ SWItch with 2 cases) and lets you insert a ready-to-use skeleton of switch-case statement with the number of cases specified by the trailing number (in this case 2).

Index-based for loops

Snippet is called cfori (abbreviation for: C++ FOR Indexed) and provides a full skeleton of a for loop and the most common default values.

Range-based for loops

Snippet is called cfore (abbreviation for: C++ FOR Element) and lets you insert almost entire range-based for loop in its most common form.

Unique pointer as a class member

Snippet is called suptrm (abbreviation for: Std Unique Poin*TeR* class Member) and utilizes the fact that many C++ projects require naming convention that adds an underscore at the end of every private class member.

Move variable copied to clipboard

Snippet is called somocb (abbreviation for: Std Operation MOve from Clip*B*oard). I often find myself in the situation in which I have a variable which I suddenly realize that needs to be moved. There are basically 2 options in such situation:

Write std::move( in front of the variable, jump to the end of the variable's name and add )
Select the variable, press Ctrl + X, write std::move() and press Ctrl + V to insert the variable between the parenthesis.

This snippet lets you make it even faster by pressing Ctrl + X and writing somocb which will insert std::move together with the name of the copied variable.

Initialize class member on the constructor's list

Snippet is called defi (abbreviation for: DEFine Initialization of class member) and lets you initialize the class member with a constructor input arguement of the same name (except the underscore in the class member name).

Check if container is empty

Snippet is called scem (abbreviation for: Standard Container EMpty) and provides you with an .empty() call on the standard container.

Storing your ATTiny program in...EEPROM?

piko::tutorial — Mon, 06 Jul 2026 05:00:00 +0000

In this proof of concept, we will build a tiny interpreter for the ATtiny85 which executes instructions directly from EEPROM memory instead of FLASH. The goal is not to replace native firmware execution, but to experiment with compact instruction encoding and runtime programmability. Each instruction in this interpreter consists of only 2 bytes: one byte for the command ID and one byte for command arguments packed bit-by-bit.

Scope of this PoC

For this PoC, the interpreter supports three commands.

Set GPIO (0x01) - sets a digital output pin to high or low. The first 3 bits of the arguments byte specify the pin number and the remaining 5 bits define the state.
Delay (0x02) - a non-blocking delay instruction that pauses EEPROM program execution without freezing the MCU itself. The arguments byte contains the delay duration in units of 100 milliseconds.
Map ADC to PWM (0x03) - reads an ADC channel and maps its value proportionally to a PWM output. The arguments byte contains:
- first 3 bits - ADC source pin
- next 3 bits - PWM output pin
- next 1 bit - direct or reversed mapping
- last 1 bit - may be used for smoothing/averaging support in the future (now I skip it)
End of program (0xFF) - marks the end of the EEPROM program and allows the interpreter to loop forever over the program.

The resulting EEPROM “program” looks similar to a compact instruction stream rather than traditional firmware, but because every operation occupies exactly and only two bytes, programs become very dense and easy to parse.

Required dependencies

Before starting, install the AVR toolchain and required utilities:

sudo apt install \
    gcc-avr \
    avr-libc \
    binutils-avr \
    avrdude \
    cmake

The interpreter also requires several AVR-specific headers, definitions, state variables and helper structures:

#include <avr/eeprom.h>
#include <avr/interrupt.h>
#include <stdbool.h>

#define PIN_PB0 0
#define PIN_PB1 1
#define PIN_PB2 2
#define PIN_PB3 3
#define PIN_PB4 4

#define STATE_LOW 0
#define STATE_HIGH 1

#define DIRECT_MAPPING 0
#define REVERSED_MAPPING 1

#define CMD_SET_GPIO 0x01
#define CMD_DELAY 0x02
#define CMD_MAP_ADC_TO_PWM 0x03

#define PROGRAM_END_BYTE 0xFF

uint32_t last_timestamp = 0;
uint32_t delay_end_time = 0;
uint8_t instruction_pointer = 0;
bool delay_active = false;

bool pwm_1_enabled = false;
bool pwm_2_enabled = false;

static const uint8_t kPinToPortbMapping[] = {PB0, PB1, PB2, PB3, PB4};
static const uint8_t kPinToAdcChannelMapping[] = {0xFF, 0xFF, 1U, 3U, 2U};

typedef struct
{
    uint8_t command_id;
    uint8_t arguments;
} Instruction;

A few things are worth mentioning here:

Instruction represents a single EEPROM bytecode instruction.
instruction_pointer acts similarly to a program counter in a CPU.
last_timestamp provides a millisecond-style timing source.
delay_active and delay_end_time will be used for implementing non-blocking delays.
the pin mapping tables translate logical pins into AVR hardware-specific identifiers.

Writing EEPROM programs

Let's take a look at 2 example programs.

Example 1 - classic blink

Instruction EEMEM eeprom_program[] =
{
    {CMD_SET_GPIO, (PIN_PB0 << 5) | STATE_LOW},
    {CMD_DELAY, 10},
    {CMD_SET_GPIO, (PIN_PB0 << 5) | STATE_HIGH},
    {CMD_DELAY, 10},
    {PROGRAM_END_BYTE, PROGRAM_END_BYTE}
};

Example 2 - map 2 ADCs to 2 PWMs

Instruction EEMEM eeprom_program[] =
{
    {CMD_MAP_ADC_TO_PWM, (PIN_PB4 << 5) | (PIN_PB0 << 2) | (DIRECT_MAPPING << 1)},
    {CMD_MAP_ADC_TO_PWM, (PIN_PB3 << 5) | (PIN_PB1 << 2) | (REVERSED_MAPPING << 1)},
    {PROGRAM_END_BYTE, PROGRAM_END_BYTE}
};

How does it work?

The key part is that eeprom_program is not a normal RAM array. It is an EEPROM-resident variable because of the EEMEM attribute:

Instruction EEMEM eeprom_program[] =
{
    ...
};

EEMEM tells the AVR compiler and linker “Place this variable inside EEPROM memory instead of RAM or FLASH.”, so even though it looks like a normal array in C, it actually represents an EEPROM address.

Microcontroller setup

The interpreter requires timer interrupts, ADC initialization, GPIO helpers and PWM support. The following code sets up all required peripherals:

ISR(TIMER0_COMPA_vect)
{
    last_timestamp++;
}

void InitTimer0()
{
    TCCR0A = (1 << WGM01);
    OCR0A = 124;
    TCCR0B = (1 << CS01) | (1 << CS00);
    TIMSK |= (1 << OCIE0A);
}

void InitAdc(void)
{
    ADMUX = 0;
    ADCSRA = (1 << ADEN) | (1 << ADPS2) | (1 << ADPS1);
}

void InitPwm(uint8_t pin)
{
    DDRB |= (1 << pin);
    TCCR0A = (1 << WGM00) | (1 << WGM01);
    TCCR0B = (1 << CS00);

    if(pin == PIN_PB0 && !pwm_1_enabled) {
        TCCR0A |= (1 << COM0A1);
    }
    else if(pin == PIN_PB1 && !pwm_2_enabled) {
        TCCR0A |= (1 << COM0B1);
    }
}

void GpioWrite(uint8_t pin, uint8_t state)
{
    uint8_t hw = kPinToPortbMapping[pin];

    DDRB |= (1 << hw);

    if(state)
        PORTB |= (1 << hw);
    else
        PORTB &= ~(1 << hw);
}

uint8_t GpioRead(uint8_t pin)
{
    uint8_t hw = kPinToPortbMapping[pin];

    DDRB &= ~(1 << hw);

    return (PINB & (1 << hw)) ? 1 : 0;
}

uint16_t AdcRead(uint8_t pin)
{
    uint8_t adc_channel = kPinToAdcChannelMapping[pin];

    if(adc_channel == 0xFF) {
        return 0;
    }

    ADMUX = (ADMUX & 0xF0) | adc_channel;
    ADCSRA |= (1 << ADSC);

    while(ADCSRA & (1 << ADSC));

    return ADC;
}

void PwmWrite(uint8_t pin, uint8_t value)
{
    switch(pin) {
        case PIN_PB0:
            OCR0A = value;
            break;
        case PIN_PB1:
            OCR0B = value;
            break;
        default:
            break;
    }
}

Timer interrupt

The timer compare interrupt ISR(TIMER0_COMPA_vect) increments a global timestamp counter periodically. This provides a lightweight software clock used for delays.

Timer initialization

void InitTimer0() configures Timer0 into CTC mode and generates periodic compare-match interrupts. The prescaler and compare register values determine the interrupt frequency.

ADC initialization

void InitAdc(void) enables the ADC peripheral and configures the ADC clock prescaler.

PWM initialization

void InitPwm(uint8_t pin) configures Timer0 for fast PWM generation and enables the selected PWM output channel.

GPIO helpers

GpioWrite() configures a pin as output and writes HIGH or LOW. GpioRead() configures a pin as input and returns its digital state.

ADC reads

AdcRead() translates logical pins into ADC channels, starts a conversion and waits until conversion completes.

PWM output

PwmWrite() updates the PWM duty cycle register corresponding to the selected PWM output pin.

AI is powerful. Snippets are instant.

Stop prompting for the same patterns repeatedly. Get almost 100 free VS Code snippets for C++, Python, CMake and Bazel from piko::snippets GitHub repository.

Executing instructions from EEPROM

The core of the interpreter is the instruction execution routine:

void ExecuteInstruction(Instruction *instruction)
{
    if(instruction->command_id == 0xFF && instruction->arguments == 0xFF) {
        instruction_pointer = 0;
        return;
    }

    switch(instruction->command_id) {
        case CMD_SET_GPIO: {
            uint8_t pin = (instruction->arguments >> 5) & 0x07;
            uint8_t state = (instruction->arguments & 0x1F) ? 1 : 0;

            GpioWrite(pin, state);

            instruction_pointer++;
            break;
        }
        case CMD_DELAY: {
            uint32_t delay_ms = ((uint32_t)instruction->arguments) * 100UL;

            delay_active = true;
            delay_end_time = last_timestamp + delay_ms;

            instruction_pointer++;
            break;
        }
        case CMD_MAP_ADC_TO_PWM: {
            uint8_t adc_pin = (instruction->arguments >> 5) & 0x07;
            uint8_t pwm_pin = (instruction->arguments >> 2) & 0x07;
            bool reversed_mapping = (bool)((instruction->arguments >> 1) & 0x01);

            InitPwm(pwm_pin);

            uint16_t adc_value = AdcRead(adc_pin);
            uint8_t pwm_value = adc_value >> 2;

            if (reversed_mapping) {
                pwm_value = 255 - pwm_value;
            }

            PwmWrite(pwm_pin, pwm_value);

            instruction_pointer++;
            break;
        }

        default: {
            instruction_pointer++;
            break;
        }
    }
}

The first thing the interpreter checks is whether the instruction equals 0xFF 0xFF which acts as an end-of-program marker. When encountered, execution jumps back to the beginning by resetting the instruction pointer.

The GPIO instruction extracts:

the pin number from the upper 3 bits
the output state from the lower 5 bits

The delay instruction converts the argument byte into milliseconds by multiplying it by 100. The ADC-to-PWM instruction:

extracts ADC and PWM pins,
initializes PWM if not yet initialized,
reads ADC value,
converts the 10-bit ADC result into an 8-bit PWM value,
optionally reverses the mapping,
writes the final duty cycle.

Each executed instruction increments the instruction pointer so the next EEPROM instruction can be fetched.

Main execution loop

The main firmware loop is extremely small because most logic lives inside the ExecuteInstruction function:

int main()
{
    InitTimer0();
    InitAdc();

    sei();

    while(1) {
        if(delay_active) {
            delay_active = (last_timestamp < delay_end_time);
            continue;
        }

        Instruction instruction;

        eeprom_read_block(&instruction,
                          &eeprom_program[instruction_pointer],
                          sizeof(Instruction));

        ExecuteInstruction(&instruction);
    }
}

Peripheral initialization

InitTimer0();
InitAdc();

initializes the timer subsystem and ADC peripheral before execution begins.

Global interrupts

sei();

enables interrupts globally so Timer0 interrupts can start updating timestamps.

Delay handling

The interpreter checks whether a delay is currently active:

if(delay_active) {
    delay_active = (last_timestamp < delay_end_time);
    continue;
}

If the delay has not expired yet, the loop simply waits without advancing instruction execution.

EEPROM instruction fetch

eeprom_read_block(&instruction,
                  &eeprom_program[instruction_pointer],
                  sizeof(Instruction));

copies the next instruction from EEPROM into RAM:

&instruction - destination in RAM
&eeprom_program[instruction_pointer] - source address inside EEPROM
sizeof(Instruction) - number of bytes to copy

Instruction execution

Finally:

ExecuteInstruction(&instruction);

decodes and executes the fetched bytecode instruction.

Building and flashing with CMake

The project can be built entirely using CMake. The following CMakeLists.txt file configures compilation, HEX generation and flashing:

cmake_minimum_required(VERSION 3.15)

project(attiny85_eeprom_interpreter C)

set(MCU attiny85)
set(F_CPU 8000000UL)

set(CMAKE_C_COMPILER avr-gcc)
set(CMAKE_OBJCOPY avr-objcopy)
set(CMAKE_SIZE avr-size)
set(COMMON_FLAGS
    -mmcu=${MCU}
    -DF_CPU=${F_CPU}
    -Os
    -flto
    -fdata-sections
    -ffunction-sections
    -fno-tree-scev-cprop
    -fno-split-wide-types
    -mcall-prologues
    -Wall
)

add_executable(${PROJECT_NAME}.elf
    main.c
)

target_compile_options(${PROJECT_NAME}.elf PRIVATE
    ${COMMON_FLAGS}
)

target_link_options(${PROJECT_NAME}.elf PRIVATE
    -mmcu=${MCU}
    -Wl,--gc-sections
    -Wl,--relax
    -flto
)

add_custom_command(
    TARGET ${PROJECT_NAME}.elf POST_BUILD
    COMMAND ${CMAKE_OBJCOPY}
            -O ihex
            -R .eeprom
            ${PROJECT_NAME}.elf
            ${PROJECT_NAME}.hex

    COMMAND ${CMAKE_SIZE}
            --mcu=${MCU}
            --format=avr
            ${PROJECT_NAME}.elf
)

add_custom_target(flash
    COMMAND avrdude
        -c usbasp
        -p t85
        -U flash:w:${PROJECT_NAME}.hex:i
    DEPENDS ${PROJECT_NAME}.elf
)

add_custom_command(
    TARGET ${PROJECT_NAME}.elf POST_BUILD
    COMMAND ${CMAKE_OBJCOPY}
            -O ihex
            -j .eeprom
            --change-section-lma .eeprom=0
            ${PROJECT_NAME}.elf
            ${PROJECT_NAME}.eep
)

add_custom_target(flash_eeprom
    COMMAND avrdude
        -c usbasp
        -p t85
        -U eeprom:w:${PROJECT_NAME}.eep:i
    DEPENDS ${PROJECT_NAME}.elf
)

add_custom_target(fuses
    COMMAND avrdude
        -c usbasp
        -p t85
        -U lfuse:w:0xE2:m
)

Notice that the flash targets are created without ALL. This is intentional because we do not want the microcontroller to be reflashed every time we simply build the project.

Read also on Medium: How to write Arduino Uno code with Python?.

Set fuses

cmake --build . --target fuses

In this project we set the low fuse to 0xE2 because we want the ATtiny85 to run from its internal 8 MHz oscillator without the default clock divider enabled. By default, many AVR chips ship with the CKDIV8 fuse enabled, which divides the system clock by 8. Even though the internal oscillator runs at 8 MHz, the CPU would actually execute at 1MHz.

That would make all timing calculations incorrect and the behavior would appear 8 times slower. The 0xE2 fuse configuration disables this divider, so the MCU truly runs at the full 8 MHz specified by:

#define F_CPU 8000000UL

Build firmware

cmake --build .

Flash firmware

cmake --build . --target flash

Flashing EEPROM program

Now, after the FW is flashed, you can call:

cmake --build . --target flash_eeprom

while the MCU is running to replace the previous EEPROM program with the new one.

Why this approach is interesting

Although this interpreter is only a proof of concept, it demonstrates several interesting ideas.

The biggest advantage is instruction density. Every operation occupies exactly 2 bytes in EEPROM, which can sometimes be significantly smaller than equivalent compiled C code stored in FLASH memory. Instead of storing large AVR machine instructions, the MCU executes a compact custom bytecode format specifically optimized for the target application.

Other advantages:

runtime-replaceable logic without reflashing firmware,
deterministic instruction size,
extremely small interpreter core,
easy serialization and external generation of programs

This kind of architecture starts resembling a tiny virtual machine for AVR microcontrollers. While it will never match native compiled performance, it can be surprisingly efficient for automation, GPIO sequencing, LED control or sensor mapping tasks where compactness matters more than raw speed.

Bug of the week #12

piko::tutorial — Mon, 29 Jun 2026 05:00:00 +0000

The error we're handling today is a real-life example simplified to the following Python code:

# user inputs several numbers in form of strings (1, 2, 3 and 123)
# which are then used to construct 2 strings
s1 = "".join(["1", "2", "3"])
s2 = "123"

# if the numbers in the constructed strings are different,
# the program flow should stop
if s1 is not s2:
    raise RuntimeError("s1 is not s2!")

# program flow continues...

The variables s1 and s2 both end up being 123, but when we run this code, we see:

Traceback (most recent call last):
  File "/home/main.py", line 9, in <module>
    raise RuntimeError("s1 is not s2!")
RuntimeError: s1 is not s2!

What's even worse, in the other parts of the app, where s1 and s2 are constructed differently, there are the same comparisons:

s1 = "123"
s2 = "123"

if s1 is not s2:
    raise RuntimeError("s1 is not s2!")

# program flow continues...

But this time the exception is not thrown, so the same comparison seems to give different results for the same s1 and s2 strings.

What does it mean?

The issue comes from misunderstanding the difference between identity and equality in Python. The is operator does not check whether two variables contain the same value. It checks whether both variables point to the exact same object in memory.

== asks: “Do these objects have the same content?”
is asks: “Are these literally the same object?”

For example:

s1 = "123"
s2 = "123"

print(s1 == s2)   # True
print(s1 is s2)   # maybe True, maybe False

The first comparison checks the values of the strings, so it reliably returns True. The second comparison depends on Python’s internal memory optimizations. Sometimes Python “interns” strings, meaning it reuses the same object for performance reasons. In those cases, s1 is s2 may accidentally return True, but not always.

In this version:

s1 = "".join(["1", "2", "3"])
s2 = "123"

print(s1 == s2)   # True
print(s1 is s2)   # False

Both strings contain exactly the same text, but they were created differently, so Python stores them as separate objects. This makes is unreliable for value comparison.

How to fix it?

Use == whenever you want to compare values. Correct version:

s1 = "".join(["1", "2", "3"])
s2 = "123"

if s1 != s2:
    raise RuntimeError("s1 is not s2!")

Reserve is for cases where you truly want to check object identity. The most common use is comparing with None:

if value is None:
    print("No value provided")

Sharing variable between bash scripts

piko::tutorial — Mon, 22 Jun 2026 05:00:00 +0000

Sharing Variables

The simplest way to share variables between Bash scripts is to place them in a separate common script and source that script wherever the variables are needed.

# common.sh

#!/bin/bash

export SOME_VAR="Hello"

Then, in another script:

# user.sh

#!/bin/bash

source common.sh

echo "SOME_VAR = $SOME_VAR"

Using source executes the contents of common.sh in the current shell, making the exported variables available to the script.

Sharing Arrays

Arrays can be shared in the same way. Define the array in common.sh and source it from another script.

# common.sh

#!/bin/bash

declare -a SOME_ARRAY=("element1" "element2" "element3")

Then use it in another script:

#!/bin/bash

source common.sh

for element in "${SOME_ARRAY[@]}"
do
    echo "$element"
done

Reading Arrays from a File

In many cases, storing the data in a text file is more convenient than hardcoding it inside a script. You can read a single-line list into an array using read:

#!/bin/bash

read -a SOME_ARRAY < data.txt

for element in "${SOME_ARRAY[@]}"
do
    echo "$element"
done

This approach forces you however to store all elements in a single line like:

element1 element2 element3

For longer lists, where each element is stored on a separate line:

element1
element2
element3
...

it is better to use mapfile:

#!/bin/bash

mapfile -t SOME_ARRAY < data.txt

for element in "${SOME_ARRAY[@]}"
do
    echo "$element"
done

The -t option removes trailing newline characters, making the array elements cleaner to work with.

A 40-line LLM-based bash command executor in Python

piko::tutorial — Mon, 15 Jun 2026 05:00:00 +0000

One of the interesting use cases for local LLMs are the natural language interfaces for the terminal commands generation. Instead of memorizing command syntax, flags and shell quirks, you can simply describe what you want to do like:

Find all PNG files larger than 5 MB and move them to archive

An LLM not only translates that request into a real shell command, but also executes it.

In this article, I will build a minimal implementation of such a tool in Python - a lightweight command-line assistant called piko::ai. The entire Python code fits in less than 40 lines of code, yet it provides:

natural language to bash conversion
configurable LLM backends
structured JSON responses
dangerous command detection
and automatic command execution

The implementation uses a local LLM through Ollama, but the architecture is flexible enough to support almost any provider.

Why build a tool like this?

Shell commands are incredibly powerful, but for complex or chained/piped cases they are also difficult to remember and prone to human error. Even experienced developers regularly search for things like rarely used command switches.

Large language models are surprisingly good at translating intent into shell syntax, so the goal of this tool is to instead of thinking in commands, allow the user to think in actions. For example:

find all jpg files modified in the last 7 days and compress them into images.tar.gz

should generate:

find . -type f -name "*.jpg" -mtime -7 | tar -czf images.tar.gz -T -

For simple commands there is no justification for writing long sentences, but as soon as you start searching the internet or asking AI:

is it -mtime or -dtime?
was it -czf or -xvf for the archive creation?
should there be -T or --files-from or both are fine?

it may be acutally quicker to just type the request directly in the terminal and get the output for that request also directly in the terminal.

The architecture

The entire flow is extremely simple:

User types a natural language request.
Python inserts that request into a prompt template.
The prompt is sent to an LLM.
The LLM returns JSON containing a shell command.
Python checks whether the command is potentially dangerous.
If approved, the command is executed.

If you have never written stuff like that, you will be surprised how little code is actually required.

The Python implementation

For the TL;DR-readers, below is the complete implementation - if you want to test it out, you can clone the piko_ai GitHub repository. I go into details on what exactly does this code do in the paragraphs below:

import os
import sys
import requests
import json
import subprocess

MAIN_FILE_PATH: str = os.path.join(os.path.dirname(os.path.abspath(__file__)))
PIKO_AI_CONFIG_FILE_PATH: str = os.path.join(MAIN_FILE_PATH, "..", "config", "pai_config.json")
PIKO_AI_PROMPT_FILE_PATH: str = os.path.join(MAIN_FILE_PATH, "..", "config", "pai_prompt.txt")

with open(PIKO_AI_CONFIG_FILE_PATH) as file:
    config = json.load(file)
with open(PIKO_AI_PROMPT_FILE_PATH) as file:
    prompt_template: str = file.read()

user_request: str = " ".join(sys.argv[1:])
prompt: str = prompt_template.replace("@USER_REQUEST@", user_request)

request_payload: dict = config["llm_request"]
request_payload["prompt"] = prompt

response = requests.post(config["llm_provider_url"], json=request_payload, timeout=config["llm_request_timeout"])
response.raise_for_status()

command: str = json.loads(response.json()["response"])["command"]

print(f"$ {command}")

for dangerous_command in config["dangerous_commands"]:
    if dangerous_command in command:
        user_response: str = input(f"WARNING: dangerous command detected ({dangerous_command})! Are you sure you want to run it? (y/n)")

        if user_response == "y":
            break

        sys.exit(0)

subprocess.run(command, shell=True)

Let’s break it down piece by piece.

AI is powerful. Snippets are instant.

Stop prompting for the same patterns repeatedly. Get almost 100 free VS Code snippets for C++, Python, CMake and Bazel from piko::snippets GitHub repository.

Step 0: set up constants

import os          # for joining paths
import sys         # for command line arguments and exit
import requests    # for sending requests to LLM
import json        # for JSON parsing
import subprocess  # for executing generated commands

# path to this file which serves as the reference for further paths
MAIN_FILE_PATH: str = os.path.join(os.path.dirname(os.path.abspath(__file__)))
# path to configuration file
PIKO_AI_CONFIG_FILE_PATH: str = os.path.join(MAIN_FILE_PATH, "..", "config", "pai_config.json")
# path to file with the prompt template
PIKO_AI_PROMPT_FILE_PATH: str = os.path.join(MAIN_FILE_PATH, "..", "config", "pai_prompt.txt")

Step 1: loading configuration and prompt files

with open(PIKO_AI_CONFIG_FILE_PATH) as file:
    config = json.load(file)

with open(PIKO_AI_PROMPT_FILE_PATH) as file:
    prompt_template: str = file.read()

Even in the smallest tools, I always like to separate:

application logic
configuration
prompts

This separation makes the tool flexible enough to support:

Ollama
OpenAI-compatible APIs
local inference servers
cloud providers
completely custom backends

For this example however, I will only use local Ollama model.

Step 2: reading the user request

The CLI request is simply reconstructed from command-line arguments. For more complex command line interfaces argparse could come in handy, but in case of this tool, such one-liner is completely enough to concatenate the entire output into a single string, without forcing user to use "" around the request.

user_request: str = " ".join(sys.argv[1:])

So:

pai find all files larger than 55kB

becomes:

"find all files larger than 55kB"

That text is then injected into the prompt template and assigned to a proper field in the request_payload.

prompt: str = prompt_template.replace("@USER_REQUEST@", user_request)

request_payload: dict = config["llm_request"]
request_payload["prompt"] = prompt

Step 3: prompt engineering

The prompt template looks like this:

You are a shell command generator.
User requests from you a bash command in a human readable language and your job is to convert this request into a bash command that the user can immediately invoke.

Requirements:
- If not stated differently, always assume that the command must be executed in the current working directory (.)
- The command must be syntactically valid
- The command must be fully executable
- Prefer a single grep command over pipelines when possible
- Command must be usable out of the box, so don't provide any mock values, but e.g. when the user says "here", it means "."

User request:
@USER_REQUEST@

This prompt emphasizes several important aspects.

Establishing assumptions

This line:

always assume that the command must be executed in the current working directory

greatly improves usability of small models because users are expected to naturally say things like:

find here all markdown files

instead of:

find all markdown files in /home/user/Documents/applications/private_projects/docs”

Biasing command style

This instruction:

Prefer a single grep command over pipelines when possible

helps shape output quality. Small LLMs often overcomplicate shell commands and at the same time (because of their size), make mistakes in these overcomplicated commands. Prompt constraints can push them toward simpler solutions.

Preventing placeholders

Without instructions like:

don't provide any mock values

models often generate unusable outputs like:

grep -r "keyword" /path/to/directory

instead of:

grep -r "keyword" .

The prompt explicitly forces executable commands and not suggestions.

Read also on pikotutorial.com: How to write Arduino Uno code with Python?

Step 4: sending the request to the LLM

response = requests.post(
    config["llm_provider_url"],
    json=request_payload,
    timeout=config["llm_request_timeout"]
)

The configuration file defines the request payload and the output schema.

{
    "llm_request": {
        "model": "qwen2.5-coder:1.5b",
        "format": {
            "type": "object",
            "properties": {
                "command": {
                    "type": "string"
                }
            },
            "required": ["command"]
        },
        "prompt": "TO BE REPLACED BY THE ACTUAL PROMPT",
        "options": {
            "temperature": 0.1,
            "seed": 42
        },
        "stream": false
    },
    "llm_provider_url": "http://localhost:11434/api/generate",
    "model_name": "qwen2.5-coder:1.5b",
    "llm_request_timeout": 60,
}

Several details here are especially important.

Structured JSON output

This is one of the most important implementation details. Instead of asking the model for plain text, the tool requests structured JSON like the one below:

{
    "command": "grep -r \"TODO\" ."
}

Without structured output, models may generate additional explanations or markdown formatting. Structured generation constrains the model into machine-readable output.

Low temperature and a fixed seed

"temperature": 0.1,
"seed": 42

Command generation is not creative writing, so we want deterministic, predictable and reproducible outputs. Low temperature and a fixed seed reduce hallucinations and let the user learn the tool because with the repeatable input-output relation, even if the tool misbehaves for some requests formulations, but improves for others, it lets the user to consistently improve on the tool usage. With unpredictable and non-reproducible outputs, the user would never be able to tune the inputs for the expected outputs.

Why qwen2.5-coder:1.5B?

Such tool is supposed to be a reasonable alternative for just invoking the command or searching for the command and then invoking it. If processing of a request would take several minutes, any other form (googling, copying, asking AI chat bot etc.) would end up being faster than using this tool. I needed to select something small, so that it can run fast locally. Fortunately, our task is highly specialized, so even small code-focused models are capable of handling it.

Step 5: parsing the model response

command: str = json.loads(response.json()["response"])["command"]

The returned command is the bash command extracted from the generated JSON. Then the tool prints it:

print(f"$ {command}")

Users should always see exactly what will be executed.

Step 6: dangerous command detection

This may be actually the most important part of the implementation. The tool scans the generated command for operations defined as dangerous in the config file:

for dangerous_command in config["dangerous_commands"]:
    if dangerous_command in command:
        user_response: str = input(f"WARNING: dangerous command detected ({dangerous_command})! Are you sure you want to run it? (y/n)")

        if user_response == "y":
            break

        sys.exit(0)

After a dangerous operation is detected, the command execution requires explicit confirmation from the user side. Here, by "dangerous" I mean any command that performs any actual modification of the user data.

Warning: this implementation intentionally favors simplicity over perfect security. The current check is only substring matching, so it may overreact e.g. if you have a folder name containg "rm" letters next to each other.

Step 7: Executing the command

Finally:

subprocess.run(command, shell=True)

executes the generated shell command. This is where the it transforms from AI suggestion into actual tool because the generated command is not only displayed, but actually called.

Example usage

Command:

pai find all files larger than 1kB

Output:

$ find . -type f -size +1k
./main.py

Command:

pai list all .py files with find, but filter out findings from ./venv folder

Output:

$ find . -name '*.py' ! -path './venv/*'
./src/main.py

Command:

pai grep for all usages of MAIN_FILE_PATH

Output:

$ grep -r 'MAIN_FILE_PATH' .
./src/main.py:MAIN_FILE_PATH: str = os.path.join(os.path.dirname(os.path.abspath(__file__)))
./src/main.py:PIKO_AI_CONFIG_FILE_PATH: str = os.path.join(MAIN_FILE_PATH, "..", "config", "pai_config.json")
./src/main.py:PIKO_AI_PROMPT_FILE_PATH: str = os.path.join(MAIN_FILE_PATH, "..", "config", "pai_prompt.txt")
./scripts/install.sh:MAIN_FILE_PATH="$PIKO_AI_DIR/src/main.py"
./scripts/install.sh:ALIAS_LINE="alias pai='$VENV_DIR/bin/python3 $MAIN_FILE_PATH'"

DEV Community: piko::tutorial

If not Python venv, then what?

Option 1: uv

Option 2: Poetry

Option 3: PDM

Option 4: Containers instead of environments

So are these really alternatives to venv?

C++ AI-generated code that looks fast, but is actually slow

std::endl vs \n

Branchless logic

Preferring function objects over templates

10 VS Code snippets essential for every Python developer

Why use snippets in the era of AI agents?

Constructor with the given number of inputs and checks for their types

Match with the given number of cases

If/else condition

Iterate over dictionary items

Enumerate over elements

New logger creation

New dataclass definition

From ... import ...

Conditional dictionary comprehension

Check if is instance

Bug of the week #13

What does it mean?

Why it happens

Stack memory

Debug vs Release changes memory behavior

How to fix it?

git log tricks you really should know

Structured output with --pretty=format:

Time-based and path-based history analysis

Exporting logs to specific file formats

Visualizing history as a graph

Extracting commit statistics for analytics

Final combo

Surprisingly necessary explanation of Python venv

What venv is NOT

Dependency isolation (the one everybody usually knows)

No need to explicitly activate/deactivate the environment

Build env on one machine and run on another

App delivery as a packaged virtual environment

A dependency backup

When AI gets C++ bitmask enums almost right

The key problem

Don't lie with the function signature

10 VS Code snippets essential for every C++ engineer

Why use snippets in the era of AI agents?

Including path copied to the clipboard

Declaring new interface class

If/else

Switch-case statements

Index-based for loops

Range-based for loops

Unique pointer as a class member

Move variable copied to clipboard

Initialize class member on the constructor's list

Check if container is empty

Storing your ATTiny program in...EEPROM?

Scope of this PoC

Required dependencies

Writing EEPROM programs

Example 1 - classic blink

Example 2 - map 2 ADCs to 2 PWMs

How does it work?

Microcontroller setup

Timer interrupt

Timer initialization

ADC initialization

PWM initialization

GPIO helpers

ADC reads

PWM output

Executing instructions from EEPROM

Main execution loop

Peripheral initialization

Global interrupts

Delay handling

EEPROM instruction fetch

Instruction execution

So are these really alternatives to `venv`?

`std::endl` vs `\n`

Structured output with `--pretty=format:`