lamindb_setup 1.9.0__py3-none-any.whl → 1.10.0__py3-none-any.whl

lamindb_setup/_setup_user.py

@@ -43,20 +43,51 @@ def load_user(email: str | None = None, handle: str | None = None) -> UserSettin
 
 
 def login(
-    user: str | None = None, *, api_key: str | None = None, key: str | None = None
+    user: str | None = None, *, api_key: str | None = None, **kwargs
 ) -> UserSettings:
-    """Log in user.
+    # note that the docstring needs to be synced with lamin login
+    """Log into LaminHub.
+
+    `login()` prompts for your API key unless you set it via the `LAMIN_API_KEY` environment variable or pass it as an argument.
+
+    You can create your API key in your account settings on LaminHub (top right corner).
 
     Args:
-        user: handle or email
-        api_key: API key
-        key: legacy API key
+        user: User handle.
+        api_key: API key.
+
+    See Also:
+        Login via the CLI command `lamin login`, see `here <https://docs.lamin.ai/cli#login>`__.
+
+    Examples:
+
+        Logging in the first time::
+
+            import lamindb as ln
+
+            ln.setup.login()  # prompts for API key
+
+        After authenticating multiple users, you can switch between user profiles::
+
+            ln.setup.login("myhandle")  # pass your user handle
     """
-    if user is None and api_key is None:
-        if "LAMIN_API_KEY" in os.environ:
-            api_key = os.environ["LAMIN_API_KEY"]
-        else:
-            raise ValueError("Both `user` and `api_key` should not be `None`.")
+    if user is None:
+        if api_key is None:
+            if "LAMIN_API_KEY" in os.environ:
+                api_key = os.environ["LAMIN_API_KEY"]
+            else:
+                api_key = input("Your API key: ")
+    elif api_key is not None:
+        raise ValueError("Please provide either 'user' or 'api_key', not both.")
+
+    for kwarg in kwargs:
+        if kwarg != "key":
+            raise TypeError(f"login() got unexpected keyword argument '{kwarg}'")
+    key: str | None = kwargs.get("key", None)  # legacy API key aka password
+    if key is not None:
+        logger.warning(
+            "the legacy API key is deprecated and will likely be removed in a future version"
+        )
 
     if api_key is None:
         if "@" in user:  # type: ignore
@@ -66,7 +97,6 @@ def login(
         user_settings = load_user(email, handle)
 
         if key is not None:
-            # within UserSettings, we still call it "password" for a while
             user_settings.password = key
 
         if user_settings.password is None:
@@ -101,9 +131,9 @@ def login(
         user_uuid, user_id, user_handle, user_name, access_token = response
 
     if api_key is not None:
-        logger.success(f"logged in {user_handle} (uid: {user_id})")
+        logger.success(f"logged in {user_handle}")
     else:  # legacy flow
-        logger.success(f"logged in with email {user_settings.email} (uid: {user_id})")
+        logger.success(f"logged in with email {user_settings.email}")
 
     user_settings.uid = user_id
     user_settings.handle = user_handle
@@ -121,6 +151,15 @@ def login(
 
 
 def logout():
+    """Log out the current user.
+
+    This deletes the `~/.lamin/current_user.env` so that you'll no longer be automatically authenticated in the environment.
+
+    It keeps a copy as `~/.lamin/user--<user_handle>.env` so you can easily switch between user profiles.
+
+    See Also:
+        Logout via the CLI command `lamin logout`, see `here <https://docs.lamin.ai/cli#logout>`__.
+    """
     if current_user_settings_file().exists():
         current_user_settings_file().unlink()
         settings._user_settings = None

lamindb_setup/core/_aws_storage.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from lamin_utils import logger
+
 
 def get_location(ip="ipinfo.io"):
     import requests  # type: ignore
@@ -32,7 +34,13 @@ def find_closest_aws_region() -> str:
         "eu-central-1": {"latitude": 50.11, "longitude": 8.68},  # Frankfurt
         "eu-west-2": {"latitude": 51.51, "longitude": -0.13},  # London, UK
     }
-    your_location = get_location()
+    # sometimes get_location fails to obtain coordinates
+    try:
+        your_location = get_location()
+    except Exception as e:
+        logger.warning(f"failed to infer location, using us-east-1: {e}")
+        return "us-east-1"
+
     closest_region = ""
     min_distance = float("inf")
     for region in aws_region_locations:

lamindb_setup/core/_hub_core.py

@@ -93,7 +93,75 @@ def _get_storage_records_for_instance(
     return response.data
 
 
-def _select_storage(
+def select_space(lnid: str) -> dict | None:
+    return call_with_fallback_auth(
+        _select_space,
+        lnid=lnid,
+    )
+
+
+def _select_space(lnid: str, client: Client) -> dict | None:
+    response = client.table("space").select("*").eq("lnid", lnid).execute()
+    return response.data[0] if response.data else None
+
+
+def update_storage_with_space(storage_lnid: str, space_lnid: str) -> dict | None:
+    return call_with_fallback_auth(
+        _update_storage_with_space,
+        storage_lnid=storage_lnid,
+        space_lnid=space_lnid,
+    )
+
+
+def _update_storage_with_space(
+    storage_lnid: str, space_lnid: str, client: Client
+) -> dict | None:
+    # unfortunately these are two network requests
+    # but postgrest doesn't allow doing it in one
+    try:
+        space_response = (
+            client.table("space").select("id").eq("lnid", space_lnid).execute()
+        )
+
+        if not space_response.data:
+            raise ValueError(
+                f"Try again! Space with lnid '{space_lnid}' not found on hub"
+            )
+
+        space_id = space_response.data[0]["id"]
+
+        update_response = (
+            client.table("storage")
+            .update({"space_id": space_id})
+            .eq("lnid", storage_lnid)
+            .execute()
+        )
+
+        if not update_response.data:
+            raise ValueError(
+                f"Try again! Storage with lnid '{storage_lnid}' not found or update failed on hub"
+            )
+
+        return update_response.data[0]
+
+    except Exception as e:
+        print(f"Try again! Error updating storage in hub: {e}")
+        return None
+
+
+def select_storage(lnid: str) -> dict | None:
+    return call_with_fallback_auth(
+        _select_storage,
+        lnid=lnid,
+    )
+
+
+def _select_storage(lnid: str, client: Client) -> dict | None:
+    response = client.table("storage").select("*").eq("lnid", lnid).execute()
+    return response.data[0] if response.data else None
+
+
+def _select_storage_by_settings(
     ssettings: StorageSettings, update_uid: bool, client: Client
 ) -> bool:
     root = ssettings.root_as_str
@@ -147,24 +215,26 @@ def select_storage_or_parent(path: str, access_token: str | None = None) -> dict
 
 def init_storage_hub(
     ssettings: StorageSettings,
-    auto_populate_instance: bool = True,
     created_by: UUID | None = None,
     access_token: str | None = None,
     prevent_creation: bool = False,
+    is_default: bool = False,
+    space_id: UUID | None = None,
 ) -> Literal["hub-record-retrieved", "hub-record-created", "hub-record-not-created"]:
     """Creates or retrieves an existing storage record from the hub."""
     if settings.user.handle != "anonymous" or access_token is not None:
         return call_with_fallback_auth(
             _init_storage_hub,
             ssettings=ssettings,
-            auto_populate_instance=auto_populate_instance,
             created_by=created_by,
             access_token=access_token,
             prevent_creation=prevent_creation,
+            is_default=is_default,
+            space_id=space_id,
         )
     else:
         storage_exists = call_with_fallback(
-            _select_storage, ssettings=ssettings, update_uid=True
+            _select_storage_by_settings, ssettings=ssettings, update_uid=True
         )
         if storage_exists:
             return "hub-record-retrieved"
@@ -175,9 +245,10 @@ def init_storage_hub(
 def _init_storage_hub(
     client: Client,
     ssettings: StorageSettings,
-    auto_populate_instance: bool,
     created_by: UUID | None = None,
     prevent_creation: bool = False,
+    is_default: bool = False,
+    space_id: UUID | None = None,
 ) -> Literal["hub-record-retrieved", "hub-record-created", "hub-record-not-created"]:
     from lamindb_setup import settings
 
@@ -185,28 +256,23 @@ def _init_storage_hub(
     # storage roots are always stored without the trailing slash in the SQL
     # database
     root = ssettings.root_as_str
-    if _select_storage(ssettings, update_uid=True, client=client):
+    if _select_storage_by_settings(ssettings, update_uid=True, client=client):
         return "hub-record-retrieved"
     if prevent_creation:
         return "hub-record-not-created"
     if ssettings.type_is_cloud:
-        id = uuid.uuid5(uuid.NAMESPACE_URL, root)
+        hash_string = (
+            root if ssettings.type_is_cloud else f"{ssettings.region}://{root}"
+        )
+        id = uuid.uuid5(uuid.NAMESPACE_URL, hash_string)
     else:
         id = uuid.uuid4()
-    if (
-        ssettings._instance_id is None
-        and settings._instance_exists
-        and auto_populate_instance
-    ):
+    if ssettings._instance_id is None and settings._instance_exists:
         logger.warning(
             f"will manage storage location {ssettings.root_as_str} with instance {settings.instance.slug}"
         )
         ssettings._instance_id = settings.instance._id
-    instance_id_hex = (
-        ssettings._instance_id.hex
-        if (ssettings._instance_id is not None and auto_populate_instance)
-        else None
-    )
+    assert ssettings._instance_id is not None, "connect to an instance"
     fields = {
         "id": id.hex,
         "lnid": ssettings.uid,
@@ -214,11 +280,10 @@ def _init_storage_hub(
         "root": root,
         "region": ssettings.region,
         "type": ssettings.type,
-        "instance_id": instance_id_hex,
-        # the empty string is important as we want the user flow to be through LaminHub
-        # if this errors with unique constraint error, the user has to update
-        # the description in LaminHub
+        "instance_id": ssettings._instance_id.hex,
         "description": "",
+        "is_default": is_default,
+        "space_id": space_id.hex if space_id is not None else None,
     }
     # TODO: add error message for violated unique constraint
     # on root & description
@@ -331,6 +396,7 @@ def _init_instance_hub(
         "schema_str": isettings._schema_str,
         "lamindb_version": lamindb_version,
         "public": False,
+        "created_by_id": account_id.hex,  # type: ignore
     }
     if isettings.dialect != "sqlite":
         db_dsn = LaminDsnModel(db=isettings.db)
@@ -351,9 +417,6 @@ def _init_instance_hub(
     except APIError:
         logger.warning(f"instance already existed at: https://lamin.ai/{slug}")
         return None
-    client.table("storage").update(
-        {"instance_id": isettings._id.hex, "is_default": True}
-    ).eq("id", isettings.storage._uuid.hex).execute()  # type: ignore
     if isettings.dialect != "sqlite" and isettings.is_remote:
         logger.important(f"go to: https://lamin.ai/{slug}")
 

lamindb_setup/core/_settings.py

@@ -2,11 +2,14 @@ from __future__ import annotations
 
 import os
 import sys
+import warnings
 from typing import TYPE_CHECKING
 
 from lamin_utils import logger
 from platformdirs import user_cache_dir
 
+from lamindb_setup.errors import CurrentInstanceNotConfigured
+
 from ._settings_load import (
     load_cache_path_from_settings,
     load_instance_settings,
@@ -87,10 +90,13 @@ class SetupSettings:
         - in Python: `ln.setup.settings.auto_connect = True/False`
         - via the CLI: `lamin settings set auto-connect true/false`
         """
