cmdbox-cli 1.0.0__py3-none-any.whl

cmdbox/services/command_services.py

@@ -0,0 +1,261 @@
+from typing import Sequence
+
+from cmdbox.models import Tag, Command
+from cmdbox.repositories.command_repository import CommandRepository
+from cmdbox.database import db
+from cmdbox.repositories.results import TagAttachResult, TagDetachResult
+from cmdbox.repositories.tag_repository import TagRepository
+
+
+class CommandServices:
+    """
+    Provides services for managing commands and their associated tags.
+
+    The `CommandServices` class encapsulates the logic for working with commands and
+    tags, offering methods to create, update, delete, and retrieve command records
+    and their tag associations. It also supports additional functionality such as
+    searching, tagging, and listing commands with filtering and sorting options.
+
+    Attributes:
+        command_repository (CommandRepository): Repository for managing command records.
+        tag_repository (TagRepository): Repository for managing tag-related operations.
+    """
+
+    def __init__(
+        self, command_repository: CommandRepository, tag_repository: TagRepository
+    ):
+        self._repo = command_repository
+        self._tag_repo = tag_repository
+
+    def create_command(
+        self,
+        alias: str,
+        template: str,
+        description: str | None = None,
+        tags: list[str] | None = None,
+        cwd: str | None = None,
+        shell: str | None = None,
+        env: dict[str, str] | None = None,
+        timeout: int | None = None,
+    ) -> Command:
+        """
+        Creates a new command by storing the provided alias, template, and optional description
+        and tags into the database. If tags are provided, they are associated with the created
+        command.
+
+        Args:
+            alias (str): The alias of the command to be created.
+            template (str): The template associated with the command.
+            description (str | None): An optional description for the command. Defaults to None.
+            tags (list[str] | None): An optional list of tags to associate with the command.
+                Defaults to None.
+            cwd (str | None): Optional working directory to run the command from. Defaults to None.
+            shell (str | None): Optional shell to use when running the command. Defaults to None.
+            env (dict[str, str] | None): Optional environment variables to set when running
+                the command. Defaults to None.
+            timeout (int | None): Optional maximum number of seconds before the process is
+                killed. Defaults to None.
+
+        Returns:
+            Command: The created command record.
+        """
+        with db.atomic():
+            tags = self._get_tags(tags)
+            cmd = self._repo.create(
+                alias=alias,
+                template=template,
+                description=description,
+                cwd=cwd,
+                shell=shell,
+                env=env,
+                timeout=timeout,
+            )
+            if tags:
+                self._repo.add_tags(cmd, tags)
+
+        command = self._repo.get_by_id(cmd.id)
+
+        return command
+
+    def update_command(self, alias: str, **fields) -> Command:
+        """
+        Updates an existing command by its alias with new field values.
+
+        Retrieves the command corresponding to the given alias and updates it
+        with the provided fields. The update is performed using the repository.
+
+        Args:
+            alias (str): The alias of the command to update.
+            **fields: Arbitrary field values to update on the command.
+
+        Returns:
+            Command: The updated command object.
+        """
+        cmd = self._repo.get_by_alias(alias)
+        return self._repo.update(cmd, **fields)
+
+    def delete_command(self, alias_: str) -> bool:
+        """
+        Deletes a command by its alias.
+
+        This method removes a command record from the repository that matches the
+        provided alias.
+
+        Args:
+            alias_: The alias of the command to delete.
+
+        Returns:
+            bool: True if the command was deleted successfully, False otherwise.
+        """
+        cmd = self._repo.get_by_alias(alias_)
+        return self._repo.delete(cmd)
+
+    def add_tags(self, alias: str, tags: list[str]) -> TagAttachResult:
+        """
+        Adds specified tags to an existing alias.
+
+        The method retrieves a command object associated with the given alias and
+        applies the provided tags to the command.
+
+        Args:
+            alias (str): The alias identifying the command to which tags are to be
+                attached.
+            tags (list[str]): A list of tags to attach to the command.
+
+        Returns:
+            TagAttachResult: The result of the tag attachment operation, indicating
+                whether the tags were successfully attached to the command.
+        """
+        cmd = self._repo.get_by_alias(alias)
+        tags = self._get_tags(tags)
+        return self._repo.add_tags(cmd, tags)
+
+    def remove_tags(self, alias: str, tags: list[str]) -> TagDetachResult:
+        """
+        Removes specific tags associated with a command alias.
+
+        This method retrieves a command by its alias and detaches the specified tags
+        from it. The updated tag associations will be handled by the repository.
+
+        Args:
+            alias: The unique identifier for the command to update.
+            tags: A list of tags to be removed from the specified command.
+
+        Returns:
+            TagDetachResult: An object representing the result of tag detachment.
+        """
+        cmd = self._repo.get_by_alias(alias)
+        tags = self._get_tags(tags)
+        return self._repo.remove_tags(cmd, tags)
+
+    def get_command(self, alias: str) -> Command:
+        """
+        Retrieves a command by its alias.
+
+        This method fetches a command object associated with the given alias from the
+        repository.
+
+        Args:
+            alias (str): The alias of the command to retrieve.
+
+        Returns:
+            Command: The command object associated with the given alias.
+        """
+        cmd = self._repo.get_by_alias(alias)
+        return cmd
+
+    def get_command_by_id(self, cmd_id: int) -> Command:
+        """
+        Retrieves a command by its unique identifier from the repository.
+
+        This method accesses the repository to fetch a command based on the provided
+        command ID. It assumes that the command ID corresponds to a valid identifier
+        within the repository.
+
+        Args:
+            cmd_id (int): The unique identifier of the command to be retrieved.
+
+        Returns:
+            The command object associated with the given command ID, or None if no
+            matching command is found.
+        """
+        cmd = self._repo.get_by_id(cmd_id)
+        return cmd
+
+    def list_commands(
+        self,
+        order_by: str | Sequence[str] = "alias",
+        tags: Sequence[str] | None = None,
+        limit: int = 25,
+    ) -> list[Command]:
+        """
+        Lists commands, optionally filtered by tags, with sorting and limit options.
+
+        This function fetches a list of commands, either filtered by specific tags
+        or returning all available commands. The results can be sorted and limited
+        based on the provided arguments.
+
+        Args:
+            order_by (str | Sequence[str]): Specifies the field(s) to sort the results by.
+                Default is "alias".
+            tags (Sequence[str], optional): A list of tags to filter the commands. If
+                provided, only commands matching the tags will be included.
+            limit (int, optional): The maximum number of commands to return. Default is 25.
+
+        Returns:
+            list[Command]: A list of commands matching the provided filters and sorted
+            according to the specified criteria.
+        """
+        if tags:
+            tags = self._get_tags(tags)
+            return self._repo.list_by_tag(tags, order_by, limit)
+        return self._repo.list_all(order_by, limit)
+
+    def search(
+        self,
+        query: str,
+        fields: str | Sequence[str] | None = None,
+        limit: int = 25,
+    ) -> list[Command]:
+        """
+        Searches for commands that match the given query across specified fields.
+
+        This method allows you to perform a search within the data repository for commands
+        that match the provided query string in the specified fields. It returns a list of
+        commands that satisfy the search criteria.
+
+        Args:
+            query (str): The search term used for matching against the repository.
+            fields (str | Sequence[str] | None): The fields to perform the search within. Defaults
+                to ("alias", "template", "description"). If None, no specific fields are targeted.
+            limit (int): The maximum number of results to return. Defaults to 25.
+
+        Returns:
+            list[Command]: A list of Command objects that match the search query.
+        """
+        if not fields:
+            fields = ("alias", "template", "description")
+        return self._repo.search(query, fields=fields, limit=limit)
+
+    def _get_tags(self, tags: Sequence[str] | None) -> list[Tag]:
+        """
+        Fetches a list of Tag objects based on the provided tag names.
+
+        This method takes a list of tag names as input and retrieves the corresponding
+        Tag objects from the tag repository. The resulting list of Tag objects is then
+        returned.
+
+        Args:
+            tags (list[str] | None): A list of string representing the names of the tags to
+                retrieve.
+
+        Returns:
+            list[Tag]: A list of Tag objects corresponding to the specified tag names.
+        """
+        if tags is None:
+            return []
+        ret_tags: list[Tag] = []
+        for name in tags:
+            tag = self._tag_repo.get_by_name(name)
+            ret_tags.append(tag)
+        return ret_tags

