feat: made 'very optional' arguments keyword-only (#1905)

* feat: made 'very optional' arguments keyword-only

* Fix one build-docs error.

* fix: pass keyword argument to `mask`

Co-authored-by: Angus Hollands <[email protected]>

docs/user-guide/how-to-create-arraybuilder.md

@@ -376,7 +376,7 @@ new_array
 new_array.layout
 ```
 
-Above, we see that `new_array` is just making references ({class}`ak.layout.IndexedArray`) of an {classY}`ak.layout.RecordArray` with `x = [1, 2, 3]` and `y = [1.1, 2.2, 3.3]`.
+Above, we see that `new_array` is just making references ({class}`ak.layout.IndexedArray`) of an {class}`ak.layout.RecordArray` with `x = [1, 2, 3]` and `y = [1.1, 2.2, 3.3]`.
 
 +++
 

src/awkward/_util.py

@@ -412,7 +412,7 @@ def behavior_of(*arrays, **kwargs):
     highs = (
         ak.highlevel.Array,
         ak.highlevel.Record,
-        #        ak.highlevel.ArrayBuilder,
+        # ak.highlevel.ArrayBuilder,
     )
     for x in arrays[::-1]:
         if isinstance(x, highs) and x.behavior is not None:
@@ -429,7 +429,6 @@ def behavior_of(*arrays, **kwargs):
     return behavior
 
 
-# maybe_wrap and maybe_wrap_like go here
 def wrap(content, behavior=None, highlevel=True, like=None):
     assert content is None or isinstance(
         content, (ak.contents.Content, ak.record.Record)

src/awkward/behaviors/mixins.py

@@ -63,7 +63,7 @@ def register(cls):
     return register
 
 
-def mixin_class_method(ufunc, rhs=None, transpose=True):
+def mixin_class_method(ufunc, rhs=None, *, transpose=True):
     """
     Args:
         ufunc (numpy.ufunc): A universal function (or NEP18 callable) that is

src/awkward/contents/listarray.py

@@ -1364,7 +1364,9 @@ def _to_arrow(self, pyarrow, mask_node, validbytes, length, options):
         )
 
     def _to_numpy(self, allow_missing):
-        return ak.operations.to_numpy(self.toRegularArray(), allow_missing)
+        return ak.operations.to_numpy(
+            self.toRegularArray(), allow_missing=allow_missing
+        )
 
     def _completely_flatten(self, nplike, options):
         if (

src/awkward/contents/listoffsetarray.py

@@ -1963,7 +1963,9 @@ def _to_numpy(self, allow_missing):
         if array_param in {"bytestring", "string"}:
             return self._nplike.array(self.to_list())
 
-        return ak.operations.to_numpy(self.toRegularArray(), allow_missing)
+        return ak.operations.to_numpy(
+            self.toRegularArray(), allow_missing=allow_missing
+        )
 
     def _completely_flatten(self, nplike, options):
         if (

src/awkward/forms/bitmaskedform.py

@@ -100,7 +100,7 @@ def _type(self, typestrs):
         return ak.types.OptionType(
             self._content._type(typestrs),
             self._parameters,
-            ak._util.gettypestr(self._parameters, typestrs),
+            typestr=ak._util.gettypestr(self._parameters, typestrs),
         ).simplify_option_union()
 
     def __eq__(self, other):

src/awkward/forms/bytemaskedform.py

@@ -84,7 +84,7 @@ def _type(self, typestrs):
         return ak.types.OptionType(
             self._content._type(typestrs),
             self._parameters,
-            ak._util.gettypestr(self._parameters, typestrs),
+            typestr=ak._util.gettypestr(self._parameters, typestrs),
         ).simplify_option_union()
 
     def __eq__(self, other):

src/awkward/forms/emptyform.py

@@ -21,7 +21,7 @@ def _to_dict_part(self, verbose, toplevel):
     def _type(self, typestrs):
         return ak.types.UnknownType(
             self._parameters,
-            ak._util.gettypestr(self._parameters, typestrs),
+            typestr=ak._util.gettypestr(self._parameters, typestrs),
         )
 
     def __eq__(self, other):

src/awkward/forms/indexedoptionform.py

@@ -69,7 +69,7 @@ def _type(self, typestrs):
         return ak.types.OptionType(
             self._content._type(typestrs),
             parameters,
-            ak._util.gettypestr(self._parameters, typestrs),
+            typestr=ak._util.gettypestr(self._parameters, typestrs),
         ).simplify_option_union()
 
     def __eq__(self, other):

src/awkward/forms/listform.py

@@ -80,7 +80,7 @@ def _type(self, typestrs):
         return ak.types.ListType(
             self._content._type(typestrs),
             self._parameters,
-            ak._util.gettypestr(self._parameters, typestrs),
+            typestr=ak._util.gettypestr(self._parameters, typestrs),
         )
 
     def __eq__(self, other):

src/awkward/forms/listoffsetform.py

@@ -50,7 +50,7 @@ def _type(self, typestrs):
         return ak.types.ListType(
             self._content._type(typestrs),
             self._parameters,
-            ak._util.gettypestr(self._parameters, typestrs),
+            typestr=ak._util.gettypestr(self._parameters, typestrs),
         )
 
     def __eq__(self, other):

src/awkward/forms/numpyform.py

@@ -101,7 +101,7 @@ def _type(self, typestrs):
         out = ak.types.NumpyType(
             self._primitive,
             None,
-            ak._util.gettypestr(self._parameters, typestrs),
+            typestr=ak._util.gettypestr(self._parameters, typestrs),
         )
         for x in self._inner_shape[::-1]:
             out = ak.types.RegularType(out, x)

src/awkward/forms/recordform.py

@@ -150,7 +150,7 @@ def _type(self, typestrs):
             [x._type(typestrs) for x in self._contents],
             self._fields,
             self._parameters,
-            ak._util.gettypestr(self._parameters, typestrs),
+            typestr=ak._util.gettypestr(self._parameters, typestrs),
         )
 
     def __eq__(self, other):

src/awkward/forms/regularform.py

@@ -57,7 +57,7 @@ def _type(self, typestrs):
             self._content._type(typestrs),
             self._size,
             self._parameters,
-            ak._util.gettypestr(self._parameters, typestrs),
+            typestr=ak._util.gettypestr(self._parameters, typestrs),
         )
 
     def __eq__(self, other):

src/awkward/forms/unionform.py

@@ -97,7 +97,7 @@ def _type(self, typestrs):
         return ak.types.UnionType(
             [x._type(typestrs) for x in self._contents],
             self._parameters,
-            ak._util.gettypestr(self._parameters, typestrs),
+            typestr=ak._util.gettypestr(self._parameters, typestrs),
         )
 
     def __eq__(self, other):

src/awkward/forms/unmaskedform.py

@@ -46,7 +46,7 @@ def _type(self, typestrs):
         return ak.types.OptionType(
             self._content._type(typestrs),
             self._parameters,
-            ak._util.gettypestr(self._parameters, typestrs),
+            typestr=ak._util.gettypestr(self._parameters, typestrs),
         ).simplify_option_union()
 
     def __eq__(self, other):

src/awkward/highlevel.py

@@ -184,6 +184,7 @@ class Array(NDArrayOperatorsMixin, Iterable, Sized):
     def __init__(
         self,
         data,
+        *,
         behavior=None,
         with_name=None,
         check_valid=False,
@@ -351,7 +352,7 @@ def __getitem__(self, where):
             with ak._errors.OperationErrorContext(
                 "ak.Array.mask", {0: self._array, 1: where}
             ):
-                return ak.operations.mask(self._array, where, True)
+                return ak.operations.mask(self._array, where, valid_when=True)
 
     @property
     def mask(self):
@@ -1475,6 +1476,7 @@ class Record(NDArrayOperatorsMixin):
     def __init__(
         self,
         data,
+        *,
         behavior=None,
         with_name=None,
         check_valid=False,
@@ -2168,7 +2170,7 @@ class ArrayBuilder(Sized):
     be considered the "least effort" approach.
     """
 
-    def __init__(self, behavior=None, initial=1024, resize=1.5):
+    def __init__(self, *, behavior=None, initial=1024, resize=1.5):
         self._layout = _ext.ArrayBuilder(initial=initial, resize=resize)
         self.behavior = behavior
 

src/awkward/index.py

@@ -18,7 +18,7 @@
 class Index:
     _expected_dtype = None
 
-    def __init__(self, data, metadata=None, nplike=None):
+    def __init__(self, data, *, metadata=None, nplike=None):
         if nplike is None:
             nplike = ak.nplikes.nplike_of(data)
         self._nplike = nplike
@@ -111,7 +111,7 @@ def forget_length(self):
             data = self._data
         else:
             data = self.raw(tt)
-        return type(self)(data.forget_length(), self._metadata, tt)
+        return type(self)(data.forget_length(), metadata=self._metadata, nplike=tt)
 
     def raw(self, nplike):
         return self.nplike.index_nplike.raw(self.data, nplike.index_nplike)
@@ -186,8 +186,8 @@ def __copy__(self):
     def __deepcopy__(self, memo):
         return type(self)(
             copy.deepcopy(self._data, memo),
-            copy.deepcopy(self._metadata, memo),
-            self._nplike,
+            metadata=copy.deepcopy(self._metadata, memo),
+            nplike=self._nplike,
         )
 
     def _nbytes_part(self):

src/awkward/operations/ak_all.py

@@ -6,7 +6,9 @@
 
 
 @ak._connect.numpy.implements("all")
-def all(array, axis=None, keepdims=False, mask_identity=False, flatten_records=False):
+def all(
+    array, axis=None, *, keepdims=False, mask_identity=False, flatten_records=False
+):
     """
     Args:
         array: Array-like data (anything #ak.to_layout recognizes).

src/awkward/operations/ak_any.py

@@ -6,7 +6,9 @@
 
 
 @ak._connect.numpy.implements("any")
-def any(array, axis=None, keepdims=False, mask_identity=False, flatten_records=False):
+def any(
+    array, axis=None, *, keepdims=False, mask_identity=False, flatten_records=False
+):
     """
     Args:
         array: Array-like data (anything #ak.to_layout recognizes).

src/awkward/operations/ak_argcartesian.py

@@ -8,6 +8,7 @@
 def argcartesian(
     arrays,
     axis=1,
+    *,
     nested=None,
     parameters=None,
     with_name=None,

src/awkward/operations/ak_argcombinations.py

@@ -8,6 +8,7 @@
 def argcombinations(
     array,
     n,
+    *,
     replacement=False,
     axis=1,
     fields=None,

src/awkward/operations/ak_argmax.py

@@ -6,7 +6,9 @@
 
 
 @ak._connect.numpy.implements("argmax")
-def argmax(array, axis=None, keepdims=False, mask_identity=True, flatten_records=False):
+def argmax(
+    array, axis=None, *, keepdims=False, mask_identity=True, flatten_records=False
+):
     """
     Args:
         array: Array-like data (anything #ak.to_layout recognizes).
@@ -59,7 +61,7 @@ def argmax(array, axis=None, keepdims=False, mask_identity=True, flatten_records
 
 @ak._connect.numpy.implements("nanargmax")
 def nanargmax(
-    array, axis=None, keepdims=False, mask_identity=True, flatten_records=False
+    array, axis=None, *, keepdims=False, mask_identity=True, flatten_records=False
 ):
     """
     Args:

src/awkward/operations/ak_argmin.py

@@ -6,7 +6,9 @@
 
 
 @ak._connect.numpy.implements("argmin")
-def argmin(array, axis=None, keepdims=False, mask_identity=True, flatten_records=False):
+def argmin(
+    array, axis=None, *, keepdims=False, mask_identity=True, flatten_records=False
+):
     """
     Args:
         array: Array-like data (anything #ak.to_layout recognizes).
@@ -59,7 +61,7 @@ def argmin(array, axis=None, keepdims=False, mask_identity=True, flatten_records
 
 @ak._connect.numpy.implements("nanargmin")
 def nanargmin(
-    array, axis=None, keepdims=False, mask_identity=True, flatten_records=False
+    array, axis=None, *, keepdims=False, mask_identity=True, flatten_records=False
 ):
     """
     Args:

src/awkward/operations/ak_argsort.py

@@ -6,7 +6,9 @@
 
 
 @ak._connect.numpy.implements("argsort")
-def argsort(array, axis=-1, ascending=True, stable=True, highlevel=True, behavior=None):
+def argsort(
+    array, axis=-1, *, ascending=True, stable=True, highlevel=True, behavior=None
+):
     """
     Args:
         array: Data for which to get a sorting index, possibly within nested

src/awkward/operations/ak_cartesian.py

@@ -8,6 +8,7 @@
 def cartesian(
     arrays,
     axis=1,
+    *,
     nested=None,
     parameters=None,
     with_name=None,
@@ -320,7 +321,7 @@ def _impl(arrays, axis, nested, parameters, with_name, highlevel, behavior):
             ak.index.Index64(x.reshape(-1), nplike=nplike)
             for x in nplike.index_nplike.meshgrid(
                 *[nplike.index_nplike.arange(len(x), dtype=np.int64) for x in layouts],
-                indexing="ij"
+                indexing="ij",
             )
         ]
         outs = [

src/awkward/operations/ak_combinations.py

@@ -8,6 +8,7 @@
 def combinations(
     array,
     n,
+    *,
     replacement=False,
     axis=1,
     fields=None,

src/awkward/operations/ak_concatenate.py

@@ -8,7 +8,7 @@
 
 @ak._connect.numpy.implements("concatenate")
 def concatenate(
-    arrays, axis=0, merge=True, mergebool=True, highlevel=True, behavior=None
+    arrays, axis=0, *, merge=True, mergebool=True, highlevel=True, behavior=None
 ):
     """
     Args:

src/awkward/operations/ak_corr.py

@@ -10,6 +10,7 @@ def corr(
     y,
     weight=None,
     axis=None,
+    *,
     keepdims=False,
     mask_identity=False,
     flatten_records=False,
@@ -71,15 +72,19 @@ def corr(
 
 
 def _impl(x, y, weight, axis, keepdims, mask_identity, flatten_records):
+    behavior = ak._util.behavior_of(x, y, weight)
     x = ak.highlevel.Array(
-        ak.operations.to_layout(x, allow_record=False, allow_other=False)
+        ak.operations.to_layout(x, allow_record=False, allow_other=False),
+        behavior=behavior,
     )
     y = ak.highlevel.Array(
-        ak.operations.to_layout(y, allow_record=False, allow_other=False)
+        ak.operations.to_layout(y, allow_record=False, allow_other=False),
+        behavior=behavior,
     )
     if weight is not None:
         weight = ak.highlevel.Array(
-            ak.operations.to_layout(weight, allow_record=False, allow_other=False)
+            ak.operations.to_layout(weight, allow_record=False, allow_other=False),
+            behavior=behavior,
         )
 
     with np.errstate(invalid="ignore", divide="ignore"):

src/awkward/operations/ak_count.py

@@ -5,7 +5,9 @@
 np = ak.nplikes.NumpyMetadata.instance()
 
 
-def count(array, axis=None, keepdims=False, mask_identity=False, flatten_records=False):
+def count(
+    array, axis=None, *, keepdims=False, mask_identity=False, flatten_records=False
+):
     """
     Args:
         array: Array-like data (anything #ak.to_layout recognizes).

src/awkward/operations/ak_count_nonzero.py

@@ -7,7 +7,7 @@
 
 @ak._connect.numpy.implements("count_nonzero")
 def count_nonzero(
-    array, axis=None, keepdims=False, mask_identity=False, flatten_records=False
+    array, axis=None, *, keepdims=False, mask_identity=False, flatten_records=False
 ):
     """
     Args: