matchbox-db 0.7.14.dev46__tar.gz → 0.7.14.dev51__tar.gz

{matchbox_db-0.7.14.dev46/src/matchbox_db.egg-info → matchbox_db-0.7.14.dev51}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matchbox-db
-Version: 0.7.14.dev46
+Version: 0.7.14.dev51
 Summary: A framework for orchestrating and comparing data linking and deduplication methodologies.
 Author: Department for Business and Trade
 Project-URL: Documentation, https://uktrade.github.io/matchbox/
@@ -11,6 +11,7 @@ License-File: LICENSE
 Requires-Dist: click>=8.1.7
 Requires-Dist: cryptography>=44.0.2
 Requires-Dist: duckdb>=1.1.1
+Requires-Dist: email-validator>=2.3.0
 Requires-Dist: faker>=36.1.1
 Requires-Dist: frozendict>=2.4.6
 Requires-Dist: httpx>=0.28.0
@@ -29,7 +30,6 @@ Requires-Dist: sqlglot[rs]>=26.12.1
 Requires-Dist: tenacity>=9.1.2
 Requires-Dist: textual>=0.87.1
 Requires-Dist: typer>=0.15.0
-Requires-Dist: psutil>=7.1.3
 Provides-Extra: server
 Requires-Dist: adbc-driver-postgresql>=1.5.0; extra == "server"
 Requires-Dist: alembic>=1.15.2; extra == "server"

{matchbox_db-0.7.14.dev46 → matchbox_db-0.7.14.dev51}/pyproject.toml

