jorisvandenbossche commented on code in PR #55264: URL: https://github.com/apache/arrow/pull/55264#discussion_r4515219800
########## python/pyarrow-stubs/pyarrow/__lib/array.pyi: ########## @@ -0,0 +1,613 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +import sys + +from collections.abc import Iterable, Iterator, Sequence + +if sys.version_info >= (3, 11): + from typing import Self +else: + from typing_extensions import Self + +from typing import Any, Literal + +import numpy as np # type: ignore[import-not-found] +import pandas as pd # type: ignore[import-not-found,import-untyped] + +from pyarrow._compute import CastOptions +from pyarrow._stubs_typing import ( + ArrayLike, + Indices, + Mask, + MapsAsPydicts, + Order, + SupportsArrowArray, + SupportsArrowDeviceArray, + SupportsPyArrowArray, +) +from pyarrow.lib import ( + Buffer, + Device, + MemoryManager, + MemoryPool, + Tensor, + _Weakrefable, +) +from typing_extensions import deprecated +import builtins + +from .scalar import Int64Scalar, Scalar +from .device import DeviceAllocationType +from .types import BaseExtensionType, DataType, Field, StructType +from pyarrow._stubs_typing import NullableCollection + +def array( + values: Iterable[Any] + | SupportsArrowArray + | SupportsArrowDeviceArray + | SupportsPyArrowArray, + type: Any | None = None, + mask: Mask | pd.Series[bool] | None = None, Review Comment: Further point, it is not actually just `pd.Series` that is accepted, but Series, Index or ExtensionArray ... Also, even the `Sequence` is not actually correct, because our code uses `PySequence_Check` C API, which does not match with the python level Sequence ABC (it just checks for having getitem, and by getting the size that it has a length). So personally, I would keep things simple for now (maybe even just `Iterable`, which is too broad, but would not incorrectly disallow things, or otherwise `Collection`, which would incorrectly flag some allowed input), and worry in a future issue/PR about how to best describe (with a typing protocol) the accepted inputs. TIL: static type checkers use nominal or structural subtype checking depending on the exact ABC class. For Collection and Sequence, that is nominal, meaning the passed object (like a pd.Series) actually has to inherit from the protocol in python (and not just implement the expected methods, i.e. that is the reason a pd.Series is not considered a a Sequence, although it quakes perfectly as one). So in general, typing the arguments of `pa.array()` here with a protocol that uses nominal subtype checking is never going to be perfect in practice, since our code is more flexible about input arguments. And so long term we probably best define our own protocol for input arguments? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
