1bcb869b6b
Due to a wrong reST header, there were two top-level headers on that page, leading to the subtitle “Style rules” being displayed on https://pygments.org/docs/ as if it were a separate section. Also harmonize the title.
157 lines
4.9 KiB
ReStructuredText
157 lines
4.9 KiB
ReStructuredText
.. -*- mode: rst -*-
|
|
|
|
======
|
|
Styles
|
|
======
|
|
|
|
Pygments comes with :doc:`some builtin styles </styles/>` that work for both the
|
|
HTML and LaTeX formatter.
|
|
|
|
The builtin styles can be looked up with the `get_style_by_name` function:
|
|
|
|
.. sourcecode:: pycon
|
|
|
|
>>> from pygments.styles import get_style_by_name
|
|
>>> get_style_by_name('colorful')
|
|
<class 'pygments.styles.colorful.ColorfulStyle'>
|
|
|
|
You can pass a instance of a `Style` class to a formatter as the `style`
|
|
option in form of a string:
|
|
|
|
.. sourcecode:: pycon
|
|
|
|
>>> from pygments.styles import get_style_by_name
|
|
>>> from pygments.formatters import HtmlFormatter
|
|
>>> HtmlFormatter(style='colorful').style
|
|
<class 'pygments.styles.colorful.ColorfulStyle'>
|
|
|
|
Or you can also import your own style (which must be a subclass of
|
|
`pygments.style.Style`) and pass it to the formatter:
|
|
|
|
.. sourcecode:: pycon
|
|
|
|
>>> from yourapp.yourmodule import YourStyle
|
|
>>> from pygments.formatters import HtmlFormatter
|
|
>>> HtmlFormatter(style=YourStyle).style
|
|
<class 'yourapp.yourmodule.YourStyle'>
|
|
|
|
|
|
Creating Own Styles
|
|
===================
|
|
|
|
See :doc:`styledevelopment`.
|
|
|
|
|
|
Builtin Styles
|
|
==============
|
|
|
|
Pygments ships some builtin styles which are maintained by the Pygments team.
|
|
|
|
To get a list of known styles you can use this snippet:
|
|
|
|
.. sourcecode:: pycon
|
|
|
|
>>> from pygments.styles import STYLE_MAP
|
|
>>> STYLE_MAP.keys()
|
|
['default', 'emacs', 'friendly', 'colorful']
|
|
|
|
|
|
Getting a list of available styles
|
|
==================================
|
|
|
|
.. versionadded:: 0.6
|
|
|
|
Because it could be that a plugin registered a style, there is
|
|
a way to iterate over all styles:
|
|
|
|
.. sourcecode:: pycon
|
|
|
|
>>> from pygments.styles import get_all_styles
|
|
>>> styles = list(get_all_styles())
|
|
|
|
|
|
.. _AnsiTerminalStyle:
|
|
|
|
Terminal Styles
|
|
===============
|
|
|
|
.. versionadded:: 2.2
|
|
|
|
Custom styles used with the 256-color terminal formatter can also map colors to
|
|
use the 8 default ANSI colors. To do so, use ``ansigreen``, ``ansibrightred`` or
|
|
any other colors defined in :data:`pygments.style.ansicolors`. Foreground ANSI
|
|
colors will be mapped to the corresponding `escape codes 30 to 37
|
|
<https://en.wikipedia.org/wiki/ANSI_escape_code#Colors>`_ thus respecting any
|
|
custom color mapping and themes provided by many terminal emulators. Light
|
|
variants are treated as foreground color with and an added bold flag.
|
|
``bg:ansi<color>`` will also be respected, except the light variant will be the
|
|
same shade as their dark variant.
|
|
|
|
See the following example where the color of the string ``"hello world"`` is
|
|
governed by the escape sequence ``\x1b[34;01m`` (Ansi bright blue, Bold, 41 being red
|
|
background) instead of an extended foreground & background color.
|
|
|
|
.. sourcecode:: pycon
|
|
|
|
>>> from pygments import highlight
|
|
>>> from pygments.style import Style
|
|
>>> from pygments.token import Token
|
|
>>> from pygments.lexers import Python3Lexer
|
|
>>> from pygments.formatters import Terminal256Formatter
|
|
|
|
>>> class MyStyle(Style):
|
|
styles = {
|
|
Token.String: 'ansibrightblue bg:ansibrightred',
|
|
}
|
|
|
|
>>> code = 'print("Hello World")'
|
|
>>> result = highlight(code, Python3Lexer(), Terminal256Formatter(style=MyStyle))
|
|
>>> print(result.encode())
|
|
b'\x1b[34;41;01m"\x1b[39;49;00m\x1b[34;41;01mHello World\x1b[39;49;00m\x1b[34;41;01m"\x1b[39;49;00m'
|
|
|
|
Colors specified using ``ansi*`` are converted to a default set of RGB colors
|
|
when used with formatters other than the terminal-256 formatter.
|
|
|
|
By definition of ANSI, the following colors are considered "light" colors, and
|
|
will be rendered by most terminals as bold:
|
|
|
|
- "brightblack" (darkgrey), "brightred", "brightgreen", "brightyellow", "brightblue",
|
|
"brightmagenta", "brightcyan", "white"
|
|
|
|
The following are considered "dark" colors and will be rendered as non-bold:
|
|
|
|
- "black", "red", "green", "yellow", "blue", "magenta", "cyan",
|
|
"gray"
|
|
|
|
Exact behavior might depends on the terminal emulator you are using, and its
|
|
settings.
|
|
|
|
.. _new-ansi-color-names:
|
|
|
|
.. versionchanged:: 2.4
|
|
|
|
The definition of the ANSI color names has changed.
|
|
New names are easier to understand and align to the colors used in other projects.
|
|
|
|
===================== ====================
|
|
New names Pygments up to 2.3
|
|
===================== ====================
|
|
``ansiblack`` ``#ansiblack``
|
|
``ansired`` ``#ansidarkred``
|
|
``ansigreen`` ``#ansidarkgreen``
|
|
``ansiyellow`` ``#ansibrown``
|
|
``ansiblue`` ``#ansidarkblue``
|
|
``ansimagenta`` ``#ansipurple``
|
|
``ansicyan`` ``#ansiteal``
|
|
``ansigray`` ``#ansilightgray``
|
|
``ansibrightblack`` ``#ansidarkgray``
|
|
``ansibrightred`` ``#ansired``
|
|
``ansibrightgreen`` ``#ansigreen``
|
|
``ansibrightyellow`` ``#ansiyellow``
|
|
``ansibrightblue`` ``#ansiblue``
|
|
``ansibrightmagenta`` ``#ansifuchsia``
|
|
``ansibrightcyan`` ``#ansiturquoise``
|
|
``ansiwhite`` ``#ansiwhite``
|
|
===================== ====================
|
|
|
|
Old ANSI color names are deprecated but will still work.
|