""" pygments.formatter ~~~~~~~~~~~~~~~~~~ Base formatter class. :copyright: Copyright 2006-2023 by the Pygments team, see AUTHORS. :license: BSD, see LICENSE for details. """ import codecs from pip._vendor.pygments.util import get_bool_opt from pip._vendor.pygments.styles import get_style_by_name __all__ = ['Formatter'] def _lookup_style(style): if isinstance(style, str): return get_style_by_name(style) return style class Formatter: """ Converts a token stream to text. Formatters should have attributes to help selecting them. These are similar to the corresponding :class:`~pygments.lexer.Lexer` attributes. .. autoattribute:: name :no-value: .. autoattribute:: aliases :no-value: .. autoattribute:: filenames :no-value: You can pass options as keyword arguments to the constructor. All formatters accept these basic options: ``style`` The style to use, can be a string or a Style subclass (default: "default"). Not used by e.g. the TerminalFormatter. ``full`` Tells the formatter to output a "full" document, i.e. a complete self-contained document. This doesn't have any effect for some formatters (default: false). ``title`` If ``full`` is true, the title that should be used to caption the document (default: ''). ``encoding`` If given, must be an encoding name. This will be used to convert the Unicode token strings to byte strings in the output. If it is "" or None, Unicode strings will be written to the output file, which most file-like objects do not support (default: None). ``outencoding`` Overrides ``encoding`` if given. """ #: Full name for the formatter, in human-readable form. name = None #: A list of short, unique identifiers that can be used to lookup #: the formatter from a list, e.g. using :func:`.get_formatter_by_name()`. aliases = [] #: A list of fnmatch patterns that match filenames for which this #: formatter can produce output. The patterns in this list should be unique #: among all formatters. filenames = [] #: If True, this formatter outputs Unicode strings when no encoding #: option is given. unicodeoutput = True def __init__(self, **options): """ As with lexers, this constructor takes arbitrary optional arguments, and if you override it, you should first process your own options, then call the base class implementation. """ self.style = _lookup_style(options.get('style', 'default')) self.full = get_bool_opt(options, 'full', False) self.title = options.get('title', '') self.encoding = options.get('encoding', None) or None if self.encoding in ('guess', 'chardet'): # can happen for e.g. pygmentize -O encoding=guess self.encoding = 'utf-8' self.encoding = options.get('outencoding') or self.encoding self.options = options def get_style_defs(self, arg=''): """ This method must return statements or declarations suitable to define the current style for subsequent highlighted text (e.g. CSS classes in the `HTMLFormatter`). The optional argument `arg` can be used to modify the generation and is formatter dependent (it is standardized because it can be given on the command line). This method is called by the ``-S`` :doc:`command-line option <cmdline>`, the `arg` is then given by the ``-a`` option. """ return '' def format(self, tokensource, outfile): """ This method must format the tokens from the `tokensource` iterable and write the formatted version to the file object `outfile`. Formatter options can control how exactly the tokens are converted. """ if self.encoding: # wrap the outfile in a StreamWriter outfile = codecs.lookup(self.encoding)[3](outfile) return self.format_unencoded(tokensource, outfile)