pyTooling.Sphinx.UnicodeTable

A Sphinx directive listing Unicode characters with their names and code points.

The characters are icons, e.g. the ones a tree draws. An icon written as a character is hard to type, and written as a code point hard to recognize. The unicode-table directive takes the icons as content, one per line, and computes a row per icon: the icon, its Unicode name and its code points, in the form the icon options of the tree directive take them:

.. unicode-table::

   📦       | a package
   U+1F4C1  | a directory
   ⚙️       | settings

An entry is a line holding an icon, written as characters or as code points U+<hex>, several words forming one icon - e.g. U+2699 U+FE0F. A | between spaces separates the icon from its description, which is inline ReST.

Names and code points

The names are Python’s unicodedata’s, so a row can’t contradict its icon. A sequence is named by its characters, joined by +; a variation selector and the zero width joiner select how the characters are drawn, and don’t count: ⚙️ - U+2699 U+FE0F - is named GEAR. A character without a name gets the label the Unicode standard gives it, e.g. <private-use-E000>. A code point not assigned in the Unicode version of unicodedata is warned about, as its name is unknown.

HTML and other formats

HTML writes a CopyButton beside an icon and beside its code points, which copies them into the clipboard; the script pyTooling.js gives the buttons their function. Every other format finds no visitor for CopyButton and writes its base-class, an empty inline element. LaTeX writes no icons, as pdfLaTeX stops at a character it has no definition for - which an emoji is - and LuaLaTeX needs an emoji font: RemoveUnicodeGlyphs removes the icons’ column.

See also

unicode-table

→ The directive’s options, with rendered examples.

Common Icons

→ Icons commonly used in a tree, listed by this directive.

Variables

Classes

  • CodePointType: The type of a code point, as the Unicode standard (section 2.4, table 2-3) defines it.

  • CodePoint: A Unicode code point: its value, and what unicodedata knows about it - its general category, its type and its

  • UnicodeEntry: An entry of a unicode-table: an icon’s characters, and the description written behind it.

  • UnicodeTable: The unicode-table directive: a table of icons, each with its Unicode name and its code points.

  • RemoveUnicodeGlyphs: A post-transform removing the icons’ column from the tables of the unicode-table directive in LaTeX.

Variables

pyTooling.Sphinx.UnicodeTable.TABLE_CLASS

The CSS class of every table the directive writes, by which RemoveUnicodeGlyphs finds them.

'pytooling-unicode-table'

Classes

class pyTooling.Sphinx.UnicodeTable.CodePointType(*values)[source]

The type of a code point, as the Unicode standard (section 2.4, table 2-3) defines it.

A code point without a name is labelled by its type (section 4.8): <control-0009>. A letter, a symbol or a format character has a name.

Inheritance

Inheritance diagram of CodePointType

Graphic = 'graphic'

A letter, mark, number, punctuation, symbol or space.

Format = 'format'

An invisible character affecting its neighbours, or a line or paragraph separator.

Control = 'control'

A control character, e.g. a tab.

PrivateUse = 'private-use'

A character assigned by a private agreement, not by Unicode.

Surrogate = 'surrogate'

Half of a UTF-16 surrogate pair, never a character of its own.

Noncharacter = 'noncharacter'

Reserved for a program’s internal use; one of the 66 noncharacters.

Reserved = 'reserved'

Not assigned in the Unicode version of unicodedata.

classmethod Parse(value)

Convert a string to the member carrying that value.

Parameters:

value (str | None) – The string to convert. None and the empty string mean no value was given.

Return type:

Self | None

Returns:

The member carrying that value. If no value was given: DEFAULT, if the enumeration declares one, otherwise None.

Raises:

  • TypeError – If parameter ‘value’ is not of type str.

  • ValueError – If no member of this enumeration carries that value.
    The note lists the values it accepts.

class pyTooling.Sphinx.UnicodeTable.CodePoint(value)[source]

A Unicode code point: its value, and what unicodedata knows about it - its general category, its type and its name.

A code point is written in the standard’s notation U+<hex> with at least four digits, e.g. U+2699 (Notation). str() returns its character.

Inheritance

Inheritance diagram of CodePoint

Parameters:

value (int)

__init__(value)[source]

Initializes a code point by its value.

Parameters:

value (int) – The code point’s value.

Raises:

  • ValueError – If parameter value is None.

  • TypeError – If parameter value isn’t of type int.

  • ValueError – If parameter value is out of range 0 to 0x10FFFF.

Return type:

None

_value: int

The code point’s value, in range 0 to 0x10FFFF.

