It took cog 17 years to become an overnight success :)
(first posted Feb 2004: https://t.co/Zmtrdy0by9) https://t.co/DON9THZ5wh

— Ned Batchelder (@nedbat) November 22, 2021

Hynek Schlawack used it to de-duplicate his pyproject.toml:

As a test balloon, I’ve switched structlog from https://t.co/PihDrIF58S to flit w/ pyproject.toml in combination with @nedbat’s cog to maintain some deduplication. I think I like it! Sharp tools that do one thing well FTW.https://t.co/w2RM4Ckyke

— Hynek Schlawack (@hynek) November 17, 2021

Automator extraordinaire Simon Willison started using it to keep docs up to date:

I’ve been solving so many documentation problems with @nedbat’s cog tool recently - it’s fantastic for keeping documentation automatically up-to-date, in Markdown or rST)

Here’s a new page of sqlite-utils docs showing --help for every CLI command! https://t.co/Dwef9p2h8P pic.twitter.com/8tyfyfe7AT

— Simon Willison (@simonw) January 11, 2022

Brett Cannon even called it trendy!

A quick, public thanks to @nedbat for creating Cog; I did the “trendy” thing and used Cog to automate the README for the Python Launcher for Unix (instead of using my home-grown solution). Makes editing the README simple again!https://t.co/F5jnqgW7cG

— Brett Cannon (@brettsky) December 31, 2021

Of course, some people were using it before it was cool.

With all this buzz(!), Tobias Macey invited me on podcast.__init__ to talk about it: Episode 347: Generate Your Text Files With Python Using Cog. It was fun to talk about this little tool I wrote nearly 18 years ago that has been plugging away all this time, and is now being re-discovered.

Even I am finding new uses for cog. I started using it to keep coverage.py docs up to date, I built my crazy over-engineered GitHub profile (source) with it, and I even used it on the source file of this blog post to pull in the tweets!

It’s a function to list strings generated by a pattern with embedded alternatives. It takes an input string with brace-wrapped possibilities, and generates all the strings made from making choices among them:

>>> list(explode("{Alice,Bob} ate a {banana,donut}."))

[

    'Alice ate a banana.',

    'Alice ate a donut.',

    'Bob ate a banana.',

    'Bob ate a donut.'

]

Here’s the function:

def explode(pattern: str) -> Iterable[str]:

    """

    Expand the brace-delimited possibilities in a string.

    """

    seg_choices = []

    for segment in re.split(r"(\{.*?\})", pattern):

        if segment.startswith("{"):

            seg_choices.append(segment.strip("{}").split(","))

        else:

            seg_choices.append([segment])



    for parts in itertools.product(*seg_choices):

        yield "".join(parts)

I call this a gem because it’s concise without being tricky, and uses Python’s tools to strong effect. Let’s look at how it works.

re.split: The first step is to break the string into pieces. I used re.split(): it takes a regular expression, divides the string wherever the pattern matches, and returns a list of parts.

A subtlety that I make use of here: if the splitting regex has capturing groups (parenthesized pieces), then those captured strings are also included in the result list. The pattern is anything enclosed in curly braces, and I’ve parenthesized the whole thing so that I’ll get those bracketed pieces in the split list.

For our sample string, re.split will return these segments:

['', '{Alice,Bob}', ' ate a ', '{banana,donut}', '.']

There’s an initial empty string which might seem concerning, but it won’t be a problem.

Grouping: I used that list of segments to make another list, the choices for each segment. If a segment starts with a brace, then I strip off the braces and split on commas to get a list of the alternatives. The segments that don’t start with a brace are the non-choices part of the string, so I add them as a one-choice list. This gives us a uniform list of lists, where the inner lists are the choices for each segment of the result.

For our sample string, this is the parts list:

[[''], ['Alice', 'Bob'], [' ate a '], ['banana', 'donut'], ['.']]

itertools.product: To generate all the combinations, I used itertools.product(), which does much of the heavy lifting of this function. It takes a number of iterables as arguments and generates all the different combinations of choosing one element from each. My seg_choices list is exactly the list of arguments needed for itertools.product, and I can apply it with the star syntax.

The values from itertools.product are tuples of the choices made. The last step is to join them together and use yield to provide the value to the caller.

Nice.

Back story: the coverage.py test suite seemed to be running oddly: it would run to near-completion, and then stall before actually finishing. To understand why, I added some debug output to see what tests were running on which workers.

I have some very slow tests (they create a virtualenv and install packages). It turned out those tests were being run near the end of the test suite, after their worker had already run a bunch of other tests. So that one worker was taking 10 seconds longer to finish than all the others. This is what made the test suite seem to stall at the end.

I figured it would be easy to schedule tests more optimally. We could record the time each test takes, then use those times in the next test run to schedule the longer tests first, and to balance the total time across workers.

The result is balance_xdist_plugin.py (commit). It’s written to be a pytest plugin, though it’s still in the coverage.py repo, so it’s not usable by others yet. And there are two things that aren’t fully general:

• The data is written to a “tmp” directory, when it should use the pytest caching feature.
• The number of workers is assumed to be 8, because I couldn’t figure out how to get the true number.

