I’m Blake. I write about probability, stochastic processes, Python tooling, and the practical side of building things with code. More about me →

  • How to get started with Python with modern tooling using `uv`

    The hard part of teaching someone how to do machine learning usually isn’t the machine learning itself – it’s installing Python.

    There have been so many articles written over the years on the topic of Pythons imperfect tooling (I doubt I can provide any new insights to this). The reason for Pythons idiosyncrasies appear to be twofold: Python is used by many people with different levels of expertise across a large number of different platforms and environments. What works for the sever admin on Linux must also work for the hobbyist on Windows and the academic researcher on Mac.

    I encourage reading what others have written on the topic. In this post I want to answer the question:

    I’m interesting in machine learning, but have relatively little Python experience. How can I get started with Python and machine learning

    New tooling has improved for python from Astral over the past couple of years, and it’s made it easier than ever to get into Python from scratch with uv. I’ll show you how to use uv to get right into Python on a fresh Ubuntu 24.04 LTS system. These instructions should also work for Mac as well.

    A disclaimer: I primarily work on Linux, and occasionally on Mac. The instructions I give here should work across both these platforms but I cannot provide any insight to Windows unfortunately.

    I also assume you’re already a developer who’s proficient with the terminal when I write this article. Here’s what we need to get started with Python:

    1. A way to execute Python code
    2. A way to download Python packages
    3. A way to isolate downloaded packages in virtual environments for each project

    All three of these can be solved with the recently released uv tool

    1. Download uv

    The uv team provides a one-line installation script:

    # If you use `curl`
    $ curl -LsSf https://astral.sh/uv/install.sh | sh
    # If you use `wget`:
    $ wget -qO- https://astral.sh/uv/install.sh | sh

    They also provide methods for using brew from the core packages if that’s your jam:

    $ brew install uv

    Once installed, start a new shell and check it

    $ uv --version
    # uv 0.6.5

    2. Start a new project

    I’m going to start a project for our toy project that uses Pytorch:

    $ mkdir -p ~/Workspace/proj-pytorch
    $ cd ~/Workspace/proj-pytorch
    $ uv init .
    # Initialised `proj-pytorch` at `/home/user/Workspace/proj-pytorch`

    A few files are generated:

    $ tree -a .
    # .
    # ├── main.py
    # ├── pyproject.toml
    # ├── .python-version
    # └── README.md
    #
    # 1 directory, 4 files

    The files main.py and README.md are where we’ll start writing code and documentation.

    $ cat main.py
    # def main():
    #     print("Hello from proj-pytorch!")
    #
    # if __name__ == "__main__":
    #     main()

    Our project configuration will live in pyproject.toml:

    $ cat pyroject.toml
    [project]
    name = "proj-pytorch"
    version = "0.1.0"
    description = "Add your description here"
    reradme = "README.md"
    requires-python = ">=3.12"
    dependencies = []

    Soon we’ll use uv to add python packages in our project dependencies – we wont need to edit this field manually.

    The file .python-version is used by uv to load and run a specific version of Python. In this case:

    $ cat .python-version
    # 3.12

    We can use uv to run the code:

    $ uv run python main.py
    # Using CPython 3.12.3 interpreter at: /usr/bin/python3.12
    # Creating virtual environment at: .venv
    # Hello from proj-pytorch!

    If the Python version is already installed and discoverable on your system, uv will automatically use that. If not (lets demonstrate this by using an older Python I don’t have installed, I’ll edit requires-python = ">=3.11" in pyproject.toml). The selected version of Python will be downloaded:

    $ uv python pin 3.11
    # Using CPython 3.11.11 interpreter
    # Removing virtual environment at: .venv
    # Creating virtual environment at: .venv

    As we can see from the command output so far, uv automatically creates a virtual environment for our project – we don’t even need to think about it! (just need to remember to .gitignore the hidden .venv directory in our project)

    3. Install python packages

    Let’s install Pytorch for our project. Python packages are installed with the built-in package manager pip. Aside from the more esoteric commands, most actions you would run with pip will work with uv.

    The official instructions for installing Pytorch (version 2.6.0 for CUDA 12.4) tell us to use

    $ pip install torch

    With uv, we’ll instead use

    $ uv add torch

    This will download Pytorch with all of the necessary dependencies (with concurrency, which pip does not do), and also adds torch to the dependency field of pyproject.toml. It will also spawn a uv.lock file so that you can distribute your code and a user can run uv sync to replicate your python environment to replicate your Python environment.

    After it’s installed, we can fire up a Python prompt to check it out:

    $ uv run python
    >>> import torch
    >>> print(torch.rand(3))
    # tensor([0.2205, 0.3637, 0.8216])

    There might be a warning about missing a numpy dependency. Let’s exit Python and add it

    >>> exit()
    $ uv add numpy

    Our pyproject.toml now has these dependencies declared:

    dependencies = [
        "numpy>=2.2.3",
        "torch>=2.6.0",
    ]

    Using package indices other than Pypi

    There are different versions of Pytorch published for use with different accelerators and CUDA versions. For example, if we want the CPU-only version of Pytorch, we’ll need to download it from their index https://download.pytorch.org/whl/cpu. Their instructions say to use

    $ pip install torch --index-url https://download.pytorch.org/whl/cpu

    To do this with uv, we’ll append the following sections to our pyproject.toml:

    [tool.uv.sources]
    torch = [
        { index = "pytorch-cpu" },
    ]
    
    [[tool.uv.index]]
    name = "pytorch-cpu"
    url = "https://download.pytorch.org/whl/cpu"
    explicit = true

    Now we can refresh our environment with uv sync.

    Conclusion

    We should now have all we need for basic Python development! The documentation for uv is extremely well-written and has been developed quite well. I encourage having a read of their website to learn more

    We can now write code in main.py and execute it with uv run python main.py, I might even add alias py='uv ruin python' to my shell RC file. We can also start developing code in a library

    $ mkdir src
    $ touch src/__init__.py
    $ touch src/foo.py

    The __init__.py file will tell Python that this is a package we can import from. We can then add the following content to foo.py:

    import torch
    
    def bar(n):
        return torch.rand(n)

    Then we can import this into a Python session:

    $ uv run python
    >>> from src.foo import bar
    >>> bar(3)
    # tensor([0.5001, 0.0048, 0.6366])

    Or we could use this in main.py:

    from src.foo import bar
    
    def main():
        print(bar(3))
        print("Hello from proj-pytorch!")
    
    if __name__ == "__main__":
        main()

    Then we can run it with

    $ uv run python main.py
    # tensor([0.5001, 0.0048, 0.6366])
    # Hello from proj-pytorch!

    There’s more we can cover, such as types, debugging, formatting and linting, but I’ll post about that another day. For now you should have what you need to get started with any of the wonderful tutorials on Pytorch, or any other python library!

  • Did you see the gorilla?

    In some high school psychology classes, students are shown a video that demonstrates selective attention. This video shows two teams bassing basketballs to each other, and students are instructed to count the number of passes for one of the teams.

    The teacher asks for their answers, the students count about about 12-15. Then the teacher asks, “but did you see the gorilla?”

    Rewinding the video reveals that there is a person wearing a gorilla suit, walking in plan views through the middle of the scene, which bewilders most of the students – how did they not notice that?!


    I also read an amusing article on testing the capability of LLMs for explorative data science by Chiraag Gohel, which talks about a study. by Itai Yanai and Martin Lercher published in 2020 that tested undergraduates ability to see the gorilla when working with a fictitious dataset. Hilariously, when the data is plotted on a scatter plot, the picture of a gorilla appears, which obviously does not appear when over analysing the statistics of the dataset. Students tasked with investigating a single hypothesis were apparently 5 times less likely to notice the gorilla that students who were tasked with an open-ended investigation. This raises concerns about hypothesis-driven research as a whole


    This is a unifying feeling, at some stage we’ve experienced something like this. I’ve personally experienced it several times in mathematics and programming. When you’re so focussed on solving a problem one way, you have to learn to actively look out for other clues that may reveal alternative successful solutions. I don’t think there’s a reliable solution to this problem when working in isolation – the focus needed to solve a problem one way takes away from the focus needed to keep the scope broad.

    I’ve been thinking about how this affects life more broadly. A post by the Association for Psychological Science explores this in more detail, and considers the life-impacting consequences of “inattentional blindness” in the medical field

    There’s three lessons I can identify from these anecdotes:

    1. Awareness
    2. Exploration
    3. Collaboration

    Being aware of the problem gives us pause, and can give us opportunity to stop and survey where we are to make sure we’re not missing something crucial

    Taking a exploratory approach instead of a hypothesis-driven approach also helps tremendously. When I have a goal of solving a problem, I first focus on learning as much as I can about the problem and planning different methods to solutions before jumping into the rabbit hole

    We all have different perspectives and blind spots. We are inherently a social species, and historically I think we’ve overcome many gorillas in the data over centuries by working together.


    This lesson seems increasingly more important recently. There are no shortage of spectacles in the news, ridiculous events and actions meant to take advantage of this quirk in our attention. These spectacles often force us collectively into a hypothesis-driven view, making it easier for the gorilla to slip through

    We can try and find ways to tackle this with exploring the data more often – but there is no substitute for collaboration. Together we can work together to overcome this quirk of psychology. As we make more progress on large problems together with our friends and neighbours and colleagues, we can look out for each other. When something seems off, and we identify blind spot for one or several people, we can ask:

    Did you see the gorilla?

  • Asynchronous Vim

    In my last post I explored using Python and nccurses to asynchronously render streamed content from curl. Upon a re-think of my strategy, I wondered why I even needed Python at all. In modern versions of Vim, I knew that asynchronous abilities were available, but I had no idea how to use it at all. After quite a bit of experimentation and reading the docs, this is what I learned:

    Jobs

    The job_start command can execute a shell command and intercept the results with callbacks. You can even create partial functions and use them as callbacks!

    " job_demo.vim
    function! OutCb(bufchannel, msg) abort
        call append('$', a:msg)
    endfunction
    
    function! ExitCb(foo, job, status) abort
        call append('$', "Status: ".a:status)
        call append("$", a:foo)
    endfunction
    
    let cmd = ['/bin/bash', '-c', 'for i in 1 2 3; do echo $i; sleep 1; done']
    let callbacks = {'out_cb': function("OutCb"), 'exit_cb': function("ExitCb", [456])}
    let job_id = job_start(cmd, callbacks)

    Write this script to as buffer and running :w job_demo.vim | so % will append the script with

    1
    2
    3
    Status: 0
    456

    as the job progresses. With this working example, I was able to understand :h job much more!

    Timers

    Sometimes you just need a function to call every N seconds or so.

    " timer_demo.vim
    let g:counter = 0
    
    function! MyFunc(msg, timer_id) abort
        if g:counter > 3
            return
        endif
        let g:counter += 1
        call append("$",a:msg)
        let n_msecs = 1000
        call timer_start(n_msecs, function('MyFunc', [1000 * n_msecs]))
    endfunction
    
    let timer_id = timer_start(1000, function('MyFunc', ["timer go!"]))

    This appends the text

    timer go!
    1000
    2000
    3000

    As the timer executes. Check out :h timer for more info.

    And both these methods don’t block other actions in Vim! You can keep editing or processing text in another buffer without interruption.

  • Using Pipes and Sockets for asynchronous local AI Chats

    Recently I was experimenting with writing a CLI interface from scratch. There’s a variety of new AI tools out there, but I was on the lookout for a plugin for Vim that would allow me to use a ChatGPT-like workflow without the constant alt-tabbing between windows and relentless copy-pasting.

    The best one I found was vim-ai by madox2, I highly recommend checking it out. It seems to be the closest candidate for what I was looking for, but its chat functionality is synchronous. Every query paused all actions in Vim, meaning I couldn’t keep exploring until after the answer had fully generated. I explored the codebase, but it looked like it was not a simple feature to add, so I decided to explore this problem from a fresh canvas.

    I was hesitant to use vimscript straight away (though I eventually built a solution with this). I initially took to Python to see if I could make a Vim-independent CLI solution so that:

    • Chats would be launched through :terminal buffers (for easy OOTB asynchronous execution)
    • Answers could be piped directly to the clipboard or a Vim register
    • Chat buffer would automatically close when the user quit the chat CLI

    This would give me the asynchronous implementation straight away. I used ncurses to generate a simple CLI and learned about sockets and pipes to allow this CLI to send and receive data to other processes. Essentially this CLI would behave a bit like less and watch combined together with some data processing thrown in.

    Using Ollama for a local API, I could generate resposes using

    curl -s http://localhost:11434/api/chat --no-buffer -d '{
      "model": "phi4:latest",
      "messages": [
        {
          "role": "user",
          "content": "hello"
        }
      ]
    }'

    which gives me a streaming repose like

    {"model":"phi4:latest","created_at":"2025-02-15T04:15:47.51450141Z","message":{"role":"assistant","content":"Hello"},"done":false}
    {"model":"phi4:latest","created_at":"2025-02-15T04:15:47.60217441Z","message":{"role":"assistant","content":"!"},"done":false}
    {"model":"phi4:latest","created_at":"2025-02-15T04:15:47.676216968Z","message":{"role":"assistant","content":" How"},"done":false}
    {"model":"phi4:latest","created_at":"2025-02-15T04:15:47.749957446Z","message":{"role":"assistant","content":" can"},"done":false}
    {"model":"phi4:latest","created_at":"2025-02-15T04:15:47.823717019Z","message":{"role":"assistant","content":" I"},"done":false}
    {"model":"phi4:latest","created_at":"2025-02-15T04:15:47.897391602Z","message":{"role":"assistant","content":" assist"},"done":false}
    {"model":"phi4:latest","created_at":"2025-02-15T04:15:47.971128894Z","message":{"role":"assistant","content":" you"},"done":false}
    {"model":"phi4:latest","created_at":"2025-02-15T04:15:48.045499791Z","message":{"role":"assistant","content":" today"},"done":false}
    {"model":"phi4:latest","created_at":"2025-02-15T04:15:48.11924118Z","message":{"role":"assistant","content":"?"},"done":false}
    {"model":"phi4:latest","created_at":"2025-02-15T04:15:49.391045405Z","message":{"role":"assistant","content":""},"done_reason":"stop","done":true,"total_duration":21531784605,"load_duration":19128188606,"prompt_eval_count":11,"prompt_eval_duration":522000000,"eval_count":26,"eval_duration":1877000000}

    So this CLI would have to listen to these incoming json objects, parse the content out of them and display it on a screen.

    So I started with defining a single class for this CLI, which has a socket for receiving input:

    import time
    import os
    import curses
    import threading
    import socket
    import textwrap
    
    SOCKET_PATH = "/tmp/pipe_viewer_socket"
    
    
    class Viewer:
        def __init__(self, stdscr):
            self.stdscr = stdscr
            self.running = True
            ...
    
        def read_socket(self):
            """Continuously accept connections and read from the Unix domain socket."""
            try:
                while self.running:
                    ...
            except KeyboardInterrupt:
                self.running = False
    
        def run(self):
            """Main curses loop to update the display."""
            ...
    
    
    if __name__ == "__main__":
        try:
            curses.wrapper(Viewer)
        except KeyboardInterrupt:
            pass

    In our __init__ method, we’ll declare the state we need to track of and start the threads:

    SOCKET_PATH = "/tmp/my_socket"
    
    
    class Viewer:
        def __init__(self, stdscr):
            self.stdscr = stdscr
            self.running = True
            self.buffer = [""]
            self.lock = threading.Lock()
    
            # Ensure no leftover socket file
            if os.path.exists(SOCKET_PATH):
                os.remove(SOCKET_PATH)
    
            # Create a Unix domain socket
            self.server_socket = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
            self.server_socket.bind(SOCKET_PATH)
            self.server_socket.listen()

    First we’ll define the loops for listening to the socket:

        def read_socket(self):
            """Continuously accept connections and read from the Unix domain socket."""
            try:
                while self.running:  # Re-open the socket if it closes
                    conn, _ = self.server_socket.accept()
                    with conn:
                        while self.running:  # Listen continuously and accept data in 1024 bytes at a time
                            data = conn.recv(1024)
                            if not data:
                                break
                            with self.lock:  # Lock structures to this thread to avoid concurrency issues
                                line = data.decode()
                                try:
                                    data = json.loads(line, strict=False)
                                except json.JSONDecodeError:
                                    continue
    
                                content = data.get("message", {}).get("content", "")
                                done = data.get("done", False)
    
                                if not self.request_in_progress:
                                    self.request_in_progress = True
    
                                self.buffer[-1] += content
    
                                if done:
                                    self.request_in_progress = False
                                    self.buffer[-1] += "\n\n"
                                    self.buffer.append("")
    
            except KeyboardInterrupt:
                self.running = False

    We can render this data in the screen using a run method:

        def run(self):
            """Main curses loop to update the display."""
            curses.curs_set(0)  # Hide cursor
            self.stdscr.timeout(100)  # Refresh every 100ms
    
            while self.running:
                self.stdscr.clear()
                h, w = self.stdscr.getmaxyx()
    
                with self.lock:
                    wrapped_buffer = textwrap.wrap("\n".join(self.buffer), width=w - 1))
    
                    scroll_offset = max(0, len(wrapped_buffer) - self.stdscr.getmaxyx()[0])
    
                    total_lines = len(wrapped_buffer)
                    start = max(0, total_lines - h - self.scroll_offset)
                    visible_lines = wrapped_buffer[start : start + h]
    
                    for i, line in enumerate(visible_lines):
                        if i >= h:
                            break
                        self.stdscr.addstr(i, 0, line)
    
            self.server_socket.close()
            os.remove(SOCKET_PATH)

    Then we can launch these this method on separate threads in __init__, and start running the application by calling the run method:

        def __init__(self, stdscr):
            ...
            # Start the input listener in a separate thread
            self.listener_thread = threading.Thread(target=self.read_socket, daemon=True)
            self.listener_thread.start()
    
            self.run()

    And now launching this script with python, we get the rendered buffer where we can pipe curl outputs from Ollama into so they can be displayed and rendered.

    The next steps are to managing copying and pasting, I’ll write about how I solved that in a future post. For now, I hope this article on listening to sockets was informative!