_character: str

The code point’s character.

classmethod FromCharacter(character)[source]

Create the code point of a character.

Parameters:

character (str) – The character.

Return type:

Self

Returns:

The character’s code point.

Raises:

  • ValueError – If parameter character is None.

  • TypeError – If parameter character isn’t of type str.

  • ValueError – If parameter character isn’t a single character.

property Value: int

Read-only property to access the code point’s value (_value).

Returns:

The value.

property Character: str

Read-only property to access the code point’s character (_character).

Returns:

The character.

property Category: str

Read-only property to return the code point’s general category, as unicodedata knows it.

Returns:

The general category’s abbreviation, e.g. Lu for an uppercase letter or Cn for an unassigned code point.

property Type: CodePointType

Read-only property to return the code point’s type, derived from its general category.

A code point of category Cn is a noncharacter or reserved.

Returns:

The type.

property Name: str

Read-only property to return the code point’s name, or the label the Unicode standard gives a code point without a name.

A label is <type-XXXX>, e.g. <control-0009>, <private-use-E000>, <reserved-0378> or <noncharacter-FFFF>: the code point’s Type, and its hexadecimal value with at least four digits.

Returns:

The name, or the label.

property IsAssigned: bool

Read-only property to return whether the code point is assigned in the Unicode version of unicodedata.

A noncharacter is assigned: Unicode reserves it permanently.

Returns:

True, if the code point isn’t reserved.

property IsNoncharacter: bool

Read-only property to return whether the code point is one of the 66 noncharacters, which Unicode reserves for a program’s internal use.

The noncharacters are U+FDD0 to U+FDEF, and the last two code points of every plane, e.g. U+FFFE and U+FFFF.

Returns:

True, if the code point is a noncharacter.

property IsSelector: bool

Read-only property to return whether the code point selects how its neighbours are drawn, instead of being drawn itself.

Such a code point is a variation selector, e.g. U+FE0F selecting an emoji’s colourful presentation, or the zero width joiner U+200D, which joins emoji into one, e.g. a man and a computer into a technologist.

Returns:

True, if the code point is a variation selector or the zero width joiner.

property Notation: str

Read-only property to return the code point in the standard’s notation: U+<hex> with at least four digits.

Returns:

The code point, e.g. U+2699.

__str__()[source]

Return the code point’s character.

Return type:

str

Returns:

The character, e.g. ⚙.

__repr__()[source]

Return a representation of the code point for debugging.

Return type:

str

Returns:

The code point and its name, e.g. <CodePoint U+2699 GEAR>.

classmethod GetMethodsWithAttributes(predicate=None)

Return the class’ methods that carry at least one matching attribute.

Parameters:

predicate (type[TAttr] | Iterable[type[TAttr]] | None) – Optional, an attribute class, an iterable of attribute classes, or None to accept every attribute.

Return type:

dict[Callable[..., Any], tuple[Attribute, ...]]

Returns:

Dictionary of methods and the matching attributes attached to them.

Raises:

  • ValueError – If an element of parameter ‘predicate’ is not a sub-class of Attribute.

  • ValueError – If parameter ‘predicate’ is neither an attribute class nor an iterable of those.

__getstate__()

Return the object’s state for pickling, collecting every slot of the class hierarchy.

Return type:

dict[str, Any]

Returns:

Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If a slot was never assigned, so it has no value to serialize.

__setstate__(state)

Restore the object’s state from unpickling, requiring exactly the slots of the class hierarchy.

Parameters:

state (dict[str, Any]) – Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If the given state misses a slot or carries an unexpected one.

Return type:

None

class pyTooling.Sphinx.UnicodeTable.UnicodeEntry(characters, description, lineIndex)[source]

An entry of a unicode-table: an icon’s characters, and the description written behind it.

Name and CodePointText are computed from the characters, so they can’t contradict the icon.

Inheritance

Inheritance diagram of UnicodeEntry

Parameters:

  • characters (str)

  • description (str)

  • lineIndex (int)

characters: str

The icon’s characters, e.g. a gear and variation selector 16.

description: str

The description as inline ReST; empty if the entry has none.

lineIndex: int

Index of the entry’s line in the directive’s content.

classmethod Parse(line, lineIndex)[source]

Read an entry from a line of the directive’s content: an icon, and optionally a description behind a separator.

The icon is read as the icon options of the tree directive read theirs - see icon(): characters as written, and a word U+<hex> as the code point it names. The separator is a | between spaces - see SEPARATOR_PATTERN.

