cmdbox-cli 1.0.0__py3-none-any.whl

cmdbox/repositories/tag_repository.py

@@ -0,0 +1,91 @@
+from typing import Sequence
+
+from peewee import IntegrityError
+
+from .base_repository import BaseRepository
+from .errors import (
+    NameConflictError,
+    UnknownNameError,
+    ValidationError,
+    UpdateError,
+    UnknownTagError,
+)
+from .validators import TagValidator
+from cmdbox.models import Tag
+
+
+class TagRepository(BaseRepository[Tag]):
+    model = Tag
+
+    def __init__(self, validator: TagValidator | None = None):
+        self.validator = validator or TagValidator()
+
+    def create(self, name: str, description: str | None = None) -> Tag:
+        name = name.strip() if name else None
+        self.validator.validate_create(name=name, description=description)
+        try:
+            return Tag.create(name=name, description=description)
+        except IntegrityError as exc:
+            if name is not None and self._is_unique_name_violation(exc):
+                raise NameConflictError(name=name) from exc
+            raise
+
+    def get_by_name(self, name: str) -> Tag | None:
+        name = name.lower()
+        tag = Tag.get_or_none(Tag.name == name)
+        if tag is None:
+            raise UnknownNameError(name=name)
+        return tag
+
+    def get_by_id(self, tag_id: int) -> Tag | None:
+        tag = Tag.get_or_none(Tag.id == tag_id)
+        if tag is None:
+            raise UnknownTagError(str(tag_id))
+        return tag
+
+    def update(self, tag: Tag, **fields) -> Tag | None:
+        if not tag:
+            raise UpdateError("Tag not found.")
+        if not fields:
+            raise UpdateError("No fields provided for update.")
+
+        if "name" in fields and fields.get("name") is not None:
+            fields["name"] = fields.get("name").strip()
+
+        self.validator.validate_update(
+            name=fields.get("name", tag.name),
+            description=fields.get("description", tag.description),
+        )
+        try:
+            for key, value in fields.items():
+                if not hasattr(tag, key):
+                    raise ValidationError(f"Invalid field: {key}")
+                if value is not None:
+                    setattr(tag, key, value)
+            tag.save()
+            return tag
+        except IntegrityError as exc:
+            name = fields.get("name", "")
+            if name is not None and self._is_unique_name_violation(exc):
+                raise NameConflictError(name=name) from exc
+            raise
+
+    def list_all(
+        self, order_by: str | Sequence[str] = "name", limit: int = 25
+    ) -> list[Tag]:
+        ordering = self._resolve_ordering(order_by)
+        return list(Tag.select().order_by(*ordering).limit(limit))
+
+    def search(
+        self,
+        query: str,
+        fields: str | Sequence[str] | None = ("name", "description"),
+        limit: int = 25,
+    ) -> list[Tag]:
+        return self._search(query, "name", fields, limit=limit)
+
+    def delete(self, tag: Tag) -> bool:
+        if not tag:
+            return False
+        tag.delete_instance()
+        return True

cmdbox/repositories/validators.py

