{"id":"9f02ebdbee56c184","repo":"pypa/pip","slug":"format-argument-must-be-a-formatter-instance-no","errorCode":null,"errorMessage":"format() argument must be a formatter instance, not a class","messagePattern":"format\\(\\) argument must be a formatter instance, not a class","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"src/pip/_vendor/pygments/__init__.py","lineNumber":72,"sourceCode":"    Format ``tokens`` (an iterable of tokens) with the formatter ``formatter``\n    (a `Formatter` instance).\n\n    If ``outfile`` is given and a valid file object (an object with a\n    ``write`` method), the result will be written to it, otherwise it\n    is returned as a string.\n    \"\"\"\n    try:\n        if not outfile:\n            realoutfile = getattr(formatter, 'encoding', None) and BytesIO() or StringIO()\n            formatter.format(tokens, realoutfile)\n            return realoutfile.getvalue()\n        else:\n            formatter.format(tokens, outfile)\n    except TypeError:\n        # Heuristic to catch a common mistake.\n        from pip._vendor.pygments.formatter import Formatter\n        if isinstance(formatter, type) and issubclass(formatter, Formatter):\n            raise TypeError('format() argument must be a formatter instance, '\n                            'not a class')\n        raise\n\n\ndef highlight(code, lexer, formatter, outfile=None):\n    \"\"\"\n    This is the most high-level highlighting function. It combines `lex` and\n    `format` in one function.\n    \"\"\"\n    return format(lex(code, lexer), formatter, outfile)\n","sourceCodeStart":54,"sourceCodeEnd":83,"githubUrl":"https://github.com/pypa/pip/blob/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_vendor/pygments/__init__.py#L54-L83","documentation":"Raised as TypeError by pygments.format() when the formatter argument is a Formatter *class* instead of an *instance*. format() calls formatter.format(tokens, outfile); with the class this raises TypeError, which the heuristic detects (issubclass(formatter, Formatter)) and re-raises with this message.","triggerScenarios":"Calling pygments.format(tokens, HtmlFormatter) (class) instead of pygments.format(tokens, HtmlFormatter()). The except-TypError branch recognizes a Formatter subclass and raises the clearer error.","commonSituations":"Forgetting parentheses when constructing the formatter, or passing the class directly to highlight()/format().","solutions":["Instantiate the formatter: pass HtmlFormatter() to format().","Use pygments.formatters.get_formatter_by_name('html') to get a ready instance.","Verify the variable holds an instance before calling format/highlight."],"exampleFix":"# before\nfrom pygments import format\nfrom pygments.formatters import HtmlFormatter\nout = format(tokens, HtmlFormatter)  # TypeError\n\n# after\nout = format(tokens, HtmlFormatter())","handlingStrategy":"type-guard","validationCode":"from pygments.formatter import Formatter\nif isinstance(formatter, type) and issubclass(formatter, Formatter):\n    raise TypeError('pass a formatter instance, not the class')\npygments.format(tokens, formatter)","typeGuard":"def is_formatter_instance(obj) -> bool:\n    from pygments.formatter import Formatter\n    return not isinstance(obj, type) and isinstance(obj, Formatter)","tryCatchPattern":"try:\n    out = pygments.format(tokens, formatter)\nexcept TypeError as e:\n    if 'must be a formatter instance' in str(e):\n        out = pygments.format(tokens, formatter())\n    raise","preventionTips":["Always instantiate formatter classes with parentheses.","Use get_formatter_by_name() for ready instances."],"tags":["python","pygments","formatter","api-misuse"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}