You can indicate that certain tests should all be assigned to the same worker. This helps with slow session-scoped fixtures, like my virtualenv-creating tests. It’s also an escape hatch if you have tests that aren’t truly isolated from each other. (Full disclosure: coverage.py has a few of these and I can’t figure out what’s wrong...)

The plugin worked: the test suite runs slightly faster than before, but as is typical, not as much faster as I thought it would. A side-benefit is that the fastest tests are now run at the end, so there’s a satisfying acceleration toward the finish line.

Maybe this plugin will be useful to others? Maybe people have improvements?

The matrix made Python wheels with cibuildwheel, and it worked. It had 15 jobs, but they built different numbers of architectures (ubuntu made three, windows made two, macos made only one). This made the overall run take longer, and made it harder to dig through logs to see if everything went OK. Conceptually, the matrix was three-axis, but expressed as two-axis, with a list of architectures for each job:

strategy:

  matrix:

    os:

      - ubuntu-latest

      - macos-latest

      - windows-latest

    cibw_build:

      - cp36

      - cp37

      - cp38

      - cp39

      - cp310

    include:

      - os: ubuntu-latest

        cibw_arch: x86_64 i686 aarch64

      - os: windows-latest

        cibw_arch: x86 AMD64

      - os: macos-latest

        cibw_arch: x86_64

I wanted to make the architectures a third axis, but couldn’t figure out how to use the YAML syntax to limit the choices for each OS. It seemed like the only way to get a ragged three-axis matrix was to list the combinations explicitly. If you know how, I’m still interested to know.

What I wanted was a way to compute the matrix with a bit more power. There are examples out there of using fromJSON to build a matrix, but I didn’t need it to be recomputed every run. I just wanted a way to not have to type out 30 combinations by hand.

I’ve often needed this sort of thing: a static file with just a bit of computed content. This is what Cog was meant for, and it worked great here too. This is what my computed matrix looks like now:

strategy:

  matrix:

    include:

      # To change the matrix, edit the choices, then process this file with cog:

      #

      # $ python -m pip install cogapp

      # $ python -m cogapp -rP .github/workflows/kit.yml

      #

      #

      # [[[cog

      #   #----- vvv Choices for the matrix vvv -----

      #   oss = ["ubuntu", "macos", "windows"]

      #   pys = ["cp36", "cp37", "cp38", "cp39", "cp310"]

      #   archs = {

      #       "ubuntu": ["x86_64", "i686", "aarch64"],

      #       "macos": ["x86_64"],

      #       "windows": ["x86", "AMD64"],

      #   }

      #   #----- ^^^ ---------------------- ^^^ -----

      #

      #   import json

      #   for the_os in oss:

      #       for the_py in pys:

      #           for the_arch in archs[the_os]:

      #               them = {

      #                   "os": the_os,

      #                   "py": the_py,

      #                   "arch": the_arch,

      #               }

      #               print(f"- {json.dumps(them)}")

      # ]]]

      - {"os": "ubuntu", "py": "cp36", "arch": "x86_64"}

      - {"os": "ubuntu", "py": "cp36", "arch": "i686"}

      - {"os": "ubuntu", "py": "cp36", "arch": "aarch64"}

      - {"os": "ubuntu", "py": "cp37", "arch": "x86_64"}

      - {"os": "ubuntu", "py": "cp37", "arch": "i686"}

      - {"os": "ubuntu", "py": "cp37", "arch": "aarch64"}

      - {"os": "ubuntu", "py": "cp38", "arch": "x86_64"}

      - {"os": "ubuntu", "py": "cp38", "arch": "i686"}

      - {"os": "ubuntu", "py": "cp38", "arch": "aarch64"}

      - {"os": "ubuntu", "py": "cp39", "arch": "x86_64"}

      - {"os": "ubuntu", "py": "cp39", "arch": "i686"}

      - {"os": "ubuntu", "py": "cp39", "arch": "aarch64"}

      - {"os": "ubuntu", "py": "cp310", "arch": "x86_64"}

      - {"os": "ubuntu", "py": "cp310", "arch": "i686"}

      - {"os": "ubuntu", "py": "cp310", "arch": "aarch64"}

      - {"os": "macos", "py": "cp36", "arch": "x86_64"}

      - {"os": "macos", "py": "cp37", "arch": "x86_64"}

      - {"os": "macos", "py": "cp38", "arch": "x86_64"}

      - {"os": "macos", "py": "cp39", "arch": "x86_64"}

      - {"os": "macos", "py": "cp310", "arch": "x86_64"}

      - {"os": "windows", "py": "cp36", "arch": "x86"}

      - {"os": "windows", "py": "cp36", "arch": "AMD64"}

      - {"os": "windows", "py": "cp37", "arch": "x86"}

      - {"os": "windows", "py": "cp37", "arch": "AMD64"}

      - {"os": "windows", "py": "cp38", "arch": "x86"}

      - {"os": "windows", "py": "cp38", "arch": "AMD64"}

      - {"os": "windows", "py": "cp39", "arch": "x86"}

      - {"os": "windows", "py": "cp39", "arch": "AMD64"}

      - {"os": "windows", "py": "cp310", "arch": "x86"}

      - {"os": "windows", "py": "cp310", "arch": "AMD64"}

    # [[[end]]]

