feat: initial array object implementation

pyproject.toml

@@ -30,7 +30,9 @@ classifiers = [
   "Typing :: Typed",
 ]
 dynamic = ["version"]
-dependencies = []
+dependencies = [
+  "awkward",
+]
 
 [project.optional-dependencies]
 test = [
@@ -100,6 +102,13 @@ module = "ragged.*"
 disallow_untyped_defs = true
 disallow_incomplete_defs = true
 
+[[tool.mypy.overrides]]
+module = "numpy.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "awkward.*"
+ignore_missing_imports = true
 
 [tool.ruff]
 src = ["src"]

src/ragged/__init__.py

@@ -1,12 +1,8 @@
-"""
-Copyright (c) 2023 Jim Pivarski. All rights reserved.
-
-ragged: Ragged array library, complying with Python API specification.
-"""
-
+# BSD 3-Clause License; see https://github.com/scikit-hep/ragged/blob/main/LICENSE
 
 from __future__ import annotations
 
 from ._version import version as __version__
+from .api_2022_12 import array
 
-__all__ = ["__version__"]
+__all__ = ["array", "__version__"]

src/ragged/api_2022_12/__init__.py

@@ -0,0 +1,9 @@
+# BSD 3-Clause License; see https://github.com/scikit-hep/ragged/blob/main/LICENSE
+
+from __future__ import annotations
+
+from ..common import array as common_array
+
+
+class array(common_array):
+    pass

src/ragged/common/__init__.py

@@ -0,0 +1,25 @@
+# BSD 3-Clause License; see https://github.com/scikit-hep/ragged/blob/main/LICENSE
+
+from __future__ import annotations
+
+import awkward as ak
+
+from ._typing import Device, Dtype, NestedSequence, SupportsDLPack
+
+
+class array:
+    def __init__(
+        self,
+        array_like: (
+            array
+            | ak.Array
+            | SupportsDLPack
+            | bool
+            | int
+            | float
+            | NestedSequence[bool | int | float]
+        ),
+        dtype: None | Dtype = None,
+        device: None | Device = None,
+    ):
+        ...

src/ragged/common/_typing.py

@@ -0,0 +1,47 @@
+# BSD 3-Clause License; see https://github.com/scikit-hep/ragged/blob/main/LICENSE
+
+from __future__ import annotations
+
+import warnings
+from typing import Any, Literal, Protocol, TypeVar, Union
+
+import numpy as np
+
+with warnings.catch_warnings():
+    warnings.simplefilter("ignore")
+
+T_co = TypeVar("T_co", covariant=True)
+
+
+class NestedSequence(Protocol[T_co]):
+    def __getitem__(self, key: int, /) -> T_co | NestedSequence[T_co]:
+        ...
+
+    def __len__(self, /) -> int:
+        ...
+
+
+PyCapsule = Any
+
+
+class SupportsDLPack(Protocol):
+    def __dlpack__(self, /, *, stream: None = ...) -> PyCapsule:
+        ...
+
+
+Device = Union[Literal["cpu"], Literal["cuda"]]
+
+Dtype = np.dtype[
+    (
+        np.int8,
+        np.int16,
+        np.int32,
+        np.int64,
+        np.uint8,
+        np.uint16,
+        np.uint32,
+        np.uint64,
+        np.float32,
+        np.float64,
+    )
+]

tests/test_0001_initial_array_object.py

@@ -0,0 +1,9 @@
+# BSD 3-Clause License; see https://github.com/scikit-hep/ragged/blob/main/LICENSE
+
+from __future__ import annotations
+
+# import ragged
+
+
+# def test():
+#     a = ragged.array([1, 2, 3])