{"record":{"id":"4ce0a3751d4485f4","repo":"pola-rs/polars","slug":"invalid-input-for-copy-copy-r","errorCode":null,"errorMessage":"invalid input for `copy`: {copy!r}","messagePattern":"invalid input for `copy`: (.+?)","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/dataframe/frame.py","lineNumber":1022,"sourceCode":"    ) -> np.ndarray[Any, Any]:\n        \"\"\"\n        Return a NumPy ndarray with the given data type.\n\n        This method ensures a Polars DataFrame can be treated as a NumPy ndarray.\n        It enables `np.asarray` and NumPy universal functions.\n\n        See the NumPy documentation for more information:\n        https://numpy.org/doc/stable/user/basics.interoperability.html#the-array-method\n        \"\"\"\n        if copy is None:\n            writable, allow_copy = False, True\n        elif copy is True:\n            writable, allow_copy = True, True\n        elif copy is False:\n            writable, allow_copy = False, False\n        else:\n            msg = f\"invalid input for `copy`: {copy!r}\"\n            raise TypeError(msg)\n\n        arr = self.to_numpy(writable=writable, allow_copy=allow_copy)\n\n        if dtype is not None and dtype != arr.dtype:\n            if copy is False:\n                # TODO: Only raise when data must be copied\n                msg = f\"copy not allowed: cast from {arr.dtype} to {dtype} prohibited\"\n                raise RuntimeError(msg)\n\n            arr = arr.__array__(dtype)\n\n        return arr\n\n    @deprecated(\n        \"Support for the dataframe interchange protocol is deprecated since version 1.40.0\"\n    )\n    def __dataframe__(\n        self,","sourceCodeStart":1004,"sourceCodeEnd":1040,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/dataframe/frame.py#L1004-L1040","documentation":"DataFrame.__array__ maps the NumPy copy protocol's copy parameter to (writable, allow_copy): None -> (False, True), True -> (True, True), False -> (False, False). Any other value (strings like 'if-needed', np._CopyMode enum members, non-bool objects) has no mapping and raises TypeError.","triggerScenarios":"np.array(df, copy=np._CopyMode.IF_NEEDED) or copy='if-needed'; passing np.copy semantics strings from other array libraries; a custom wrapper calling df.__array__(copy=some_int) directly.","commonSituations":"Interoperability code targeting array-api copy modes; migrating from libraries that accept string copy modes (numpy accepts np._CopyMode enums in its own API but the level-1 __array__ protocol here only handles tri-state bool/None).","solutions":["Pass only True, False, or None for copy when invoking df.__array__ / np.array on a DataFrame","Translate np._CopyMode.ALWAYS->True, NEVER->False, IF_NEEDED->None before calling","Prefer the public df.to_numpy(writable=..., allow_copy=...) which has explicit flags"],"exampleFix":"# before\nnp.array(df, copy=np._CopyMode.IF_NEEDED)  # TypeError\n\n# after\nnp.array(df, copy=None)","handlingStrategy":"type-guard","validationCode":"import numpy as np\n\nCOPY_MODE_MAP = {\n    np._CopyMode.ALWAYS: True,\n    np._CopyMode.NEVER: False,\n    np._CopyMode.IF_NEEDED: None,\n}\ncopy_arg = COPY_MODE_MAP.get(copy, copy)  # translate before calling\nif copy_arg not in (True, False, None):\n    raise TypeError(f'copy must be True/False/None, got {copy!r}')","typeGuard":"def is_valid_copy_flag(c: object) -> bool:\n    return c is None or isinstance(c, bool)","tryCatchPattern":null,"preventionTips":["Only pass True/False/None for copy on the DataFrame/NumPy boundary","Translate np._CopyMode enums at your library's edge before forwarding","Prefer df.to_numpy(writable=, allow_copy=) for explicit control"],"tags":["numpy-interop","copy-semantics","array-protocol"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}