@@ -10,6 +10,7 @@ dependencies = [
     "click>=8.1.7",
     "cryptography>=44.0.2",
     "duckdb>=1.1.1",
+    "email-validator>=2.3.0",
     "faker>=36.1.1",
     "frozendict>=2.4.6",
     "httpx>=0.28.0",
@@ -28,7 +29,6 @@ dependencies = [
     "tenacity>=9.1.2",
     "textual>=0.87.1",
     "typer>=0.15.0",
-    "psutil>=7.1.3"
 ]
 
 [project.optional-dependencies]

{matchbox_db-0.7.14.dev46 → matchbox_db-0.7.14.dev51}/src/matchbox/client/_handler.py

@@ -65,7 +65,7 @@ from matchbox.common.exceptions import (
     MatchboxUserNotFoundError,
 )
 from matchbox.common.hash import hash_to_base64
-from matchbox.common.logging import logger, profile_time
+from matchbox.common.logging import logger, profile
 
 URLEncodeHandledType = str | int | float | bytes | StrEnum
 
@@ -189,7 +189,7 @@ def login(user_name: str) -> int:
     """Log into Matchbox and return the user ID."""
     logger.debug(f"Log in attempt for {user_name}")
     response = CLIENT.post("/auth/login", json=User(user_name=user_name).model_dump())
-    return User.model_validate(response.json()).user_id
+    return User.model_validate(response.json()).user_name
 
 
 @http_retry
@@ -422,7 +422,7 @@ def update_resolution(
     return ResourceOperationStatus.model_validate(res.json())
 
 
-@profile_time(kwarg="path")
+@profile(kwarg="path")
 @http_retry
 def get_resolution(path: ResolutionPath) -> Resolution | None:
     """Get a resolution from Matchbox."""
@@ -435,7 +435,7 @@ def get_resolution(path: ResolutionPath) -> Resolution | None:
     return Resolution.model_validate(res.json())
 
 
-@profile_time(kwarg="path")
+@profile(kwarg="path")
 @http_retry
 def set_data(path: ResolutionPath, data: pl.DataFrame | Table) -> None:
     """Upload source hashes or model results to server."""
@@ -482,7 +482,7 @@ def get_resolution_stage(path: ResolutionPath) -> UploadStage:
     return upload_info.stage
 
 
-@profile_time(kwarg="path")
+@profile(kwarg="path")
 @http_retry
 def get_results(path: ModelResolutionPath) -> Table:
     """Get model results from Matchbox."""
@@ -515,7 +515,7 @@ def delete_resolution(
 
 
 @http_retry
-def sample_for_eval(n: int, resolution: ModelResolutionPath, user_id: int) -> Table:
+def sample_for_eval(n: int, resolution: ModelResolutionPath, user_name: str) -> Table:
     """Sample model results for evaluation."""
     res = CLIENT.get(
         "/eval/samples",
@@ -525,7 +525,7 @@ def sample_for_eval(n: int, resolution: ModelResolutionPath, user_id: int) -> Ta
                 "collection": resolution.collection,
                 "run_id": resolution.run,
                 "resolution": resolution.name,
-                "user_id": user_id,
+                "user_name": user_name,
             }
         ),
     )
@@ -548,7 +548,7 @@ def send_eval_judgement(judgement: Judgement) -> None:
     """Send judgements to the server."""
     logger.debug(
         f"Submitting judgement {judgement.shown}:{judgement.endorsed} "
-        f"for {judgement.user_id}"
+        f"for {judgement.user_name}"
     )
     CLIENT.post("/eval/judgements", json=judgement.model_dump())
 

{matchbox_db-0.7.14.dev46 → matchbox_db-0.7.14.dev51}/src/matchbox/client/_settings.py

@@ -42,7 +42,7 @@ class ClientSettings(BaseSettings):
             # Decode header and payload
             header = json.loads(base64.urlsafe_b64decode(parts[0] + "=="))
             payload = json.loads(base64.urlsafe_b64decode(parts[1] + "=="))
-        except Exception as e:  # noqa: BLE0001
+        except Exception as e:  # noqa: BLE001
             raise ValueError("Invalid JWT.") from e
 
         # Basic header checks

{matchbox_db-0.7.14.dev46 → matchbox_db-0.7.14.dev51}/src/matchbox/client/cli/eval/app.py

@@ -108,7 +108,6 @@ class EntityResolutionApp(App):
 
     sample_limit: int
     resolution: ModelResolutionPath
-    user_id: int
     user_name: str
     dag: DAG
     show_help: bool
@@ -304,8 +303,7 @@ class EntityResolutionApp(App):
         if not user_name:
             raise MatchboxClientSettingsException("User name is unset.")
 
-        self.user_name = user_name
-        self.user_id = _handler.login(user_name=user_name)
+        self.user_name = _handler.login(user_name=user_name)
 
     async def load_samples(self) -> None:
         """Load evaluation samples from the server."""
@@ -326,7 +324,7 @@ class EntityResolutionApp(App):
             new_samples_dict = get_samples(
                 n=needed,
                 resolution=self.resolution.name,
-                user_id=self.user_id,
+                user_name=self.user_name,
                 dag=self.dag,
             )
         except Exception as e:  # noqa: BLE001
@@ -370,10 +368,10 @@ class EntityResolutionApp(App):
             return
 
         try:
-            if self.user_id is None:
-                raise RuntimeError("User ID is not set")
+            if self.user_name is None:
+                raise RuntimeError("User name is not set")
             judgement = create_judgement(
-                current.item, current.assignments, self.user_id
+                current.item, current.assignments, self.user_name
             )
             _handler.send_eval_judgement(judgement)
         except Exception as exc:

{matchbox_db-0.7.14.dev46 → matchbox_db-0.7.14.dev51}/src/matchbox/client/dags.py

@@ -28,7 +28,7 @@ from matchbox.common.exceptions import (
     MatchboxCollectionNotFoundError,
     MatchboxResolutionNotFoundError,
 )
-from matchbox.common.logging import logger, profile_time
+from matchbox.common.logging import logger, profile
 from matchbox.common.transform import truth_int_to_float
 
 
@@ -561,7 +561,7 @@ class DAG:
         # If no matches, _handler will raise
         return {from_source: list(matches[0].source_id), **to_sources_results}
 
-    @profile_time(kwarg="node")
+    @profile(kwarg="node")
     def resolve(
         self,
         node: ResolutionName | None = None,

{matchbox_db-0.7.14.dev46 → matchbox_db-0.7.14.dev51}/src/matchbox/client/eval/samples.py

@@ -73,14 +73,14 @@ class EvaluationItem(BaseModel):
 
 
 def create_judgement(
-    item: EvaluationItem, assignments: dict[int, str], user_id: int
+    item: EvaluationItem, assignments: dict[int, str], user_name: str
 ) -> Judgement:
     """Convert item assignments to Judgement - no default group assignment.
 
     Args:
         item: Evaluation item
         assignments: Column assignments (group_idx -> group_letter)
-        user_id: User ID for the judgement
+        user_name: User name for the judgement
 
     Returns:
         Judgement with endorsed groups based on assignments
@@ -93,7 +93,7 @@ def create_judgement(
         groups.setdefault(group, []).extend(leaf_ids)
 
     endorsed = [sorted(set(leaf_ids)) for leaf_ids in groups.values()]
-    return Judgement(user_id=user_id, shown=item.cluster_id, endorsed=endorsed)
+    return Judgement(user_name=user_name, shown=item.cluster_id, endorsed=endorsed)
 
 
 def create_evaluation_item(
@@ -136,7 +136,7 @@ def create_evaluation_item(
 def get_samples(
     n: int,
     dag: DAG,
-    user_id: int,
+    user_name: str,
     resolution: ModelResolutionName | None = None,
 ) -> dict[int, EvaluationItem]:
     """Retrieve samples enriched with source data as EvaluationItems.
@@ -144,7 +144,7 @@ def get_samples(
     Args:
         n: Number of clusters to sample
         dag: DAG for which to retrieve samples
-        user_id: ID of the user requesting the samples
+        user_name: Name of the user requesting the samples
         resolution: The optional resolution from which to sample. If not provided,
             the final step in the DAG is used
 
@@ -163,7 +163,9 @@ def get_samples(
     samples: pl.DataFrame = cast(
         pl.DataFrame,
         pl.from_arrow(
-            _handler.sample_for_eval(n=n, resolution=resolution_path, user_id=user_id)
+            _handler.sample_for_eval(
+                n=n, resolution=resolution_path, user_name=user_name
+            )
         ),
     )
 

{matchbox_db-0.7.14.dev46 → matchbox_db-0.7.14.dev51}/src/matchbox/client/models/models.py

@@ -24,7 +24,7 @@ from matchbox.common.dtos import (
 )
 from matchbox.common.exceptions import MatchboxResolutionNotFoundError
 from matchbox.common.hash import hash_model_results
-from matchbox.common.logging import logger, profile_mem, profile_time
+from matchbox.common.logging import logger, profile
 from matchbox.common.transform import truth_float_to_int, truth_int_to_float
 
 if TYPE_CHECKING:
@@ -234,8 +234,7 @@ class Model:
         result = _handler.delete_resolution(path=self.resolution_path, certain=certain)
         return result.success
 
-    @profile_mem()
-    @profile_time(attr="name")
+    @profile(attr="name")
     def run(
         self, for_validation: bool = False, cache_queries: bool = False
     ) -> ModelResults:
@@ -285,8 +284,7 @@ class Model:
         return self.results
 
     @post_run
-    @profile_mem()
-    @profile_time(attr="name")
+    @profile(attr="name")
     def sync(self) -> None:
         """Send the model config and results to the server.
 

{matchbox_db-0.7.14.dev46 → matchbox_db-0.7.14.dev51}/src/matchbox/client/sources.py

@@ -24,7 +24,7 @@ from matchbox.common.dtos import (
 )
 from matchbox.common.exceptions import MatchboxResolutionNotFoundError
 from matchbox.common.hash import HashMethod, hash_arrow_table, hash_rows
-from matchbox.common.logging import logger, profile_mem, profile_time
+from matchbox.common.logging import logger, profile
 
 if TYPE_CHECKING:
     from matchbox.client.dags import DAG
@@ -223,7 +223,7 @@ class Source:
             return False
         return self.config == other.config
 
-    @profile_time(attr="name")
+    @profile(attr="name")
     def fetch(
         self,
         qualify_names: bool = False,
@@ -270,8 +270,7 @@ class Source:
                 return_type=return_type,
             )
 
-    @profile_mem()
-    @profile_time(attr="name")
+    @profile(attr="name")
     def run(self, batch_size: int | None = None) -> ArrowTable:
         """Hash a dataset from its warehouse, ready to be inserted, and cache hashes.
 
@@ -376,8 +375,7 @@ class Source:
         return self.config.f(self.name, fields)
 
     @post_run
-    @profile_mem()
-    @profile_time(attr="name")
+    @profile(attr="name")
     def sync(self) -> None:
         """Send the source config and hashes to the server.
 

{matchbox_db-0.7.14.dev46 → matchbox_db-0.7.14.dev51}/src/matchbox/common/arrow.py

@@ -36,7 +36,7 @@ SCHEMA_RESULTS: Final[pa.Schema] = pa.schema(
 
 SCHEMA_JUDGEMENTS: Final[pa.Schema] = pa.schema(
     [
-        ("user_id", pa.uint64()),
+        ("user_name", pa.large_string()),
         ("endorsed", pa.uint64()),
         ("shown", pa.uint64()),
     ]

{matchbox_db-0.7.14.dev46 → matchbox_db-0.7.14.dev51}/src/matchbox/common/dtos.py

@@ -30,6 +30,54 @@ from matchbox.common.exceptions import MatchboxNameError
 from matchbox.common.hash import base64_to_hash, hash_to_base64
 
 
+class MatchboxName(str):
+    """Sub-class of string which validates names for the Matchbox DB."""
+
+    PATTERN = r"^[a-zA-Z0-9_.-]+$"
+
+    def __new__(cls, value: str) -> Self:
+        """Creates new instance of validated name."""
+        if not isinstance(value, str):
+            raise MatchboxNameError("Name must be a string")
+        if not re.match(cls.PATTERN, value):
+            raise MatchboxNameError(
+                f"Name '{value}' is invalid. It can only include "
+                "alphanumeric characters, underscores, dots or hyphens."
+            )
+
+        return super().__new__(cls, value)
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls,
+        source_type: Any,  # noqa: ANN401
+        handler: GetCoreSchemaHandler,
+    ) -> core_schema.CoreSchema:
+        """Generate core schema for Pydantic compatibility."""
+        return core_schema.no_info_plain_validator_function(
+            cls,
+            serialization=core_schema.plain_serializer_function_ser_schema(
+                lambda x: x, return_schema=core_schema.str_schema()
+            ),
+        )
+
+    @classmethod
+    def __get_pydantic_json_schema__(
+        cls,
+        schema: core_schema.CoreSchema,
+        handler: GetJsonSchemaHandler,
+    ) -> JsonSchemaValue:
+        """Generate JSON schema for OpenAPI documentation."""
+        json_schema = handler(core_schema.str_schema())
+        json_schema.update(
+            {
+                "type": "string",
+                "pattern": cls.PATTERN,
+            }
+        )
+        return json_schema
+
+
 class DataTypes(StrEnum):
     """Enumeration of supported data types.
 
@@ -169,6 +217,7 @@ class BackendResourceType(StrEnum):
     CLUSTER = "cluster"
     USER = "user"
     JUDGEMENT = "judgement"
+    SYSTEM = "system"
 
 
 class BackendParameterType(StrEnum):
@@ -205,24 +254,30 @@ class User(BaseModel):
 
     model_config = ConfigDict(populate_by_name=True)
 
-    user_id: int | None = None
     user_name: str = Field(alias="sub")
     email: EmailStr | None = None
 
 
+GroupName: TypeAlias = MatchboxName
+"""Type alias for group names."""
+
+
 class Group(BaseModel):
     """Group definition."""
 
-    name: str
+    name: GroupName
     description: str | None = None
     is_system: bool = False
     members: list[User] = []
 
 
 class PermissionGrant(BaseModel):
-    """A permission on a resource. Resource context comes from URL."""
+    """A permission on a resource.
 
-    group_name: str
+    Resource context should always be supplied.
+    """
+
+    group_name: GroupName
     permission: PermissionType
 
 
@@ -234,54 +289,6 @@ class AuthStatusResponse(BaseModel):
     token: str | None = None
 
 
-class MatchboxName(str):
-    """Sub-class of string which validates names for the Matchbox DB."""
-
-    PATTERN = r"^[a-zA-Z0-9_.-]+$"
-
-    def __new__(cls, value: str) -> Self:
-        """Creates new instance of validated name."""
-        if not isinstance(value, str):
-            raise MatchboxNameError("Name must be a string")
-        if not re.match(cls.PATTERN, value):
-            raise MatchboxNameError(
-                f"Name '{value}' is invalid. It can only include "
-                "alphanumeric characters, underscores, dots or hyphens."
-            )
-
-        return super().__new__(cls, value)
-
-    @classmethod
-    def __get_pydantic_core_schema__(
-        cls,
-        source_type: Any,  # noqa: ANN401
-        handler: GetCoreSchemaHandler,
-    ) -> core_schema.CoreSchema:
-        """Generate core schema for Pydantic compatibility."""
-        return core_schema.no_info_plain_validator_function(
-            cls,
-            serialization=core_schema.plain_serializer_function_ser_schema(
-                lambda x: x, return_schema=core_schema.str_schema()
-            ),
-        )
-
-    @classmethod
-    def __get_pydantic_json_schema__(
-        cls,
-        schema: core_schema.CoreSchema,
-        handler: GetJsonSchemaHandler,
-    ) -> JsonSchemaValue:
-        """Generate JSON schema for OpenAPI documentation."""
-        json_schema = handler(core_schema.str_schema())
-        json_schema.update(
-            {
-                "type": "string",
-                "pattern": cls.PATTERN,
-            }
-        )
-        return json_schema
-
-
 CollectionName: TypeAlias = MatchboxName
 """Type alias for collection names."""
 

{matchbox_db-0.7.14.dev46 → matchbox_db-0.7.14.dev51}/src/matchbox/common/eval.py

@@ -18,7 +18,7 @@ ModelComparison: TypeAlias = dict[ModelResolutionPath, PrecisionRecall]
 class Judgement(BaseModel):
     """User determination on how to group source clusters from a model cluster."""
 
-    user_id: int
+    user_name: str
     shown: int = Field(description="ID of the model cluster shown to the user")
     endorsed: list[list[int]] = Field(
         description="""Groups of source cluster IDs that user thinks belong together"""

{matchbox_db-0.7.14.dev46 → matchbox_db-0.7.14.dev51}/src/matchbox/common/exceptions.py

@@ -174,15 +174,17 @@ class MatchboxServerFileError(MatchboxException):
 class MatchboxUserNotFoundError(MatchboxException):
     """User not found."""
 
-    def __init__(self, message: str | None = None, user_id: str | None = None) -> None:
+    def __init__(
+        self, message: str | None = None, user_name: str | None = None
+    ) -> None:
         """Initialise the exception."""
         if message is None:
             message = "User not found."
-            if user_id is not None:
-                message = f"User {user_id} not found."
+            if user_name is not None:
+                message = f"User {user_name} not found."
 
         super().__init__(message)
-        self.user_id = user_id
+        self.user_name = user_name
 
 
 class MatchboxResolutionNotFoundError(MatchboxException):
@@ -260,6 +262,10 @@ class MatchboxConnectionError(MatchboxException):
     """Connection to Matchbox's backend database failed."""
 
 
+class MatchboxPermissionDeniedError(MatchboxException):
+    """Raised when a user lacks permission for an action."""
+
+
 class MatchboxDeletionNotConfirmed(MatchboxException):
     """Deletion must be confirmed: if certain, rerun with certain=True."""
 
@@ -319,6 +325,18 @@ class MatchboxTooManySamplesRequested(MatchboxException):
     """Too many samples have been requested from the server."""
 
 
+class MatchboxGroupNotFoundError(MatchboxException):
+    """Raised when a group is not found."""
+
+
+class MatchboxGroupAlreadyExistsError(MatchboxException):
+    """Raised when attempting to create a group that already exists."""
+
+
+class MatchboxSystemGroupError(MatchboxException):
+    """Raised when attempting to modify or delete a system group."""
+
+
 # -- Adapter DB exceptions --
 
 

{matchbox_db-0.7.14.dev46 → matchbox_db-0.7.14.dev51}/src/matchbox/common/logging.py

@@ -4,11 +4,9 @@ import functools
 import importlib.metadata
 import logging
 import time
-import tracemalloc
 from collections.abc import Callable
 from typing import Any, Final, Literal, ParamSpec, TypeVar
 
-import psutil
 from rich.console import Console
 from rich.progress import (
     BarColumn,
@@ -117,14 +115,14 @@ T = TypeVar("T")
 P = ParamSpec("P")
 
 
-def profile_time(
+def profile(
     logger: PrefixedLoggerAdapter = logger,
     level: int = logging.INFO,
     prefix: str | None = "Profiling",
     attr: str | None = None,
     kwarg: str | None = None,
 ) -> Callable[[Callable[P, T]], Callable[P, T]]:
-    """Decorator to profile running time of functions and methods using logger.
+    """Decorator to profile functions and methods using logger.
 
     Args:
         logger: The logger to use.
@@ -172,45 +170,3 @@ def profile_time(
         return wrapper
 
     return decorator
-
-
-def profile_mem(
-    logger: PrefixedLoggerAdapter = logger,
-    level: int = logging.DEBUG,
-    prefix: str | None = "Memory",
-) -> Callable[[Callable[P, T]], Callable[P, T]]:
-    """Decorator to profile memory use of functions and methods using logger.
-
-    Args:
-        logger: The logger to use.
-        level: The level to use to log the profiling information. It defaults to INFO.
-        prefix: Prefix to pass to the logged message.
-    """
-
-    def decorator(func: Callable[P, T]) -> Callable[P, T]:
-        @functools.wraps(func)
-        def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
-            tracemalloc.start()
-
-            try:
-                return func(*args, **kwargs)
-            finally:
-                # Final and peak mem use of decorated function
-                curr, peak = tracemalloc.get_traced_memory()
-                tracemalloc.stop()
-                # OS memory availability after function run
-                mem = psutil.virtual_memory()
-
-                msg = (
-                    f"Memory usage of {func.__name__}: "
-                    f"current {round(curr / 10**6, 2)} MB, "
-                    f"peak {round(peak / 10**6, 2)} MB. "
-                    f"Total memory: {round(mem[0] / 10**6, 2)} MB, "
-                    f"available memory: {round(mem[1] / 10**6, 2)} MB."
-                )
-
-                logger.log(level, msg, prefix=prefix)
-
-        return wrapper
-
-    return decorator

{matchbox_db-0.7.14.dev46 → matchbox_db-0.7.14.dev51}/src/matchbox/server/api/routers/auth.py

@@ -48,9 +48,7 @@ def login(
     credentials: User,
 ) -> User:
     """Receive a User with a username and returns it with a user ID."""
-    return User(
-        user_id=backend.login(credentials.user_name), user_name=credentials.user_name
-    )
+    return backend.login(credentials)
 
 
 @router.get("/status")

{matchbox_db-0.7.14.dev46 → matchbox_db-0.7.14.dev51}/src/matchbox/server/api/routers/eval.py

@@ -115,7 +115,7 @@ def sample(
     run_id: RunID,
     resolution: ModelResolutionName,
     n: int,
-    user_id: int,
+    user_name: str,
 ) -> ParquetResponse:
     """Sample n cluster to validate."""
     try:
@@ -124,7 +124,7 @@ def sample(
                 collection=collection, run=run_id, name=resolution
             ),
             n=n,
-            user_id=user_id,
+            user_name=user_name,
         )
         buffer = table_to_buffer(sample)
         return ParquetResponse(buffer.getvalue())