venv/lib/python3.11/site-packages/pip/_vendor/pygments/__init__.py

   1 """
   2     Pygments
   3     ~~~~~~~~
   4
   5     Pygments is a syntax highlighting package written in Python.
   6
   7     It is a generic syntax highlighter for general use in all kinds of software
   8     such as forum systems, wikis or other applications that need to prettify
   9     source code. Highlights are:
  10
  11     * a wide range of common languages and markup formats is supported
  12     * special attention is paid to details, increasing quality by a fair amount
  13     * support for new languages and formats are added easily
  14     * a number of output formats, presently HTML, LaTeX, RTF, SVG, all image
  15       formats that PIL supports, and ANSI sequences
  16     * it is usable as a command-line tool and as a library
  17     * ... and it highlights even Brainfuck!
  18
  19     The `Pygments master branch`_ is installable with ``easy_install Pygments==dev``.
  20
  21     .. _Pygments master branch:
  22        https://github.com/pygments/pygments/archive/master.zip#egg=Pygments-dev
  23
  24     :copyright: Copyright 2006-2023 by the Pygments team, see AUTHORS.
  25     :license: BSD, see LICENSE for details.
  26 """
  27 from io import StringIO, BytesIO
  28
  29 __version__ = '2.15.1'
  30 __docformat__ = 'restructuredtext'
  31
  32 __all__ = ['lex', 'format', 'highlight']
  33
  34
  35 def lex(code, lexer):
  36     """
  37     Lex `code` with the `lexer` (must be a `Lexer` instance)
  38     and return an iterable of tokens. Currently, this only calls
  39     `lexer.get_tokens()`.
  40     """
  41     try:
  42         return lexer.get_tokens(code)
  43     except TypeError:
  44         # Heuristic to catch a common mistake.
  45         from pip._vendor.pygments.lexer import RegexLexer
  46         if isinstance(lexer, type) and issubclass(lexer, RegexLexer):
  47             raise TypeError('lex() argument must be a lexer instance, '
  48                             'not a class')
  49         raise
  50
  51
  52 def format(tokens, formatter, outfile=None):  # pylint: disable=redefined-builtin
  53     """
  54     Format ``tokens`` (an iterable of tokens) with the formatter ``formatter``
  55     (a `Formatter` instance).
  56
  57     If ``outfile`` is given and a valid file object (an object with a
  58     ``write`` method), the result will be written to it, otherwise it
  59     is returned as a string.
  60     """
  61     try:
  62         if not outfile:
  63             realoutfile = getattr(formatter, 'encoding', None) and BytesIO() or StringIO()
  64             formatter.format(tokens, realoutfile)
  65             return realoutfile.getvalue()
  66         else:
  67             formatter.format(tokens, outfile)
  68     except TypeError:
  69         # Heuristic to catch a common mistake.
  70         from pip._vendor.pygments.formatter import Formatter
  71         if isinstance(formatter, type) and issubclass(formatter, Formatter):
  72             raise TypeError('format() argument must be a formatter instance, '
  73                             'not a class')
  74         raise
  75
  76
  77 def highlight(code, lexer, formatter, outfile=None):
  78     """
  79     This is the most high-level highlighting function. It combines `lex` and
  80     `format` in one function.
  81     """
  82     return format(lex(code, lexer), formatter, outfile)