Brian Okken posted and published his Top pytest Plugins script and then a follow-up post, Finding the top pytest plugins, which was pretty cool.

I have written a few throw-away scripts, which William Vincent wrote about and updated a few times in the Top 10 Django Third-Party Packages (2024) and The 10 Most-Used Django Packages (2024).

These efforts are powered by Hugo van Kemenade’s excellent Top PyPI Packages.

This inspired me to fork Brian’s top-pytest-plugins project, which I updated to support passing in other package names like “django” to get a rough estimate of monthly package downloads.

The refactored project is jefftriplett/top-python-packages.

Please note: Looking at the package name doesn’t scale as well for projects that have their own Trove classifiers. For a project like pytest, it works well. Many of the top packages may not even have Django in their name for a project like Django. Some projects may even actively discourage a project from using their project in their package’s name for trademark reasons. So, YMMV applies here.

Prompts

I added uv run support, which I have written about a lot lately.

I also copied the top_pytest.py file into a Claude 3.5 Sonnet session, and I let it handle the whole refactor. It even handled adding the PEP 723 new package dependencies without me asking it to.

In case it’s useful to anyone, here are my prompts:

## Prompt:
Please update this script to use a rich table.


## Prompt:
Please update the table styles to be ascii so I can copy and paste it into a markdown doc


## Prompt:
Please remove the description column


## Prompt:
Please change all PyTest and pytest references to Django and django


## Prompt:
Please add back `if 'django' in project.lower() and 'django' != project.lower():`


## Prompt:
please remove the \*# Export to markdown section. I can just pipe the output \*


## Prompt:
Please add the typer library.


## Prompt:
Please remove days and limit


## Prompt:
Please refactor the script to allow me to pass the package name instead of django. You can default to django though.


This way I can pass pytest or flask or other projects.


## Prompt:
Please change the default Table box type to MARKDOWN

Outro

I don’t usually write about Claude or prompts, but the tool has been handy lately.

If you have had some similar successes, let me know. I have been exploring some rabbit holes, and it’s changing the way I approach solving problems.

I wanted to know how hard it would be to turn one of my django-startproject projects into a uv run friendly project. As it turns out, it worked, and the steps were more than reasonable.

Before the PEP 723’ing…

I started with a fairly vanilla manage.py that Django will give you after running python -m manage startproject.

"""Django's command-line utility for administrative tasks."""

import os
import sys


def main():
    """Run administrative tasks."""
    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings")
    try:
        from django.core.management import execute_from_command_line
    except ImportError as exc:
        raise ImportError(
            "Couldn't import Django. Are you sure it's installed and "
            "available on your PYTHONPATH environment variable? Did you "
            "forget to activate a virtual environment?"
        ) from exc
    execute_from_command_line(sys.argv)


if __name__ == "__main__":
    main()

shebang

Then we add #!/usr/bin/env -S uv run to the top of our manage.py file.

Next, we make our manage.py executable and try to run it.

$ chmod +x manage.py
$ ./manage.py
ModuleNotFoundError: No module named 'django'

Our script ran, but Python couldn’t find Django. To tell our script to install Django, we can use uv add—- script to add it.

$ uv add --script manage.py django
Updated `manage.py`
$ ./manage.py
...

Type 'manage.py help <subcommand>' for help on a specific subcommand.

Available subcommands:

[django]
    check
    compilemessages
    createcachetable
    dbshell
    diffsettings
    dumpdata
    flush
    inspectdb
    loaddata
    makemessages
    makemigrations
    migrate
    optimizemigration
    runserver
    sendtestemail
    shell
    showmigrations
    sqlflush
    sqlmigrate
    sqlsequencereset
    squashmigrations
    startapp
    startproject
    test
    testserver
Note that only Django core commands are listed as settings are not properly configured (error: No module named 'environs').

Django worked as expected this time, but Python could not find a few third-party libraries I like to include in my projects.

To add these, I passed the other four to uv add --script which will add them to the project.

$ uv add --script manage.py django-click "environs[django]" psycopg2-binary whitenoise
Updated `manage.py`
...
$ ./manage.py
...

Our Django app’s manage.py works when we run it.

After the PEP 723’ing…

