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

{matchbox_db-0.7.14.dev45/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.dev45
+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/

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

@@ -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
@@ -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.dev45 → 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.dev45 → 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.dev45 → 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.dev45 → 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.dev45 → 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.dev45 → 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.dev45 → 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.dev45 → 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.dev45 → 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())

{matchbox_db-0.7.14.dev45 → matchbox_db-0.7.14.dev51}/src/matchbox/server/base.py

@@ -12,16 +12,22 @@ from pydantic import BaseModel, Field, SecretStr, field_validator, model_validat
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 from matchbox.common.dtos import (
+    BackendResourceType,
     Collection,
     CollectionName,
+    Group,
+    GroupName,
     Match,
     ModelResolutionPath,
+    PermissionGrant,
+    PermissionType,
     Resolution,
     ResolutionPath,
     Run,
     RunID,
     SourceResolutionPath,
     UploadStage,
+    User,
 )
 from matchbox.common.eval import Judgement, ModelComparison
 from matchbox.common.logging import LogLevelType
@@ -32,6 +38,25 @@ else:
     S3Client = Any
 
 
+PERMISSION_GRANTS: dict[PermissionType, list[PermissionType]] = {
+    PermissionType.READ: [
+        PermissionType.READ,
+        PermissionType.WRITE,
+        PermissionType.ADMIN,
+    ],
+    PermissionType.WRITE: [PermissionType.WRITE, PermissionType.ADMIN],
+    PermissionType.ADMIN: [PermissionType.ADMIN],
+}
+"""A global variable that defines the permission hierarchy.
+
+Keys are the permission, values are a list of permissions that would
+grant the permission.
+
+For example, only `PermissionType.ADMIN` can grant `PermissionType.ADMIN`,
+but any permission implies `PermissionType.READ`.
+"""
+
+
 class MatchboxBackends(StrEnum):
     """The available backends for Matchbox."""
 
@@ -584,12 +609,153 @@ class MatchboxDBAdapter(ABC):
         Orphan clusters are clusters recorded in the Clusters table but that are
         not referenced in other tables.
         """
+        ...
+
+    # User, group and permissions management
+
+    @abstractmethod
+    def login(self, user: User) -> User:
+        """Upserts the user to the database.
+
+        Args:
+            user: A User with a username and optionally an email
+        """
+        ...
+
+    @abstractmethod
+    def get_user_groups(self, user_name: str) -> list[GroupName]:
+        """Get names of all groups a user belongs to.
+
+        Args:
+            user_name: The username to get the groups of
+        """
+        ...
+
+    @abstractmethod
+    def list_groups(self) -> list[Group]:
+        """List all groups."""
+        ...
+
+    @abstractmethod
+    def get_group(self, name: GroupName) -> Group:
+        """Get group details including members.
+
+        Args:
+            name: The name of the group to fetch.
+
+        Raises:
+            MatchboxGroupNotFoundError: If group doesn't exist.
+        """
+        ...
+
+    @abstractmethod
+    def create_group(self, group: Group) -> None:
+        """Create a new group.
+
+        Arg:
+            group: The group to create
+
+        Raises:
+            MatchboxGroupAlreadyExistsError: If group name taken.
+        """
+        ...
+
+    @abstractmethod
+    def delete_group(self, name: GroupName, certain: bool = False) -> None:
+        """Delete a group.
+
+        Args:
+            name: The name of the group to delete
+            certain: Whether to delete the group without confirmation.
+
+        Raises:
+            MatchboxGroupNotFoundError: If group doesn't exist.
+            MatchboxSystemGroupError: If attempting to delete a system group.
+            MatchboxDeletionNotConfirmed: If certain=False.
+        """
+        ...
+
+    @abstractmethod
+    def add_user_to_group(self, user_name: str, group_name: GroupName) -> None:
+        """Add a user to a group. Creates user if they don't exist.
+
+        Raises:
+            MatchboxGroupNotFoundError: If group doesn't exist.
+        """
+        ...
+
+    @abstractmethod
+    def remove_user_from_group(self, user_name: str, group_name: GroupName) -> None:
+        """Remove a user from a group.
+
+        Raises:
+            MatchboxGroupNotFoundError: If group doesn't exist.
+            MatchboxUserNotFoundError: If user doesn't exist.
+        """
+        ...
+
+    @abstractmethod
+    def check_permission(
+        self,
+        user_name: str,
+        permission: PermissionType,
+        resource: Literal[BackendResourceType.SYSTEM] | CollectionName,
+    ) -> bool:
+        """Check user permission against a resource.
+
+        Args:
+            user_name: The username to check.
+            permission: The permission type to check
+            resource: The resource to check. One of "system" or a collection name
+        """
+        ...
+
+    @abstractmethod
+    def get_permissions(
+        self,
+        resource: Literal[BackendResourceType.SYSTEM] | CollectionName,
+    ) -> list[PermissionGrant]:
+        """Get all granted permissions against a resource.
+
+        Args:
+            resource: The resource to get permissions for. One of "system" or a
+                collection name
+        """
+        ...
 
-    # User management
+    @abstractmethod
+    def grant_permission(
+        self,
+        group_name: GroupName,
+        permission: PermissionType,
+        resource: Literal[BackendResourceType.SYSTEM] | CollectionName,
+    ) -> None:
+        """Grants a permission on a resource.
+
+        Args:
+            group_name: The name of the group to grant permission to
+            permission: The permission to grant
+            resource: The resource to grant permission on. One of "system" or a
+                collection name
+        """
+        ...
 
     @abstractmethod
-    def login(self, user_name: str) -> int:
-        """Receives a user name and returns user ID."""
+    def revoke_permission(
+        self,
+        group_name: GroupName,
+        permission: PermissionType,
+        resource: Literal[BackendResourceType.SYSTEM] | CollectionName,
+    ) -> None:
+        """Revoke permission on a resource.
+
+        Args:
+            group_name: The name of the group to revoke permission of
+            permission: The permission to revoke
+            resource: The resource to revoke permission from. One of "system" or a
+                collection name
+        """
+        ...
 
     # Evaluation management
 
@@ -625,13 +791,15 @@ class MatchboxDBAdapter(ABC):
         ...
 
     @abstractmethod
-    def sample_for_eval(self, n: int, path: ModelResolutionPath, user_id: int) -> Table:
+    def sample_for_eval(
+        self, n: int, path: ModelResolutionPath, user_name: str
+    ) -> Table:
         """Sample a cluster to validate.
 
         Args:
             n: Number of clusters to sample
             path: Path of resolution from which to sample
-            user_id: ID of user requesting the sample
+            user_name: Name of user requesting the sample
 
         Returns:
             An Arrow table with the same schema as returned by `query()`