{"record":{"id":"73f9c6c571e63548","repo":"pola-rs/polars","slug":"it-is-not-allowed-to-create-a-compatlevel-object","errorCode":null,"errorMessage":"it is not allowed to create a CompatLevel object","messagePattern":"it is not allowed to create a CompatLevel object","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/interchange/protocol.py","lineNumber":262,"sourceCode":"\n    LITTLE = \"<\"\n    BIG = \">\"\n    NATIVE = \"=\"\n    NA = \"|\"\n\n\nclass CopyNotAllowedError(RuntimeError):\n    \"\"\"Exception raised when a copy is required, but `allow_copy` is set to `False`.\"\"\"\n\n\nclass CompatLevel:\n    \"\"\"Data structure compatibility level.\"\"\"\n\n    _version: int\n\n    def __init__(self) -> None:\n        msg = \"it is not allowed to create a CompatLevel object\"\n        raise TypeError(msg)\n\n    @staticmethod\n    def _with_version(version: int) -> CompatLevel:\n        compat_level = CompatLevel.__new__(CompatLevel)\n        compat_level._version = version\n        return compat_level\n\n    @staticmethod\n    def _newest() -> CompatLevel:\n        return CompatLevel._future1  # type: ignore[attr-defined]\n\n    @staticmethod\n    def newest() -> CompatLevel:\n        \"\"\"\n        Get the highest supported compatibility level.\n\n        .. warning::\n            Highest compatibility level is considered **unstable**. It may be changed","sourceCodeStart":244,"sourceCodeEnd":280,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/interchange/protocol.py#L244-L280","documentation":"CompatLevel is a sentinel-style class: its __init__ unconditionally raises TypeError. Valid instances exist only as pre-created class singletons built internally via _with_version, and user code obtains them through the factory methods CompatLevel.oldest() and CompatLevel.newest(), which are accepted wherever polars APIs take a compat_level argument (e.g. serialization controls). Direct construction, or operations like copy/deepcopy/unpickling that re-run __init__, trigger this error.","triggerScenarios":"Calling pl.CompatLevel() directly; copy.copy / copy.deepcopy / pickle round-trips that reconstruct through __init__; test doubles or subclasses that instantiate CompatLevel.","commonSituations":"Passing compat_level options to polars serialization APIs and mistakenly constructing the object; code copied from examples of other option classes; pickling DataFrames or configs that reference a CompatLevel instance.","solutions":["Use the factories: pl.CompatLevel.oldest() for maximum compatibility, pl.CompatLevel.newest() for the newest level","For copies or unpickling, re-fetch the singleton by version instead of reconstructing the object","If you need a level that does not exist, file a feature request - custom versions are not supported"],"exampleFix":"// before\ncompat = pl.CompatLevel()  # TypeError: it is not allowed to create a CompatLevel object\n\n// after\ncompat = pl.CompatLevel.oldest()   # or pl.CompatLevel.newest()\ndf.write_csv('out.csv', compat_level=compat)","handlingStrategy":"validation","validationCode":"import polars as pl\n\n# correct way to obtain a CompatLevel - never construct it\ncompat = pl.CompatLevel.oldest()   # or pl.CompatLevel.newest()\n\n# guard before passing compat_level around\ndef is_compat_level(obj: object) -> bool:\n    return isinstance(obj, type(pl.CompatLevel.oldest()))","typeGuard":"import polars as pl\n\ndef is_compat_level(value: object) -> bool:\n    \"\"\"True for valid, factory-produced CompatLevel singletons.\"\"\"\n    return isinstance(value, pl.CompatLevel)","tryCatchPattern":"try:\n    compat = pl.CompatLevel()\nexcept TypeError:\n    compat = pl.CompatLevel.oldest()  # fall back to the factory method","preventionTips":["Never call pl.CompatLevel() - only CompatLevel.oldest() and CompatLevel.newest() are supported","Store the version int, not the object, across pickle/copy boundaries, and re-fetch the singleton after loading","Treat CompatLevel as an opaque token; do not subclass or instantiate it in tests - use the factories"],"tags":["polars","compatlevel","singleton","type-error","api-misuse"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}