unicode-table

The unicode-table directive lists icons - Unicode characters, e.g. emoji - with their Unicode names and code points, e.g. the icons a tree uses.

The content is the icons, one per line, written as characters or as code points. An icon may have a description, behind a |.

The names and code points are computed from the icon, so a row can’t contradict its icon.

In HTML, a button beside the icon copies the icon into the clipboard, and a button beside the code points copies these - in the form a tree’s icon options take them.

.. unicode-table::

   📦             | a package
   U+1F4C1        | a directory
   U+2699 U+FE0F  | a configuration file
   👨‍💻

This is how the example renders:

Icon	Name	Code points	Description
📦	PACKAGE	`U+1F4E6`	a package
📁	FILE FOLDER	`U+1F4C1`	a directory
⚙️	GEAR	`U+2699 U+FE0F`	a configuration file
👨‍💻	MAN + PERSONAL COMPUTER	`U+1F468 U+200D U+1F4BB`

Common Icons lists icons commonly used in a tree, by this directive.

Content

An entry is a line holding an icon. Blank lines are ignored.
An icon is written as characters, e.g. 📁, or as Unicode code points, e.g. U+1F4C1. Several words form one icon, and characters and code points may be mixed: U+2699 U+FE0F and ⚙ U+FE0F are the same icon. A code point keeps the source readable in an editor whose font lacks the icon’s glyph, and shows a variation selector, which is invisible as a character.
A | between spaces separates the icon from its description, which is inline ReST. A table without any description has no column for them.
Spaces around the | don’t matter, so the separators may be aligned in the source. A | in an inline literal or in a role’s text separates nothing; elsewhere, a | belonging to the description is escaped as \|.

Names and code points

The names are the ones Python’s unicodedata knows, so a name is always the icon’s.

A single character is named by its Unicode name: 📦 is PACKAGE.
A sequence is named by its characters, joined by +: 👨‍💻 is MAN + PERSONAL COMPUTER. A variation selector and the zero width joiner select how the characters are drawn and aren’t named: ⚙️ - U+2699 U+FE0F - is GEAR.
A character without a name - a control character, a private-use character or a noncharacter - is named by the label the Unicode standard gives it, e.g. <private-use-E000>. An icon font such as a Nerd Font maps its icons to private-use characters.
A code point not assigned in the Unicode version of unicodedata is named <reserved-XXXX> and warned about: either it is a typo, or the icon is newer than the Python running the build. Python 3.12 knows Unicode 15.0, 3.13 Unicode 15.1 and 3.14 Unicode 16.0.

The code points are written as the icon options of the tree take them: U+ and at least four hexadecimal digits per character, separated by spaces.

Options

.. unicode-table::

Lists the icons written in the content, with their names and code points.

:class: <CSS classes>: Additional CSS classes on the table.

Copy buttons

In HTML, the icon and the code points are each followed by a <button>, labelled for a screen reader - e.g. Copy the icon PACKAGE -, which copies them into the clipboard. After a click, the button shows a check mark for a moment, and a status message tells a screen reader what was copied.

The buttons work by the script pyTooling.js, which the extension links into every HTML page, as it does its stylesheet. The browser grants a page the clipboard, if it is served by HTTPS or from localhost; elsewhere, a button turns red.

Styling

The stylesheet takes its values from CSS custom properties, so a project changes them without replacing the stylesheet - in a stylesheet of its own, listed in html_css_files:

Property	Default	Sets
`--pyTooling-unicode-glyph-size`	`1.5em`	the size of the icons
`--pyTooling-copy-color`	`#666`	the colour of a copy button
`--pyTooling-copy-hover-color`	`#06f`	the colour of a copy button under the mouse or with the keyboard focus
`--pyTooling-copy-success-color`	`#093`	the colour of a copy button, which copied its text
`--pyTooling-copy-failure-color`	`#c00`	the colour of a copy button, which couldn’t copy its text

HTML and other formats

HTML writes the table with its copy buttons. Every other format writes the table without buttons.

LaTeX writes no icons: pdfLaTeX stops at a character it has no definition for - which an emoji is -, and LuaLaTeX and XeLaTeX need an emoji font to draw one. So a table in LaTeX has no column of icons; the names and the code points identify them.

Errors

A mistake in the content is reported on the page, where the table would be, and in the build’s log:

unicode-table: The directive's content holds no entry.
unicode-table: '| a package' has a description, but no icon.
unicode-table: '📦 | a | b' has more than one separator ' | '; a '|' in a text is escaped as '\|'.
unicode-table: 'U+110000' has an invalid icon: 'U+110000' is beyond the last code point U+10FFFF.
unicode-table: 'U+D800' has an invalid icon: 'U+D800' is a surrogate code point, which is no character.

A code point not assigned in the Unicode version of unicodedata is a warning, at the icon’s line; the icon still gets its row:

unicode-table: U+0378 isn't assigned in Unicode 16.0.0, which Python's 'unicodedata' knows; its name is unknown.