lamindb 0.75.1__tar.gz → 0.76.1__tar.gz

{lamindb-0.75.1 → lamindb-0.76.1}/.github/workflows/build.yml

@@ -21,7 +21,7 @@ jobs:
           - "faq"
           - "storage"
           - "cli"
-    timeout-minutes: 6
+    timeout-minutes: 7
 
     steps:
       - uses: actions/checkout@v4

{lamindb-0.75.1 → lamindb-0.76.1}/.pre-commit-config.yaml

@@ -51,5 +51,5 @@ repos:
         additional_dependencies: ["types-requests", "types-attrs"]
         exclude: |
           (?x)(
-              test_notebooks.py
+              test_notebooks.py|script-to-test-versioning.py
           )

{lamindb-0.75.1 → lamindb-0.76.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: lamindb
-Version: 0.75.1
+Version: 0.76.1
 Summary: A data framework for biology.
 Author-email: Lamin Labs <open-source@lamin.ai>
 Requires-Python: >=3.8
@@ -9,10 +9,10 @@ Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
-Requires-Dist: lnschema_core==0.72.2
-Requires-Dist: lamindb_setup==0.76.3
+Requires-Dist: lnschema_core==0.73.1
+Requires-Dist: lamindb_setup==0.76.5
 Requires-Dist: lamin_utils==0.13.2
-Requires-Dist: lamin_cli==0.16.0
+Requires-Dist: lamin_cli==0.16.2
 Requires-Dist: rapidfuzz
 Requires-Dist: pyarrow
 Requires-Dist: typing_extensions!=4.6.0
@@ -24,7 +24,7 @@ Requires-Dist: pandas
 Requires-Dist: graphviz
 Requires-Dist: psycopg2-binary
 Requires-Dist: lamindb_setup[aws] ; extra == "aws"
-Requires-Dist: bionty==0.48.0 ; extra == "bionty"
+Requires-Dist: bionty==0.48.2 ; extra == "bionty"
 Requires-Dist: pre-commit ; extra == "dev"
 Requires-Dist: nox ; extra == "dev"
 Requires-Dist: laminci>=0.3 ; extra == "dev"

{lamindb-0.75.1 → lamindb-0.76.1}/docs/api.md

@@ -27,6 +27,14 @@ bionty
 wetlab
 ```
 
+```{toctree}
+:maxdepth: 1
+:caption: SDK
+:hidden:
+
+rest
+```
+
 ```{toctree}
 :maxdepth: 1
 :caption: Utilities

{lamindb-0.75.1 → lamindb-0.76.1}/docs/faq/idempotency.ipynb

@@ -71,9 +71,8 @@
     "import pytest\n",
     "\n",
     "ln.settings.verbosity = \"hint\"\n",
-    "ln.settings.transform.stem_uid = \"ANW20Fr4eZgM\"\n",
-    "ln.settings.transform.version = \"1\"\n",
-    "ln.track()"
+    "ln.context.uid = \"ANW20Fr4eZgM0000\"\n",
+    "ln.context.track()"
    ]
   },
   {
@@ -398,7 +397,7 @@
    },
    "outputs": [],
    "source": [
-    "ln.track(new_run=True)\n",
+    "ln.context.track(new_run=True)\n",
     "artifact3 = ln.Artifact(filepath, description=\"My fcs artifact\")\n",
     "assert artifact3.id == artifact2.id\n",
     "assert artifact3.run != artifact2.run\n",

{lamindb-0.75.1 → lamindb-0.76.1}/docs/faq/keep-artifacts-local.ipynb

@@ -37,9 +37,8 @@
     "# !pip install 'lamindb[jupyter,aws]'\n",
     "import lamindb as ln\n",
     "\n",
-    "ln.settings.transform.stem_uid = \"l9lFf83aPwRc\"\n",
-    "ln.settings.transform.version = \"1\"\n",
-    "ln.track()"
+    "ln.context.uid = \"l9lFf83aPwRc0000\"\n",
+    "ln.context.track()"
    ]
   },
   {

{lamindb-0.75.1 → lamindb-0.76.1}/docs/faq/key.ipynb

@@ -119,9 +119,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "ln.settings.transform.stem_uid = \"WIwaNDvlEkwS\"\n",
-    "ln.settings.transform.version = \"1\"\n",
-    "ln.track()"
+    "ln.context.uid = \"WIwaNDvlEkwS0000\"\n",
+    "ln.context.track()"
    ]
   },
   {

{lamindb-0.75.1 → lamindb-0.76.1}/docs/faq/setup.ipynb

@@ -56,7 +56,7 @@
    "outputs": [],
    "source": [
     "with pytest.raises(ln._InstanceNotSetupError):\n",
-    "    ln.track()"
+    "    ln.context.track()"
    ]
   },
   {
@@ -85,9 +85,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "ln.settings.transform.stem_uid = \"2lhqA4uTKSFP\"\n",
-    "ln.settings.transform.version = \"0\"\n",
-    "ln.track()"
+    "ln.context.uid = \"2lhqA4uTKSFP0000\"\n",
+    "ln.context.track()"
    ]
   },
   {

{lamindb-0.75.1 → lamindb-0.76.1}/docs/faq/track-run-inputs.ipynb

@@ -53,7 +53,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "ln.track(transform=ln.Transform(name=\"Dummpy pipeline\"))\n",
+    "ln.context.track(transform=ln.Transform(name=\"Dummpy pipeline\"))\n",
     "ln.Artifact(ln.core.datasets.file_jpg_paradisi05(), description=\"My image\").save()\n",
     "ln.Artifact(ln.core.datasets.file_mini_csv(), description=\"My csv\").save()"
    ]
