{"record":{"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":"validation","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/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_vendor/pygments/__init__.py#L54-L83","documentation":"Raised by pygments.format() when the formatter argument is a Formatter *subclass* rather than an *instance*. format() calls formatter.format(...); a TypeError triggers a heuristic check (is the arg a class subclassing Formatter?) and re-raises this clearer message. Mirrors the analogous lexer guard.","triggerScenarios":"Calling pygments.format(tokens, HtmlFormatter) (class) instead of pygments.format(tokens, HtmlFormatter()). The TypeError from an unbound method call triggers __init__.py:68-74.","commonSituations":"Passing the formatter class directly after constructing tokens manually; example code that omits the parentheses; switching from get_formatter_by_name (returns instance) to a direct class.","solutions":["Instantiate the formatter: format(tokens, HtmlFormatter()).","Use get_formatter_by_name('html') which returns an instance.","Pass instances, not classes, to the top-level highlight() helper."],"exampleFix":"# before\nfrom pip._vendor.pygments.formatters import HtmlFormatter\nout = pygments.format(tokens, HtmlFormatter)\n# after\nout = pygments.format(tokens, HtmlFormatter())","handlingStrategy":"type-guard","validationCode":"from inspect import isclass\nif isclass(formatter):\n    raise TypeError('pass a formatter instance, not the class')","typeGuard":"def is_formatter_instance(obj) -> bool:\n    from pip._vendor.pygments.formatter import Formatter\n    return isinstance(obj, Formatter)","tryCatchPattern":"try:\n    out = pygments.format(tokens, formatter)\nexcept TypeError as e:\n    if 'formatter instance' in str(e):\n        formatter = formatter()\n        out = pygments.format(tokens, formatter)\n    else:\n        raise","preventionTips":["Always instantiate: FormatterClass().","Prefer get_formatter_by_name which returns instances."],"tags":["python","pygments","formatter","validation","vendored"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}