A Syntax Highlight Mystery

While writing some documentation for Django today, I noticed something that I thought was a bit weird inside one of the code samples. Can you spot it?

.. code-block:: pycon

    # Import the models we created from our "news" app
    >>> from news.models import Article, Reporter

    # No reporters are in the system yet.
    >>> Reporter.objects.all()
    <QuerySet []>

I must have scrolled past that section a bunch of times and never noticed it, but once I saw it I couldn't un-see it and it really puzzled me.

.. code-block:: pycon

What's that pycon doing there? Surely whoever wrote that made a funny typo and meant to write python, right? What does a Python conference like Pycon have to do with syntax highlighting? I cobbled together some quick bash commands to count the usage of pycon vs. python in the docs, and to my horror suprise I got the following results:

$ git grep -Eo "code-block:: py(c|th)on" -- docs/ | cut -d: -f4 | sort | uniq -c
    959  pycon
    133  python

That's almost 10 times more pycons than pythons! What's going on here?

Luckily I just happened to be in a zoom call with some smart people at the time, and one of them quickly figured out that "pycon" stands for python console in that context. And indeed, all those code blocks using code-block:: pycon are examples of how things look like in a Python console, whereas code-block:: python is used for actual code samples (the ones you'd put in a .py file).

The authoritative answer came from the documentation for pygments, the library that does the syntax highlighting under the hood. Their "Available lexers" page conveniently lists all the languages it knows how to highlight, and a quick control-F on that page quickly reveals that pycon is indeed a "short name" for the PythonConsoleLexer which is used:

For Python console output or doctests [...]

Mystery solved!

Even knowing what pycon is used for now, I still think it's not a great name as I believe most people would not associate it with "python console". So I quickly put together a PR for the pygments project to add an alias for it (I picked python-console). If that PR is accepted, I plan to suggest switching to this alias in Django's documentation.