@@ -63,7 +63,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Call `ln.track()`:"
+    "Call `ln.context.track()`:"
    ]
   },
   {
@@ -72,9 +72,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "ln.settings.transform.stem_uid = \"Rx2s9aPTMQLY\"\n",
-    "ln.settings.transform.version = \"1\"\n",
-    "ln.track()"
+    "ln.context.uid = \"Rx2s9aPTMQLY0000\"\n",
+    "ln.context.track()"
    ]
   },
   {
@@ -126,7 +125,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "ln.Run.filter(id=ln.core.run_context.run.id).one().input_artifacts.all()"
+    "ln.Run.filter(id=ln.context.run.id).one().input_artifacts.all()"
    ]
   },
   {
@@ -139,7 +138,7 @@
    },
    "outputs": [],
    "source": [
-    "assert len(ln.Run.filter(id=ln.core.run_context.run.id).one().input_artifacts.all()) == 0"
+    "assert len(ln.Run.filter(id=ln.context.run.id).one().input_artifacts.all()) == 0"
    ]
   },
   {
@@ -181,7 +180,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "for input in ln.Run.filter(id=ln.core.run_context.run.id).one().input_artifacts.all():\n",
+    "for input in ln.Run.filter(id=ln.context.run.id).one().input_artifacts.all():\n",
     "    print(input)"
    ]
   },
@@ -195,7 +194,7 @@
    },
    "outputs": [],
    "source": [
-    "assert len(ln.Run.filter(id=ln.core.run_context.run.id).one().input_artifacts.all()) == 1"
+    "assert len(ln.Run.filter(id=ln.context.run.id).one().input_artifacts.all()) == 1"
    ]
   },
   {
@@ -247,7 +246,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "for input in ln.Run.filter(id=ln.core.run_context.run.id).one().input_artifacts.all():\n",
+    "for input in ln.Run.filter(id=ln.context.run.id).one().input_artifacts.all():\n",
     "    print(input)"
    ]
   },