@@ -0,0 +1,256 @@
+from dataclasses import dataclass
+
+from .errors import ValidationError
+
+
+@dataclass(frozen=True)
+class CommandValidatorConfig:
+    """Configuration for command validation rules."""
+
+    reserved_aliases: frozenset[str] = frozenset(
+        {
+            "help",
+            "init",
+            "list",
+            "ls",
+            "add",
+            "rm",
+            "delete",
+        }
+    )
+    max_alias_length: int = 100
+    max_description_length: int = 1000
+
+
+class CommandValidator:
+
+    def __init__(self, config: CommandValidatorConfig | None = None):
+        self.config = config or CommandValidatorConfig()
+
+    def validate_create(
+        self,
+        *,
+        alias: str,
+        template: str,
+        description: str | None = None,
+    ) -> None:
+        """
+        Validates the parameters for creating a Command. Ensures that the provided alias,
+        template, and description meet the required conditions and do not contain
+        self-referencing patterns.
+
+        Args:
+            alias (str): The alias to validate.
+            template (str): The template to validate.
+            description (str | None): The optional description to validate.
+        """
+        self.validate_alias(alias)
+        self.validate_template(template)
+        self.validate_description(description)
+        self.validate_no_self_reference(alias, template)
+
+    def validate_update(
+        self,
+        *,
+        alias: str | None = None,
+        template: str | None = None,
+        description: str | None = None,
+    ):
+        """
+        Validates various update parameters, ensuring they meet the required conditions
+        and constraints. This method can validate a combination of alias, template,
+        and description, applying specific checks for each provided parameter.
+
+        Args:
+            alias (str | None): An optional alias to validate. If provided, it will
+                be checked using the `self.validate_alias` method.
+            template (str | None): An optional template to validate. If provided, it
+                will be checked using the `self.validate_template` method.
+            description (str | None): An optional description to validate. If
+                provided, it will be checked using the `self.validate_description`
+                method.
+        """
+        if alias is not None:
+            self.validate_alias(alias)
+        if template is not None:
+            self.validate_template(template)
+        if description is not None:
+            self.validate_description(description)
+        if alias is not None and template is not None:
+            self.validate_no_self_reference(alias, template)
+
+    def validate_alias(self, alias: str) -> None:
+        if not alias:
+            raise ValidationError("Alias cannot be empty.")
+
+        stripped = alias.strip()
+        if not stripped:
+            raise ValidationError("Alias cannot contain only whitespace.")
+
+        if " " in stripped:
+            raise ValidationError("Alias cannot contain spaces.")
+
+        if stripped in self.config.reserved_aliases:
+            raise ValidationError(f"Alias '{stripped}' is reserved.")
+
+        if len(stripped) > self.config.max_alias_length:
+            raise ValidationError(
+                f"Alias '{stripped}' is too long. Maximum length is {self.config.max_alias_length}."
+            )
+
+    def validate_template(self, template: str) -> None:
+        if not template:
+            raise ValidationError("Template cannot be empty.")
+
+        stripped = template.strip()
+        if not stripped:
+            raise ValidationError("Template cannot contain only whitespace.")
+
+    def validate_description(self, description: str | None) -> None:
+        if not description:
+            return
+        if len(description) > self.config.max_description_length:
+            raise ValidationError(
+                f"Description is too long. Maximum length is {self.config.max_description_length}."
+            )
+
+    def validate_no_self_reference(self, alias: str, template: str) -> None:
+        self_reference = f"<{alias}>"
+        if self_reference in template:
+            raise ValidationError(
+                f"Template cannot contain self-reference: {self_reference}"
+            )
+
+
+@dataclass(frozen=True)
+class VariableValidatorConfig:
+    """Configuration for variable validation rules."""
+
+    reserved_names: frozenset[str] = frozenset(
+        {
+            "help",
+            "init",
+            "list",
+            "ls",
+            "add",
+            "rm",
+            "delete",
+            # Reserved because they are options to the run command and can conflict when dynamically called
+            "preview",
+            "cwd",
+            "env",
+            "capture",
+            "shell",
+            "emit",
+            "verbose",
+        }
+    )
+    max_name_length: int = 100
+
+
+class VariableValidator:
+
+    def __init__(self, config: VariableValidatorConfig | None = None):
+        self.config = config or VariableValidatorConfig()
+
+    def validate_create(self, name: str, value: str) -> None:
+        self.validate_name(name)
+        self.validate_value(value)
+
+    def validate_update(self, name: str | None, value: str | None) -> None:
+        if name is not None:
+            self.validate_name(name)
+        if value is not None:
+            self.validate_value(value)
+
+    def validate_name(self, name: str) -> None:
+        if not name:
+            raise ValidationError("Variable name cannot be empty.")
+
+        stripped = name.strip()
+        if not stripped:
+            raise ValidationError("Variable name cannot contain only whitespace.")
+
+        if " " in stripped:
+            raise ValidationError("Variable name cannot contain spaces.")
+
+        if stripped in self.config.reserved_names:
+            raise ValidationError(f"Variable name '{stripped}' is reserved.")
+
+        if len(stripped) > self.config.max_name_length:
+            raise ValidationError(
+                f"Variable name '{stripped}' is too long. Maximum length is {self.config.max_name_length}."
+            )
+
+    def validate_value(self, value: str) -> None:
+        if value is None:
+            raise ValidationError("Variable value cannot be None.")
+
+    def validate_no_self_reference(self, name: str, value: str) -> None:
+        self_reference = f"<{name}>"
+        if self_reference in value:
+            raise ValidationError(
+                f"Variable value cannot contain self-reference: {self_reference}"
+            )
+
+
+@dataclass(frozen=True)
+class TagValidatorConfig:
+    """Configuration for variable validation rules."""
+
+    reserved_names: frozenset[str] = frozenset(
+        {
+            "help",
+            "init",
+            "list",
+            "ls",
+            "add",
+            "rm",
+            "delete",
+        }
+    )
+    max_name_length: int = 100
+    max_description_length: int = 1000
+
+
+class TagValidator:
+
+    def __init__(self, config: TagValidatorConfig | None = None):
+        self.config = config or TagValidatorConfig()
+
+    def validate_create(self, name: str, description: str | None) -> None:
+        self.validate_name(name)
+        self.validate_description(description)
+
+    def validate_update(self, name: str | None, description: str | None) -> None:
+        if name is not None:
+            self.validate_name(name)
+        if description is not None:
+            self.validate_description(description)
+
+    def validate_name(self, name: str) -> None:
+        if not name:
+            raise ValidationError("Variable name cannot be empty.")
+
+        stripped = name.strip()
+        if not stripped:
+            raise ValidationError("Variable name cannot contain only whitespace.")
+
+        if " " in stripped:
+            raise ValidationError("Variable name cannot contain spaces.")
+
+        if stripped in self.config.reserved_names:
+            raise ValidationError(f"Variable name '{stripped}' is reserved.")
+
+        if len(stripped) > self.config.max_name_length:
+            raise ValidationError(
+                f"Variable name '{stripped}' is too long. Maximum length is {self.config.max_name_length}."
+            )
+
+    def validate_description(self, description: str | None) -> None:
+        if not description:
+            return
+        if len(description) > self.config.max_description_length:
+            raise ValidationError(
+                f"Description is too long. Maximum length is {self.config.max_description_length}."
+            )

