redditadmin 0.0.4__py3-none-any.whl

redditadmin/__init__.py

@@ -0,0 +1,4 @@
+from .core import RedditAdmin, get_reddit_admin
+from .program import *
+from .plugin import *
+from .utility import *

redditadmin/core.py

@@ -0,0 +1,440 @@
+import logging
+import os
+import signal
+import sys
+import time
+from abc import ABC, abstractmethod
+from logging.handlers import TimedRotatingFileHandler
+from pathlib import Path
+from typing import List
+
+from .utility.botcredentials import BotCredentials
+from .utility.exceptions import BotInitializationError, InvalidBotCredentialsError
+from .plugin.asynchronouspluginsexecutor import AsynchronousPluginsExecutor
+from .plugin.exceptions import PluginsExecutorInitializationError
+from .plugin.plugin import Plugin
+from .plugin.pluginsexecutor import PluginsExecutor
+from .plugin.redditinterfacefactory import RedditInterfaceFactory
+
+
+class RedditAdmin(ABC):
+    """Type encapsulating a RedditAdmin instance"""
+
+    def __init__(self, *args):
+        pass
+
+    @abstractmethod
+    def run(self, bot_credentials: BotCredentials, listen: bool = False):
+        """Run the bot"""
+
+        raise NotImplementedError
+
+    @abstractmethod
+    def stop(self):
+        """Shutdown the bot"""
+
+        raise NotImplementedError
+
+
+class RedditAdminImplementation(RedditAdmin):
+    """Reddit Admin Bot"""
+
+    __plugins: List[Plugin]
+    __pluginsExecutor: PluginsExecutor
+    __mainLogger: logging.Logger
+    __defaultConsoleLoggingLevel: int
+
+    __RESOURCES_PATH = os.path.join(
+        os.path.dirname(os.path.abspath(__file__)),
+        'resources'
+    )
+
+    # Bot initialization commands
+    # -------------------------------------------------------------------------------
+    # -------------------------------------------------------------------------------
+
+    def __init__(self, plugins: List[Plugin]):
+        super().__init__(self)
+        self.__plugins = plugins
+
+    def __initialize_logging(self, log_file_name: str):
+        """Initialize the bot's logging apparatus"""
+
+        # Disabling any 3rd party loggers
+        for _ in logging.root.manager.loggerDict:
+            logging.getLogger(_).setLevel(logging.CRITICAL)
+
+        # Initializing the root logger
+        logging.basicConfig(level=logging.DEBUG)
+        root_logger = logging.getLogger()
+
+        # Initializing the core bot application logger
+        self.__mainLogger = logging.getLogger(__name__)
+
+        # Clearing any existing log handlers for program loggers
+        for logger in [root_logger, self.__mainLogger]:
+            if len(logger.handlers):
+                logger.handlers.clear()
+
+        # Setting up log handlers
+        log_file_handler = TimedRotatingFileHandler(
+            filename=log_file_name,
+            when='D',
+            utc=True
+        )
+        console_handler = logging.StreamHandler()
+        log_file_handler.set_name('log_file')
+        console_handler.set_name('console')
+        log_file_handler.setFormatter(
+            logging.Formatter(
+                '[%(asctime)s] %(name)-16s : '
+                '%(levelname)-8s - %(message)s'
+            )
+        )
+        console_handler.setFormatter(
+            logging.Formatter(
+                '%(name)-16s : %(message)s'
+            )
+        )
+        log_file_handler.setLevel(logging.DEBUG)
+        console_handler.setLevel(logging.DEBUG)
+
+        # Adding the handlers to the root logger
+        root_logger.addHandler(log_file_handler)
+        root_logger.addHandler(console_handler)
+
+        # Setting the default console logging level global variable
+        self.__defaultConsoleLoggingLevel = console_handler.level
+
+    def ___get_new_bot_credentials(self) -> BotCredentials:
+        """Convenience method to retrieve bot credentials from user input"""
+
+        try:
+            # Prompt for new valid credentials
+            while True:
+
+                # Pause console logging while listening for input
+                self.__pause_console_logging()
+
+                user_agent = input("Enter User Agent: ")
+                client_id = input("Enter Client ID: ")
+                client_secret = input("Enter Client Secret: ")
+                username = input("Enter Username: ")
+                password = input("Enter Password: ")
+
+                # Resume console logging
+                self.__resume_console_logging()
+
+                return BotCredentials(
+                    user_agent, client_id,
+                    client_secret, username,
+                    password
+                )
+
+        # Handle if listening interrupted
+        except (KeyboardInterrupt, EOFError) as ex:
+            self.__resume_console_logging()
+            raise ex
+
+    def __get_reddit_interface_factory(self, bot_credentials: BotCredentials) \
+            -> RedditInterfaceFactory:
+        """ Initialize Reddit Interface Factory"""
+
+        # Attempting to retrieve a valid RedditInterfaceFactory
+        # instance from provided credentials
+
+        try:
+            reddit_interface_factory = RedditInterfaceFactory(
+                bot_credentials
+            )
+        # Handle if credential authentication fails
+        except InvalidBotCredentialsError:
+            self.__mainLogger.error(
+                "The provided credentials are invalid. "
+                "Please enter new valid credentials"
+            )
+            try:
+                new_bot_credentials = self.___get_new_bot_credentials()
+                reddit_interface_factory = self.__get_reddit_interface_factory(new_bot_credentials)
+            except (KeyboardInterrupt, EOFError):
+                raise BotInitializationError(
+                    "Retrieval of bot credentials from user input "
+                    "aborted"
+                )
+
+        return reddit_interface_factory
+
+    def __initialize_plugins_executor(self, bot_credentials: BotCredentials) \
+            -> PluginsExecutor:
+        """Initialize the Plugins Executor"""
+
+        # Initializing the Plugins Executor
+
+        reddit_interface_factory = self.__get_reddit_interface_factory(bot_credentials)
+
+        try:
+            plugins_executor = AsynchronousPluginsExecutor(
+                plugins=self.__plugins,
+                reddit_interface_factory=reddit_interface_factory
+            )
+
+        # Handle if there is an error initializing the Programs Executor
+        except PluginsExecutorInitializationError as ex:
+            raise BotInitializationError(
+                "An error occurred while initializing "
+                "the Programs Executor.", ex
+            )
+
+        return plugins_executor
+
+    def __initialize_bot(self, bot_credentials: BotCredentials):
+        """Initialize the bot"""
+
+        log_file = Path(os.path.join(
+            self.__RESOURCES_PATH, 'logs', 'reddit-admin.log'
+        ))
+        log_file.parent.mkdir(exist_ok=True, parents=True)
+
+        # Setting up logging apparatus
+        self.__initialize_logging(str(log_file.resolve()))
+
+        self.__mainLogger.info("Initializing the bot")
+
+        try:
+
+            # Initializing the Programs Executor
+            self.__pluginsExecutor = self.__initialize_plugins_executor(
+                bot_credentials
+            )
+
+            # -------------------------------------------------------------------------------
+
+        # Handle if an initialization error occurs
+        except BotInitializationError as er:
+            self.__mainLogger.critical(
+                "A fatal error occurred during the "
+                "bot's initialization. The application "
+                "will now exit. Error(s): " + str(er),
+                exc_info=True
+            )
+            sys.exit(2)  # TODO: May need future cleaning up
+
+        self.__mainLogger.info("Bot successfully initialized")
+
+    # -------------------------------------------------------------------------------
+
+    # Bot runtime commands
+    # -------------------------------------------------------------------------------
+    # -------------------------------------------------------------------------------
+
+    def __pause_console_logging(self):
+        """Pause console logging across entire application"""
+
+        for handler in logging.getLogger().handlers:
+            if handler.name == "console":
+                handler.setLevel(logging.CRITICAL)
+                return
+        self.__mainLogger.warning(
+            "Failed to pause logging because "
+            "the console logger was not found"
+        )
+
+    def __resume_console_logging(self):
+        """Resume console logging across entire application"""
+
+        for handler in logging.getLogger().handlers:
+            if handler.name == "console":
+                handler.setLevel(self.__defaultConsoleLoggingLevel)
+                return
+        self.__mainLogger.warning(
+            "Failed to resume logging because "
+            "the console logger was not found"
+        )
+
+    def __start_command_listener(self):
+        """Start the bot command listener"""
+
+        try:
+            while not self.__is_bot_shut_down():
+                # Pause console logging while bot is
+                # listening for commands
+                self.__pause_console_logging()
+
+                command = input('Enter bot command: ')
+
+                # Resume console logging once command
+                # entered
+                self.__resume_console_logging()
+
+                self.__process_bot_command(command)
+
+        except BaseException as ex:
+            self.__resume_console_logging()
+            raise ex
+
+    def __process_bot_command(self, command: str):
+        """Process a bot command"""
+
+        # For blank command
+        if command == '' or command == '\n':
+            return
+
+        # For program command
+        elif command.startswith('run '):
+            self.__pluginsExecutor.execute_program(command.split('run ', 1)[1])
+
+        # For program status request
+        elif command == 'status':
+
+            print('\nPrograms status:')
+
+            # Printing all program statuses
+            for _program, status in self.__pluginsExecutor \
+                    .get_program_statuses() \
+                    .items():
+                print('{}\t\t: {}'.format(
+                    _program, status
+                ))
+            print()
+
+        # For shutdown command
+        elif (
+                command == 'shutdown' or
+                command == 'quit' or
+                command == 'exit'
+        ):
+            self.__shut_down_bot()
+
+        else:
+            self.__mainLogger.debug(
+                "'{}' is not a valid bot command".format(command)
+            )
+
+    @staticmethod
+    def __kill_bot():
+        """Forcefully shut down the bot"""
+
+        # Windows kill command
+        if (
+                sys.platform.startswith('win32') or
+                sys.platform.startswith('cygwin')
+        ):
+            os.kill(os.getpid(), signal.CTRL_BREAK_EVENT)
+
+        # Linux kill command
+        os.kill(os.getpid(), signal.SIGKILL)
+
+    def __shut_down_bot(self, wait=True, shutdown_exit_code=0):
+        """Shut down the bot"""
+
+        if wait:
+            self.__mainLogger.info(
+                'Shutting down the bot. Please wait a bit while the '
+                'remaining tasks ({}) are being finished off'.format(
+                    ", ".join(
+                        {
+                            _program: status
+                            for (_program, status) in self.__pluginsExecutor
+                            .get_program_statuses()
+                            .items()
+                            if status != "DONE"
+                        }.keys()
+                    )
+                )
+            )
+            try:
+                self.__pluginsExecutor.shut_down(True)
+                self.__mainLogger.info('Bot successfully shut down')
+                if shutdown_exit_code != 0:
+                    sys.exit(shutdown_exit_code)
+
+            # Handle keyboard interrupt midway through graceful shutdown
+            except KeyboardInterrupt:
+
+                self.__mainLogger.warning(
+                    'Graceful shutdown aborted.'
+                )
+                self.__pluginsExecutor.shut_down(False)
+                self.__mainLogger.info('Bot shut down')
+
+                # Killing the process (only way to essentially stop all threads)
+                self.__kill_bot()
+
+        else:
+            self.__pluginsExecutor.shut_down(False)
+            self.__mainLogger.info('Bot shut down')
+
+            self.__kill_bot()
+
+    def __is_bot_shut_down(self):
+        """Check if bot is shutdown"""
+
+        return self.__pluginsExecutor and self.__pluginsExecutor.is_shut_down()
+
+    def __start_bot(self, bot_credentials: BotCredentials, listen: bool):
+        """Start up the bot"""
+
+        # Initializing the bot
+        self.__initialize_bot(bot_credentials)
+        self.__mainLogger.info('The bot is now running')
+
+        try:
+            if listen:
+                self.__start_command_listener()
+
+        # Handle forced shutdown request
+        except (KeyboardInterrupt, EOFError):
+            self.__mainLogger.warning(
+                'Forced bot shutdown requested. Please wait a bit wait while '
+                'a graceful shutdown is attempted or press '
+                'Ctrl+C to exit immediately'
+            )
+            self.__shut_down_bot(True, 1)
+
+        # Handle unknown exception while bot is running
+        except BaseException as ex:
+            self.__mainLogger.critical(
+                "A fatal error just occurred while the bot was "
+                "running. Please wait a bit wait while "
+                "a graceful shutdown is attempted or press "
+                "Ctrl+C to exit immediately: " + str(ex.args), exc_info=True
+            )
+            self.__shut_down_bot(True, 2)
+
+    def run(self, bot_credentials: BotCredentials, listen: bool = False):
+
+        # Setting up interrupt signal handlers
+        signal.signal(signal.SIGINT, signal.default_int_handler)
+        signal.signal(signal.SIGTERM, signal.default_int_handler)
+
+        # Start bot
+        self.__start_bot(bot_credentials, listen)
+
+        try:
+            # Wait for tasks to complete before shutdown
+            while True:
+                if not (
+                    "RUNNING" in self.__pluginsExecutor
+                    .get_program_statuses().values()
+                ):
+                    break
+                time.sleep(1)
+        # Handle shutdown by Keyboard interrupt
+        except KeyboardInterrupt:
+            pass
+        finally:
+            # Shut bot down if not already
+            if not self.__is_bot_shut_down():
+                self.__shut_down_bot()
+
+    def stop(self):
+
+        self.__shut_down_bot()
+
+    # -------------------------------------------------------------------------------
+
+
+def get_reddit_admin(plugins: List[Plugin]) -> RedditAdmin:
+    """Get a Reddit Admin instance"""
+
+    return RedditAdminImplementation(plugins=plugins)

