{"record":{"id":"b7aa4741ad4c1da3","repo":"python/cpython","slug":"the-value-with-fake-globals-format-is-for-internal","errorCode":null,"errorMessage":"The VALUE_WITH_FAKE_GLOBALS format is for internal use only","messagePattern":"The VALUE_WITH_FAKE_GLOBALS format is for internal use only","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"Lib/annotationlib.py","lineNumber":716,"sourceCode":"    can be called with any of the format arguments in the Format enum, but\n    compiler-generated __annotate__ functions only support the VALUE format.\n    This function provides additional functionality to call __annotate__\n    functions with the FORWARDREF and STRING formats.\n\n    *annotate* must be an __annotate__ function, which takes a single argument\n    and returns a dict of annotations.\n\n    *format* must be a member of the Format enum or one of the corresponding\n    integer values.\n\n    *owner* can be the object that owns the annotations (i.e., the module,\n    class, or function that the __annotate__ function derives from). With the\n    FORWARDREF format, it is used to provide better evaluation capabilities\n    on the generated ForwardRef objects.\n\n    \"\"\"\n    if format == Format.VALUE_WITH_FAKE_GLOBALS:\n        raise ValueError(\"The VALUE_WITH_FAKE_GLOBALS format is for internal use only\")\n    try:\n        return annotate(format)\n    except NotImplementedError:\n        pass\n    if format == Format.STRING:\n        # STRING is implemented by calling the annotate function in a special\n        # environment where every name lookup results in an instance of _Stringifier.\n        # _Stringifier supports every dunder operation and returns a new _Stringifier.\n        # At the end, we get a dictionary that mostly contains _Stringifier objects (or\n        # possibly constants if the annotate function uses them directly). We then\n        # convert each of those into a string to get an approximation of the\n        # original source.\n\n        # Attempt to call with VALUE_WITH_FAKE_GLOBALS to check if it is implemented\n        # See: https://github.com/python/cpython/issues/138764\n        # Only fail on NotImplementedError\n        try:\n            annotate(Format.VALUE_WITH_FAKE_GLOBALS)","sourceCodeStart":698,"sourceCodeEnd":734,"githubUrl":"https://github.com/python/cpython/blob/bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6/Lib/annotationlib.py#L698-L734","documentation":"call_annotate_function() explicitly rejects Format.VALUE_WITH_FAKE_GLOBALS. That format exists only for CPython-internal use: it runs the annotate function in a sandbox where global name lookups return sentinel objects, and it is not part of the public annotation contract. Passing it as a caller is treated as API misuse and raises ValueError.","triggerScenarios":"annotationlib.call_annotate_function(func, format=Format.VALUE_WITH_FAKE_GLOBALS); passing the raw integer value of that enum member; copy-pasting internal CPython code that uses the format into application code.","commonSituations":"Developers exploring PEP 649 internals and reusing private formats; code that iterates over all Format enum members and calls the API with each; version upgrades where the enum gained new members not intended for public use.","solutions":["Use Format.VALUE, Format.STRING, or Format.FORWARDREF instead — these are the public formats.","If you need string-like capture of unresolved names, use Format.STRING; for lazy evaluation use FORWARDREF.","Filter VALUE_WITH_FAKE_GLOBALS out when iterating over Format members."],"exampleFix":"# before\nann = annotationlib.call_annotate_function(func.__annotate__, format=Format.VALUE_WITH_FAKE_GLOBALS)\n\n# after\nann = annotationlib.call_annotate_function(func.__annotate__, format=Format.FORWARDREF)","handlingStrategy":"validation","validationCode":"from annotationlib import Format\n\nPUBLIC_FORMATS = {Format.VALUE, Format.STRING, Format.FORWARDREF}\n\ndef check_format(fmt):\n    if fmt not in PUBLIC_FORMATS:\n        raise ValueError(f'use one of {PUBLIC_FORMATS}, not {fmt!r}')","typeGuard":"from annotationlib import Format\n\ndef is_public_format(fmt) -> bool:\n    return fmt in (Format.VALUE, Format.STRING, Format.FORWARDREF)","tryCatchPattern":"try:\n    ann = annotationlib.call_annotate_function(annotate, format=fmt)\nexcept ValueError as e:\n    if 'internal use only' in str(e):\n        fmt = Format.STRING  # fall back to a public format\n        ann = annotationlib.call_annotate_function(annotate, format=fmt)\n    else:\n        raise","preventionTips":["Only pass the three public Format members","Do not iterate all Format enum members blindly into APIs","Treat VALUE_WITH_FAKE_GLOBALS as private CPython surface"],"tags":["python","annotations","pep649","api-misuse","format-enum"],"backgroundTag":null,"analyzedSha":"bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6","analyzedAt":"2026-08-14T22:01:13.976Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}