paleolimbot commented on code in PR #444: URL: https://github.com/apache/arrow-nanoarrow/pull/444#discussion_r1584754417
########## python/src/nanoarrow/c_array.py: ########## @@ -0,0 +1,573 @@ +# 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. + +from typing import Any, Iterable, Literal, Tuple + +from nanoarrow._lib import ( + CArray, + CArrayBuilder, + CArrayView, + CArrowType, + CBuffer, + CBufferBuilder, + CSchema, + CSchemaBuilder, + NoneAwareWrapperIterator, + _obj_is_buffer, + _obj_is_capsule, +) +from nanoarrow.c_buffer import c_buffer +from nanoarrow.c_schema import c_schema, c_schema_view + + +def c_array(obj, schema=None) -> CArray: + """ArrowArray wrapper + + This class provides a user-facing interface to access the fields of an ArrowArray + as defined in the Arrow C Data interface, holding an optional reference to a + :class:`CSchema` that can be used to safely deserialize the content. + + These objects are created using :func:`c_array`, which accepts any array-like + object according to the Arrow PyCapsule interface, Python buffer protocol, + or iterable of Python objects. + + This Python wrapper allows access to array fields but does not automatically + deserialize their content: use :func:`c_array_view` to validate and deserialize + the content into a more easily inspectable object. + + Note that the :class:`CArray` objects returned by ``.child()`` hold strong + references to the original ``ArrowArray`` to avoid copies while inspecting an + imported structure. + + Parameters + ---------- + obj : array-like + An object supporting the Arrow PyCapsule interface, the Python buffer + protocol, or an iterable of Python objects. + schema : schema-like or None + A schema-like object as sanitized by :func:`c_schema` or None. This value + will be used to request a data type from ``obj``; however, the conversion + is best-effort (i.e., the data type of the returned ``CArray`` may be + different than ``schema``). + + Examples + -------- + + >>> import nanoarrow as na + >>> # Create from iterable + >>> array = na.c_array([1, 2, 3], na.int32()) + >>> # Create from Python buffer (e.g., numpy array) + >>> import numpy as np + >>> array = na.c_array(np.array([1, 2, 3])) + >>> # Create from Arrow PyCapsule (e.g., pyarrow array) + >>> import pyarrow as pa + >>> array = na.c_array(pa.array([1, 2, 3])) + >>> # Access array fields + >>> array.length + 3 + >>> array.null_count + 0 + """ + + if schema is not None: + schema = c_schema(schema) + + if isinstance(obj, CArray) and schema is None: + return obj + + # Try Arrow PyCapsule protocol + if hasattr(obj, "__arrow_c_array__"): + schema_capsule = None if schema is None else schema.__arrow_c_schema__() + return CArray._import_from_c_capsule( + *obj.__arrow_c_array__(requested_schema=schema_capsule) + ) + + # Try import of bare capsule + if _obj_is_capsule(obj, "arrow_array"): + if schema is None: + schema_capsule = CSchema.allocate()._capsule Review Comment: You can inspect the fields (`length`, `offset`, etc.) but that is about it. Its utility would mostly be in an interactive debug scenario where you want to actually look the contents of a capsule (there's really no other way to do that). -- 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]
