feat: add ak.enforce_type (#2365)

* feat: add `ak.enforce_type`

* test: add tests

* test: fix argument order

* feat: add removal of option!

* feat: add option to keep type parameters

* refactor: use independent `recurse_` functions

* test: add more test cases

* feat!: don't permute for recordarrays

* feat!: make union conversions stricter

* refactor: drop closure abstraction

Now that we don't need multi-branch error handling

* fix: check metadata in layout equality

* fix: allow unions to be unconverted

* fix: Python 3.7's sum doesn't accept kwargs

* style: pre-commit fixes

* feat: don't project indexed types if type matches

* misc fixes

* feat: convert between strings and char arrays

* feat: support changing record lengths

* refactor: rename `layout_equal_type`

* refactor: change error types

* refactor: simplify record handling

* fix: recurse into all contents, even if same type!

* fix: pack option only for one level

* fix: only project option if content type changes

* fix: more packing work!

* refactor: make all functions private

* refactor: rename function

* Fix: invert condition

* refactor: cleanups

* wip: work on documentation

* docs: add to toctree

* docs: clean-up docstring

* docs: small change

* fix: correct record (todo: add test with different fields)

* fix: regular is also list!

* feat: add projection mode

* docs: update docstrings

* test: add tests for new behavior

* docs: fix docstring formatting

* docs: fix formatting

* docs: small formatting change

* docs: small internal notice

* fix: support converting 0-length lists to sized regular

* refactor: pull out index_nplike

* feat: detect projection automatically

* refactor: drop single-use helper functions

* refactor: simplify branches

* test: ensure indexing works properly

* docs: clarify when projection vs conversion is used

* fix: add note about high level types

* test: add scalar test

* refactor: move functions around

* fix: only operate on part of array used for records

* fix: take parameters from `_parameters`

* fix: take parameters from `_parameters`

* docs: expand on docstrings

* fix: catch bug with packing

* test: check packing of indexed

* fix: preserve field order

* test: check _exact_ layouts

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: agoose77

docs/reference/toctree.txt

@@ -148,6 +148,7 @@
 .. toctree::
     :caption: Value and type conversions
 
+    generated/ak.enforce_type
     generated/ak.nan_to_none
     generated/ak.nan_to_num
     generated/ak.values_astype

src/awkward/forms/form.py

@@ -187,8 +187,11 @@ def from_type(type_: ak.types.Type) -> Form:
     # Categorical types are reintroduced into forms using metadata
     if type_.parameter("__categorical__"):
         # Drop categorical placeholder parameter
-        next_parameters = type_.parameters.copy()
-        next_parameters.pop("__categorical__")
+        if type_._parameters is None:
+            next_parameters = None
+        else:
+            next_parameters = type_._parameters.copy()
+            next_parameters.pop("__categorical__")
 
         if isinstance(type_, ak.types.OptionType):
             next_content = from_type(type_.content)
@@ -206,38 +209,38 @@ def from_type(type_: ak.types.Type) -> Form:
             )
 
     if isinstance(type_, ak.types.NumpyType):
-        return ak.forms.NumpyForm(type_.primitive, parameters=type_.parameters)
+        return ak.forms.NumpyForm(type_.primitive, parameters=type_._parameters)
     elif isinstance(type_, ak.types.ListType):
         return ak.forms.ListOffsetForm(
-            "i64", from_type(type_.content), parameters=type_.parameters
+            "i64", from_type(type_.content), parameters=type_._parameters
         )
     elif isinstance(type_, ak.types.RegularType):
         return ak.forms.RegularForm(
             from_type(type_.content),
             size=type_.size,
-            parameters=type_.parameters,
+            parameters=type_._parameters,
         )
     elif isinstance(type_, ak.types.OptionType):
         return ak.forms.IndexedOptionForm(
             "i64",
             from_type(type_.content),
-            parameters=type_.parameters,
+            parameters=type_._parameters,
         )
     elif isinstance(type_, ak.types.RecordType):
         return ak.forms.RecordForm(
             [from_type(c) for c in type_.contents],
             type_.fields,
-            parameters=type_.parameters,
+            parameters=type_._parameters,
         )
     elif isinstance(type_, ak.types.UnionType):
         return ak.forms.UnionForm(
             "i8",
             "i64",
             [from_type(c) for c in type_.contents],
-            parameters=type_.parameters,
+            parameters=type_._parameters,
         )
     elif isinstance(type_, ak.types.UnknownType):
-        return ak.forms.EmptyForm(parameters=type_.parameters)
+        return ak.forms.EmptyForm(parameters=type_._parameters)
     elif isinstance(type_, (ak.types.ArrayType, ak.types.ScalarType)):
         raise TypeError(
             "High-level types (ak.types.ArrayType, ak.types.ScalarType) do not have representations as Awkward forms. "

src/awkward/operations/__init__.py

@@ -22,6 +22,7 @@
 from awkward.operations.ak_count_nonzero import *
 from awkward.operations.ak_covar import *
 from awkward.operations.ak_drop_none import *
+from awkward.operations.ak_enforce_type import *
 from awkward.operations.ak_fields import *
 from awkward.operations.ak_fill_none import *
 from awkward.operations.ak_firsts import *