feat: initial array object implementation (#1)

* feat: initial array object implementation

* do something with no errors

* bump minimal support version to 3.9 for a typing feature

* Implemented a few more features.

* Move 'import cupy' to an _import module.

* Added property and method docstrings and stubs from the specification.

* Added in-place and reflected operator implementations.

* Move code out of __init__.py.

* Final directory rearrangement.

* Make files distinct by adding docstrings.

.github/workflows/ci.yml

@@ -40,7 +40,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.8", "3.12"]
+        python-version: ["3.9", "3.12"]
         runs-on: [ubuntu-latest, macos-latest, windows-latest]
 
         include:

.pre-commit-config.yaml

@@ -65,14 +65,6 @@ repos:
     hooks:
       - id: shellcheck
 
-  - repo: local
-    hooks:
-      - id: disallow-caps
-        name: Disallow improper capitalization
-        language: pygrep
-        entry: PyBind|Numpy|Cmake|CCache|Github|PyTest
-        exclude: .pre-commit-config.yaml
-
   - repo: https://github.com/abravalheri/validate-pyproject
     rev: v0.15
     hooks:

pyproject.toml

@@ -11,7 +11,7 @@ authors = [
 description = "Ragged array library, complying with Python API specification."
 readme = "README.md"
 license.file = "LICENSE"
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 classifiers = [
   "Development Status :: 1 - Planning",
   "Intended Audience :: Science/Research",
@@ -21,7 +21,6 @@ classifiers = [
   "Programming Language :: Python",
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3 :: Only",
-  "Programming Language :: Python :: 3.8",
   "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
@@ -30,7 +29,9 @@ classifiers = [
   "Typing :: Typed",
 ]
 dynamic = ["version"]
-dependencies = []
+dependencies = [
+  "awkward",
+]
 
 [project.optional-dependencies]
 test = [
@@ -87,7 +88,7 @@ report.exclude_also = [
 
 [tool.mypy]
 files = ["src", "tests"]
-python_version = "3.8"
+python_version = "3.9"
 warn_unused_configs = true
 strict = true
 enable_error_code = ["ignore-without-code", "redundant-expr", "truthy-bool"]
@@ -100,6 +101,17 @@ module = "ragged.*"
 disallow_untyped_defs = true
 disallow_incomplete_defs = true
 
+[[tool.mypy.overrides]]
+module = "numpy.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "cupy.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "awkward.*"
+ignore_missing_imports = true
 
 [tool.ruff]
 src = ["src"]
@@ -132,6 +144,8 @@ ignore = [
   "PLR09",    # Too many <...>
   "PLR2004",  # Magic value used in comparison
   "ISC001",   # Conflicts with formatter
+  "RET505",   # I like my if (return) elif (return) else (return) pattern
+  "PLR5501",  # I like my if (return) elif (return) else (return) pattern
 ]
 isort.required-imports = ["from __future__ import annotations"]
 # Uncomment if using a _compat.typing backport
@@ -143,7 +157,7 @@ isort.required-imports = ["from __future__ import annotations"]
 
 
 [tool.pylint]
-py-version = "3.8"
+py-version = "3.9"
 ignore-paths = [".*/_version.py"]
 reports.output-format = "colorized"
 similarities.ignore-imports = "yes"
@@ -153,4 +167,7 @@ messages_control.disable = [
   "line-too-long",
   "missing-module-docstring",
   "wrong-import-position",
+  "missing-class-docstring",
+  "missing-function-docstring",
+  "R1705",   # I like my if (return) elif (return) else (return) pattern
 ]

src/ragged/__init__.py

@@ -1,12 +1,13 @@
-"""
-Copyright (c) 2023 Jim Pivarski. All rights reserved.
+# BSD 3-Clause License; see https://github.com/scikit-hep/ragged/blob/main/LICENSE
 
-ragged: Ragged array library, complying with Python API specification.
 """
+Ragged array module.
 
+FIXME: needs more documentation!
 
-from __future__ import annotations
+Version 2022.12 is current, so `ragged.v202212.*` is identical to `ragged.*`.
+"""
 
-from ._version import version as __version__
+from __future__ import annotations
 
-__all__ = ["__version__"]
+from .v202212 import *  # noqa: F403

src/ragged/common/__init__.py

@@ -0,0 +1,14 @@
+# BSD 3-Clause License; see https://github.com/scikit-hep/ragged/blob/main/LICENSE
+
+"""
+Generic definitions used by the version-specific modules, such as
+`ragged.v202212`.
+
+https://data-apis.org/array-api/latest/API_specification/
+"""
+
+from __future__ import annotations
+
+from ._obj import array
+
+__all__ = ["array"]

src/ragged/common/_import.py

@@ -0,0 +1,22 @@
+# BSD 3-Clause License; see https://github.com/scikit-hep/ragged/blob/main/LICENSE
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def cupy() -> Any:
+    try:
+        import cupy as cp  # pylint: disable=C0415
+
+        return cp
+    except ModuleNotFoundError as err:
+        error_message = """to use the "cuda" backend, you must install cupy:
+
+    pip install cupy
+
+or
+
+    conda install -c conda-forge cupy
+"""
+        raise ModuleNotFoundError(error_message) from err