Parameters:

  • line (str) – The line, not blank.

  • lineIndex (int) – Index of the line in the directive’s content.

Return type:

Self

Returns:

The entry.

Raises:

  • SphinxExtensionError – If the line has more than one separator |.

  • SphinxExtensionError – If the line has a description, but no icon.

  • SphinxExtensionError – If a word names a code point beyond U+10FFFF, or a surrogate.

property CodePoints: list[CodePoint]

Read-only property to return the code points of the icon’s characters.

Returns:

The code points, in the order written.

property Name: str

Read-only property to return the icon’s name: the names of its characters, joined by +.

Variation selectors and the zero width joiner select how the characters are drawn and aren’t named, unless the icon consists of nothing else: U+2699 U+FE0F is named GEAR. A character without a name contributes its label - see CodePoint.Name.

Returns:

The name, e.g. GEAR or MAN + PERSONAL COMPUTER.

property CodePointText: str

Read-only property to return the icon’s code points, as the icon options of the tree directive take them.

Returns:

The code points U+<hex> with at least four digits, separated by spaces, e.g. U+2699 U+FE0F.

property UnassignedCodePoints: list[CodePoint]

Read-only property to return the code points, which aren’t assigned in the Unicode version of unicodedata.

Such a code point is a typo - or newer than the Python running the build: Python 3.12 knows Unicode 15.0.

Returns:

The unassigned code points, in the order written.

__add__(value, /)

Return self+value.

__contains__(key, /)

Return bool(key in self).

__eq__(value, /)

Return self==value.

__ge__(value, /)

Return self>=value.

__getitem__(key, /)

Return self[key].

__getnewargs__()

Return self as a plain tuple. Used by copy and pickle.

__gt__(value, /)

Return self>value.

__hash__()

Return hash(self).

__iter__()

Implement iter(self).

__le__(value, /)

Return self<=value.

__len__()

Return len(self).

__lt__(value, /)

Return self<value.

__mul__(value, /)

Return self*value.

__ne__(value, /)

Return self!=value.

static __new__(_cls, characters, description, lineIndex)

Create new instance of UnicodeEntry(characters, description, lineIndex)

Parameters:

  • characters (str)

  • description (str)

  • lineIndex (int)

__replace__(**kwds)

Return a new UnicodeEntry object replacing specified fields with new values

__repr__()

Return a nicely formatted representation string

__rmul__(value, /)

Return value*self.

_asdict()

Return a new dict which maps field names to their values.

classmethod _make(iterable)

Make a new UnicodeEntry object from a sequence or iterable

_replace(**kwds)

Return a new UnicodeEntry object replacing specified fields with new values

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