cmdbox/services/errors.py

@@ -0,0 +1,37 @@
+from typing import Sequence
+
+from cmdbox.exceptions import CmdboxError
+
+
+class FieldSelectionError(CmdboxError):
+    pass
+
+
+class UnknownFieldError(FieldSelectionError):
+
+    def __init__(
+        self, unknown: str, allowed: Sequence[str], context: str | None = None
+    ):
+        self.unknown = unknown
+        self.allowed = allowed
+        self.context = context
+        msg = f'Unknown field "{unknown}".'
+        if context:
+            msg += f" ({context})"
+        msg += f" Allowed fields: {', '.join(allowed)}"
+        super().__init__(msg)
+
+
+class EmptyFieldSelectionError(FieldSelectionError):
+
+    def __init__(self, context: str | None = None):
+        msg = "No fields specified"
+        if context:
+            msg += f" ({context})"
+        super().__init__(msg)
+
+
+class HistoryIndexError(CmdboxError):
+
+    def __init__(self, index: int):
+        super().__init__(f"No history entry at index {index}.")

cmdbox/services/field_selection.py

@@ -0,0 +1,162 @@
+from typing import Mapping, Sequence
+from dataclasses import dataclass
+
+from cmdbox.services.errors import EmptyFieldSelectionError, UnknownFieldError
+
+
+@dataclass(frozen=True)
+class FieldSelectionResolver:
+    """
+    Resolves and validates field selections based on allowed fields, aliases, and additional rules.
+
+    This class is designed to handle validation and resolution of a set of field selections provided
+    by the user. It allows for enforcement of constraints like allowed fields, support for field aliases,
+    removal of duplicates, and handling special tokens like "all". You can use it to process raw field
+    selections into a sanitized and verified list of valid field names.
+
+    Attributes:
+        allowed_fields (list[str]): A list of fields that are explicitly allowed. Any field not
+            present in this list will result in a validation error.
+        allow_duplicates (bool): A flag indicating whether duplicate fields are permitted in the
+            final resolved list. Defaults to False.
+        all_token (str): A special token used to indicate that all allowed fields should be selected.
+            Defaults to "all".
+    """
+
+    allowed_fields: list[str]
+    allow_duplicates: bool = False
+    all_token: str = "all"
+
+    @property
+    def _allowed_fields(self):
+        """
+        Property method that retrieves a list of allowed fields in lowercase.
+
+        This method iterates through the fields defined in the `allowed_fields`
+        attribute, converts each field to lowercase, and returns the updated list.
+
+        Returns:
+            list: A list of strings representing the fields converted to lowercase.
+        """
+        return [x.lower() for x in self.allowed_fields]
+
+    def resolve(
+        self,
+        raw: Sequence[str] | None,
+        *,
+        default_fields: Sequence[str] | None = None,
+        aliases: Mapping[str, str] | None = None,
+        context: str | None = None,
+    ) -> list[str]:
+        """
+        Resolves and validates a list of field names based on the provided raw input, default
+        fields, and context. This method processes the field input, checks for special tokens,
+        and ensures the fields comply with the allowed fields defined in the current instance.
+
+        Args:
+            raw (Sequence[str] | None): A sequence of raw field names provided for resolution.
+                If None, the `default_fields` argument or allowed fields will be used as a
+                fallback.
+            default_fields (Sequence[str] | None, optional): A sequence of default field names
+                to use if `raw` is None. If omitted or None, all allowed fields are used.
+            aliases: (Mapping[str, str] | None, optional): A dictionary mapping field aliases to
+                a corresponding field name. If provided, aliases will be applied to the raw input.
+            context (str | None, optional): An optional string providing additional contextual
+                information for validation or error handling.
+
+        Returns:
+            list[str]: A list of validated and resolved field names, taking into account allowed
+            fields, special tokens, and fallback mechanisms.
+
+        Raises:
+            EmptyFieldSelectionError: If `raw` contains no valid field tokens or is equivalent
+            to an empty selection within the specified context.
+        """
+        if not self._allowed_fields:
+            return []
+
+        if raw is None:
+            fields = (
+                list(default_fields)
+                if default_fields is not None
+                else self._allowed_fields
+            )
+            return self.validate(fields, context)
+
+        raw = [x.lower() for x in raw]
+        tokens = [self.apply_alias(x, aliases) for x in raw if x.strip()]
+
+        if not tokens:
+            raise EmptyFieldSelectionError(context=context)
+
+        if any(x.lower() == self.all_token.lower() for x in tokens):
+            return self._allowed_fields
+
+        return self.validate(tokens, context)
+
+    def validate(self, tokens: Sequence[str], context: str | None) -> list[str]:
+        """
+        Validates a sequence of tokens based on allowed fields and duplicate rules.
+
+        This method processes the provided tokens to ensure they are within the set of
+        allowed fields. Optionally, it filters out duplicate tokens based on the
+        `allow_duplicates` rule. If any token does not match the allowed fields, an
+        `UnknownFieldError` is raised.
+
+        Args:
+            tokens (Sequence[str]): A sequence of tokens to validate.
+            context (str | None): An optional context string providing additional
+                information for debug or error messages.
+
+        Returns:
+            list[str]: A list of validated tokens, preserving the original order and
+            optionally excluding duplicates.
+
+        Raises:
+            UnknownFieldError: If a token is not in the allowed fields or violates
+            validation rules.
+        """
+        out: list[str] = []
+        seen: set[str] = set()
+
+        for token in tokens:
+            key = token.lower()
+
+            if key not in self._allowed_fields:
+                raise UnknownFieldError(token, self._allowed_fields, context=context)
+
+            if not self.allow_duplicates and key in seen:
+                continue
+
+            seen.add(key)
+            out.append(token)
+
+        return out
+
+    def apply_alias(self, token: str, aliases: Mapping[str, str] | None) -> str:
+        """
+        Processes a token and applies alias transformations if a matching alias is found.
+
+        This method checks if a given token matches any of the keys in the provided alias
+        mappings. If a match is found, the token is replaced with the associated value
+        from the mapping. If no match is found or no aliases are provided, the original
+        token is returned unmodified.
+
+        Args:
+            token (str): The token to be processed and potentially transformed.
+            aliases (Mapping[str, str] | None): A dictionary where keys represent alias
+                tokens, and values are the replacement tokens. If None is provided, no
+                alias transformations will be applied.
+
+        Returns:
+            str: The transformed token if a matching alias was found, or the original
+            token otherwise.
+        """
+        if not aliases:
+            return token
+
+        for alias, target in aliases.items():
+            if alias.lower() == token.lower():
+                return target
+
+        return token

