lamindb_setup 1.9.0__tar.gz → 1.10.0__tar.gz

{lamindb_setup-1.9.0 → lamindb_setup-1.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: lamindb_setup
-Version: 1.9.0
+Version: 1.10.0
 Summary: Setup & configure LaminDB.
 Author-email: Lamin Labs <open-source@lamin.ai>
 Requires-Python: >=3.10
@@ -21,7 +21,7 @@ Requires-Dist: psutil
 Requires-Dist: packaging
 Requires-Dist: urllib3<2 ; extra == "aws"
 Requires-Dist: aiobotocore[boto3]>=2.5.4,<3.0.0 ; extra == "aws"
-Requires-Dist: s3fs>=2023.12.2,<=2025.3.2,!=2024.10.0 ; extra == "aws"
+Requires-Dist: s3fs>=2023.12.2,<=2025.7.0,!=2024.10.0 ; extra == "aws"
 Requires-Dist: line_profiler ; extra == "dev"
 Requires-Dist: psycopg2-binary ; extra == "dev"
 Requires-Dist: python-dotenv ; extra == "dev"
@@ -32,7 +32,7 @@ Requires-Dist: pytest-xdist ; extra == "dev"
 Requires-Dist: nbproject-test>=0.4.3 ; extra == "dev"
 Requires-Dist: pandas ; extra == "dev"
 Requires-Dist: django-schema-graph ; extra == "erdiagram"
-Requires-Dist: gcsfs>=2023.12.2,<=2025.3.2 ; extra == "gcp"
+Requires-Dist: gcsfs>=2023.12.2,<=2025.7.0 ; extra == "gcp"
 Project-URL: Home, https://github.com/laminlabs/lamindb-setup
 Provides-Extra: aws
 Provides-Extra: dev

{lamindb_setup-1.9.0 → lamindb_setup-1.10.0}/docs/hub-cloud/08-test-multi-session.ipynb

@@ -7,6 +7,13 @@
     "# Test multi instance and multi user session"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This notebook is complemented by the `faq/setup.ipynb` notebook in lamindb."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -54,6 +61,15 @@
     "ln_setup.init(storage=\"./testsetup\")"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "assert ln_setup.settings.instance.slug == \"testuser1/testsetup\""
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -111,43 +127,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Let us try to init another instance in the same Python session:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from lamindb_setup._init_instance import CannotSwitchDefaultInstance\n",
-    "\n",
-    "with pytest.raises(CannotSwitchDefaultInstance):\n",
-    "    ln_setup.init(storage=\"./testsetup2\")\n",
-    "with pytest.raises(CannotSwitchDefaultInstance):\n",
-    "    ln_setup.connect(\"testsetup\")\n",
-    "with pytest.raises(RuntimeError):\n",
-    "    ln_setup.migrate.create()\n",
-    "with pytest.raises(RuntimeError):\n",
-    "    ln_setup.migrate.deploy()\n",
-    "\n",
-    "assert ln_setup.settings.instance.slug == \"testuser1/testsetup\""
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "Reset `django` and connect to another instance:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "ln_setup.core.django.reset_django()"
+    "Connect to another instance in the same process:"
    ]
   },
   {
@@ -182,7 +162,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": "py312",
    "language": "python",
    "name": "python3"
   },
@@ -196,7 +176,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.16"
+   "version": "3.12.8"
   }
  },
  "nbformat": 4,

{lamindb_setup-1.9.0 → lamindb_setup-1.10.0}/docs/hub-prod/test-insufficient-user-info.ipynb