redditadmin/plugin/__init__.py

@@ -0,0 +1,3 @@
+from .plugin import Plugin
+from .pluginsexecutor import PluginsExecutor
+from .redditinterfacefactory import RedditInterfaceFactory

redditadmin/plugin/asynchronouspluginsexecutor.py

@@ -0,0 +1,203 @@
+# -*- coding: utf-8 -*-
+
+import concurrent.futures
+from concurrent.futures import ThreadPoolExecutor, Future
+from typing import Dict, List
+from .pluginsexecutor import PluginsExecutor
+from .redditinterfacefactory import RedditInterfaceFactory
+from .plugin import Plugin
+from .exceptions import PluginsExecutorInitializationError
+
+
+class AsynchronousPluginsExecutor(PluginsExecutor):
+    """
+    Class responsible for asynchronously executing
+    multiple plugins in different threads
+    """
+
+    __executor: ThreadPoolExecutor
+    __plugins: Dict[str, Plugin]
+    __executedPrograms: Dict[str, Future]
+    __redditInterfaceFactory: RedditInterfaceFactory
+
+    def __init__(
+            self,
+            plugins: List[Plugin],
+            reddit_interface_factory: RedditInterfaceFactory,
+            executor=ThreadPoolExecutor(),
+    ):
+        super().__init__("Asynchronous Plugins Executor")
+        self.__executor = executor
+        self.__plugins = dict(
+            map(
+                lambda plugin: (plugin.get_program_command(), plugin), plugins
+            )
+        )
+        self.__executedPrograms = {}
+        self.__redditInterfaceFactory = reddit_interface_factory
+        self.__initialize_plugins_executor()
+
+    def __initialize_plugins_executor(self):
+        """Initialize the plugin executor"""
+
+        self._pluginsExecutorLogger.debug('Initializing Plugins Executor')
+
+        try:
+            # Retrieving initial program commands
+            self._pluginsExecutorLogger.debug(
+                "Retrieving initial program commands"
+            )
+
+            # Executing initial program commands 
+            self._pluginsExecutorLogger.debug(
+                "Executing initial program commands"
+            )
+            self.execute_programs()
+
+        # Handle in case the program executor fails to initialize
+        except PluginsExecutorInitializationError as ex:
+            self._pluginsExecutorLogger.critical(
+                "A terminal error occurred while initializing the Programs "
+                "Executor. Error(s): " + str(ex)
+            )
+            raise ex
+
+        self._isPluginsExecutorShutDown = False
+        self._pluginsExecutorLogger.info(
+            "Programs Executor initialized"
+        )
+
+    def execute_program(self, program_command):
+
+        # Confirm if shut down first
+        if self._inform_if_shut_down():
+            return
+
+        # Checking if there are duplicate running program
+        if program_command in self.__executedPrograms.keys():
+            if not self.__executedPrograms[program_command].done():
+                self._pluginsExecutorLogger.warning(
+                    "Did not run the '{}' program command "
+                    "because an identical command is"
+                    " still running".format(program_command)
+                )
+                return
+
+        # Generating an asynchronous worker thread for the program
+        try:
+            task = self.__executor.submit(
+                self.__process_program,
+                program_command
+            )
+        except RuntimeError:
+            self._pluginsExecutorLogger.error(
+                "Failed to execute '{}' because the executor is "
+                "shutting down or is shut down".format(program_command)
+            )
+            return
+
+        try:
+
+            raise task.exception(0.1)
+
+        # Add to running program if task was started successfully
+        except concurrent.futures.TimeoutError:
+
+            self.__executedPrograms[program_command] = task
+
+        # Handle if provided program could not be parsed
+        except ValueError as ex:
+            self._pluginsExecutorLogger.error(
+                "Did not run the '{}' program command "
+                "because there was an error parsing the "
+                "program command. Error(s): {}".format(
+                    program_command, str(ex.args)
+                )
+            )
+
+        # Handle if plugin task failed to run
+        except TypeError:
+            self._pluginsExecutorLogger.error(
+                "Failed to run the plugin '{}'".format(
+                    program_command
+                )
+            )
+
+    def execute_programs(self):
+        """Execute multiple program"""
+
+        # Confirm if shut down first
+        if self._inform_if_shut_down():
+            return
+
+        for program_command in self.__plugins.keys():
+            self.execute_program(program_command)
+
+    def __process_program(self, program_command):
+        """Synthesize the provided program"""
+
+        program_command_breakdown = program_command.split()
+        program_name = program_command_breakdown[0]
+
+        try:
+
+            if program_name in self.__plugins.keys():
+                reddit_interface = self.__redditInterfaceFactory.get_reddit_interface()
+                self._pluginsExecutorLogger.info(
+                    "Running program '{}'".format(program_name)
+                )
+                self.__plugins[program_name].get_program(reddit_interface).execute()
+
+                # Completion message determination
+                if self.is_shut_down():
+                    self._pluginsExecutorLogger.info(
+                        "{} program instance successfully shut down".format(
+                            program_name
+                        )
+                    )
+                else:
+                    self._pluginsExecutorLogger.info(
+                        "{} program instance completed".format(
+                            program_name
+                        )
+                    )
+
+            # Raise error if provided program does not exist
+            else:
+                raise ValueError(
+                    "Program '{}' is not recognized".format(program_name)
+                )
+
+        # Handle if provided program not found
+        except ValueError as ex:
+            raise ex
+
+        # Handle if unexpected exception crashes a program TODO: Revisit
+        except Exception as ex:
+            self._pluginsExecutorLogger.error(
+                "An unexpected error just caused the '{}' "
+                "program to crash. Error: {}".format(
+                    program_name, str(ex.args)
+                ), exc_info=True
+            )
+
+    def get_program_statuses(self):
+        """Get the executed program statuses"""
+
+        program_statuses = \
+            {
+                program: ("RUNNING" if not task.done() else "DONE")
+                for (program, task) in self.__executedPrograms.items()
+            }
+        return program_statuses
+
+    def shut_down(self, wait):
+        """Shut down the plugin executor"""
+
+        super().shut_down()
+        for plugin in self.__plugins.values():
+            plugin.shut_down()
+        self.__executor.shutdown(wait)
+        self._pluginsExecutorLogger.info(
+            "Programs executor successfully shut down"
+        )