@@ -261,7 +260,7 @@
    },
    "outputs": [],
    "source": [
-    "assert len(ln.Run.filter(id=ln.core.run_context.run.id).one().input_artifacts.all()) == 2"
+    "assert len(ln.Run.filter(id=ln.context.run.id).one().input_artifacts.all()) == 2"
    ]
   },
   {

{lamindb-0.75.1 → lamindb-0.76.1}/docs/introduction.ipynb

@@ -60,7 +60,7 @@
     "pip install 'lamindb[jupyter,bionty]'\n",
     "```\n",
     "\n",
-    "Initialize a LaminDB instance mounting plugin {py:mod}`bionty` for biological types."
+    "Initialize a LaminDB instance mounting plugin {py:mod}`bionty`."
    ]
   },
   {
@@ -103,13 +103,11 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Track\n",
+    "### Track data transformations\n",
     "\n",
-    "Call {meth}`~lamindb.track` to track code along with its inputs and outputs.\n",
+    "When you first call {meth}`~lamindb.core.Context.track`, it auto-generates a `uid` to identify a notebook or script.\n",
     "\n",
-    "When you first call `ln.track()`, it raises an exception and creates a `stem_uid` & `version` to identify a notebook or script in your database.\n",
-    "\n",
-    "When you call it a second time, `ln.track()` saves transform and run records in their registries. The {class}`~lamindb.Transform` registry allows you to find your notebooks, scripts and pipelines. The {class}`~lamindb.Run` registry allows you to find their runs."
+    "When you call it a second time, it saves transform and run records: {class}`~lamindb.Transform` stores your notebooks, script, functions, and pipelines and {class}`~lamindb.Run` stores runs."
    ]
   },
   {
@@ -122,14 +120,10 @@
    },
    "outputs": [],
    "source": [
-    "ln.settings.transform.stem_uid = \"FPnfDtJz8qbE\"  # <-- auto-generated by ln.track()\n",
-    "ln.settings.transform.version = \"1\"  # <-- auto-generated by ln.track()\n",
-    "\n",
-    "# track the execution of your notebook or script\n",
-    "run = ln.track()\n",
+    "ln.context.uid = \"FPnfDtJz8qbE0000\"  # <-- auto-generated by ln.context.track()\n",
     "\n",
-    "# see your currently running transform\n",
-    "run.transform"
+    "# track the execution of your notebook or script with inputs & outputs\n",
+    "ln.context.track()"
    ]
   },
   {
@@ -142,21 +136,13 @@
     "\n",
     ":::\n",
     "\n",
-    ":::{dropdown} Are the global identifiers `stem_uid` and `version` really necessary?\n",
+    ":::{dropdown} Why is the global `ln.context.uid` necessary?\n",
     "\n",
-    "Yes, if you want to track data lineage outside of workflow managers.\n",
+    "To tie a piece of code to a record in a database in a way that survives name and content changes, you need to attach the code to an immutable identifier, e.g., LaminDB's `uid`.\n",
     "\n",
-    "To tie a piece of code to a record in a database in a way that survives name changes (notebook file name, script name, pipeline name) and content changes, you need to attach the code to an immutable identifier.\n",
+    "git, by comparison, identifies code by its content hash & name. If you rename a notebook or script file and change the content, you lose the identity of the file. Notebook platforms like Google Colab and DeepNote support renaming and changing content of a given notebook, but they do not support versioning (every notebook version comes with the same [notebook id](https://lamin.ai/blog/nbproject#metadata-tracking) without versioning appearing in its metadata).\n",
     "\n",
-    "Content changes need to correlate with the identifier, but shouldn't give rise to an entirely new identifier. To implement this behavior we code hashes with user input for `version` and create a universal identifier as follows:\n",
-    "\n",
-    "```python\n",
-    "stem_uid = random_base62(n_char)  # a random base62 sequence of length n_char\n",
-    "version_uid = encode_base62(md5_hash(version))[:4]  # version is, e.g., \"1\" or \"2.1.0\" or \"2022-03-01\"\n",
-    "uid = f\"{stem_uid}{version_uid}\"  # concatenate the stem_uid & version_uid\n",
-    "```\n",
-    "\n",
-    "git, by comparison, identifies code by its content hash alone. Notebook platforms like Google Colab and DeepNote [do not encode versions into their notebook ids](https://lamin.ai/blog/nbproject#metadata-tracking). \n",
+    "To enable versioning, LaminDB auto-generates `uid` values so that different versions of a notebook or script are grouped by a random \"stem uid\" `suid`, consisting in the same first 12 characters of the `uid`. The remaining 4 characters encode a revision in a `ruid`, hence, `uid = f\"{suid}{ruid}\"`. You can optionally label any given version with a semantic tag via the `transform.version` field.\n",
     "\n",
     ":::"
    ]