cmdbox/repositories/variable_repository.py

@@ -0,0 +1,324 @@
+from typing import Sequence
+
+from peewee import IntegrityError
+
+from .base_repository import BaseRepository
+from .errors import (
+    ValidationError,
+    NameConflictError,
+    UnknownTagError,
+    TagAttachError,
+    TagDetachError,
+    UpdateError,
+    UnknownVariableError,
+)
+from .validators import VariableValidator
+from .results import TagAttachResult, TagDetachResult
+from cmdbox.database import db
+from cmdbox.models import Variable, Tag, VariableTag
+
+
+class VariableRepository(BaseRepository[Variable]):
+    model = Variable
+
+    def __init__(self, validator: VariableValidator | None = None):
+        self.validator = validator or VariableValidator()
+
+    def create(self, name: str, value: str) -> Variable:
+        """
+        Validates and creates a new Variable object based on provided input parameters.
+
+        Args:
+            name (str): Unique identifier for the variable to be created.
+            value (str): The value that will be subbed for the name when executing.
+
+        Returns:
+            Variable: The created Variable object.
+
+        Raises:
+            NameConflictError: If a variable with the provided name already exists
+                and causes a unique constraint violation during creation.
+            IntegrityError: If any database integrity issue occurs during the creation.
+        """
+        name = name.strip() if name else None
+        self.validator.validate_create(name=name, value=value)
+        try:
+            return Variable.create(name=name, value=value)
+        except IntegrityError as exc:
+            if name is not None and self._is_unique_name_violation(exc):
+                raise NameConflictError(name=name) from exc
+            raise
+
+    def get_by_name(self, name: str) -> Variable | None:
+        """
+        Retrieves a variable instance by its name.
+
+        Converts the provided name to lowercase, searches for a variable with the
+        matching name in the database, and retrieves it. This function returns None
+        if no variable with the specified name is found.
+
+        Args:
+            name (str): The name of the variable to retrieve.
+
+        Returns:
+            Variable | None: The variable object if found, otherwise None.
+        """
+        name = name.lower()
+        return Variable.get_or_none(Variable.name == name)
+
+    def get_by_id(self, var_id: int) -> Variable:
+        var = Variable.get_or_none(Variable.id == var_id)
+        if var is None:
+            raise UnknownVariableError(var_id=var_id)
+        return var
+
+    def update(self, variable: Variable, **fields) -> Variable:
+        """
+        Updates an existing variable based on the provided name and fields.
+
+        This method retrieves a variable by its name and updates its fields with the
+        provided values. It validates the updates, ensuring field integrity and
+        uniqueness. If the variable doesn't exist or an update violates constraints,
+        appropriate actions are taken.
+
+        Args:
+            variable (Variable): The variable to update.
+            **fields: Arbitrary keyword arguments representing the fields to update.
+                Supported fields include 'name' and 'value'.
+
+        Returns:
+            Variable: The updated variable object if successful, or None if the
+                variable is not found.
+
+        Raises:
+            ValidationError: If any of the provided fields are invalid or do not exist
+                on a variable.
+            NameConflictError: If the new name conflicts with an existing variable's
+                name.
+            IntegrityError: If there is a general integrity constraint violation during
+                the update process.
+        """
+        if not variable:
+            raise UpdateError("No variable provided for update.")
+        if not fields:
+            raise UpdateError("No fields provided for update.")
+
+        if "name" in fields and fields.get("name") is not None:
+            fields["name"] = fields.get("name").strip()
+
+        self.validator.validate_update(
+            name=fields.get("name", variable.name),
+            value=fields.get("value", variable.value),
+        )
+
+        try:
+            for key, value in fields.items():
+                if not hasattr(variable, key):
+                    raise ValidationError(f"Invalid field: {key}")
+                if value is not None:
+                    setattr(variable, key, value)
+            variable.save()
+            return variable
+        except IntegrityError as exc:
+            name = fields.get("name", "")
+            if name is not None and self._is_unique_name_violation(exc):
+                raise NameConflictError(name=name) from exc
+            raise
+
+    def add_tags(self, variable: Variable, tags: Sequence[Tag]) -> TagAttachResult:
+        """
+        Attach tags to a variable identified by its name.
+
+        This function associates tags with a specified variable. If the tags already
+        exist for the variable, they are added to an existing list. Otherwise, new tags
+        are created and linked to the variable. If no tags are provided, it returns
+        immediately with empty results. In case of a database integrity issue, an
+        appropriate error is raised.
+
+        Args:
+            variable (Variable): The variable to which the tags are to be attached.
+            tags (Sequence[Tag]): A collection of tags to be attached to the
+                variable.
+
+        Returns:
+            TagAttachResult: An object containing lists of newly added tags and
+                tags that already existed.
+
+        Raises:
+            TagAttachError: If there is an issue attaching the tags to the variable,
+                typically due to database integrity constraints.
+        """
+        if not tags:
+            return TagAttachResult(added=[], existing=[])
+        try:
+            with db.atomic():
+                added = []
+                existing = []
+                for tag in tags:
+                    var_tag, created = VariableTag.get_or_create(
+                        variable=variable, tag=tag
+                    )
+                    if created:
+                        added.append(tag.name)
+                    else:
+                        existing.append(tag.name)
+                return TagAttachResult(added=added, existing=existing)
+        except UnknownTagError:
+            raise
+        except IntegrityError as exc:
+            raise TagAttachError("Could not attach tags to variable.") from exc
+
+    def remove_tags(self, variable: Variable, tags: Sequence[Tag]) -> TagDetachResult:
+        """
+        Removes tags from a variable identified by the provided name. The method first validates
+        the tags to ensure they exist in the database, then attempts to remove the associations
+        between the variable and the respective tags. If a tag is not attached to the variable, it
+        is recorded in the `not_attached` list, while successfully removed tags are recorded in
+        the `removed` list. Any errors during detachment raise a `TagDetachError`.
+
+        Args:
+            variable (Variable): The variable from which the tags will be detached.
+            tags (Sequence[Tag]): A list of tags to be detached from the variable.
+
+        Returns:
+            TagDetachResult: Object that contains two lists:
+                - `removed`: A list of successfully detached tags.
+                - `not_attached`: A list of tags that were not associated with the variable.
+
+        Raises:
+            TagDetachError: If the detachment process encounters an issue, such as database
+                integrity errors.
+        """
+        if not variable and not tags:
+            return TagDetachResult(removed=[], not_attached=[])
+        removed = []
+        not_attached = []
+        try:
+            with db.atomic():
+                for tag in tags:
+                    deleted = (
+                        VariableTag.delete()
+                        .where(
+                            (VariableTag.variable == variable)
+                            & (VariableTag.tag == tag)
+                        )
+                        .execute()
+                    )
+                    if deleted:
+                        removed.append(tag.name)
+                    else:
+                        not_attached.append(tag.name)
+        except IntegrityError as exc:
+            raise TagDetachError("Could not detach tags from variable.") from exc
+        except AttributeError:
+            raise TagDetachError("Invalid tag provided.")
+        return TagDetachResult(removed=removed, not_attached=not_attached)
+
+    def list_all(
+        self, order_by: str | Sequence[str] = "name", limit: int = 25
+    ) -> list[Variable]:
+        """
+        Lists all variables from the database, optionally ordered by specified fields.
+
+        Args:
+            order_by (str | Sequence[str]): A string or sequence of strings indicating the field(s)
+                by which the variables should be ordered. Defaults to "name".
+            limit (int): The maximum number of variables to return. Defaults to 25.
+
+        Returns:
+            List[Variable]: A list of Variable objects retrieved from the database,
+                sorted based on the specified ordering criteria.
+        """
+        ordering = self._resolve_ordering(order_by)
+        return list(Variable.select().order_by(*ordering).limit(limit))
+
+    def list_by_tag(
+        self,
+        tags: Sequence[Tag],
+        order_by: str | Sequence[str] = "name",
+        limit: int = 25,
+    ) -> list[Variable]:
+        """
+        Fetches a list of variables filtered by specified tags and ordered by specific
+        criteria.
+
+        This method retrieves a list of `Variable` objects associated with the tags
+        provided in the `tags` argument. The results are optionally ordered based on the
+        `order_by` field and limited by the `limit` argument.
+
+        Args:
+            tags (Sequence[Tag]): A list of Tag objects to filter variables by.
+            order_by (str | Sequence[str]): Criteria to order the resulting variable
+                list. Defaults to "name".
+            limit (int): The maximum number of variables to return. Defaults to 25.
+
+        Returns:
+            list[Variable]: A list of `Variable` objects matching the tags and ordered as
+                requested.
+
+        Raises:
+            UnknownTagError: If one or more provided tags do not exist in the database.
+        """
+        ordering = self._resolve_ordering(order_by)
+        return list(
+            Variable.select()
+            .join(VariableTag)
+            .where(VariableTag.tag << tags)
+            .order_by(*ordering)
+            .distinct()
+            .limit(limit)
+        )
+
+    def search(
+        self,
+        query: str,
+        fields: str | Sequence[str] | None = ("name", "value"),
+        limit: int = 25,
+    ) -> list[Variable]:
+        """
+        Searches for variables matching the given query across specified fields.
+
+        This function performs a case-insensitive search for the query in the specified
+        fields of the Variable model. It calculates a relevance score for each match
+        based on the occurrence count and position of the query within the fields and
+        sorts the results by relevance.
+        Args:
+            query (str): The search query to match in the specified fields.
+            fields (str | Sequence[str] | None): The fields to search within. By
+                default, searches within "name". Can be a single field name as a string
+                or a sequence of field names.
+            limit (int): The maximum number of results to return. Defaults to 25.
+
+        Returns:
+            list[Variable]: A list of Variable objects matching the search query, sorted
+                by relevance.
+
+        Raises:
+            ValueError: If any provided field does not exist on the Variable model.
+        """
+        return self._search(
+            query, secondary_ordering="name", fields=fields, limit=limit
+        )
+
+    def delete(self, variable: Variable) -> bool:
+        """
+        Deletes the variable with the specified name.
+
+        Args:
+            variable (Variable): The variable to delete.
+
+        Returns:
+            bool: True if the variable was deleted, False otherwise.
+        """
+        if not variable:
+            return False
+        variable.delete_instance()
+        return True
+
+    def _is_unique_variable_tag_violation(self, exc: IntegrityError) -> bool:
+        msg = str(exc)
+        return (
+            "UNIQUE constraint failed" in msg
+            and "variabletag.variable_id" in msg
+            and "variabletag.tag_id" in msg
+        )