redditadmin/plugin/exceptions.py

@@ -0,0 +1,11 @@
+from ..utility.exceptions import InitializationError
+
+
+class PluginsExecutorInitializationError(InitializationError):
+    """
+    Class to encapsulate an error in the initialization
+    of a Plugins Executor module
+    """
+
+    def __init__(self, *args):
+        super().__init__(*args)

redditadmin/plugin/plugin.py

@@ -0,0 +1,62 @@
+import logging
+from abc import ABC, abstractmethod
+from typing import TypeVar, Generic
+
+from ..program.program import Program
+from ..utility.redditinterface import RedditInterface
+from ..utility.exceptions import InitializationError
+
+T = TypeVar("T", bound=Program)
+
+
+class Plugin(Generic[T], ABC):
+    """
+    Class responsible for generating multiple
+    instances of a specific program
+    """
+
+    _programCommand: str
+    _pluginLogger: logging.Logger
+    _isPluginShutDown: bool
+
+    def __init__(
+            self,
+            program_command: str,
+    ):
+        self._programCommand = program_command
+        self._pluginLogger = logging.getLogger(
+            program_command
+        )
+        self._isPluginShutDown = False
+
+    @abstractmethod
+    def get_program(self, reddit_interface: RedditInterface) -> T:
+        """Get new program instance"""
+
+        raise NotImplementedError
+
+    def get_program_command(self) -> str:
+        """Get the program command string"""
+        return self._programCommand
+
+    def is_shut_down(self) -> bool:
+        """Check if plugin is shut down"""
+        return self._isPluginShutDown
+
+    def shut_down(self):
+        """Shut down the plugin"""
+        self._isPluginShutDown = True
+
+    def __eq__(self, value) -> bool:
+        return isinstance(value, Plugin) and \
+               self.get_program_command() == value.get_program_command()
+
+
+class PluginInitializationError(InitializationError):
+    """
+    Class to encapsulate an error in the initialization
+    of a plugin module
+    """
+
+    def __init__(self, *args):
+        super().__init__(*args)