After we installed our dependencies in our manage.py file, they were added to the top of the file between the /// blocks.

#!/usr/bin/env -S uv run
# /// script
# requires-python = ">=3.10"
# dependencies = [
#     "django",
#     "django-click",
#     "environs[django]",
#     "psycopg2-binary",
#     "whitenoise",
# ]
# ///
"""Django's command-line utility for administrative tasks."""

import os
import sys


def main():
    """Run administrative tasks."""
    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings")
    try:
        from django.core.management import execute_from_command_line
    except ImportError as exc:
        raise ImportError(
            "Couldn't import Django. Are you sure it's installed and "
            "available on your PYTHONPATH environment variable? Did you "
            "forget to activate a virtual environment?"
        ) from exc
    execute_from_command_line(sys.argv)


if __name__ == "__main__":
    main()

This UV shebang trick that Simon Willison linked up is a nice pattern, and I plan to rebuild some of my one-off scripts in my dotfiles using it.

Here is a demo that will print “hello python” using the Python Branding colors using the Rich library while letting UV install and manage rich for you.

#!/usr/bin/env -S uv run
# /// script
# requires-python = ">=3.10"
# dependencies = [
#     "rich",
# ]
# ///

from rich.console import Console
from rich.theme import Theme

python_theme = Theme(
    {
        "pyyellow": "#ffde57",
        "pyblue": "#4584b6",
    }
)

console = Console(theme=python_theme)

console.print("[pyyellow]hello[/pyyellow] [pyblue]python[/pyblue]", style="on #646464")

Assuming you have UV installed, and you save and chmod +x this file as hello-python.py, then you should be able to run it via ./hello-python.py.

I suspect I can more easily bootstrap new machines using this trick without fewer worries about polluting my global system packages.

The uv: Unified Python packaging update brings fresh air to the Python community, with several improvements streamlining the development process. One exciting addition is an early preview of PEP 723, also known as Single-file scripts.

The Single-file scripts feature particularly caught my attention due to its potential to simplify the distribution and execution of small Python projects. Streamlining the process is highly appealing to someone who frequently creates GitHub Gists and shares them privately and publicly.

With this new feature, I can now instruct users to run uv run main.py without explaining what a venv or virtualenv is, plus a long list of requirements that need to be passed to pip install.

I had the opportunity to test this feature over lunch today. While adding libraries to the script was straightforward, I encountered a few hurdles when I forgot to invoke uv run in my virtual environment (venv). This makes sense, given that it’s a new habit, but it highlights the importance of adapting to changes in our development workflow.

Overall, the UV: Unified Python packaging update and the introduction of Single-file scripts mark a significant step in simplifying Python development. As developers become more familiar with these improvements, we expect increased adoption and smoother collaboration on small-scale projects.

Bonus Example

I looked through some of my recent visits, and one I recently shared with a few conference organizer friends was a one-off script I used to read several YouTube video JSON files that I’m using to bootstrap another project. It was the first time I used DuckDB to make quick work of reading data from a bunch of JSON files using SQL.

Overall, I was happy with DuckDB and what PEP 723 might bring to the future of Python apps, even if my example only does a little.

# To run this application, use:
#   uv run demo-duckdb.py
#
# /// script
# requires-python = ">=3.10"
# dependencies = [
#     "duckdb",
#     "rich",
#     "typer",
# ]
# ///
import duckdb
import typer

from rich import print


def main():
    result = duckdb.sql("SELECT id,snippet FROM read_json('json/*.json')").fetchall()

    for row in result:
        id, snippet = row
        print("-" * 80)
        print(f"{id=}")
        print(f"{snippet['channelTitle']=}")
        print(f"{snippet['title']=}")
        print(f"{snippet['publishedAt']=}")
        print(snippet["description"])
        print(snippet["thumbnails"].get("maxres") or snippet.get("standard"))
        print()


if __name__ == "__main__":
    typer.run(main)

Overall, the future is bright with UV and PEP 723 may bring us. I’m excited to have more one-file Python apps that are easier to share and run with others.

PEP 723 also opens the door to turning a one-file Python script into a runnable Docker image that doesn’t even need Python on the machine or opens the door for Beeware and Briefcase to build standalone apps.