class pyTooling.Sphinx.UnicodeTable.UnicodeTable(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

The unicode-table directive: a table of icons, each with its Unicode name and its code points.

_ParseContent() reads the content into UnicodeEntry instances, and run() turns them into a table: the icon, its name, its code points and - if an entry has one - its description. The icon and the code points each get a CopyButton. :class: puts additional CSS classes on the table.

Inheritance

Inheritance diagram of UnicodeTable

directiveName: str = 'unicode-table'

Name the directive is invoked by.

has_content = True

A boolean; True if content is allowed.

required_arguments = 0

Number of required directive arguments.

optional_arguments = 0

Number of optional arguments after the required ones.

final_argument_whitespace = False

A boolean; True if the last argument may contain spaces.

option_spec: dict[str, Any] = {'class': <function strip>}

Mapping of option names to validator functions.

run()[source]

Write the table of the icons listed in the content.

An icon with a character, which isn’t assigned in the Unicode version of unicodedata, is warned about at its line, and still gets its row.

Return type:

list[Node]

Returns:

The table, followed by the messages about the descriptions and the unassigned characters, or the message of whatever the content got wrong.

static _ParseContent(content)[source]

Read the content into entries: an entry per line, blank lines skipped.

Parameters:

content (Iterable[str]) – The directive’s content, line by line.

Return type:

list[UnicodeEntry]

Returns:

The entries, in the order written.

Raises:

  • SphinxExtensionError – If the content holds no entry.

  • SphinxExtensionError – If a line isn’t an entry - see UnicodeEntry.Parse().

_CreateDoubleRowTableHeader(columns, identifier, classes)

Create a table whose header spans two rows, so a column can group sub-columns.

A column’s subColumns is None when it spans both header rows, and otherwise holds the (title, width) pairs below it.

Parameters:
Return type:

tgroup

Returns:

The table’s column group, with both header rows already in it.

_CreateRotatedTableHeader(columns, identifier, classes)

Create a table whose header titles are rotated, for many narrow columns.

Parameters:

  • columns (list[tuple[str, list[str] | None]]) – One (title, classes) pair per column; the classes are put on the header cell.

  • identifier (str) – Identifier of the table.

  • classes (list[str]) – CSS classes to put on the table.

Return type:

tgroup

Returns:

The table’s column group, with the header row already in it.

_CreateSingleRowTableHeader(columns, identifier, classes)

Create a table with a single header row.

Parameters:

  • columns (list[tuple[str, int | None]]) – One (title, width) pair per column; a width of None leaves it to the writer.

  • identifier (str) – Identifier of the table.

  • classes (list[str]) – CSS classes to put on the table.

Return type:

tgroup

Returns:

The table’s column group, with the header row already in it.

_ParseBooleanOption(optionName, default=None)

Read an option written as yes/true or no/false.

Parameters:

  • optionName (str) – Name of the option to read.

  • default (bool | None) – Optional, the value to return when the option wasn’t given.

Return type:

bool

Returns:

The option’s value.

Raises:

  • SphinxExtensionError – If the option wasn’t given and has no default.

  • SphinxExtensionError – If the option’s value is neither of the two accepted spellings.

_ParseEnumOption(optionName, enumType, default=None)

Read an option naming a member of an enumeration.

The written value is lowered and its dashes become underscores, so horizontal-table in a document selects the horizontal_table member - a document reads in the spelling documents use, and the enumeration keeps the spelling Python uses.

Parameters:

  • optionName (str) – Name of the option to read.

  • enumType (type[_EnumType]) – The enumeration whose members the value is looked up in.

  • default (_EnumType | None) – Optional, the member to return when the option wasn’t given.

Return type:

_EnumType

Returns:

The named member of the enumeration.

Raises:

  • SphinxExtensionError – If the option wasn’t given and has no default.

  • SphinxExtensionError – If the value names no member of the enumeration.

_ParseStringOption(optionName, default=None, regexp='\\w+')

Read an option that has to match a regular expression.

The pattern defaults to one or more word characters.

Parameters:

  • optionName (str) – Name of the option to read.

  • default (str | None) – Optional, the value to return when the option wasn’t given.

  • regexp (str) – Optional, the pattern the value has to match.

Return type:

str

Returns:

The option’s value.

Raises:

  • SphinxExtensionError – If the option wasn’t given and has no default.

  • SphinxExtensionError – If the option’s value doesn’t match the pattern.

__init__(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)
Return type:

None

_internalError(container, location, message, exception)

Report an exception a directive couldn’t recover from, in the log and on the page.

A directive that fails silently leaves a hole in the documentation that nobody notices. This puts the message where a reader sees it and the traceback where a maintainer does. The exception’s notes - e.g. how to install a missing package - are logged below it.

Parameters:

  • container (container) – The container the message is put into.

  • location (str) – Name of the logger, which is what the log line is attributed to.

  • message (str) – What went wrong, in one sentence.

  • exception (Exception) – The exception that was caught.

Return type:

list[Node]

Returns:

The container, as the list a directive’s run returns.

_object_hierarchy_parts(sig_node)

Returns a tuple of strings, one entry for each part of the object’s hierarchy (e.g. ('module', 'submodule', 'Class', 'method')). The returned tuple is used to properly nest children within parents in the table of contents, and can also be used within the _toc_entry_name() method.

This method must not be used outwith table of contents generation.

Return type:

tuple[str, ...]

Parameters:

sig_node (desc_signature)

_toc_entry_name(sig_node)

Returns the text of the table of contents entry for the object.

This function is called once, in run(), to set the name for the table of contents entry (a special attribute _toc_name is set on the object node, later used in environment.collectors.toctree.TocTreeCollector.process_doc().build_toc() when the table of contents entries are collected).

To support table of contents entries for their objects, domains must override this method, also respecting the configuration setting toc_object_entries_show_parents. Domains must also override _object_hierarchy_parts(), with one (string) entry for each part of the object’s hierarchy. The result of this method is set on the signature node, and can be accessed as sig_node['_toc_parts'] for use within this method. The resulting tuple is also used to properly nest children within parents in the table of contents.

An example implementations of this method is within the python domain (PyObject._toc_entry_name()). The python domain sets the _toc_parts attribute within the handle_signature() method.

Return type:

str

Parameters:

sig_node (desc_signature)

add_name(node)

Append self.options[‘name’] to node[‘names’] if it exists.

Also normalize the name string and register it as explicit target.

Return type:

None

add_target_and_index(name, sig, signode)

Add cross-reference IDs and entries to self.indexnode, if applicable.

name is whatever handle_signature() returned.

Return type:

None

Parameters:

  • name (ObjDescT)

  • sig (str)

  • signode (desc_signature)

after_content()

Called after parsing content.

Used to reset information about the current directive context on the build environment.

Return type:

None

assert_has_content()

Throw an ERROR-level DirectiveError if the directive doesn’t have contents.

before_content()

Called before parsing content.

Used to set information about the current directive context on the build environment.

Return type:

None

property config: Config

Reference to the Config object.

Added in version 1.8.

directive_error(level, message)

Return a DirectiveError suitable for being thrown as an exception.

Call “raise self.directive_error(level, message)” from within a directive implementation to return one single system message at level level, which automatically gets the directive block and the line number added.

Preferably use the debug, info, warning, error, or severe wrapper methods, e.g. self.error(message) to generate an ERROR-level directive error.

property env: BuildEnvironment

Reference to the BuildEnvironment object.

Added in version 1.8.

get_location()

Get current location info for logging.

Added in version 4.2.

Return type:

str

get_signatures()

Retrieve the signatures to document from the directive arguments.

By default, signatures are given as arguments, one per line.

Return type:

list[str]

get_source_info()

Get source and line number.

Added in version 3.0.

Return type:

tuple[str | None, int | None]

handle_signature(sig, signode)

Parse the signature sig.

The individual nodes are then appended to signode. If ValueError is raised, parsing is aborted and the whole sig is put into a single desc_name node.

The return value should be a value that identifies the object. It is passed to add_target_and_index() unchanged, and otherwise only used to skip duplicates.

Return type:

str

Parameters:

  • sig (str)

  • signode (desc_signature)

parse_content_to_nodes(allow_section_headings=False)

Parse the directive’s content into nodes.

Parameters:

allow_section_headings (bool) – Are titles (sections) allowed in the directive’s content? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

Return type:

list[Node]

Added in version 7.4.

parse_inline(text, *, lineno=-1)

Parse text as inline elements.

Parameters:

  • text (str) – The text to parse, which should be a single line or paragraph. This cannot contain any structural elements (headings, transitions, directives, etc).

  • lineno (int) – The line number where the interpreted text begins.

Return type:

tuple[list[Node], list[system_message]]

Returns:

A list of nodes (text and inline elements) and a list of system_messages.

Added in version 7.4.

parse_text_to_nodes(text='', /, *, offset=-1, allow_section_headings=False)

Parse text into nodes.

Parameters:

  • text (str) – Text, in string form. StringList is also accepted.

  • allow_section_headings (bool) – Are titles (sections) allowed in text? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

  • offset (int) – The offset of the content.

Return type:

list[Node]

Added in version 7.4.

set_source_info(node)

Set source and line number to the node.

Added in version 2.1.

Return type:

None

Parameters:

node (Node)

transform_content(content_node)

Can be used to manipulate the content.

Called after creating the content through nested parsing, but before the object-description-transform event is emitted, and before the info-fields are transformed.

Return type:

None

Parameters:

content_node (desc_content)

class pyTooling.Sphinx.UnicodeTable.RemoveUnicodeGlyphs(document, startnode=None)[source]

A post-transform removing the icons’ column from the tables of the unicode-table directive in LaTeX.

pdfLaTeX stops at a character it has no definition for - which an emoji is -, and LuaLaTeX needs an emoji font to draw one. The names and the code points identify the icons without it.

Inheritance

Inheritance diagram of RemoveUnicodeGlyphs

default_priority = 200

Priority among the post-transforms.

__init__(document, startnode=None)

Initial setup for in-place document transforms.

Return type:

None

property app: Sphinx

Reference to the Sphinx object.

apply(**kwargs)

Override to apply the transform to the document tree.

Return type:

None

Parameters:

kwargs (Any)

property config: Config

Reference to the Config object.

property env: BuildEnvironment

Reference to the BuildEnvironment object.

formats: tuple[str, ...] = ('latex',)

Output formats the transform runs for.

is_supported()

Check this transform working for current builder.

Return type:

bool

document

The document tree to transform.

startnode

Node from which to begin the transform. For many transforms which apply to the document as a whole, startnode is not set (i.e. its value is None).

language

Language module local to this document.

run(**kwargs)[source]

Remove the first column - the icons’ - of every table of the unicode-table directive.

Parameters:

kwargs (Any) – Keyword arguments Sphinx passes to a post-transform; none is used.

Return type:

None