@@ -424,10 +410,13 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# get an entity by uid (here, the current notebook)\n",
+    "# get a single record by uid (here, the current notebook)\n",
     "transform = ln.Transform.get(\"FPnfDtJz8qbE\")\n",
     "\n",
-    "# filter by description\n",
+    "# get a single record by matching a field\n",
+    "transform = ln.Transform.get(name=\"Introduction\")\n",
+    "\n",
+    "# get a set of records by filtering on description\n",
     "ln.Artifact.filter(description=\"my RNA-seq\").df()\n",
     "\n",
     "# query all artifacts ingested from the current notebook\n",
@@ -1073,7 +1062,7 @@
     "<img src=\"https://lamin-site-assets.s3.amazonaws.com/.lamindb/KQmzmmLOeBN0C8Ykitjn.svg\" width=\"800\">\n",
     "\n",
     "\n",
-    "Both figures are based on mere calls to `ln.track()` in notebooks, pipelines & app."
+    "Both figures are based on mere calls to `ln.context.track()` in notebooks, pipelines & app."
    ]
   },
   {

{lamindb-0.75.1 → lamindb-0.76.1}/docs/records.ipynb

@@ -110,13 +110,34 @@
     "users_dict = ln.User.lookup().dict()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "d54676dd",
+   "metadata": {},
+   "source": [
+    "## Query exactly one record"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "463ff17c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# by uid\n",
+    "ln.User.get(\"DzTjkKse\")\n",
+    "# by any expression involving fields\n",
+    "ln.User.get(handle=\"testuser1\")"
+   ]
+  },
   {
    "attachments": {},
    "cell_type": "markdown",
    "id": "45ac3b5c",
    "metadata": {},
    "source": [
-    "## Filter by metadata"
+    "## Query sets of records"
    ]
   },
   {
@@ -148,7 +169,7 @@
     "\n",
     "- `.df()`: A pandas `DataFrame` with each record in a row.\n",
     "- `.all()`: A {class}`~lamindb.core.QuerySet`.\n",
-    "- `.one()`: Exactly one record. Will raise an error if there is none.\n",
+    "- `.one()`: Exactly one record. Will raise an error if there is none. Is equivalent to the `.get()` method shown above.\n",
     "- `.one_or_none()`: Either one record or `None` if there is no query result."
    ]
   },

lamindb-0.76.1/docs/rest.md

@@ -0,0 +1,3 @@
+# `REST`
+
+Actual content in lamin-docs.

{lamindb-0.75.1 → lamindb-0.76.1}/docs/track.ipynb