If you haven’t seen cog before, this is how it works: it finds chunks of Python code between [[[cog and ]]] markers, executes them, and inserts the output into the file up to the [[[end]]] marker. Existing output is replaced.

Here, the 30 lines of combinations are the output. They weren’t in the file originally; they were created when I ran cog and it re-wrote the whole file. If I change the lists of choices, or the Python code, and re-run cog, it will remove those 30 lines and replace them with the new output.

This is perfect for this use: the choices for the matrix are only going to change very infrequently, and manually. When the choices need to change, I can edit the lists in the Python code, and run cog again to update the generated matrix.

Coverage.py has a --fail-under option that will check the total coverage percentage, and exit with a failing status if it is too low. This lets people set a goal, and then check that they are meeting it in their CI systems.

The feature request is to check each file individually, rather than the project as a whole, to exert tighter control over the goal. That sounds fine, but I could see that it would actually be more complicated than that, because people sometimes have more complicated goals: 100% coverage in tests and 85% in product code, or whatever.

I suggested implementing it as a separate tool that used data from a JSON report. Then, I did just that.

The goals.py tool is flexible: you give it a percentage number, and then a list of glob patterns. It collects up the files that match the patterns, and checks the coverage of that set of files. You can choose to measure the group as a whole, or each file individually. Patterns can be negated to remove files from consideration.

For example:

# Check all Python files collectively, except in the tests/ directory.

$ python goals.py --group 85 '**/*.py' '!tests/*.py'



# We definitely want complete coverage of anything related to html.

$ python goals.py --group 100 '**/*html*.py'



# No Python file should be below 90% covered.

$ python goals.py --file 90 '**/*.py'

Each run of goals.py checks one set of files against one goal, but you can run it multiple times if you want to check multiple goals.

If you want to have more control over your coverage goals, give goals.py a try. It might turn into a full-fledged coverage.py feature, or maybe it’s enough as it is.

Feedback is welcome, either here or on the original feature request.

Things we talked about:

• Walking
• Right and wrong ways to do things
• Geographic meetups during virtual times
• Open source attention
• Coverage.py
• The evolution of the Python standard library
• Python 3.10’s trace behavior
• Coverage as a measure of test quality
• UX of test information
• Developer gamification
• Upgrading Django with third-party packages
• Convincing people to test
• Using non-public interfaces
• Cog
• Side projects as outlets
• Rewriting my wacky personal site (this site)
• edX being acquired by 2U
• Open source from first principles

• Python 2 is no longer supported.
• Third-party packages are automatically ignored, which could be a big change for some people.

There are other smaller improvements, described in the change history.

Give it a try, and let me know what you think.

Here are three map thumbnails, showing the new streets visited in the first hundred walks, the next hundred, and the third hundred:

Although the total distance is longer in the last third than in the first, the total of new streets covered is much less, because of how far I had to go to even get to the new streets.

But the walks will continue, still targeting new streets. It’s a great way to get out, see new things, and get some exercise.

Here’s an animation of the 300 walks:

On to 400!

Update (Sept 29) Today was my 301st walk, and my mapping toolchain started the fourth hundred-map thumbnail, but it’s underwhelming since it only shows the new streets covered by one walk...

BTW: I wrote about how I do the mapping back in February: Mapping walks. The new thing here is how I do the 100-walk new-street maps. Low tech: to make the 201–300 map, I draw walks 1–300 with a thin black line, then I draw walks 1–200 with a thicker white line. Only the new streets remain.

My hosting provider was being acquired, and they said they would migrate my site to the new host. Then they wrote last month to say they couldn’t migrate it (no word why), and that I had six weeks to find a new home.

I briefly tried to just move the site as it was, but PHP 5 was in the mix. Rather than learn how to move it to PHP 7, I bit the bullet and converted it to a real Django-served site.

For 13 years this site has been built with Django, but served as static HTML pages. The comments were handled by PHP code. As part of this move, the site is now served directly by Django on the host, with Django-implemented comments.

This should all be invisible to readers of the site, except for one thing: comments are now written as Markdown instead of as neutered HTML. Having a Django foundation means I will be able to make changes more easily in the future.

Behind the scenes, there is still plenty of strange tech: content is in XML, loaded into a SQLite database locally, then rsync’ed to the server.

Some dormant areas of the site aren’t serving properly yet, but the important stuff works. If you see a problem, please let me know.

Bug Hunters Café is a fun open-ended conversation about bugs and other programming topics, hosted by Jason C McDonald and Bojan Miletić. It’s whimsically set in a science-fiction-themed café.

We talked about a bunch of things: testing, coverage.py, printers, abstractions, Python’s unfortunate readability, kudzu, IRC, Python Discord, Libera.chat, sitting up straight, asking and answering questions, yes and no, studying data structures, singletons, and more.

It was great to have an extended discussion, and it was fun to play along with the café setting.