Source code for labelord.printers

"""Printers module

This module contains BasePrinter class and its descendants. They serve to
print information so user is notified about application's performed actions.
"""

import click

class BasePrinter:
    """Basic printer interface

    This class serves as an ancestor to other printer classes within this
    module and defines their common interface. Initializing an instance
    will initialize an empty set of the printer's registered GitHub repositories
    and sets error count to zero.

    Example:
        .. testcode::

           import labelord
           printer = labelord.printers.BasePrinter()

        .. doctest::

           >>> type(printer.repos)
           <class 'set'>

           >>> len(printer.repos)
           0

           >>> printer.errors
           0
    """

    SUCCESS_SUMMARY = '{} repo(s) updated successfully'
    """str: Summarizing message in case of success."""
    ERROR_SUMMARY = '{} error(s) in total, please check log above'
    """str: Summarizing message in case of error."""

    EVENT_CREATE = 'ADD'
    """str: Output tag for create event (new label is created)."""
    EVENT_DELETE = 'DEL'
    """str: Output tag for delete event (label is deleted)."""
    EVENT_UPDATE = 'UPD'
    """str: Output tag for update event (label is updated)."""
    EVENT_LABELS = 'LBL'
    """str: Output tag for read labels event (labels are read from repository,
     shows only if an error occurs in this phase)."""

    RESULT_SUCCESS = 'SUC'
    """str: Output tag for successfully performed operation."""
    RESULT_ERROR = 'ERR'
    """str: Output tag for unsuccessfully performed operation."""
    RESULT_DRY = 'DRY'
    """str: Output tag for successfully simulated operation."""

    def __init__(self):
        self.repos = set()
        self.errors = 0

    def add_repo(self, slug):
        """Registers repository for the printer

        This method adds given repository to the printer's set of
        registered repositories.

        Example:
            .. testcode::

               import labelord

               printer = labelord.printers.BasePrinter()
               printer.add_repo('User/Repo')

            .. doctest::

               >>> 'User/Repo' in printer.repos
               True

        Args:
            slug (str): GitHub repository slug (eg. User/Repo).
        """
        self.repos.add(slug)

    def event(self, event, result, repo, *args):
        """Processes printer events

        This method processes printer events and increments its error count
        in case of unsuccessfully performed operation.

        Example:
            .. testcode::

               import labelord

               printer = labelord.printers.BasePrinter()
               printer.event('Test error event', 'ERR', 'User/Repo')

            .. doctest::

               >>> printer.errors
               1

        Args:
            event (str): Event description.
            result (str): Event result.
            repo (str): Repository where event happened.
            args (list): Additional arguments (placeholder).
        """
        if result == self.RESULT_ERROR:
            self.errors += 1

    def summary(self):
        """Interface for printing summary

        This method only passes control to the subclass.
        """
        pass

    def _create_summary(self):
        if self.errors > 0:
            return self.ERROR_SUMMARY.format(self.errors)
        return self.SUCCESS_SUMMARY.format(len(self.repos))


class Printer(BasePrinter):
    """Default printer

    This class describes default printer, which only prints errors
    and summary.
    """

    def event(self, event, result, repo, *args):
        """Processes printer events

        This method processes printer events through base class' method
        and prints any errors.

        Example:
            .. testcode::

               import labelord
               printer = labelord.printers.Printer()

            .. doctest::

               >>> printer.event('ADD', 'ERR', 'User/Repo')
               ERROR: ADD; User/Repo

               >>> printer.errors
               1

        Args:
            event (str): Event description.
            result (str): Event result.
            repo (str): Repository where event happened.
            args (list): Additional arguments describing the error.
        """
        super().event(event, result, repo, *args)
        if result == self.RESULT_ERROR:
            line_parts = ['ERROR: ' + event, repo, *args]
            click.echo('; '.join(line_parts))

    def summary(self):
        """Prints summary

        This method prints summary after all operations are processed.

        Example:
            .. testcode::

               import labelord
               printer = labelord.printers.Printer()

            .. doctest::

               >>> printer.summary()
               SUMMARY: 0 repo(s) updated successfully

        """
        click.echo('SUMMARY: ' + self._create_summary())


class QuietPrinter(BasePrinter):
    """Quiet printer

    This class describes quiet printer, which prints nothing.

    Example:
        .. testcode::

           import labelord
           printer = labelord.printers.QuietPrinter()

        .. doctest::

           >>> printer.event('ADD', 'SUC', 'User/Repo')
           >>> printer.event('UPD', 'ERR', 'User/Repo')
           >>> printer.summary()

           >>> printer.errors
           1
    """
    pass


class VerbosePrinter(BasePrinter):
    """Verbose printer

    This class describes verbose printer, which prints detailed information
    about every performed operation including its result. Also prints summary
    after all operations are processed.
    """

    LINE_START = '[{}][{}] {}'
    """str: Defines printed line format."""

    def event(self, event, result, repo, *args):
        """Processes printer events

        This method processes printer events through base class' method
        and prints detailed information about every event including its result.

        Example:
            .. testcode::

               import labelord
               printer = labelord.printers.VerbosePrinter()

            .. doctest::

               >>> printer.event('ADD', 'ERR', 'User/Repo')
               [ADD][ERR] User/Repo

               >>> printer.event('UPD', 'SUC',  'User/Repo')
               [UPD][SUC] User/Repo

               >>> printer.errors
               1

        Args:
            event (str): Event description.
            result (str): Event result.
            repo (str): Repository where event happened.
            args (list): Additional arguments describing the event.
        """
        super().event(event, result, repo, *args)
        line_parts = [self.LINE_START.format(event, result, repo), *args]
        click.echo('; '.join(line_parts))

    def summary(self):
        """Prints summary

        This method prints summary after all operations are processed.

        Example:
            .. testcode::

               import labelord
               printer = labelord.printers.VerbosePrinter()

            .. doctest::

               >>> printer.summary()
               [SUMMARY] 0 repo(s) updated successfully
        """
        click.echo('[SUMMARY] ' + self._create_summary())