@@ -6,7 +6,7 @@
    "source": [
     "# Track notebooks & scripts\n",
     "\n",
-    "Call {meth}`~lamindb.track` to track code along with its inputs and outputs.\n",
+    "Call {meth}`~lamindb.core.Context.track` to track code along with its inputs and outputs.\n",
     "\n",
     "```{note}\n",
     "\n",
@@ -39,9 +39,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "When you first call `ln.track()`, it raises an exception and creates a `stem_uid` & `version` to identify a notebook or script in your database.\n",
+    "When you first call `ln.context.track()`, it raises an exception and creates a `stem_uid` & `version` to identify a notebook or script in your database.\n",
     "\n",
-    "When you call it a second time, `ln.track()` saves transform and run records in their registries. The {class}`~lamindb.Transform` registry allows you to find your notebooks, scripts and pipelines. The {class}`~lamindb.Run` registry allows you to find their runs."
+    "When you call it a second time, `ln.context.track()` saves transform and run records in their registries. The {class}`~lamindb.Transform` registry allows you to find your notebooks, scripts and pipelines. The {class}`~lamindb.Run` registry allows you to find their runs."
    ]
   },
   {
@@ -52,9 +52,8 @@
    "source": [
     "import lamindb as ln\n",
     "\n",
-    "ln.settings.transform.stem_uid = \"9priar0hoE5u\"  # <-- auto-generated by ln.track()\n",
-    "ln.settings.transform.version = \"1\"  # <-- auto-generated by ln.track()\n",
-    "ln.track()"
+    "ln.context.uid = \"9priar0hoE5u0000\"\n",
+    "ln.context.track()"
    ]
   },
   {
@@ -153,7 +152,7 @@
     "ln.settings.sync_git_repo = \"https://github.com/...\"\n",
     "ln.settings.transform.stem_uid = \"9priar0hoE5u\"\n",
     "ln.settings.transform.version = \"1\"\n",
-    "run = ln.track()\n",
+    "ln.context.track()\n",
     "\n",
     "# load input artifacts\n",
     "artifact = ln.Artifact.filter(...).one()\n",

{lamindb-0.75.1 → lamindb-0.76.1}/docs/transfer.ipynb

@@ -40,9 +40,8 @@
    "source": [
     "import lamindb as ln\n",
     "\n",
-    "ln.settings.transform.stem_uid = \"ITeOtm7bhtdq\"\n",
-    "ln.settings.transform.version = \"1\"\n",
-    "ln.track()"
+    "ln.context.uid = \"ITeOtm7bhtdq0000\"\n",
+    "ln.context.track()"
    ]
   },
   {

{lamindb-0.75.1 → lamindb-0.76.1}/docs/tutorial.ipynb

@@ -132,12 +132,10 @@
    },
    "outputs": [],
    "source": [
-    "# copy-pasted identifiers for your notebook or script\n",
-    "ln.settings.transform.stem_uid = \"NJvdsWWbJlZS\"  # <-- auto-generated by running ln.track()\n",
-    "ln.settings.transform.version = \"1\"  # <-- auto-generated by running ln.track()\n",
+    "ln.context.uid = \"NJvdsWWbJlZS0000\"  # <-- auto-generated by ln.context.track()\n",
     "\n",
     "# track the execution of your notebook or script\n",
-    "ln.track()"
+    "ln.context.track()"
    ]
   },
   {
@@ -145,7 +143,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "By calling {func}`~lamindb.track`, the notebook is automatically linked as the source of all data that's about to be saved!"
+    "By calling {func}`~lamindb.core.Context.track`, the notebook is automatically linked as the source of all data that's about to be saved!"
    ]
   },
   {
@@ -169,7 +167,7 @@
     "\n",
     "```python\n",
     "transform = ln.Transform(name=\"My pipeline\", version=\"1.2.0\")\n",
-    "ln.track(transform)\n",
+    "ln.context.track(transform)\n",
     "```\n",
     "\n",
     ":::\n",
@@ -182,7 +180,7 @@
     "\n",
     "A notebook that's run a single time on specific data is not a pipeline: it's a (versioned) **document** that produced insight or some other form of data representation (with parallels to an ELN in the wetlab).\n",
     "\n",
-    "Because humans are in the loop, most mistakes happen when using notebooks: {func}`~lamindb.track` helps avoiding some.\n",
+    "Because humans are in the loop, most mistakes happen when using notebooks: {func}`~lamindb.core.Context.track` helps avoiding some.\n",
     "\n",
     "(An early blog post on this is [here](https://lamin.ai/blog/2022/nbproject).)\n",
     "\n",

{lamindb-0.75.1 → lamindb-0.76.1}/docs/tutorial2.ipynb

@@ -391,7 +391,7 @@
     "    return output_data\n",
     "\n",
     "transform = ln.Transform(name=\"Petal & sepal regressor\", type=\"pipeline\")\n",
-    "run = ln.track(transform=transform)\n",
+    "ln.context.track(transform=transform)\n",
     "df = run_ml_model()"
    ]
   },
