tessl/pypi-pygments

A syntax highlighting package that supports over 500 programming languages and text formats with extensive output format options

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

High-Level API

Name: tessl/pypi-pygments
Author: tessl

The high-level API provides the most convenient interface for syntax highlighting tasks. These three functions form the core of Pygments and can handle most common highlighting needs.

Capabilities

Lexical Analysis

Tokenizes source code using a lexer and returns an iterable of tokens.

def lex(code: str, lexer) -> Iterator[tuple[TokenType, str]]:
    """
    Lex code with the lexer and return an iterable of tokens.
    
    Parameters:
    - code: Source code string to tokenize
    - lexer: Lexer instance (must be instantiated, not a class)
    
    Returns:
    Iterator of (token_type, value) tuples
    
    Raises:
    TypeError: If lexer is a class instead of an instance
    """

Usage example:

from pygments import lex
from pygments.lexers import PythonLexer

code = "print('Hello, World!')"
lexer = PythonLexer()
tokens = list(lex(code, lexer))
# tokens: [(Token.Name.Builtin, 'print'), (Token.Punctuation, '('), ...]

Token Formatting

Formats a token stream using a formatter and optionally writes to a file.

def format(tokens: Iterator[tuple[TokenType, str]], formatter, outfile=None) -> str:
    """
    Format tokens with the formatter.
    
    Parameters:
    - tokens: Iterable of (token_type, value) tuples
    - formatter: Formatter instance (must be instantiated, not a class)
    - outfile: Optional file object with write() method
    
    Returns:
    Formatted string if outfile is None, otherwise None (writes to outfile)
    
    Raises:
    TypeError: If formatter is a class instead of an instance
    """

Usage example:

from pygments import lex, format
from pygments.lexers import PythonLexer
from pygments.formatters import HtmlFormatter

code = "print('Hello, World!')"
tokens = lex(code, PythonLexer())
result = format(tokens, HtmlFormatter())
# result: '<div class="highlight"><pre><span></span><span class="nb">print</span>...'

Complete Highlighting

Combines lexing and formatting in a single function call.

def highlight(code: str, lexer, formatter, outfile=None) -> str:
    """
    High-level highlighting function combining lex and format.
    
    Parameters:
    - code: Source code string to highlight
    - lexer: Lexer instance for tokenization
    - formatter: Formatter instance for output generation
    - outfile: Optional file object with write() method
    
    Returns:
    Formatted string if outfile is None, otherwise None (writes to outfile)
    """

Usage example:

from pygments import highlight
from pygments.lexers import PythonLexer
from pygments.formatters import HtmlFormatter

code = '''
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)
'''

result = highlight(code, PythonLexer(), HtmlFormatter())
print(result)  # HTML with syntax highlighting

File Output

All three functions support writing directly to files:

# Write to file
with open('output.html', 'w') as f:
    highlight(code, PythonLexer(), HtmlFormatter(), outfile=f)

# Or collect as string
html_output = highlight(code, PythonLexer(), HtmlFormatter())

Error Handling

Common errors when using the high-level API:

TypeError: Passing lexer or formatter classes instead of instances
Encoding errors: When working with binary data or mixed encodings

# Incorrect - will raise TypeError
from pygments.lexers import PythonLexer
from pygments.formatters import HtmlFormatter
result = highlight(code, PythonLexer, HtmlFormatter)  # Classes, not instances

# Correct - instantiate the classes
result = highlight(code, PythonLexer(), HtmlFormatter())  # Instances

Install with Tessl CLI