diff --git a/argenta/command/exceptions.py b/argenta/command/exceptions.py index faf7cf2..1ef7b08 100644 --- a/argenta/command/exceptions.py +++ b/argenta/command/exceptions.py @@ -2,15 +2,24 @@ from argenta.command.flag.models import InputFlag, Flag class BaseInputCommandException(Exception): + """ + Private. Base exception class for all exceptions raised when parse input command + """ pass class UnprocessedInputFlagException(BaseInputCommandException): + """ + Private. Raised when an unprocessed input flag is detected + """ def __str__(self): return "Unprocessed Input Flags" class RepeatedInputFlagsException(BaseInputCommandException): + """ + Private. Raised when repeated input flags are detected + """ def __init__(self, flag: Flag | InputFlag): self.flag = flag def __str__(self): @@ -19,5 +28,8 @@ class RepeatedInputFlagsException(BaseInputCommandException): class EmptyInputCommandException(BaseInputCommandException): + """ + Private. Raised when an empty input command is detected + """ def __str__(self): return "Input Command is empty" diff --git a/argenta/command/flag/models.py b/argenta/command/flag/models.py index ed71d3d..d77c527 100644 --- a/argenta/command/flag/models.py +++ b/argenta/command/flag/models.py @@ -4,7 +4,7 @@ from abc import ABC, abstractmethod class BaseFlag(ABC): def __init__(self, name: str, - prefix: Literal['-', '--', '---'] = '--'): + prefix: Literal['-', '--', '---'] = '--') -> None: """ Private. Base class for flags :param name: the name of the flag @@ -14,18 +14,26 @@ class BaseFlag(ABC): self._name = name self._prefix = prefix - def get_string_entity(self): + def get_string_entity(self) -> str: """ - Private. Returns a string representation of the flag - :return: None + Public. Returns a string representation of the flag + :return: string representation of the flag as str """ string_entity: str = self._prefix + self._name return string_entity - def get_name(self): + def get_name(self) -> str: + """ + Public. Returns the name of the flag + :return: the name of the flag as str + """ return self._name - def get_prefix(self): + def get_prefix(self) -> str: + """ + Public. Returns the prefix of the flag + :return: the prefix of the flag as str + """ return self._prefix @@ -34,13 +42,29 @@ class InputFlag(BaseFlag): def __init__(self, name: str, prefix: Literal['-', '--', '---'] = '--', value: str = None): + """ + Public. The entity of the flag of the entered command + :param name: the name of the input flag + :param prefix: the prefix of the input flag + :param value: the value of the input flag + :return: None + """ super().__init__(name, prefix) self._flag_value = value def get_value(self) -> str | None: + """ + Public. Returns the value of the flag + :return: the value of the flag as str + """ return self._flag_value def set_value(self, value): + """ + Private. Sets the value of the flag + :param value: the fag value to set + :return: None + """ self._flag_value = value @@ -48,11 +72,23 @@ class InputFlag(BaseFlag): class Flag(BaseFlag): def __init__(self, name: str, prefix: Literal['-', '--', '---'] = '--', - possible_values: list[str] | Pattern[str] | False = True): + possible_values: list[str] | Pattern[str] | False = True) -> None: + """ + Public. The entity of the flag being registered for subsequent processing + :param name: The name of the flag + :param prefix: The prefix of the flag + :param possible_values: The possible values of the flag, if False then the flag cannot have a value + :return: None + """ super().__init__(name, prefix) self.possible_values = possible_values def validate_input_flag_value(self, input_flag_value: str | None): + """ + Private. Validates the input flag value + :param input_flag_value: The input flag value to validate + :return: whether the entered flag is valid as bool + """ if self.possible_values is False: if input_flag_value is None: return True @@ -79,22 +115,44 @@ class Flag(BaseFlag): class BaseFlags(ABC): + """ + Private. Base class for groups of flags + """ __slots__ = ('_flags',) @abstractmethod def get_flags(self): + """ + Public. Returns a list of flags + :return: list of flags + """ pass @abstractmethod def add_flag(self, flag: Flag | InputFlag): + """ + Public. Adds a flag to the list of flags + :param flag: flag to add + :return: None + """ pass @abstractmethod def add_flags(self, flags: list[Flag] | list[InputFlag]): + """ + Public. Adds a list of flags to the list of flags + :param flags: list of flags to add + :return: None + """ pass @abstractmethod def get_flag(self, name: str): + """ + Public. Returns the flag entity by its name or None if not found + :param name: the name of the flag to get + :return: entity of the flag or None + """ pass def __iter__(self): diff --git a/argenta/command/models.py b/argenta/command/models.py index 71897c5..8013e8c 100644 --- a/argenta/command/models.py +++ b/argenta/command/models.py @@ -1,7 +1,7 @@ from argenta.command.flag.models import Flag, InputFlag, Flags, InputFlags from argenta.command.exceptions import (UnprocessedInputFlagException, - RepeatedInputFlagsException, - EmptyInputCommandException) + RepeatedInputFlagsException, + EmptyInputCommandException) from typing import Generic, TypeVar, cast, Literal @@ -9,10 +9,18 @@ InputCommandType = TypeVar('InputCommandType') class BaseCommand: - def __init__(self, trigger: str): + def __init__(self, trigger: str) -> None: + """ + Private. Base class for all commands + :param trigger: A string trigger, which, when entered by the user, indicates that the input corresponds to the command + """ self._trigger = trigger def get_trigger(self) -> str: + """ + Returns the trigger of the command + :return: the trigger of the command as str + """ return self._trigger @@ -21,6 +29,13 @@ class Command(BaseCommand): description: str = None, flags: Flag | Flags = None, aliases: list[str] = None): + """ + Public. The command that can and should be registered in the Router + :param trigger: A string trigger, which, when entered by the user, indicates that the input corresponds to the command + :param description: the description of the command + :param flags: processed commands + :param aliases: string synonyms for the main trigger + """ super().__init__(trigger) self._registered_flags: Flags = flags if isinstance(flags, Flags) else Flags(flags) if isinstance(flags, Flag) else Flags() self._description = f'Description for "{self._trigger}" command' if not description else description diff --git a/source/index.rst b/source/index.rst index 8165076..0617667 100644 --- a/source/index.rst +++ b/source/index.rst @@ -15,6 +15,4 @@ documentation for details. :maxdepth: 2 :caption: Contents: -.. automodule:: argenta - :members: - +.. automodule:: argenta \ No newline at end of file