-        return self._auto_connect_path.exists()
+        return True
 
     @auto_connect.setter
     def auto_connect(self, value: bool) -> None:
+        # logger.warning(
+        #     "setting auto_connect to `False` no longer has an effect and the setting will likely be removed in the future; since lamindb 1.7, auto_connect `True` no longer clashes with connecting in a Python session",
+        # )
         if value:
             self._auto_connect_path.touch()
         else:
@@ -201,9 +207,10 @@ class SetupSettings:
         If `True`, the current instance is connected, meaning that the db and other settings
         are properly configured for use.
         """
-        from .django import IS_SETUP  # always import to protect from assignment
-
-        return IS_SETUP
+        if self._instance_exists:
+            return self.instance.slug != "none/none"
+        else:
+            return False
 
     @property
     def private_django_api(self) -> bool:
@@ -266,7 +273,7 @@ class SetupSettings:
             self.instance  # noqa
             return True
         # this is implicit logic that catches if no instance is loaded
-        except SystemExit:
+        except CurrentInstanceNotConfigured:
             return False
 
     @property

lamindb_setup/core/_settings_instance.py

@@ -17,6 +17,7 @@ from ._settings_storage import (
     LEGACY_STORAGE_UID_FILE_KEY,
     STORAGE_UID_FILE_KEY,
     StorageSettings,
+    get_storage_type,
     init_storage,
     instance_uid_from_uuid,
 )
@@ -31,6 +32,7 @@ if TYPE_CHECKING:
     from uuid import UUID
 
     from ._settings_user import UserSettings
+    from .types import UPathStr
 
 LOCAL_STORAGE_MESSAGE = "No local storage location found in current environment: defaulting to cloud storage"
 
@@ -50,6 +52,18 @@ def is_local_db_url(db_url: str) -> bool:
     return False
 
 
+def check_is_instance_remote(root: UPathStr, db: str | None) -> bool:
+    # returns True for cloud SQLite
+    # and remote postgres
+    root_str = str(root)
+    if not root_str.startswith("create-s3") and get_storage_type(root_str) == "local":
+        return False
+
+    if db is not None and is_local_db_url(db):
+        return False
+    return True
+
+
 class InstanceSettings:
     """Instance settings."""
 
@@ -58,9 +72,8 @@ class InstanceSettings:
         id: UUID,  # instance id/uuid
         owner: str,  # owner handle
         name: str,  # instance name
-        storage: StorageSettings,  # storage location
+        storage: StorageSettings | None = None,  # storage location
         keep_artifacts_local: bool = False,  # default to local storage
-        uid: str | None = None,  # instance uid/lnid
         db: str | None = None,  # DB URI
         modules: str | None = None,  # comma-separated string of module names
         git_repo: str | None = None,  # a git repo URL
@@ -76,8 +89,7 @@ class InstanceSettings:
         self._id_: UUID = id
         self._owner: str = owner
         self._name: str = name
-        self._uid: str | None = uid
-        self._storage: StorageSettings = storage
+        self._storage: StorageSettings | None = storage
         validate_db_arg(db)
         self._db: str | None = db
         self._schema_str: str | None = modules
@@ -232,7 +244,7 @@ class InstanceSettings:
         For a cloud instance, this is cloud storage. For a local instance, this
         is a local directory.
         """