redditadmin/plugin/pluginsexecutor.py

@@ -0,0 +1,54 @@
+# -*- coding: utf-8 -*-
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Dict
+
+
+class PluginsExecutor(ABC):
+    """
+    Class responsible for executing plugins
+    """
+
+    _isPluginsExecutorShutDown: bool
+    _pluginsExecutorLogger: logging.Logger
+
+    def __init__(self, plugins_executor_name: str):
+        self._pluginsExecutorLogger = logging.getLogger(
+            plugins_executor_name
+        )
+        self._isPluginsExecutorShutDown = False
+
+    @abstractmethod
+    def execute_program(self, program_command):
+        """Execute the provided program command"""
+
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_program_statuses(self) -> Dict[str, str]:
+        """Get the executed program statuses"""
+
+        raise NotImplementedError
+
+    def shut_down(self, *args):
+        """Shut down the plugins executor"""
+
+        self._isPluginsExecutorShutDown = True
+
+    def is_shut_down(self) -> bool:
+        """Check if the Plugins Executor is shut down"""
+
+        return self._isPluginsExecutorShutDown
+
+    def _inform_if_shut_down(self):
+        """
+        Convenience method to check shutdown status and log
+        if plugins executor is shut down
+        """
+
+        if self._isPluginsExecutorShutDown:
+            self._pluginsExecutorLogger.warning(
+                "The plugins executor cannot execute any more program "
+                "after it has been shut down"
+            )

redditadmin/plugin/redditinterfacefactory.py

@@ -0,0 +1,49 @@
+import praw
+
+from ..utility.botcredentials import BotCredentials
+from ..utility.exceptions import InvalidBotCredentialsError
+from ..utility.redditinterface import RedditInterface
+
+
+class RedditInterfaceFactory:
+    """Factory for RedditInterface objects"""
+
+    __botCredentials: BotCredentials
+
+    def __init__(
+            self,
+            bot_credentials: BotCredentials
+    ):
+        praw_reddit = praw.Reddit(
+            user_agent=bot_credentials.get_user_agent,
+            client_id=bot_credentials.get_client_id,
+            client_secret=bot_credentials.get_client_secret,
+            username=bot_credentials.getusername,
+            password=bot_credentials.get_password
+        )
+        if not self.__authenticated(praw_reddit):
+            raise InvalidBotCredentialsError
+
+        self.__botCredentials = bot_credentials
+
+    @staticmethod
+    def __authenticated(praw_reddit_instance: praw.Reddit) -> bool:
+        """
+        Convenience method to authenticate bot credentials
+        provided to Reddit instance
+        """
+
+        return not praw_reddit_instance.read_only
+
+    def get_reddit_interface(self) -> RedditInterface:
+        """Retrieve new Reddit Interface"""
+
+        bot_credentials = self.__botCredentials
+        praw_reddit = praw.Reddit(
+            user_agent=bot_credentials.get_user_agent,
+            client_id=bot_credentials.get_client_id,
+            client_secret=bot_credentials.get_client_secret,
+            username=bot_credentials.getusername,
+            password=bot_credentials.get_password
+        )
+        return RedditInterface(praw_reddit)

redditadmin/program/__init__.py

@@ -0,0 +1,3 @@
+from .program import Program, RecurringProgram
+from .streamprocessingprogram import StreamProcessingProgram, StreamFactory, SubmissionStreamFactory, \
+    CommentStreamFactory, CustomStreamFactory

redditadmin/program/program.py

@@ -0,0 +1,45 @@
+import logging
+import time
+from abc import ABC, abstractmethod
+from typing import Callable
+
+
+class Program(ABC):
+    """Class representing a simple program"""
+
+    def __init__(self, program_name: str):
+        self._programLogger = logging.getLogger(
+            program_name
+        )        
+
+    @abstractmethod
+    def execute(self, *args, **kwargs):
+        """Execute the program"""
+
+        raise NotImplementedError()
+
+
+class RecurringProgram(Program, ABC):
+    """Class encapsulating a looping program type"""
+
+    def __init__(
+            self,
+            program_name: str,
+            stop_condition: Callable[..., bool],
+            cooldown: float = 0
+    ):
+        super().__init__(program_name)
+        self._stopCondition = stop_condition
+        self._cooldown = cooldown
+
+    def execute(self, *args, **kwargs):
+        while not self._stopCondition():
+            self._run_nature_core(*args, **kwargs)
+            if self._cooldown and self._cooldown > 0:
+                time.sleep(self._cooldown)
+
+    @abstractmethod
+    def _run_nature_core(self, *args, **kwargs):
+        """Run core program"""
+
+        raise NotImplementedError()

redditadmin/program/streamprocessingprogram.py

@@ -0,0 +1,139 @@
+from abc import ABC, abstractmethod
+from typing import Generator, Callable
+
+from praw.models import Subreddit, ListingGenerator
+from praw.models.util import stream_generator
+
+from .program import RecurringProgram
+from ..utility.decorators import consumestransientapierrors
+
+
+class StreamFactory(ABC):
+    """
+    Class responsible for producing
+    new Reddit Object streams at request
+    """
+
+    @abstractmethod
+    def get_new_stream(self) -> Generator:
+        """Produce new stream"""
+
+        raise NotImplementedError()
+
+
+class StreamProcessingProgram(RecurringProgram, ABC):
+    """
+    Class encapsulating a stream processing
+    program
+    """
+
+    def __init__(
+            self,
+            stream_factory: StreamFactory,
+            stop_condition: Callable[..., bool],
+            program_name: str
+    ):
+        super().__init__(program_name, stop_condition)
+        self.__streamFactory = stream_factory
+
+    @consumestransientapierrors
+    def execute(self, *args, **kwargs):
+
+        # In case we somehow run out of
+        # new items in the stream (IYKYK)
+        while not self._stopCondition():
+
+            stream = self.__streamFactory.get_new_stream()
+
+            # "New item listener" loop
+            for streamItem in stream:
+
+                # Handle "pause" token
+                if streamItem is None:
+
+                    # Exit the loop if stop condition satisfied
+                    if self._stopCondition():
+                        break
+
+                    self._run_pause_handler()
+                    continue
+
+                self._run_nature_core(streamItem)
+
+    def _run_pause_handler(self, *args):
+        """Execute when stream is paused"""
+        pass
+
+
+class SubmissionStreamFactory(StreamFactory):
+    """
+    Class responsible for producing
+    new Submission streams at request
+    """
+
+    def __init__(
+            self,
+            subreddit: Subreddit,
+            pause_after: int = 0,
+            skip_existing: bool = False
+    ):
+        super().__init__()
+        self.__subreddit = subreddit
+        self.__pause_after = pause_after
+        self.__skip_existing = skip_existing
+
+    def get_new_stream(self) -> Generator:
+        return self.__subreddit.stream.submissions(
+            pause_after=self.__pause_after,
+            skip_existing=self.__skip_existing
+        )
+
+
+class CommentStreamFactory(StreamFactory):
+    """
+    Class responsible for producing
+    new Comment streams at request
+    """
+
+    def __init__(
+            self,
+            subreddit: Subreddit,
+            pause_after: int = 0,
+            skip_existing: bool = False
+    ):
+        super().__init__()
+        self.__subreddit = subreddit
+        self.__pause_after = pause_after
+        self.__skip_existing = skip_existing
+
+    def get_new_stream(self) -> Generator:
+        return self.__subreddit.stream.comments(
+            pause_after=self.__pause_after,
+            skip_existing=self.__skip_existing
+        )
+
+
+class CustomStreamFactory(StreamFactory):
+    """
+    Class responsible for producing new
+    stream of custom Reddit objects according to
+    the provided Listing Generator
+    """
+
+    def __init__(
+            self,
+            listing_generator_callback: Callable[..., ListingGenerator],
+            pause_after: int = 0,
+            skip_existing: bool = False
+    ):
+        super().__init__()
+        self.__listingGeneratorCallback = listing_generator_callback
+        self.__pause_after = pause_after
+        self.__skip_existing = skip_existing
+
+    def get_new_stream(self) -> Generator:
+        return stream_generator(
+            self.__listingGeneratorCallback,
+            pause_after=self.__pause_after,
+            skip_existing=self.__skip_existing
+        )

redditadmin/utility/__init__.py

@@ -0,0 +1,5 @@
+from .botcredentials import BotCredentials
+from .contributionsutility import retrieve_submissions_from_subreddit, retrieve_select_submissions, is_removed
+from .decorators import consumestransientapierrors
+from .redditinterface import RedditInterface
+from .redditsubmission import RedditSubmission

redditadmin/utility/botcredentials.py

@@ -0,0 +1,63 @@
+class BotCredentials:
+    """
+    Class holding the bot's credentials
+    """
+
+    __user_agent: str
+    __client_id: str
+    __client_secret: str
+    __username: str
+    __password: str
+
+    def __init__(
+            self,
+            user_agent,
+            client_id,
+            client_secret,
+            username,
+            password
+    ):
+        self.__user_agent = user_agent
+        self.__client_id = client_id
+        self.__client_secret = client_secret
+        self.__username = username
+        self.__password = password
+
+    @property
+    def get_user_agent(self):
+        """Retrieve the bot's User Agent"""
+
+        return self.__user_agent
+
+    @property
+    def get_client_id(self):
+        """Retrieve the bot's Client ID"""
+
+        return self.__client_id
+
+    @property
+    def get_client_secret(self):
+        """Retrieve the bot's Client Secret"""
+
+        return self.__client_secret
+
+    @property
+    def getusername(self):
+        """Retrieve the bot's Username"""
+
+        return self.__username
+
+    @property
+    def get_password(self):
+        """Retrieve the bot's Password"""
+
+        return self.__password
+
+    def clear_credentials(self):
+        """Convenience method to clear the bot's credentials"""
+
+        self.__user_agent = ""
+        self.__client_id = ""
+        self.__client_secret = ""
+        self.__username = ""
+        self.__password = ""

redditadmin/utility/contributionsutility.py

@@ -0,0 +1,64 @@
+"""
+Module providing various utility methods
+for submissions and comments
+"""
+from typing import List, Union
+
+from praw import Reddit
+from praw.models import Submission, Comment
+
+
+# TODO: Unpushshift
+def retrieve_submissions_from_subreddit(
+        reddit: Reddit,
+        subreddit_name: str,
+        from_time: str,
+        filters: List[str]
+) -> List[Submission]:
+    """
+    Retrieves all submissions from a given subreddit
+    after the provided time containing only filtered info
+    """
+    # return list(
+    #     reddit.subreddit.search_submissions(
+    #         subreddit=subredditName,
+    #         after=fromTime,
+    #         filter=filters
+    #     )
+    # )
+    raise NotImplementedError
+
+
+def retrieve_select_submissions(
+        praw_reddit: Reddit,
+        submission_ids: List[str]
+) -> List[Submission]:
+    """
+    Retrieves submissions with the given
+    submissionIds
+    """
+
+    submissions = []
+
+    for submissionId in submission_ids:
+        submissions.append(
+            praw_reddit.submission(submissionId)
+        )
+
+    return submissions
+
+
+def is_removed(
+        contribution: Union[Submission, Comment]
+) -> bool:
+    """
+    Checks if provided comment or
+    submission is removed
+    """
+
+    try:
+        author = contribution.author
+    except AttributeError:
+        author = None
+    return author is None or author == '[Deleted]' or \
+        contribution.banned_by is not None

redditadmin/utility/decorators.py

@@ -0,0 +1,50 @@
+"""
+Module containing utility decorators which may
+be used by program
+"""
+
+import functools
+import time
+
+from prawcore.exceptions import RequestException, ServerError
+
+
+def consumestransientapierrors(_execute_function=None, *, timeout: int = 30):
+    """
+    Decorator responsible for consuming common transient
+    errors which may occur while connecting to the
+    Reddit API during the running of the provided
+    program
+    """
+
+    def subsuming_function(execute_function):
+
+        @functools.wraps(execute_function)
+        def wrapper(*args, **kwargs):
+            try:
+                program_logger = getattr(args[0], '_programLogger', None)
+            except IndexError:
+                program_logger = None
+            while True:
+                try:
+                    function_value = execute_function(*args, **kwargs)
+                    return function_value
+                # Handle for problems connecting to the Reddit API
+                except (RequestException, ServerError) as ex:
+                    message = "Failed to connect to the Reddit API: {}".format(
+                                ex.args
+                    )
+                    if program_logger:
+                        program_logger.warning(
+                            message
+                        )
+                    else:
+                        print(message)
+                    time.sleep(timeout)
+        return wrapper
+
+    # Handle if decorator is called with arguments
+    if _execute_function is None:
+        return subsuming_function
+    else:
+        return subsuming_function(_execute_function)

redditadmin/utility/exceptions.py

@@ -0,0 +1,28 @@
+class InitializationError(Exception):
+    """
+    Class to encapsulate an error in the
+    initialization of a module
+    """
+
+    def __init__(self, *args):
+        super().__init__(self, args)
+
+
+class BotInitializationError(InitializationError):
+    """
+    Class to encapsulate an error in the
+    initialization of a bot module
+    """
+
+    def __init__(self, *args):
+        super().__init__(*args)
+
+
+class InvalidBotCredentialsError(Exception):
+    """
+    Class encapsulating an exception raised
+    when provided bot credentials are invalid
+    """
+
+    def __init__(self, *args):
+        super().__init__(self, args)

redditadmin/utility/redditinterface.py