@@ -422,15 +422,6 @@
     "And this is the pipeline that produced the dataframe:"
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "run"
-   ]
-  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -441,7 +432,7 @@
    },
    "outputs": [],
    "source": [
-    "run.transform.view_lineage()"
+    "ln.context.transform.view_lineage()"
    ]
   },
   {

{lamindb-0.75.1 → lamindb-0.76.1}/lamindb/__init__.py

@@ -21,9 +21,8 @@ Key functionality:
 .. autosummary::
    :toctree: .
 
+   context
    connect
-   track
-   finish
    Curate
    view
    save
@@ -42,7 +41,7 @@ Modules & settings:
 """
 
 # denote a release candidate for 0.1.0 with 0.1rc1, 0.1a1, 0.1b1, etc.
-__version__ = "0.75.1"
+__version__ = "0.76.1"
 
 import os as _os
 
@@ -93,10 +92,9 @@ if _check_instance_setup(from_lamindb=True):
         integrations,
     )
     from ._curate import Curate
-    from ._finish import finish
     from ._save import save
     from ._view import view
-    from .core._run_context import run_context as _run_context
+    from .core._context import context
     from .core._settings import settings
 
     # schema modules
@@ -107,8 +105,8 @@ if _check_instance_setup(from_lamindb=True):
 
         _reload_schema_modules(_lamindb_setup.settings.instance)
 
-    track = _run_context._track
+    track = context.track  # backward compat
+    finish = context.finish  # backward compat
     settings.__doc__ = """Global :class:`~lamindb.core.Settings`."""
+    context.__doc__ = """Global :class:`~lamindb.core.Context`."""
     from django.db.models import Q
-
-    Annotate = Curate  # backward compat

{lamindb-0.75.1 → lamindb-0.76.1}/lamindb/_artifact.py

@@ -107,7 +107,7 @@ def process_pathlike(
                 new_root = list(filepath.parents)[-1]
                 # do not register remote storage locations on hub if the current instance
                 # is not managed on the hub
-                storage_settings = init_storage(
+                storage_settings, _ = init_storage(
                     new_root, prevent_register_hub=not setup_settings.instance.is_on_hub
                 )
                 storage_record = register_storage_in_instance(storage_settings)
@@ -594,6 +594,7 @@ def __init__(artifact: Artifact, *args, **kwargs):
     kwargs["description"] = description
     kwargs["visibility"] = visibility
     kwargs["_accessor"] = accessor
+    kwargs["is_new_version_of"] = is_new_version_of
     # this check needs to come down here because key might be populated from an
     # existing file path during get_artifact_kwargs_from_data()
     if (

{lamindb-0.75.1 → lamindb-0.76.1}/lamindb/_collection.py

@@ -158,6 +158,7 @@ def __init__(
             run=run,
             version=version,
             visibility=visibility,
+            is_new_version_of=is_new_version_of,
             **kwargs,
         )
     collection._artifacts = artifacts

{lamindb-0.75.1 → lamindb-0.76.1}/lamindb/_curate.py

@@ -313,11 +313,11 @@ class DataFrameCurator:
 
     def clean_up_failed_runs(self):
         """Clean up previous failed runs that don't save any outputs."""
-        from lamindb.core._run_context import run_context
+        from lamindb.core._context import context
 
-        if run_context.transform is not None:
-            Run.filter(transform=run_context.transform, output_artifacts=None).exclude(
-                uid=run_context.run.uid
+        if context.run is not None:
+            Run.filter(transform=context.run.transform, output_artifacts=None).exclude(
+                uid=context.run.uid
             ).delete()
 
 

{lamindb-0.75.1 → lamindb-0.76.1}/lamindb/_feature.py

@@ -42,7 +42,7 @@ def __init__(self, *args, **kwargs):
         return None
     # now we proceed with the user-facing constructor
     if len(args) != 0:
-        raise ValueError("Only non-keyword args allowed")
+        raise ValueError("Only keyword args allowed")
     dtype: type | str = kwargs.pop("dtype") if "dtype" in kwargs else None
     # cast type
     if dtype is None: