Forem: Kristof Bruyninckx

The enigma of Python Enums

Kristof Bruyninckx — Wed, 15 Oct 2025 21:05:38 +0000

The basics of Enums are explained pretty well here. My goal here is to go over some specific pitfalls and provide some insight into how things work under the hood, without diving into the nitty-gritty details of meta-classes.

Python Enums are not some special language construct, they are made using Python tools available to us, and provided as part of the standard library. In fact, you could create your own Enum if you wanted to. To do that, you'd use metaclasses, which you can also see in the standard library implementation. For now, the takeaway is that Enums don't require any special syntax unlike in some other languages (for example, in c++ you'd use the reserved keyword enum or enum class), whereas is python you create them just like a class.

How do Enums work

An Enum is meant to be some limited set of values known statically, before running your code. As previously said, there is no special syntax, You make an enum by inheriting from Enum. Taking an example from the how-to page:

class Weekday(Enum):
    MONDAY = 1
    TUESDAY = 2
    WEDNESDAY = 3
    THURSDAY = 4
    FRIDAY = 5
    SATURDAY = 6
    SUNDAY = 7

Because you inherit from Enum, the way this class is created is significantly altered. As a side note, this is what metaclasses are for, customizing how classes should work, much like how classes describe how objects should work.

Most importantly, a finite set of objects is created, one for each property defined on the class, It is made impossible ¹ to ever create any other objects of this class. Where in a regular class, you create an object by calling the class, this gives us a value based lookup for the enum above.

>>> Weekday(5)
<Weekday.FRIDAY: 5>

If we access the object by Weekday.FRIDAY we get the exact same object. Basically, no matter how we try to access it, only one object was ever created and that object is returned. Keeping this in mind, it makes more sense Enums are compared by identity using is, as opposed to ==.

💡 Compare enums by identity (using is or is not).

Enum values

There aren't a whole lot of enforced restrictions on the value given to an Enum, but it is important to keep a few things in mind. Mutables can be used but have some performance implications as some operations get less efficient, one of which is mentioned in the docs. In general, the Enum implementation relies on hashability to do certain things efficiently. With unhashable types, it falls back to a less efficient method. For example, A value based lookup such as in the previous section would take O(n) time, rather than a simple dict lookup.

With that in mind, and from my own experience of trying to do things that are too complex with Enums, I'd recommend sticking with either simple types (int, str) or frozen dataclasses as the value type for enums. You could use something like a tuple or named tuple as well, but i find frozen dataclasses to almost always be a better alternative (my other blog may provide more insight on this).

💡 Keep your enums simple, use builtin immutables like int or str, or basic frozen dataclasses.

Enum aliases

One interesting thing happens if you assign the same value for different Enums members:

class Test(Enum):
    FOO=1
    BAR=1

Rather than making two enum member objects, you'll get a single object and an alias that points to the same object. This can be shown by an identity comparison

>> Test.FOO is Test.BAR
True

This is covered well by the docs, but i'm bringing it up because it's particularly interesting to look at the combination of aliases and mutables. Looking at the following example:

class Test(Enum):
    FOO=[]
    BAR=[]

Since BAR is just an alias for FOO, you get:

>> Test.FOO.value.append(1)
>>> Test.BAR.value
[1]

This is one more reason to be mindful of using mutables in the context of enums.

💡 If you want to prevent aliases, use the unique decorator on your enum class.

A note on IntEnum, StrEnum and more

Enums are not just an alias to a raw value. Especially when using a type checker, they help in making sure you don't compare apples to oranges. This is because an Enum and its value are separate types, if you want the value of an enum, you use WeekDay.FRIDAY.value, but you have to be explicit. You can't just pass WeekDay.FRIDAY to a function that accepts integers. On the other hand, the standard library also offer an IntEnum and StrEnum, which blur the lines between value type and enum type. Consider the following example:

class Direction(IntEnum):
    UP = 1
    DOWN = 2
    LEFT = 3
    RIGHT = 4

class Color(IntEnum):
    RED = 1
    GREEN = 2
    BLUE = 3

The problem with using IntEnum and StrEnum is that these inherit from int and str, and as a result, a bunch of operations suddenly become possible. For example:

>> Direction.UP + 2
3
>> direction = Direction.DOWN
>> speed = 2
>> speed == direction # Comparing these doesn't make sense, with a regular Enum a type checker will flag this
True
>> Color.RED == Direction.UP # We should compare by identity using `is` instead, but if we do so by mistake this happily passes
True

Also any function that can take an integer now also accepts every IntEnum passed to it.

This is not to say that there aren't ever use-cases for these classes, but most of the time there is a clear separation between an Enum and the internal value that happens to represent it. In this case a regular Enum provides better type safety and prevents some forms of misuse. You have to be explicit about when you want to convert to and from the raw value, and that's a good thing.

💡 Prefer Enum over IntEnum and StrEnum, as it's more explicit and type-safe when using a type checker.

Final remarks

There is so much more to cover on enums. One of my personal favorites that i haven't mentioned so far is usage of auto, when I really don't care about the value used to represent an Enum. I haven't mentioned it because i did not have any additional insights that aren't covered by the docs.

All that's left is one final piece of general advice: When it comes to Enums, Keep it Simple!

That's not entirely true, it has been made impossible through the standard object creation flow, but it is technically still possible, for example through WeekDay._new_member_ or object.__new__. This breaks in various ways, you might be able to manually fix those, but please just don't. ↩

Back to bash: Customization

Kristof Bruyninckx — Sun, 20 Jul 2025 11:40:00 +0000

This post explores a number of different ways in which your bash experience can be customized and, even more so, the underlying mechanism. It's good to be aware of this, as tooling will often either modify your bash startup scripts, or ask you to make the changes.

Customize your bash experience with... bash!

Generally, you use bash itself to customize your own bash experience, since every shell you start will begin by running bash code from a couple of startup scripts.

This means that you can customize things like:

define aliases and functions
Modify shell options through set and shopt.
Alter environment variables
...

Aliases

When invoked these are replaced by the underlying command. For example, i quite often do ls -lrtah to list all (a) file details (l) sorted by reversed modification time (rt) in a human readable format (h). I could define an alias as such:

alias lsd="ls -lrtah"

Now i just need to remember lsd. If i would have a more complex case that required several commands, i could go for a shell function instead.

Shell options

As an example, i can set shopt -s globstar to make ls **/*.txt list files within sub directories.

Alter environment

A very common operation is to modify PATH so that your executables are searched in new locations.

export PATH="/opt/some_dir/:$PATH"

Using export ensures sub processes have access to the variable as well, for example spawning a shell from within a shell will still 'see' the PATH variable.

The loading process

Depending on what kind of shell you start, bash attempts to run the following files ¹.

Interactive login shell: ~/.bash_profile, ~/.bash_login or ~/profile. These are tried in order as specified, the first one that is found is loaded.
interactive non-login shell: ~/.bashrc

Since i refer to these files a lot, i'll simply call them the profile and bashrc files from now on.

you will probably only directly use login shells when using ssh to access a remote machine. On a GUI based OS, the login shell is typically hidden away, but all shells you launch will be subprocesses of the login shell, taking over its execution environment. Those new shells will only load your bashrc file. Herein lies an important factor in choosing which file to modify. Profile scripts are only executed once upon logging in, while bashrc is ran for every interactive shell you spawn. If you add something to your profile script, you'll need to re-login for this to take effect, as opposed to just spawning a new shell when modifying bashrc. There are alternatives to both undesirable options though, as discussed in the next section.

It's worth noting that on my ubuntu 24.04, the profile script will also run bashrc (you can verify this on your own setup) as such:

if [ -n "$BASH_VERSION" ]; then
    # include .bashrc if it exists
    if [ -f "$HOME/.bashrc" ]; then
        . "$HOME/.bashrc"
    fi  
fi

This is not guaranteed though.

Tricks to prevent having to start a new shell

As an example, suppose we have just installed pyenv. The installation process contains instructions to update both your profile and bashrc files. Suppose you've updated your bashrc file, the changes don't take effect for the current shell you were using for the installation. Having to start a new shell can be a real pain, which can be circumvented in a couple of ways.

Spawning a new shell (worse)

You can use bash inside your current shell to spawn a new shell, but the old shell remains open as shown by printing out the process tree. The new shell gets the old shell as its parent.

$ pstree -s $$
systemd───systemd───gnome-terminal-───bash───bash───pstree

A very annoying problem with this is that you loose your recent shell history because that only gets written once the old shell is closed ². I've found this to be quite disruptive.

Sourcing startup scripts

Manually telling bash to re-execute the startup script (source ~/.bashrc or source ~/.profile) does the job. All that's important here is sourcing the script.

Be aware that newly spawned shells will still not see the changes made to profile unless you manually source the profile script each time. This is because they are started from the hidden login shell provided by your OS, which is now out-of-date with your profile script.

An important caveat related to that out-of-date login shell here is that if you remove something from your profile script, such as an export, it will still be there even if you source your profile script, since the export is still taken over from the existing out-of-date login shell.

This is a great option, but it's still useful to know about the others and their downsides.

Replacing your shell

You can use exec $BASH, $BASH being a variable that is automatically set and pointing to your bash executable, usually /bin/bash. This essentially replaces the current bash process with a newly spawned bash (loading bashrc as usual). You might also loose some things, such as function definitions and variables that were not exported, this is shown in the example below.

$ TEST="test"
$ echo $TEST
test
$ exec $BASH
$ echo $TEST

$ export TEST="test"
$ echo $TEST
test
$ exec $BASH
$ echo $TEST
test

It depends on what you were doing, but for me this typically isn't a big deal. This behavior makes sense as we are spawning a new shell so only what was explicitly exported is taken over.

Note that if you want to reload the profile script, you can run exec bash -l, giving you a login shell, however any other shell you spawn will still be out-of-date, for the same reason as mentioned in the section above. Logins shells will also run ~/.bash_logout upon exiting.

It should be noted that there are also system-wide variants that apply first, for every user (/etc/profile and /etc/bash.bashrc). ↩
Under the assumption that you did not modify bash to write history immediately, which is possible using PROMPT_COMMAND ↩

Data oriented python

Kristof Bruyninckx — Mon, 24 Feb 2025 22:04:47 +0000

There is a plethora of options in python to bundle data together. You could use builtin types such as lists, tuples and dicts. You could also create a class, a named tuple or a dataclass, or go even further and use external libraries such as attrs or pydantic. But when to use what, what are the benefits and downsides of each approach? That is the question i hope to tackle in this blog post.

Tuples and Lists

The most basic built-in tuples and lists are very easy to use, but also easy to misuse. Imagine you want to represent a 2-dimensional point of natural numbers. You could do this with a tuple.

>>> p1 = (1,2)
>>> print(p1[0]) # print the x-coordinate
1

While this works, this has a number of downsides. The knowledge that this a point with x and y coordinates is not explicit. You may be able to decipher this from the context and variable naming, but this makes the code less readable. Especially if you are accessing individual x and y coordinates as this is done by indexing.

The lack of readability and intent becomes more apparent if we consider other methods that take points as there input.

def distance(p1: tuple[int, int], p2: tuple[int, int]) -> float:
    return math.sqrt((p2[0]-p1[0])**2 + (p2[1]-p1[1])**2)

Of course, we could create a type alias so that it becomes slightly more readable, but that only helps partially.

type Point2D = tuple[int, int] # Note that this syntax is python 3.12+
def distance(p1: Point2D, p2: Point2D):
    return math.sqrt((p2[0]-p1[0])**2 + (p2[1]-p1[1])**2)

also note that, as tuples are immutable, you can't change the values

>>> p1[0] = 3
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: 'tuple' object does not support item assignment

One last thing to note is that tuples, like other sequence types such as list, offer equality by content rather than reference out of the box. This is one thing that is rather desirable for the example.

>>> p1 = (1, 2)
>>> p2 = (1, 2)
>>> p1 == p2 
True

We may represent the point as a list, which would give us mutability but this also gives us access to all kinds of unwanted methods that can be misused to introduce bugs.

>>> p1 = [1, 2]
>>> p1[0] = 3 # we can update the value now
>>> p1.append(4) # this really does not make sense in the context of a 2d point

Named tuples

A better option would be to use named tuples.

class Point2d(NamedTuple):
    x: int
    y: int

>>> p1 = Point2d(x=1, y=2)

If we now look at the previous distance function it looks quite good.

def distance(p1: Point2D, p2: Point2D):
    return math.sqrt((p2.x-p1.x)**2 + (p2.y-p1.y)**2)

While this is a good option, named tuples are always immutable. They also, being tuples, support all operations that regular tuples support. For example:

>>> p1 = Point2d(x=1.0, y=2.0)
# Some tuple operations
>>> x, y = *p1
>>> p1 == (1, 2)  
True # Given that you can compare with any tuple, this allows comparing apples and oranges without complaint, you might accidentally compare with a tuple containing completely different data and unrelated data.
>>> Test(x=1,y=3) + Test(x=1, y=3) 
(1, 3, 1, 3). # Not exactly desirable in our context. 
>>> for el in tuple:
>>>    ... #

Regular Classes

So what else can we do? We could make use of a regular class

class Point2D
    def __init__(self, x, y):
        self.x = x 
        self.y = y

But this is not enough, Aside from this being slightly more code than the named tuple, we'll have to implement some custom dunder methods or we get this:

>>> Point2D(1,2) == Point2D(1,2) 
False # By default, object equality will by by reference
>>> print(Point2D(1,2))
<__main__.Point2D object at 0x78d45a6dd890>

This makes sense as regular classes are used in many different contexts, the global default should not narrow down its use-cases. However for data oriented classes you would end up having to write a lot of boilerplate (commonly at least __init__, __eq__ and __repr__).

Dataclasses

In come dataclasses. By using a simple decorator you automatically get implementations for those dunder methods mentioned above.

from dataclasses import dataclass

@dataclass
class Point2D:
    x: int
    y: int

Now, we automatically get the following:

>>> Point2D(1,2) == Point2D(1,2)
True
>>> print(Point2D(1,2))
Point2D(x=1, y=2)

You can customize things to your specific needs by providing some arguments to the decorator as below:

 @dataclasses.dataclass(*, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False)¶

So you can really do a lot with a single line of code. Notably you can use frozen=True to make your dataclass immutable. Also note that if you provide both frozen=True and eq=True, you automatically get a sensible hash function so that you can use your object in contexts that require it, such as in sets and for dict keys.

Conclusion

By default, i suggest using the option that is the most restrictive in the sense that it should allow exactly what you need, nothing more. Often this is a choice between dataclasses and pydantic, which i will briefly discuss in a bit. I only use NamedTuple if i have a very specific reason to stay compatible with regular tuples (for example if i am refactoring existing code and i want to retain backwards compatibility). This is the safest in terms of preventing misuse.

Pydantic is great but don't just use it willy-nilly. If you need to do runtime validation on inputs, whether it being loading from files or any place where you deal with user input it tends to be a great fit. As an example, FastApi is a wonderful framework using pydantic for input validation in the context of building web APIs.

Finally, though i didn't explicitly handle it because i never used it, there is also the the attrs package. This predates the standard library dataclasses and seems to be a bit more powerful but also more complex. I suggest you have a look it it (as well i probably) if you encounter an use case that you can't handle with dataclasses.

Advent of code 2023: 01

Kristof Bruyninckx — Thu, 28 Mar 2024 00:09:27 +0000

While it's 2024 and the challenge is long past, I've decided to have a look at the 2023 advent of code. The aim of putting this in a blog series, is to document my approach and gain some feedback. I'm not sure how many of these challenges i'll end up tackling, but i suppose now is as good a moment as any to get started with number one

Part 1

As a brief summary, the goal is to parse a bunch of text lines and, for each line, construct a number composed from the first and the last digit encountered. Then all line numbers need to be summed to a single value. The example taking from the challenge should make everything clear:

1abc2
pqr3stu8vwx
a1b2c3d4e5f
treb7uchet

In this example, the calibration values of these four lines are 12, 38, 15, and 77. Adding these together produces 142.

Let's start by making a helper that, for a line of text, extracts the number. As a side note, since the challenge doesn't mention input where no number is present in a line, i suppose we don't really need to cover it. I decided to support this though, by having lines without any digits give zero and have no effect on the final sum.

def get_line_num(line: str) -> int:
    def first_number(line: Iterable[str]) -> int:
        return next((int(ch) for ch in line if ch.isdigit()), 0)

    first_digit = first_number(line)
    last_digit = first_number(reversed(line))

    return int(f"{first_digit}{last_digit}")

I've used an inner function to keep things DRY, since the task of finding the first and the last number is pretty much the same. The implementation is a neat little one-liner pattern i like to use once in a while. Using next with a generator expression gives a very compact way to retrieve the first element matching some condition. A key thing to know here is that next throws a StopIteration exception by default, but can be given an optional default value to return instead (0).

The only odd thing here is typing wise. Since there is no char type in python, and reversed gives an iterable of strings, the first_number function takes an Iterable[str] so that both cases are covered. While this works, it is not ideal. You could pass a list of strings to the function, which is not intended and not caught statically by the type checker.

All that is left is to take some input lines, pass them to the get_line_number function and sum them.

def get_number(lines: Iterable[str]):
    return sum(get_line_num(line) for line in lines)

Part 2

For the next part, we need to extend our parsing by also supporting spelled out digits.

two1nine
eightwothree
abcone2threexyz
xtwone3four
4nineeightseven2
zoneight234
7pqrstsixteen

In this example, the calibration values are 29, 83, 13, 24, 42, 14, and 76. Adding these together produces 281.

To solve this I extend the previous method by adding some bookkeeping to track how much of each pattern was encountered so far in pattern_seen_chars. Each number represents the amount of characters currently seen in sequence of a specific pattern. If the full pattern was encountered, the corresponding number is returned.

patterns = [
    "one",
    "two",
    "three",
    "four",
    "five",
    "six",
    "seven",
    "eight",
    "nine",
]

def get_line_num(line: str) -> int:
    def first_number(line: Iterable[str], patterns: Sequence[str]) -> int:
        pattern_seen_chars = [0] * len(patterns)
        for ch in line:
            if ch.isdigit():
                return int(ch)
            else:
                for i, p in enumerate(patterns):
                    if p[pattern_seen_chars[i]] == ch:
                        if len(p) - 1 == pattern_seen_chars[i]:
                            return i + 1
                        pattern_seen_chars[i] += 1
                    else:
                        pattern_seen_chars[i] = 1 if p[0] == ch else 0

        return 0

    first_digit = first_number(line, patterns)
    last_digit = first_number(reversed(line), [p[::-1] for p in patterns])

    return int(f"{first_digit}{last_digit}")

Note that i still use the same method of calling the inner helper to get both the first and the last number. Only this time, the patterns also need to be supplied in reverse ([p[::-1] for p in patterns]).

The rest of the solution, namely summing all line numbers, stays the same.

That's it for this challenge. Don't hesitate to give some feedback in case you have done it as well!

AI assisted coding: A word of caution

Kristof Bruyninckx — Tue, 13 Feb 2024 23:11:44 +0000

Ever since the since release of ChatGPT, a myriad of AI tools and assistants, such as Github Copilot, have popped up. AI tools can be used to generate code based on prompting or on the fly suggestions in your IDE. There are concerns regarding the data you share while using these, especially when used in a work environment. But there is another big reason why I'm personally not keen to adopt these kind of tools. The risk of sabotaging my own development skills. Hear me out.

As a developer, you can use all the tools you want provided that they confirm to your company's policies. At least you should be, developer freedom matters. You are however, in the end, solely responsible for the work you deliver. You cannot blame the tools you used if you copied a piece of code, whether from ChatGPT or one of the older go-tos like StackOverflow.

Life long learning

Our capabilities are ever changing. We learn new things every day, but knowledge, if not refreshed, also fades and some knowledge simply becomes outdated. This is especially true in the rapidly evolving field of IT. Thus is important to not just deliver the work we need to deliver, but also use that time effectively to build long-lasting knowledge.

The conclusion from this is that we should try to incorporate principles of effective learning on the job. I've read some interesting material on this in the past, which i wholeheartedly recommend ¹.

How not to use ChatGPT

As coders, we use our toolbox of language features, design patterns and so on to solve new problems. Coming up with a solution should require effort, it should require us to dig into our existing knowledge and try to make new connections. This process of trial and error is an effective tool of learning. On the other hand, generating code with ChatGPT, copying it and then trying to understand it skips this process entirely. It requires less effort, but also gives less long-term gains. Over time, i believe this approach would be a detriment to my coding abilities. It is these same coding abilities that we need to analyse the code generated by ChatGPT.

Not all is bad

Much like linters, AI generated code reviews may help you to spot mistakes and improvements. The Key thing is these happen after you've made the effort to write the code. Getting feedback after making the effort is very valuable. The process of trial and error requires knowing that you've made a mistake to then learn from it, otherwise it would just be trail and ignorance. While the AI review may contain mistakes, it will help you reflect on your work and consider alternatives.

Final thoughts

I'm sure there are many more ways of how not to use or not to use tools like ChatGPT for work other than the two i've just mentioned. The most important question i ask myself is whether it reduces mental effort. Seeing as effort is an important indicator of creating lasting knowledge, this is something i want to avoid.

Brown, P. C. (2014). Make it stick. Belknap Press. ↩

Back to bash: Inception, running bash inside bash

Kristof Bruyninckx — Fri, 02 Feb 2024 23:07:45 +0000

This post will be a shorter one that goes into different ways of running bash scripts inside bash (interactive shell or another bash script). While in general it is a fairly simple process, there are some useful things to keep in mind. At first i wasn't sure if it warranted it's own post, but I've been meaning to make my blogs a bit shorter, and I'm happy how it turned out in the end.

There's essentially two main ways of running another bash script inside bash (spoiler, there is a third way, but i suspect you won't use it as often).

Running a script by specifying the path

First things first, any script you try to run directly must have executable permissions. This is not the default when creating files, so you must remember to add them. As an example, granting only the user that owns the file access to execute it can be done using chmod u+x a.bash.

To run another bash script, simply specify the path, as in ./a.bash, to run it in the current working directory. Note that this is no different from how you would run any other program. Also note that the path to the script/executable must be given, hence the ./ prefix. Bash will do a few things under the hood:

Prepare a new execution environment for the command. This contains a couple of things ¹, the most important of which are the current working directory and the environment variables. These are inherited from the parent execution environment.
Run the script into a new bash process with the newly prepared execution environment. Any changes the script makes to its environment do not affect the parent. As an example, consider the following script that sets an environment variable (export)

export ABC="42"
cd ../

When executed, we can observe that the ABC variable is not available in the environment of the parent, nor is the working directory altered.

~/some_dir/other_dir$ ./a.bash 
~/some_dir/other_dir$ echo $ABC

Sourcing the script

The source builtin, as in source a.bash or . a.bash (the first is just an alias for the latter), can be used to execute all commands from a given script in the current execution environment, allowing you to effectively run scripts that alter the environment and the working directory. The example from above is shown again, but this time it affects the shell.

~/some_dir/other_dir$ source ./a.bash 
~/some_dir$ echo $ABC
42

Running scripts from PATH

Remember how i said the executable must be specified as a path? That is because, when bash does not see a path (no slashes), it will try to look for an executable in any of the PATH directories. This can be desirable if you want to make a script readily available from any location. For example, if you add the a.bash file from before to /usr/local/bin, you can run it, like any other program, using its name, a.bash (assuming /usr/local/bin is in the PATH variable).

A final remark

At the very top of a file you want to execute, you can specify what is called a shebang ². This will be picked up in most Unix systems, and indicates what interpreter should be used to run the script.

#!/usr/bin/bash
...

In fact, it is good practice to put this in shared executable scripts as it ensures that bash will be used even if someone tries to run it in a different shell.

You can also use this to run scripts in other interpreters, such as python, so that you can use some_script.py rather than python some_script.py. If you then drop the .py extension, you can obfuscate the fact that it's running python entirely.

Among others, the execution environment also includes aliases and signal traps. For a full overview, check the bash manual or man bash help pages. ↩
Apparently this is a contraption of the 2 characters used, I never would have guessed that though... ↩

Async behaviour in python web frameworks

Kristof Bruyninckx — Mon, 26 Jun 2023 00:14:45 +0000

When using python web frameworks it's important to understand how they deal with asynchrony, otherwise you will surely run into some massive performance road bumps as your application scales up. In this blog, I explore some of the biggest differences you may need to be aware of for frameworks like Flask, FastApi, Django and many more. In particular, Flask and FastApi are compared by means of small example applications.

The basics of concurrency and parallelism in python

CPython, The most common implementation of Python inherently doesn't support running code in parallel. This is prevented by the GIL (global interpreter lock), which allows only one thread to run python code at a time. This is a rather big topic on its own, more information can be found here.

This is not to say that nothing can run in parallel, some packages like Numpy are mostly written in c, and while running they may release the GIL until they need to call the python C API or update python objects. IO-bound operations that involve system calls will also release the GIL (because in this case, the kernel is responsible for handling the request safely).

All in all you must keep in mind that, when writing pure python code, a single process can run your python code concurrently, but not in parallel. Note the emphasis, as you can create multiple processes to handle requests in parallel. This is done in web servers by spawning multiple worker processes to handle incoming requests. Typically you want to have a stateless application to support this pattern of deployment.

WSGI and ASGI

The Web Server Gateway Interface(WSGI) is a standard to decouple the choice of various web frameworks like Flask and Django from the choice of web servers like Gunicorn or Waitress. Without standardization, the best case scenario is shown below at the left, where each framework is compatible with each web server. Of course in reality, there would be missing links and some would be incompatible. On the right the WSGI standard is introduced. Developers of web frameworks will only have to implement this interface to automatically support all web servers and vice-versa.

This kind of indirection through standardisation is pretty common to make compatibility between different kinds of software components easier. Some other good examples are the LSP project from Microsoft and ONNX to represent machine learning models. The first provides a standard so that IDEs don't have to re-invent the weel for every programming language. The latter decouples training frameworks from inference frameworks. Going back to WSGI, you can find a pretty extensive rationale for the WSGI standard here if interested.

Asynchronous Server Gateway Interface(ASGI) is also a standardisation, focusing on... asynchronous behaviour. One shortcoming of WSGI is that applications must offer a single synchronous callable that takes a HTTP request and returns the response. A worker (typically multiple worker processes are available and each will handle requests) within WSGI will be blocked until the response is there. In ASGI, the worker may be freed up for other requests rather than actively waiting until it can continue. This allows for a higher throughput, especially when the number of IO bound requests is high. The following figure illustrates this key difference. For WSGI request 1 must be finished before the worker can take on request 2.

Note that in the explanation above, we have left out workers with multiple threads, as supported by many WSGI web servers. We will get back to that later on

Async behavior in WSGI frameworks

It may be somewhat confusing but Flask, which is a WSGI framework, also supports using async for request handlers. This works very differently from async request handlers in an ASGI framework! I'll illustrate this by implementing the same example in Flask(WSGI) and FastAPI(ASGI).

Consider the following web app in Flask. Two routes are offered to retrieve some resources. Let's assume the resources are on a different machine at a different location, and they may take a while to retrieve (simulated with a sleep call).

from flask import Flask
from flask import jsonify
import asyncio

app = Flask(__name__)
resource_ids = [1,2,3,4,5]


async def download_resource(id):
    # Dummy method to simulate long running IO
    await asyncio.sleep(5)
    return f"dummy_result_id_{id}" 


@app.route("/resource/<id>")
async def retrieve_resource(id : int):
    """Get all available resources"""
    result = await download_resource(id)
    return jsonify(result)


@app.route("/resources")
async def retrieve_resources():
    """Get a specific resource"""
    async with asyncio.TaskGroup() as tg:
        dl_tasks = [tg.create_task(download_resource(id)) for id in resource_ids]
    # All downloads have completed
    return jsonify([task.result() for task in dl_tasks])

Let's spin this one up using the WSGI web server Gunicorn (Note that the given options are defaults, but are given here to emphasize their value of 1):

gunicorn flask_async:app --workers 1 --threads 1

Now we will send 3 requests at the same time and measure the total response time

$ time curl --parallel --parallel-immediate --parallel-max 3 -X GET http://localhost:8000/resource/1 http://localhost:8000/resource/2 http://localhost:8000/resource/3   -H 'accept: application/json'
"dummy_result_id_3"
"dummy_result_id_1"
"dummy_result_id_2"

real    0m15,038s
user    0m0,006s
sys     0m0,000s

Notice how the async route didn't really do anything in this case. However, if we use the other route to get all resources in a single request:

$ time curl -X GET http://localhost:8000/resources -H 'accept: application/json'
["dummy_result_id_1","dummy_result_id_2","dummy_result_id_3","dummy_result_id_4","dummy_result_id_5"]

real    0m5,014s
user    0m0,005s
sys     0m0,000s

Here we see what we'd like, Multiple requests are handled concurrently. Before explaining this, let's look at the same program in FastAPI, which is an ASGI application,

from fastapi import FastAPI
from pydantic import Field
import asyncio

app = FastAPI()
resource_ids = [1,2,3,4,5]


async def download_resource(id):
    # Dummy method to simulate long running IO
    await asyncio.sleep(5)
    return f"dummy_result_id_{id}" 


@app.get("/resource/{id}")
async def retrieve_resource(id : int = Field(ge=1)):
    """Get all available resources"""
    result = await download_resource(id)
    return result


@app.get("/resources")
async def retrieve_resources():
    """Get a specific resource"""
    async with asyncio.TaskGroup() as tg:
        dl_tasks = [tg.create_task(download_resource(id)) for id in resource_ids]
    # All downloads have completed
    return [task.result() for task in dl_tasks]

To spin this one up, we use an ASGI web server named Uvicorn.

uvicorn fastapi_async:app --workers 1

For this one, we again run 3 simultaneous requests:

$ time curl --parallel --parallel-immediate --parallel-max 3 -X GET http://localhost:8000/resource/1 http://localhost:8000/resource/2 http://localhost:8000/resource/3   -H 'accept: application/json'
"dummy_result_id_3""dummy_result_id_1""dummy_result_id_2"
real    0m5,018s
user    0m0,003s
sys     0m0,003s

Note that, while the route is the same as in Flask (putting aside differences in the frameworks that are irrelevant to async behaviour) the response time here is only 5 seconds, compared to the 15 seconds from before!

This difference can be explained in where the async event loop is set up. For Flask, being WSGI, it is set up in the request handler itself. This means that if we await a single result in the request handler, control is given back to the event loop, but there is nothing else to do than wait. The requests have to be processed one by one as the only worker is blocked for 5 seconds each time. For the single route that requests all resources, The 3 downloads can be done immediately as they are done within the same request. In contrast, FastAPI, being ASGI, will set up the event loop one level higher. When a request awaits a result, the worker is immediately free to take on a new request.

Understanding this example is essential when working with different web frameworks, especially if you work on a larger project that mixes WSGI applications (for instance Dash as a frontend, which used Flask) and FastAPI as a backend.

A note on threads

Flask can run multiple worker threads, which is the default when running a development server using flask --app flask_async run. When using threads with Flask there are two backends:

Gthread: Threads in the regular sense, managed and scheduled by the OS. This is expensive and it directly ties the number of concurrent requests you can handle to n_worker_processes * n_threads
Greenlet: These are pseudo-threads implemented without any OS involvement. The user can decide when control is handed over to a different thread, and/or blocking operations may be altered automatically (using monkeypatch). You could say that with ASGI, async behavior is explicit, while WSGI with greenlets is implicit. Code may look exactly the same as synchronous code, while still gaining async benefits. Performance wise, it is difficult to say which one is better, as both rely on the same backbone of python co-routines. More info can be found here

Conclusion

It is fair to say there are a lot of possibilities when it comes to running async code in web servers. If you are having issues with responsiveness make sure you know the differences between your development setup and production setup (how many workers and threads are being used, what kind of worker is being used). Also be aware of the underlying standard (WSGI or ASGI) used by your framework when deciding on async routes.

Back to bash: [ vs [[, A case of input interpretation

Kristof Bruyninckx — Tue, 01 Feb 2022 02:06:52 +0000

One can generally get by, by knowing a loose set of rules that bash uses to parse input into commands. There are however some commonplace features that are handled differently, notably aliases and the [[ operator. Understanding these differences can save you quite a bit of ~~googling~~ stackoverflowing in the long run. It also helps to solidify your understanding of those features themselves. If you catch yourself looking up similar things over and over, it may help to dive a bit deeper in the inner workings of bash. Speaking of diving in, let's!

Do I really need to know this?

Before going into some dry rules and definitions, let's make things a bit more concrete. Ask yourself if you really know the difference between [ and [[. Was it really necessary for bash to add [[ on top of the Bourne shell? Couldn't we get the same behavior there?

Both of these commands provide the means to do all kinds of conditional tests on files, strings and, in the case of [[ arithmetic comparisons. If a test succeeds, it will return an exit status of 0(success), otherwise 1(error). This means that it can be combined nicely with other features, such as &&.

$ touch test.txt
$ [ -f test.txt ] && echo "file exists!"
file exists!
$ [[ -f test.txt ]] && echo "file exists!"
file exists!

Great, but the commands behave exactly the same. Now let's look at some cases where the commands diverge.

$ touch test2.txt
$ [[ -f test.txt && -f test2.txt ]] && echo "test"
test
$ [ -f test.txt && -f test2.txt ] && echo "test"
bash: [: missing `]'
$ [ -f test.txt ] && [ -f test2.txt ] && echo "test"
test

If we want to combine conditional tests with [, we have to be a bit more verbose. The key difference is that [[ is special to bash, and as such has its own rules of operation. On the other hand [ is a command like any other (with ] as the last argument), and is bound to follow some general rules. In this case [[ overrides the behavior of &&. Adhering to general rules, the second test fails as it first tries to run [ -f test.txt and upon succes also -f test2.txt ]. Note that [ does have it own, less readable syntax to perform an and test ¹

Another important example involves the need for quoting with [.

$ PYTHONPATH="/some/path"
$ [ -n $PYTHONPATH ] && echo "Python path set"
Python path set
$ PYTHONPATH="/some/path/with spaces"
$ [ -n $PYTHONPATH ] && echo "Python path set"
bash: [: /some/path/with: binary operator expected
$ [ -n "$PYTHONPATH" ] && echo "Python path set"
Python path set
$ [[ -n $PYTHONPATH ]] && echo "Python path set"
Python path set

With [, bash will expand $PYTHONPATH, and split that into multiple parts based on whitespace. Subsequently bash will run [ -n /some/path/with spaces ]. The command will not know what to do here, as there are too many operands. On the other hand [[ again overrides the default behavior to make things easier and less error-prone. How this happens will be explained in more detail in the next section. Also consider this contradictory example, in which opposite tests both succeed.

$ [ -n $UNDEFINED_VAR ] && echo "Test succeeded"
Test succeeded
$ [ -z $UNDEFINED_VAR ] && echo "Test succeeded"
Test succeeded

This happens because, as the variable is empty, the command will run as [ -n ]. If [ receives a single argument (not counting the ]), it will default to checking if the argument is empty or not, which is equivalent to [ -n -n ]. That last one looks a bit confusing because the string happens to be -n as well.

Because of these odd cases, one needs to be careful about quoting, or rather not quoting when using [.

Interpreting rules

To fully explain and understand the differences between [ and [[, we need to go over some terminology and rules of operation. Bash continuously executes the following steps:

Parse input into words and operators, where quoting rules
can be used to discard the special meaning of characters. More on that here

Back to bash: Quoting

Kristof Bruyninckx ・ Jan 10 '22

#bash #linux #shell
- Word: Any collection of characters treated as a unit by bash
- Operator:
  - Control Operator: Determine the flow of execution between multiple commands. Some examples are ;, &, |, || and &&.
  - Redirection Operator: The > and < based operators used to redirect stdin, stdout and stderr.
- Metacharacter: Any character that causes input to be split into several words. The most common ones are space and newline, with tab also being possible. Characters used in Operators are also metacharacters.
In the following example, the input is split into words echo, a and b followed by operator > and word c.
```
$ echo a b>c
```
Also note that we don't need spaces when using control operators (throwing readability out of the window)
```
$ echo a&&echo b
a
b
```
Organize words and operators into a tree of commands. At this point, a distinction is made between simple commands, like [ and compound commands, like [[. Simple commands follow the upcoming rules strictly, while compound commands may deviate. As a user, we can create simple commands at will, either through creating and executing separate bash scripts, or defining and using bash functions. Contrary to this, we cannot create our own compound commands.

It is here that operators like && from the previous section, but also || are overridden for [[. They will cause a split into multiple separate tests, as shown in the previous section.
Perform shell expansions. These are some common expansions in order of execution
1. Command substitution $() or ` `
2. Variable expansion such as $VAR
3. Word splitting. Similar to step one, but only split on whitespace. Implicit null arguments (empty string from expanding unset variables) are removed.
  
  Using [[, this step is omitted², which explains why [[ -n $PYTHONPATH ]] && echo "Python path" doesn't need any quotes around $PYTHONPATH, whether it contains spaces or it is empty. The final command that is ran is equivalent to [[ -n "/some/path/with spaces" ]] or, when empty, [[ -n "" ]]. Quotes are not added explicitly, so as to not get something like [[ -n """" ]] in case $PYTHONPATH is quoted. This is just the easiest way to show the equivalence.
4. Filename pattern matching, such as in echo *.sh. This is also not performed for [[, it would simply use the asterisk directly.
Setup redirections and remove the corresponding symbols from the command. e.g. echo a>b becomes echo a and the redirection is set up under the hood.

Note that since at this point it is already decided whether we are in a simple of compound command, the behavior of redirection symbols can be overridden. In [[ it will perform a lexicographical ordering check like so
```
$ [[ a < b ]] && echo "success!" || echo "No success!"
success!
$ [[ b < a ]] && echo "success!" || echo "No success!"
No success!
```
Execute the commands. Actively wait for the return status of any (sub)command that is executed in the foreground.

Given this set of rules, it should now be clear why the following commands are not equivalent, and the first one fails.

$ [[ -n some words ]] && echo "words!"
bash: syntax error in conditional expression
bash: syntax error near `words'
$ WORDS="some words"
$ [[ -n $WORDS ]] && echo "words!"
words!

Conclusion

By now, we have an answer to the question we originally started with

Is it possible to get the behavior from [[ into the Bourne shell?

In the previous section we described the behavior of bash, but the Bourne shell follows the same steps for simple commands. As discussed in step 2 of the previous section , it is only possible to create simple commands. We have seen some examples where [[ overrides the behavior of simple commands (step 2-4), to make our life easier. So no, doing this in the Bourne shell (in the form of a custom script or function) is not possible.

Finally we haven't touched upon the =~ operator supported by [[. This can be used to check if something matches a regular expression and should not be overlooked. As it's not supported by [ and doesn't override any defaults, it didn't really fit in this blog post. It's important enough to at least mention it.

[-f test.txt -a -f test2.txt] ↩
An exception is made for "$@" ↩

Back to bash: Quoting

Kristof Bruyninckx — Mon, 10 Jan 2022 00:27:36 +0000

As the default interactive shell on many Linux based systems, bash is used by everyone and their grandmother - which may not be the most apt expression in this case - on a daily basis. I suspect most people, like myself, gradually roll into it while focusing on other tasks. While this gave me a workable knowledge, i think it can still be improved in some areas.

Back to bash is a series where i revisit bash principles from A to Z, using the official bash manual as a reference. Each post will focus on one specific element in detail, supported by examples. I will try to include pitfalls as much as possible.

To start off lightly, let's begin with quoting rules in bash. The purpose of quoting is to remove the meaning of characters that are interpreted in special ways. There are 3 supported ways of quoting, and each have their use-cases.

Scenario: we want to print that a is larger than b.

Backslash

A backslash can be used to quote the subsequent character.

$ echo a\>b
a>b

When not escaped, > has the special meaning of redirection to files. The following would redirect the command output a to a file named b, which we print using cat.

$ echo a>b
$ cat b
a

Single quotes

Single quotes escape all enclosed characters without exception.

$ echo 'a>b'
a>b

Note that single quotes can never be nested, they cannot be escaped within single quotes. Because of this it is generally not great to use in combination with natural language strings.

#Wrong!
$ echo 'Isn\'t it true that a>b?'

We can use the upcoming double quotes or escape single characters with special meaning.

$ echo Isn\'t it true that a\>b?
Isn't it true that a>b?

It is ideal for encoding some things like simple json strings, which have double quotes in them, and rarely feature single quotes (even though that is not invalid).

$ echo '{"option_1":42}' > config.json

Double quotes

Double quotes escape enclosed characters with some notable exceptions for these symbols: $, `, \, and, if history expansion is enabled and the shell is not in POSIX mode, !.

$ echo "a>b"
a>b

Double quotes can be nested by escaping them.

$ echo "He said \"Isn't a>b?\""
He said "Isn't a>b?"

One notable thing to point out here is the irregular behavior of escaping !. When escaped, the backslash is maintained! As an example, consider creating a git commit that follows the default formatting guidelines of gitchangelog

Attempt 1: Doesn't work, bash will try history expansion and fail.

$ git commit -m "fix: dev: Login doesn't set correct access rights !wip"
bash: !wip: event not found

Attempt 2: The commit will now include the backslash!

$ git commit -m "fix: dev: Login doesn't set correct access rights \!wip"
[master (root-commit) f71201c] fix: dev: Login doesn't set correct access rights \!wip
...

Attempt 3: Works but ugly construct

$ git commit -m "fix: dev: Login doesn't set correct access rights "'!'"wip"

The bash manual doesn't hint at the reasoning for maintaining the backslash. I'd be curious to know that. Note that, if you don't use it you can also disable history expansion using set +H in your interactive shell. It is disabled by default in a non-interactive environment (i.e. running scripts).

ANSI-C quoting

There is also a special form of quoting $'string' which will follow escape rules as in ANSI-C, and can be used to interpret things like newlines, tabs and Unicode characters.

$ echo $'a\tb'
a   b
$ echo $'a\nb'
a
b
$ echo $'\u00AE'
®

Note that echo also has its own support for this

$ echo -e "a\tb"
a   b

Some final thoughts

Quoting is often necessary around variables. Especially when creating scripts that take outside input, we need to be mindful of this. Consider the following script to search for text in a given string. It will take two arguments and print out if the second was found in the first. We will name it search

#!/bin/bash
input=$1
search_str=$2
echo $input | grep -qi $search_str && echo "Found a match!" \
    || echo "No match found!"

If we execute this, it only works with very specific input.

$ ./search trains i
Found a match!

If the input contains spaces the script will break

$ ./search "I like trains" "like trains"
grep: trains: No such file or directory
No match found!

Consider the modified script, which we will name search_v2. Note that echo doesn't really need the extra quotes as it can work with any number of arguments.

#!/bin/bash
input=$1
search_str=$2
echo "$input" | grep -qi "$search_str" && echo "Found a match!" \
    || echo "No match found!"

Which will now give the expected output

$ ./search_v2 "I like trains" "like trains"
Found a match!

That's it for quoting. While it is not the most exciting topic, a solid of understanding of the rules can save you a lot of time!

Neural network initialization: Exploding gradients

Kristof Bruyninckx — Thu, 28 Jan 2021 01:03:44 +0000

The goal of this blog post is to delve into the exploding gradients problem for neural networks and its causes. While the subject has extensive exposure through various courses and blog posts on the web, i found it difficult to find sources with the right kind of depth. Throughout this post, things will be explained by making an explicit link with the neural networks graph structure, something that a lot of people will be familiar with. Finally, there are two questions that will be answered:
1) How exactly are exploding activations linked to exploding gradients?
2) When gradients explode, do they explode equally much throughout the network?

We will start by covering the background for the exploding/vanishing gradients problem.This builds on a lot of concepts and notations, which we cannot cover in a single post. In such cases, links will be added to relevant material. I also want to give a special mention to one specific source. They have a detailed overview of the everything related to neural network initialization, and most importantly, they offer an amazing embedded visualisation tool.

A future post will build on this work to explain the specifics of He vs Xavier initialization

Neural networks background

Let's use the following not so deep neural network as a leading example:

During training, we determine how to slightly nudge our weights, based on a cost function that measures how good of a prediction we made compared to some labeled samples. To determine how much each weight should be nudged, we look at how a tiny change in said weight would impact the cost function. Then we alter the weight in the direction that decreases the cost function for those samples. Applied iteratively, this is a layman's terms explanation for gradient descent. Modern day neural network optimizers, such as Adams, have a bit more whistles and bells, but this covers the absolute basics. More information on the concepts that lead to Adams can be found here
For this blog post, I'll simplify things further by assuming that we update weights for every single sample, which is called stochastic gradient descent. This is not a good idea in practice, as learning will be noisy and slow, but it doesn't really impact this discussion.

In the figure, the gradient or partial derivative to w00^[2] tells us how to update that weight for the next iteration. Nodes and edges that are not greyed out all contribute to the impact of a weight change on the final cost function. In order to calculate this partial derivative, we use the chain rule of derivatives, which breaks it up into a multiplication (note that we use J(x), to represent some cost function)

The last part, which we will call the forward part, can be expanded as:

Writing it out explicitly like this shows an important property:

We can rewrite this as a sum over products, where each term of the product represents a path from an input node through w00^[2] up to the output layer. Each term has a number of factors that scales the with the depth of the neural network 2*(L), where L is the amount of layers in the network. The total amount of paths going through w00^[2], is

where K is the current layer and ni the amount of nodes in layer i.

Each path also has a number of terms that scales with the depth of the network. For the forward part, we have one term per layer plus one term for the input. For the backwards part, we have two terms per layer, because we have both the linear computation of the neuron, and the non-linear activation function. Finally, there is also the derivative of the cost function that adds an additional term.

Exploding gradients

The sample network has just 5 layers in total. In our sum over products view, that would give

2*2*1 paths (the final layer has just one neuron) going through w00^[2]
individual terms (i.e. paths) consisting of 9 factors (2 for the forward part, 1 for the cost derivative, and 6 from the 3 layers in the backwards path)

If we disregard the activation functions for a moment - Note that the power of the network becomes equivalent to that of linear regression -, we get paths consisting of 6 factors.

Let's explore the effects of changing some network parameters. Suppose both inputs, as well as each weight is one. Note that the derivative of the cost function to the final activation is the same for each path, we will call it dc.

If we choose 1 for all weights, the gradient for w00^[2] is 4*dc.
If we decide to change the width of the hidden layers to 100, our calculation becomes 2 * 100 * 1 * dc = 200*dc
If we change the depth to 100 total layers, our calculation becomes 2**97 * 1 * dc. In this case, changing the depth causes the number of paths, and subsequently the gradient to explode.

The key takeaway is that changing the depth has an exponential effect, both in the amount of paths or terms, as in the amount of factors per term. Depth is directly tied to the importance of a good initialization.

What if we take the activation functions into the equation? First note the following property

The partial derivatives to weights in earlier layers are impacted more by activation functions. More precisely, each path has L-K activation factors, where K is the current layer and L the total amount of layers (inlcuding the input layer).

Let's examine the effect of both ReLu and Sigmoid activations.

When using only ReLu activations, they will either do nothing, or drop the contribution of a path if it is negative, thus they will make the partial derivatives for weights in earlier layers higher.
When using only Sigmoids activations, they will reduce the impact of paths, whether they are positive or negative. The partial derivative will move closer to 0.

Conclusion

Now we have all the elements to answer the initial questions.
1) How exactly are exploding activations linked to exploding gradients?
Activations are part of the gradient formula. The further to the right of the network, the more the gradient correlates with the activation.
2) When gradients explode, do they explode equally much at the back and the front of the network?
As a consequence of the activations, no. The precise effect depends on the used activation functions. If the final layer uses Sigmoid, and all the hidden layers use ReLu (a common setup), both positive and negative paths can be dropped (depending on the sign of the weights in the final layer).

The next question is, can we initialize weights in a systematic way, so that we can avoid exploding or vanishing gradients? In the next post of this series, we will explore how to do this by using statistics to keep the variance and mean of activations in check, and subsequently - as we have explored in this post - also the gradients. We will see how this results in different initialization methods for each activation function, more precisely, He- and Xavier initialization.

Forem: Kristof Bruyninckx

The enigma of Python Enums

How do Enums work

Enum values

Enum aliases

A note on IntEnum, StrEnum and more

Final remarks

Back to bash: Customization

Customize your bash experience with... bash!

Aliases

Shell options

Alter environment

The loading process

Tricks to prevent having to start a new shell

Spawning a new shell (worse)

Sourcing startup scripts

Replacing your shell

Data oriented python

Tuples and Lists

Named tuples

Regular Classes

Dataclasses

Conclusion

Advent of code 2023: 01

Part 1

Part 2

AI assisted coding: A word of caution

Life long learning

How not to use ChatGPT

Not all is bad

Final thoughts

Back to bash: Inception, running bash inside bash

Running a script by specifying the path

Sourcing the script

Running scripts from PATH

A final remark

Async behaviour in python web frameworks

The basics of concurrency and parallelism in python

WSGI and ASGI

Async behavior in WSGI frameworks

A note on threads

Conclusion

Back to bash: [ vs [[, A case of input interpretation

Do I really need to know this?

Interpreting rules

Back to bash: Quoting

Kristof Bruyninckx ・ Jan 10 '22

Conclusion

Back to bash: Quoting

Backslash

Single quotes

Double quotes

ANSI-C quoting

Some final thoughts

Neural network initialization: Exploding gradients

Neural networks background

Exploding gradients

Conclusion