@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*
+from praw import Reddit
+
+
+class RedditInterface:
+    """
+    Class holding tools to interface with the Reddit API
+    """
+
+    __prawReddit: Reddit
+
+    def __init__(self, praw_reddit: Reddit):
+        self.__prawReddit = praw_reddit
+
+    @property
+    def get_praw_reddit(self):
+        """Retrieve the interface's PrawReddit instance"""
+
+        return self.__prawReddit

redditadmin/utility/redditsubmission.py

@@ -0,0 +1,36 @@
+from praw.models import Submission
+
+
+class RedditSubmission:
+    """
+    Class encapsulating a submission
+    """
+
+    __submissionId: str
+
+    def __init__(self, submission_id):
+        self.__submissionId = submission_id
+
+    @property
+    def get_submission_id(self):
+        return self.__submissionId
+
+    @classmethod
+    def get_submission_from_id(
+            cls, submission_id: str
+    ):
+        """
+        Returns a SimpleSubmission object from
+        the provided submissionId
+        """
+        return RedditSubmission(submission_id)
+
+    @classmethod
+    def get_submission_from_praw_submission(
+            cls, praw_submission: Submission
+    ):
+        """
+        Returns a SimpleSubmission object from
+        the provided PRAW submission
+        """
+        return RedditSubmission(praw_submission.id)

redditadmin-0.0.4.dist-info/METADATA

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: redditadmin
+Version: 0.0.4
+Summary: Extensible Python administrative bot
+Project-URL: Homepage, https://github.com/Grod56/reddit-admin
+Project-URL: Issues, https://github.com/Grod56/reddit-admin/issues
+Author-email: Grod56 <providenceuniversalstudios@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+Extensible Reddit admin bot

redditadmin-0.0.4.dist-info/RECORD

@@ -0,0 +1,22 @@
+redditadmin/__init__.py,sha256=H9tJpqCduGTfE__euVT9Qp5vWzS6VI3iXmGfbl_cixw,120
+redditadmin/core.py,sha256=iGgN74nYgRLvrkAue9hk-Ptdmpr0oUCx8xWdW5ROBaY,15173
+redditadmin/plugin/__init__.py,sha256=qHKyhBz5ovgef0lcXtIUsP7ZbryDrXCxRylyGJJjgTo,134
+redditadmin/plugin/asynchronouspluginsexecutor.py,sha256=WkEbTFciqgJ2cQ59AgXJBsPpPntugJxF2KapB1NNmwY,7096
+redditadmin/plugin/exceptions.py,sha256=tNwWiitjeCXVFTL9_y3fXF_Dzjk-CUHd2uqvl0_UUmI,298
+redditadmin/plugin/plugin.py,sha256=_Zr1mhTP6y1cZDxxd8vcRYodSeiOViprmZ7TGJwaA6A,1673
+redditadmin/plugin/pluginsexecutor.py,sha256=i758rqdlFysJh63ZzVY3fqQJriH2hc-gubiuK9wa24Y,1496
+redditadmin/plugin/redditinterfacefactory.py,sha256=20RInQUmvHFnbE7-SttjfYa1dsRTD0lgdh5mQVieFUw,1654
+redditadmin/program/__init__.py,sha256=86ezrveWRark-dpsSjuD_dPvsxDbh7uqHE-Porlhd_E,200
+redditadmin/program/program.py,sha256=pGvx03PWkfQsfdRfQ-g5DbXSG0NjDuGQBrTU3baQJaE,1205
+redditadmin/program/streamprocessingprogram.py,sha256=r-VuHmNdEiJq6sAoDDUub-VlX04lVCjgYCBfiiw9gPE,3888
+redditadmin/utility/__init__.py,sha256=bZlqoWdMCmR7COJiiSY6RamzyqQSvbLHyifdvrBW4Ac,302
+redditadmin/utility/botcredentials.py,sha256=qkrKtqXvA0h1NSwy70ESxsZyyXwXPiB5USpMt-56UwY,1462
+redditadmin/utility/contributionsutility.py,sha256=FHOlMJE3Vdk5H2j-_b0TzGP9rhGn-tAxQqx4_-hk8mg,1492
+redditadmin/utility/decorators.py,sha256=T0Mir1zX3_tHVDuU3UaQ1Mg1ayapaL84_GSbuifg5lY,1661
+redditadmin/utility/exceptions.py,sha256=8XliprLrcYtKYji6JPYw6nfC3yA0i551iOSV3Op06A4,652
+redditadmin/utility/redditinterface.py,sha256=kWmUrdQffujf3j9bDE9wCH3FAmvckeaOWcl9NV3MRy0,415
+redditadmin/utility/redditsubmission.py,sha256=tB830FGKmnFMBg5GXrMcGKYdGtSSYgt_uCCaLnNYlC4,862
+redditadmin-0.0.4.dist-info/METADATA,sha256=lBDvuLj28a18VyjP2ae02Xx8wZudDQ38YkbwckcbcLc,523
+redditadmin-0.0.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+redditadmin-0.0.4.dist-info/licenses/LICENSE,sha256=kieFEKjHWxFgNnmvKA_eXHmaQQZ9ZgEI_5m14IiVzAo,1091
+redditadmin-0.0.4.dist-info/RECORD,,

redditadmin-0.0.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

redditadmin-0.0.4.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Garikai Gumbo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.