cmdbox/services/history_service.py

@@ -0,0 +1,68 @@
+import json
+from typing import Callable
+
+from cmdbox.models import CommandHistory
+from cmdbox.repositories.history_repository import HistoryRepository
+from cmdbox.services.errors import HistoryIndexError
+from cmdbox.settings.models import Settings
+
+
+class HistoryService:
+
+    def __init__(self, repo: HistoryRepository, get_settings: Callable[[], Settings]):
+        self._repo = repo
+        self._get_settings = get_settings
+
+    def get_recent(
+        self,
+        alias: str | None = None,
+        limit: int = 20,
+    ) -> list[CommandHistory]:
+        return self._repo.get_recent(alias, limit)
+
+    def get_by_ref(self, ref: str, alias: str | None = None) -> CommandHistory:
+        if ref.isdigit():
+            return self._get_by_index(int(ref), alias=alias)
+        return self._repo.get_by_id(ref)
+
+    def get_variables(self, entry: CommandHistory) -> dict[str, str] | None:
+        if entry.variables_used is None:
+            return None
+        return json.loads(entry.variables_used)
+
+    def delete_by_ref(self, ref: str) -> bool:
+        entry = self.get_by_ref(ref)
+        return self._repo.delete_by_id(entry.id)
+
+    def clear(self, alias: str | None = None) -> int:
+        return self._repo.clear(alias=alias)
+
+    def _get_by_index(self, index: int, alias: str | None = None) -> CommandHistory:
+        """
+        Fetches a specific command history entry by its index.
+
+        This method retrieves a command history entry from the repository based on
+        the passed index. If the index is out of range or invalid, a
+        HistoryIndexError is raised. The method optionally allows limiting the
+        retrieval to a specific alias.
+
+        Args:
+            index (int): The one-based index of the command history entry to
+                retrieve. Must be greater than 0.
+            alias (str | None): Optional alias to filter the history entries. If
+                None, no alias filter is applied.
+
+        Returns:
+            CommandHistory: The command history entry corresponding to the provided
+            index.
+
+        Raises:
+            HistoryIndexError: If the provided index is less than 1 or if the index
+            exceeds the number of available entries.
+        """
+        if index < 1:
+            raise HistoryIndexError(index=index)
+        entries = self._repo.get_recent(alias=alias, limit=index)
+        if index > len(entries):
+            raise HistoryIndexError(index=index)
+        return entries[index - 1]