-        return self._storage
+        return self._storage  # type: ignore
 
     @property
     def local_storage(self) -> StorageSettings:
@@ -431,6 +443,10 @@ class InstanceSettings:
                 "It overwrites all db connections and is used instead of `instance.db`."
             )
         if self._db is None:
+            from .django import IS_SETUP
+
+            if self._storage is None and self.slug == "none/none":
+                return "sqlite:///:memory:"
             # here, we want the updated sqlite file
             # hence, we don't use self._sqlite_file_local()
             # error_no_origin=False because on instance init
@@ -476,15 +492,7 @@ class InstanceSettings:
     @property
     def is_remote(self) -> bool:
         """Boolean indicating if an instance has no local component."""
-        if not self.storage.type_is_cloud:
-            return False
-
-        if self.dialect == "postgresql":
-            if is_local_db_url(self.db):
-                return False
-        # returns True for cloud SQLite
-        # and remote postgres
-        return True
+        return check_is_instance_remote(self.storage.root_as_str, self.db)
 
     @property
     def is_on_hub(self) -> bool:
@@ -523,7 +531,7 @@ class InstanceSettings:
             write_to_disk: Save these instance settings to disk and
                 overwrite the current instance settings file.
         """
-        if write_to_disk:
+        if write_to_disk and self.slug != "none/none":
             assert self.name is not None
             filepath = self._get_settings_file()
             # persist under filepath for later reference

lamindb_setup/core/_settings_load.py

@@ -9,7 +9,7 @@ from dotenv import dotenv_values
 from lamin_utils import logger
 from pydantic import ValidationError
 
-from lamindb_setup.errors import SettingsEnvFileOutdated
+from lamindb_setup.errors import CurrentInstanceNotConfigured, SettingsEnvFileOutdated
 
 from ._settings_instance import InstanceSettings
 from ._settings_storage import StorageSettings
@@ -50,7 +50,7 @@ def load_instance_settings(instance_settings_file: Path | None = None):
     if instance_settings_file is None:
         instance_settings_file = current_instance_settings_file()
     if not instance_settings_file.exists():
-        raise SystemExit("No instance connected! Call `lamin connect` or `lamin init`")
+        raise CurrentInstanceNotConfigured
     try:
         settings_store = InstanceSettingsStore(_env_file=instance_settings_file)
     except (ValidationError, TypeError) as error:

lamindb_setup/core/_settings_storage.py

@@ -92,11 +92,11 @@ def init_storage(
     instance_id: UUID,
     instance_slug: str,
     register_hub: bool | None = None,
-    prevent_register_hub: bool = False,
     init_instance: bool = False,
     created_by: UUID | None = None,
     access_token: str | None = None,
     region: str | None = None,
+    space_uuid: UUID | None = None,
 ) -> tuple[
     StorageSettings,
     Literal["hub-record-not-created", "hub-record-retrieved", "hub-record-created"],
@@ -145,19 +145,17 @@ def init_storage(
     )
     # this retrieves the storage record if it exists already in the hub
     # and updates uid and instance_id in ssettings
-    register_hub = (
-        register_hub or ssettings.type_is_cloud
-    )  # default to registering cloud storage
     if register_hub and not ssettings.type_is_cloud and ssettings.host is None:
         raise ValueError(
             "`host` must be set for local storage locations that are registered on the hub"
         )
     hub_record_status = init_storage_hub(
         ssettings,
-        auto_populate_instance=not init_instance,
         created_by=created_by,
         access_token=access_token,
-        prevent_creation=prevent_register_hub or not register_hub,
+        prevent_creation=not register_hub,
+        is_default=init_instance,
+        space_id=space_uuid,
     )
     # we check the write access here if the storage record has not been retrieved from the hub
     if hub_record_status != "hub-record-retrieved":

lamindb_setup/core/django.py

@@ -9,7 +9,7 @@ import jwt
 import time
 from pathlib import Path
 import time
-from ._settings_instance import InstanceSettings
+from ._settings_instance import InstanceSettings, is_local_db_url
 
 from lamin_utils import logger
 
@@ -156,18 +156,33 @@ def setup_django(
 
     import dj_database_url
     import django
+    from django.apps import apps
     from django.conf import settings
     from django.core.management import call_command
 
     # configuration
     if not settings.configured:
+        instance_db = isettings.db
+        if isettings.dialect == "postgresql":
+            if os.getenv("LAMIN_DB_SSL_REQUIRE") == "false":
+                ssl_require = False
+            else:
+                ssl_require = not is_local_db_url(instance_db)
+            options = {"connect_timeout": os.getenv("PGCONNECT_TIMEOUT", 20)}
+        else:
+            ssl_require = False
+            options = {}
         default_db = dj_database_url.config(
             env="LAMINDB_DJANGO_DATABASE_URL",
-            default=isettings.db,
+            default=instance_db,
             # see comment next to patching BaseDatabaseWrapper below
             conn_max_age=CONN_MAX_AGE,
             conn_health_checks=True,
+            ssl_require=ssl_require,
         )
+        if options:
+            # do not overwrite keys in options if set
+            default_db["OPTIONS"] = {**options, **default_db.get("OPTIONS", {})}
         DATABASES = {
             "default": default_db,
         }
@@ -214,6 +229,9 @@ def setup_django(
                 STATIC_URL="static/",
             )
         settings.configure(**kwargs)
+        # this isn't needed the first time django.setup() is called, but for unknown reason it's needed the second time
+        # the first time, it already defaults to true
+        apps.apps_ready = True
         django.setup(set_prefix=False)
         # https://laminlabs.slack.com/archives/C04FPE8V01W/p1698239551460289
         from django.db.backends.base.base import BaseDatabaseWrapper
@@ -278,6 +296,7 @@ def reset_django():
     app_names = {"django"} | {app.name for app in apps.get_app_configs()}
 
     apps.app_configs.clear()
+    apps.all_models.clear()
     apps.apps_ready = apps.models_ready = apps.ready = apps.loading = False
     apps.clear_cache()
 

lamindb_setup/core/upath.py

@@ -994,6 +994,9 @@ def check_storage_is_empty(
             root_string += "/"
         directory_string = root_string + ".lamindb"
     objects = root_upath.fs.find(directory_string)
+    if account_for_sqlite_file:
+        # ignore exclusion dir for cloud sqlite
+        objects = [o for o in objects if "/.lamindb/_exclusion/" not in o]
     n_files = len(objects)
     n_diff = n_files - n_offset_objects
     ask_for_deletion = (
@@ -1001,10 +1004,7 @@ def check_storage_is_empty(
         if raise_error
         else "consider deleting them"
     )
-    message = (
-        f"'{directory_string}' contains {n_files - n_offset_objects} objects"
-        f" - {ask_for_deletion}"
-    )
+    message = f"'{directory_string}' contains {n_diff} objects" f" - {ask_for_deletion}"
     if n_diff > 0:
         if raise_error:
             raise StorageNotEmpty(message) from None

lamindb_setup/errors.py

@@ -3,6 +3,7 @@
 .. autosummary::
    :toctree: .
 
+   CurrentInstanceNotConfigured
    InstanceNotSetupError
    ModuleWasntConfigured
    StorageAlreadyManaged
@@ -27,6 +28,7 @@ class DefaultMessageException(Exception):
         super().__init__(message)
 
 
+# TODO: remove this exception sooner or later because we don't have a need for it anymore
 class InstanceNotSetupError(DefaultMessageException):
     default_message = """\
 To use lamindb, you need to connect to an instance.
@@ -37,6 +39,14 @@ If you used the CLI to set up lamindb in a notebook, restart the Python session.
 """
 
 
+class CurrentInstanceNotConfigured(DefaultMessageException):
+    default_message = """\
+No instance is connected! Call
+- CLI:     lamin connect / lamin init
+- Python:  ln.connect()  / ln.setup.init()
+- R:       ln$connect()  / ln$setup$init()"""
+
+
 MODULE_WASNT_CONFIGURED_MESSAGE_TEMPLATE = (
     "'{}' wasn't configured for this instance -- "
     "if you want it, go to your instance settings page and add it under 'schema modules' (or ask an admin to do so)"

{lamindb_setup-1.9.0.dist-info → lamindb_setup-1.10.0.dist-info}/METADATA

@@ -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