@@ -38,16 +38,6 @@
     "## Log in with in-sufficient information"
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "with pytest.raises(ValueError):\n",
-    "    ln_setup.login()"
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -179,7 +169,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.17"
+   "version": "3.10.16"
   },
   "nbproject": {
    "id": "vLOmzd6d4Jow",

{lamindb_setup-1.9.0 → lamindb_setup-1.10.0}/lamindb_setup/__init__.py

@@ -35,7 +35,7 @@ Modules & settings:
 
 """
 
-__version__ = "1.9.0"  # denote a release candidate for 0.1.0 with 0.1rc1
+__version__ = "1.10.0"  # denote a release candidate for 0.1.0 with 0.1rc1
 
 import os
 

{lamindb_setup-1.9.0 → lamindb_setup-1.10.0}/lamindb_setup/_cache.py

@@ -8,6 +8,7 @@ from lamin_utils import logger
 
 from .core._settings_save import save_platform_user_storage_settings
 from .core._settings_store import system_settings_file
+from .errors import CurrentInstanceNotConfigured
 
 
 def clear_cache_dir():
@@ -19,9 +20,8 @@ def clear_cache_dir():
                 "disconnecting the current instance to update the cloud sqlite database."
             )
             disconnect()
-    except SystemExit as e:
-        if str(e) != "No instance connected! Call `lamin connect` or `lamin init`":
-            raise e
+    except CurrentInstanceNotConfigured:
+        pass
 
     cache_dir = settings.cache_dir
     if cache_dir.exists():

{lamindb_setup-1.9.0 → lamindb_setup-1.10.0}/lamindb_setup/_check_setup.py

@@ -4,7 +4,9 @@ import functools
 import importlib as il
 import inspect
 import os
+from importlib.metadata import distributions
 from typing import TYPE_CHECKING
+from uuid import UUID
 
 from lamin_utils import logger
 
@@ -25,6 +27,7 @@ if TYPE_CHECKING:
 
 
 CURRENT_ISETTINGS: InstanceSettings | None = None
+MODULE_CANDIDATES: set[str] | None = None
 IS_LOADING: bool = False
 
 
@@ -42,7 +45,25 @@ def disable_auto_connect(func: Callable):
     return wrapper
 
 
-def _get_current_instance_settings() -> InstanceSettings | None:
+def find_module_candidates():
+    """Find all local packages that depend on lamindb."""
+    global MODULE_CANDIDATES
+    if MODULE_CANDIDATES is not None:
+        return MODULE_CANDIDATES
+    all_dists = list(distributions())
+    lamindb_deps = {
+        dist.metadata["Name"].lower()
+        for dist in all_dists
+        if dist.requires and any("lamindb" in req.lower() for req in dist.requires)
+    }
+    lamindb_deps.remove("lamindb")
+    MODULE_CANDIDATES = lamindb_deps
+    return lamindb_deps
+
+
+def _get_current_instance_settings(from_module: str | None = None) -> InstanceSettings:
+    from .core._settings_instance import InstanceSettings
+
     global CURRENT_ISETTINGS
 
     if CURRENT_ISETTINGS is not None:
@@ -60,9 +81,17 @@ def _get_current_instance_settings() -> InstanceSettings | None:
                 " command line: `lamin connect <instance>` or `lamin init <...>`"
             )
             raise e
-        return isettings
     else:
-        return None
+        module_candidates = find_module_candidates()
+        isettings = InstanceSettings(
+            id=UUID("00000000-0000-0000-0000-000000000000"),
+            owner="none",
+            name="none",
+            storage=None,
+            modules=",".join(module_candidates),
+        )
+    CURRENT_ISETTINGS = isettings
+    return isettings
 
 
 def _normalize_module_name(module_name: str) -> str:
@@ -132,12 +161,7 @@ def _check_instance_setup(from_module: str | None = None) -> bool:
         return True
     isettings = _get_current_instance_settings()
     if isettings is not None:
-        if (
-            from_module is not None
-            and settings.auto_connect
-            and not django_lamin.IS_SETUP
-            and not IS_LOADING
-        ):
+        if from_module is not None and not django_lamin.IS_SETUP and not IS_LOADING:
             if from_module != "lamindb":
                 _check_module_in_instance_modules(from_module, isettings)
 
@@ -146,13 +170,15 @@ def _check_instance_setup(from_module: str | None = None) -> bool:
                 il.reload(il.import_module(from_module))
             else:
                 django_lamin.setup_django(isettings)
-                logger.important(f"connected lamindb: {isettings.slug}")
-                settings._instance_settings = (
-                    isettings  # update of local storage location
-                )
+                if isettings.slug != "none/none":
+                    logger.important(f"connected lamindb: {isettings.slug}")
+                    # update of local storage location through search_local_root()
+                    settings._instance_settings = isettings
+                else:
+                    logger.warning("not connected, call: ln.connect('account/name')")
         return django_lamin.IS_SETUP
     else:
-        if from_module is not None and settings.auto_connect:
+        if from_module is not None:
             # the below enables users to auto-connect to an instance
             # simply by setting an environment variable, bypassing the
             # need of calling connect() manually

{lamindb_setup-1.9.0 → lamindb_setup-1.10.0}/lamindb_setup/_connect_instance.py

@@ -2,23 +2,22 @@ from __future__ import annotations
 
 import importlib
 import os
+import sys
 from typing import TYPE_CHECKING, Any
 from uuid import UUID
 
 from lamin_utils import logger
 
-from ._check_setup import _check_instance_setup, _get_current_instance_settings
-from ._disconnect import disconnect
-from ._init_instance import (
-    MESSAGE_CANNOT_SWITCH_DEFAULT_INSTANCE,
-    load_from_isettings,
+from ._check_setup import (
+    _check_instance_setup,
+    _get_current_instance_settings,
+    find_module_candidates,
 )
+from ._disconnect import disconnect
+from ._init_instance import load_from_isettings
 from ._silence_loggers import silence_loggers
 from .core._hub_core import connect_instance_hub
-from .core._hub_utils import (
-    LaminDsn,
-    LaminDsnModel,
-)
+from .core._hub_utils import LaminDsnModel
 from .core._settings import settings
 from .core._settings_instance import InstanceSettings
 from .core._settings_load import load_instance_settings
@@ -69,21 +68,18 @@ def update_db_using_local(
     if hub_instance_result["db_scheme"] == "postgresql":
         if db is not None:
             # use only the provided db if it is set
-            db_dsn_hub = LaminDsnModel(db=db)
-            db_dsn_local = db_dsn_hub
-        else:
-            db_dsn_hub = LaminDsnModel(db=hub_instance_result["db"])
+            db_updated = db
+        elif (db_env := os.getenv("LAMINDB_INSTANCE_DB")) is not None:
+            logger.important("loading db URL from env variable LAMINDB_INSTANCE_DB")
             # read directly from the environment
-            if os.getenv("LAMINDB_INSTANCE_DB") is not None:
-                logger.important("loading db URL from env variable LAMINDB_INSTANCE_DB")
-                db_dsn_local = LaminDsnModel(db=os.getenv("LAMINDB_INSTANCE_DB"))
-            # read from a cached settings file in case the hub result is only
-            # read level or inexistent
-            elif settings_file.exists() and (
-                db_dsn_hub.db.user in {None, "none"} or "read" in db_dsn_hub.db.user  # type:ignore
-            ):
+            db_updated = db_env
+        else:
+            db_hub = hub_instance_result["db"]
+            db_dsn_hub = LaminDsnModel(db=db_hub)
+            # read from a cached settings file in case the hub result is inexistent
+            if db_dsn_hub.db.user in {None, "none"} and settings_file.exists():
                 isettings = load_instance_settings(settings_file)
-                db_dsn_local = LaminDsnModel(db=isettings.db)
+                db_updated = isettings.db
             else:
                 # just take the default hub result and ensure there is actually a user
                 if (
@@ -95,22 +91,7 @@ def update_db_using_local(
                         "No database access, please ask your admin to provide you with"
                         " a DB URL and pass it via --db <db_url>"
                     )
-                db_dsn_local = db_dsn_hub
-            if not check_db_dsn_equal_up_to_credentials(db_dsn_hub.db, db_dsn_local.db):
-                raise ValueError(
-                    "The local differs from the hub database information:\n"
-                    "did your database get updated by an admin?\n"
-                    "Consider deleting your cached database environment:\nrm"
-                    f" {settings_file.as_posix()}"
-                )
-        db_updated = LaminDsn.build(
-            scheme=db_dsn_hub.db.scheme,
-            user=db_dsn_local.db.user,
-            password=db_dsn_local.db.password,
-            host=db_dsn_hub.db.host,  # type: ignore
-            port=db_dsn_hub.db.port,
-            database=db_dsn_hub.db.database,
-        )
+                db_updated = db_hub
     return db_updated
 
 
@@ -127,7 +108,12 @@ def _connect_instance(
     if settings_file.exists():
         isettings = load_instance_settings(settings_file)
         # skip hub request for a purely local instance
-        make_hub_request = isettings.is_remote
+        if isettings.is_remote:
+            make_hub_request = True
+        else:
+            make_hub_request = False
+            if db is not None and isettings.dialect == "postgresql":
+                isettings._db = db
     if make_hub_request:
         # the following will return a string if the instance does not exist
         # on the hub
@@ -188,6 +174,62 @@ def _connect_instance(
     return isettings
 
 
+def reset_django_module_variables():
+    # This function updates all module-level references to Django classes
+    # But it will fail to update function level references
+    # So, if a user has
+    # def my_function():
+    #     import lamindb as ln
+    #     ...
+    #
+    # Then it will **not** work and the `ln` variable will become stale and hold a reference
+    # to the old classes
+    # There doesn't seem to be an easy way to fix this problem
+
+    import types
+
+    from django.apps import apps
+
+    app_names = {app.name for app in apps.get_app_configs()}
+
+    for name, module in sys.modules.items():
+        if (
+            module is not None
+            and (not name.startswith("__") or name == "__main__")
+            and name not in sys.builtin_module_names
+            and not (
+                hasattr(module, "__file__")
+                and module.__file__
+                and any(
+                    path in module.__file__ for path in ["/lib/python", "\\lib\\python"]
+                )
+            )
+        ):
+            try:
+                for k, v in vars(module).items():
+                    if (
+                        isinstance(v, types.ModuleType)
+                        and not k.startswith("_")
+                        and getattr(v, "__name__", None) in app_names
+                    ):
+                        if v.__name__ in sys.modules:
+                            vars(module)[k] = sys.modules[v.__name__]
+                    # Also reset classes from Django apps - but check if the class module starts with any app name
+                    elif hasattr(v, "__module__") and getattr(v, "__module__", None):
+                        class_module = v.__module__
+                        # Check if the class module starts with any of our app names
+                        if any(
+                            class_module.startswith(app_name) for app_name in app_names
+                        ):
+                            if class_module in sys.modules:
+                                fresh_module = sys.modules[class_module]
+                                attr_name = getattr(v, "__name__", k)
+                                if hasattr(fresh_module, attr_name):
+                                    vars(module)[k] = getattr(fresh_module, attr_name)
+            except (AttributeError, TypeError):
+                continue
+
+
 def _connect_cli(instance: str) -> None:
     from lamindb_setup import settings as settings_
 
@@ -214,6 +256,9 @@ def connect(instance: str | None = None, **kwargs: Any) -> str | tuple | None:
         instance: Pass a slug (`account/name`) or URL (`https://lamin.ai/account/name`).
             If `None`, looks for an environment variable `LAMIN_CURRENT_INSTANCE` to get the instance identifier.
             If it doesn't find this variable, it connects to the instance that was connected with `lamin connect` through the CLI.
+
+    See Also:
+        Configure an instance for auto-connect via the CLI, see `here <https://docs.lamin.ai/cli#connect>`__.
     """
     # validate kwargs
     valid_kwargs = {
@@ -250,19 +295,45 @@ def connect(instance: str | None = None, **kwargs: Any) -> str | tuple | None:
                     "No instance was connected through the CLI, pass a value to `instance` or connect via the CLI."
                 )
             isettings = isettings_or_none
+            if _db is not None and isettings.dialect == "postgresql":
+                isettings._db = _db
         else:
+            from django.db import connection
+
             owner, name = get_owner_name_from_identifier(instance)
             if _check_instance_setup() and not _test:
                 if (
                     settings._instance_exists
                     and f"{owner}/{name}" == settings.instance.slug
+                    # below is to ensure that if another process interferes
+                    # we don't use the in-memory mock database
+                    # could be made more specific by checking whether the django
+                    # configured database is the same as the one in settings
+                    and connection.settings_dict["NAME"] != ":memory:"
                 ):
-                    logger.important(f"connected lamindb: {settings.instance.slug}")
+                    logger.important(
+                        f"doing nothing, already connected lamindb: {settings.instance.slug}"
+                    )
                     return None
                 else:
-                    raise CannotSwitchDefaultInstance(
-                        MESSAGE_CANNOT_SWITCH_DEFAULT_INSTANCE
-                    )
+                    from lamindb_setup.core.django import reset_django
+
+                    if (
+                        settings._instance_exists
+                        and settings.instance.slug != "none/none"
+                    ):
+                        import lamindb as ln
+
+                        if ln.context.transform is not None:
+                            raise CannotSwitchDefaultInstance(
+                                "Cannot switch default instance while `ln.track()` is live: call `ln.finish()`"
+                            )
+                        else:
+                            logger.important_hint(
+                                "switching the default lamindb instance might produce unexpected side effects with function-scoped imports: "
+                                "please import lamindb at the module level instead of inside functions"
+                            )
+                    reset_django()
             elif (
                 _write_settings
                 and settings._instance_exists
@@ -315,7 +386,9 @@ def connect(instance: str | None = None, **kwargs: Any) -> str | tuple | None:
         load_from_isettings(isettings, user=_user, write_settings=_write_settings)
         if _reload_lamindb:
             importlib.reload(importlib.import_module("lamindb"))
-        logger.important(f"connected lamindb: {isettings.slug}")
+            reset_django_module_variables()
+        if isettings.slug != "none/none":
+            logger.important(f"connected lamindb: {isettings.slug}")
     except Exception as e:
         if isettings is not None:
             if _write_settings:

{lamindb_setup-1.9.0 → lamindb_setup-1.10.0}/lamindb_setup/_delete.py

@@ -65,6 +65,9 @@ def delete(slug: str, force: bool = False, require_empty: bool = True) -> int |
             If the instance is owned by you, it suffices to pass the instance name.
         force: Whether to skip the confirmation prompt.
         require_empty: Whether to check if the instance is empty before deleting.
+
+    See Also:
+        Delete an instance via the CLI, see `here <https://docs.lamin.ai/cli#delete>`__.
     """
     owner, name = get_owner_name_from_identifier(slug)
     isettings = _connect_instance(owner, name, raise_permission_error=False)

{lamindb_setup-1.9.0 → lamindb_setup-1.10.0}/lamindb_setup/_disconnect.py

@@ -8,9 +8,12 @@ from .core.cloud_sqlite_locker import clear_locker
 
 
 def disconnect(mute: bool = False) -> None:
-    """Disconnect an instance.
+    """Clear default instance configuration.
 
     Returns `None` if succeeds, otherwise an exception is raised.
+
+    See Also:
+        Clear default instance configuration via the CLI, see `here <https://docs.lamin.ai/cli#disconnect>`__.
     """
     if current_instance_settings_file().exists():
         instance = settings.instance.slug