printBuddies.printBuddies API documentation

# Module `printBuddies.printBuddies`

Expand source code

    from os import get_terminal_size
    from time import sleep
    from typing import Any

    from noifTimer import Timer

    def clear():
        """Erase the current line from the terminal."""
        print(" " * (get_terminal_size().columns - 1), flush=True, end="\r")

    def printInPlace(string: str, animate: bool = False, animateRefresh: float = 0.01):
        """Calls to printInPlace will overwrite
        the previous line of text in the terminal
        with the 'string' param.

        :param animate: Will cause the string
        to be printed to the terminal
        one character at a time.

        :param animateRefresh: Number of seconds
        between the addition of characters
        when 'animate' is True."""
        clear()
        string = str(string)
        width = get_terminal_size().columns
        string = string[: width - 2]
        if animate:
            for i in range(len(string)):
                print(f"{string[:i+1]}", flush=True, end=" \r")
                sleep(animateRefresh)
        else:
            print(string, flush=True, end="\r")

    def ticker(info: list[str]):
        """Prints info to terminal with
        top and bottom padding so that repeated
        calls print info without showing previous
        outputs from ticker calls.

        Similar visually to printInPlace,
        but for multiple lines."""
        width = get_terminal_size().columns
        info = [str(line)[: width - 1] for line in info]
        height = get_terminal_size().lines - len(info)
        print("\n" * (height * 2), end="")
        print(*info, sep="\n", end="")
        print("\n" * (int((height) / 2)), end="")

    class ProgBar:
        """Self incrementing, dynamically sized progress bar.

        Includes a Timer object from noifTimer that starts timing
        on the first call to display and stops timing once
        self.counter >= self.total.
        It can be easily added to the progress bar display by calling
        Timer's checkTime function and passing the value to the 'prefix' or 'suffix'
        param of self.display():

        bar = ProgBar(total=someTotal)
        bar.display(prefix=f"Run time: {bar.timer.checkTime()}")"""

        def __init__(
            self,
            total: float,
            fillCh: str = "_",
            unfillCh: str = "/",
            widthRatio: float = 0.75,
            newLineAfterCompletion: bool = True,
            clearAfterCompletion: bool = False,
        ):
            """:param total: The number of calls to reach 100% completion.

            :param fillCh: The character used to represent the completed part of the bar.

            :param unfillCh: The character used to represent the uncompleted part of the bar.

            :param widthRatio: The width of the progress bar relative to the width of the terminal window.

            :param newLineAfterCompletion: Make a call to print() once self.counter >= self.total.

            :param clearAfterCompletion: Make a call to printBuddies.clear() once self.counter >= self.total.

            Note: if newLineAfterCompletion and clearAfterCompletion are both True, the line will be cleared
            then a call to print() will be made."""
            self.total = total
            self.fillCh = fillCh[0]
            self.unfillCh = unfillCh[0]
            self.widthRatio = widthRatio
            self.newLineAfterCompletion = newLineAfterCompletion
            self.clearAfterCompletion = clearAfterCompletion
            self.timer = Timer(subsecondFormat=True)
            self.reset()

        def reset(self):
            self.counter = 0
            self.percent = ""
            self.prefix = ""
            self.suffix = ""
            self.filled = ""
            self.unfilled = ""
            self.bar = ""

        def getPercent(self) -> str:
            """Returns the percentage complete to two decimal places
            as a string without the %."""
            percent = str(round(100.0 * self.counter / self.total, 2))
            if len(percent.split(".")[1]) == 1:
                percent = percent + "0"
            if len(percent.split(".")[0]) == 1:
                percent = "0" + percent
            return percent

        def _prepareBar(self):
            self.terminalWidth = get_terminal_size().columns - 1
            barLength = int(self.terminalWidth * self.widthRatio)
            progress = int(barLength * self.counter / self.total)
            self.filled = self.fillCh * progress
            self.unfilled = self.unfillCh * (barLength - progress)
            self.percent = self.getPercent()
            self.bar = self._getBar()

        def _trimBar(self):
            originalRatio = self.widthRatio
            while len(self.bar) > self.terminalWidth and self.widthRatio > 0:
                self.widthRatio -= 0.01
                self._prepareBar()
            self.widthRatio = originalRatio

        def _getBar(self):
            return f"{self.prefix} [{self.filled}{self.unfilled}]-{self.percent}% {self.suffix}"

        def display(
            self,
            prefix: str = "",
            suffix: str = "",
            counterOverride: float = None,
            totalOverride: float = None,
            returnObject: Any = None,
        ) -> Any:
            """Writes the progress bar to the terminal.

            :param prefix: String affixed to the front of the progress bar.

            :param suffix: String appended to the end of the progress bar.

            :param counterOverride: When an externally incremented completion counter is needed.

            :param totalOverride: When an externally controlled bar total is needed.

            :param returnObject: An object to be returned by display().

            Allows display() to be called within a comprehension:

            e.g.

            progBar = ProgBar(9)

            myList = [progBar.display(returnObject=i) for i in range(10)]"""
            if not self.timer.started:
                self.timer.start()
            if counterOverride:
                self.counter = counterOverride
            if totalOverride:
                self.total = totalOverride
            # Don't wanna divide by 0 there, pal
            while self.total <= 0:
                self.total += 1
            self.prefix = prefix
            self.suffix = suffix
            self._prepareBar()
            self._trimBar()
            pad = " " * (self.terminalWidth - len(self.bar))
            width = get_terminal_size().columns
            print(f"{self.bar}{pad}"[: width - 2], flush=True, end="\r")
            if self.counter >= self.total:
                self.timer.stop()
                if self.clearAfterCompletion:
                    clear()
                if self.newLineAfterCompletion:
                    print()
            self.counter += 1
            return returnObject

## Functions

`def clear()`

  Erase the current line from the terminal.

  Expand source code

      def clear():
          """Erase the current line from the terminal."""
          print(" " * (get_terminal_size().columns - 1), flush=True, end="\r")

`def printInPlace(string: str, animate: bool = False, animateRefresh: float = 0.01)`

  Calls to printInPlace will overwrite the previous line of text in the terminal with the 'string' param.

  :param animate: Will cause the string to be printed to the terminal one character at a time.

  :param animateRefresh: Number of seconds between the addition of characters when 'animate' is True.

  Expand source code

      def printInPlace(string: str, animate: bool = False, animateRefresh: float = 0.01):
          """Calls to printInPlace will overwrite
          the previous line of text in the terminal
          with the 'string' param.

          :param animate: Will cause the string
          to be printed to the terminal
          one character at a time.

          :param animateRefresh: Number of seconds
          between the addition of characters
          when 'animate' is True."""
          clear()
          string = str(string)
          width = get_terminal_size().columns
          string = string[: width - 2]
          if animate:
              for i in range(len(string)):
                  print(f"{string[:i+1]}", flush=True, end=" \r")
                  sleep(animateRefresh)
          else:
              print(string, flush=True, end="\r")

`def ticker(info: list[str])`

  Prints info to terminal with top and bottom padding so that repeated calls print info without showing previous outputs from ticker calls.

  Similar visually to printInPlace, but for multiple lines.

  Expand source code

      def ticker(info: list[str]):
          """Prints info to terminal with
          top and bottom padding so that repeated
          calls print info without showing previous
          outputs from ticker calls.

          Similar visually to printInPlace,
          but for multiple lines."""
          width = get_terminal_size().columns
          info = [str(line)[: width - 1] for line in info]
          height = get_terminal_size().lines - len(info)
          print("\n" * (height * 2), end="")
          print(*info, sep="\n", end="")
          print("\n" * (int((height) / 2)), end="")

## Classes

`class ProgBar (total: float, fillCh: str = '_', unfillCh: str = '/', widthRatio: float = 0.75, newLineAfterCompletion: bool = True, clearAfterCompletion: bool = False)`

  Self incrementing, dynamically sized progress bar.

  Includes a Timer object from noifTimer that starts timing on the first call to display and stops timing once self.counter >= self.total. It can be easily added to the progress bar display by calling Timer's checkTime function and passing the value to the 'prefix' or 'suffix' param of self.display():

  bar = ProgBar(total=someTotal) bar.display(prefix=f"Run time: {bar.timer.checkTime()}")

  :param total: The number of calls to reach 100% completion.

  :param fillCh: The character used to represent the completed part of the bar.

  :param unfillCh: The character used to represent the uncompleted part of the bar.

  :param widthRatio: The width of the progress bar relative to the width of the terminal window.

  :param newLineAfterCompletion: Make a call to print() once self.counter >= self.total.

  :param clearAfterCompletion: Make a call to printBuddies.clear() once self.counter >= self.total.

  Note: if newLineAfterCompletion and clearAfterCompletion are both True, the line will be cleared then a call to print() will be made.

  Expand source code

      class ProgBar:
          """Self incrementing, dynamically sized progress bar.

          Includes a Timer object from noifTimer that starts timing
          on the first call to display and stops timing once
          self.counter >= self.total.
          It can be easily added to the progress bar display by calling
          Timer's checkTime function and passing the value to the 'prefix' or 'suffix'
          param of self.display():

          bar = ProgBar(total=someTotal)
          bar.display(prefix=f"Run time: {bar.timer.checkTime()}")"""

          def __init__(
              self,
              total: float,
              fillCh: str = "_",
              unfillCh: str = "/",
              widthRatio: float = 0.75,
              newLineAfterCompletion: bool = True,
              clearAfterCompletion: bool = False,
          ):
              """:param total: The number of calls to reach 100% completion.

              :param fillCh: The character used to represent the completed part of the bar.

              :param unfillCh: The character used to represent the uncompleted part of the bar.

              :param widthRatio: The width of the progress bar relative to the width of the terminal window.

              :param newLineAfterCompletion: Make a call to print() once self.counter >= self.total.

              :param clearAfterCompletion: Make a call to printBuddies.clear() once self.counter >= self.total.

              Note: if newLineAfterCompletion and clearAfterCompletion are both True, the line will be cleared
              then a call to print() will be made."""
              self.total = total
              self.fillCh = fillCh[0]
              self.unfillCh = unfillCh[0]
              self.widthRatio = widthRatio
              self.newLineAfterCompletion = newLineAfterCompletion
              self.clearAfterCompletion = clearAfterCompletion
              self.timer = Timer(subsecondFormat=True)
              self.reset()

          def reset(self):
              self.counter = 0
              self.percent = ""
              self.prefix = ""
              self.suffix = ""
              self.filled = ""
              self.unfilled = ""
              self.bar = ""

          def getPercent(self) -> str:
              """Returns the percentage complete to two decimal places
              as a string without the %."""
              percent = str(round(100.0 * self.counter / self.total, 2))
              if len(percent.split(".")[1]) == 1:
                  percent = percent + "0"
              if len(percent.split(".")[0]) == 1:
                  percent = "0" + percent
              return percent

          def _prepareBar(self):
              self.terminalWidth = get_terminal_size().columns - 1
              barLength = int(self.terminalWidth * self.widthRatio)
              progress = int(barLength * self.counter / self.total)
              self.filled = self.fillCh * progress
              self.unfilled = self.unfillCh * (barLength - progress)
              self.percent = self.getPercent()
              self.bar = self._getBar()

          def _trimBar(self):
              originalRatio = self.widthRatio
              while len(self.bar) > self.terminalWidth and self.widthRatio > 0:
                  self.widthRatio -= 0.01
                  self._prepareBar()
              self.widthRatio = originalRatio

          def _getBar(self):
              return f"{self.prefix} [{self.filled}{self.unfilled}]-{self.percent}% {self.suffix}"

          def display(
              self,
              prefix: str = "",
              suffix: str = "",
              counterOverride: float = None,
              totalOverride: float = None,
              returnObject: Any = None,
          ) -> Any:
              """Writes the progress bar to the terminal.

              :param prefix: String affixed to the front of the progress bar.

              :param suffix: String appended to the end of the progress bar.

              :param counterOverride: When an externally incremented completion counter is needed.

              :param totalOverride: When an externally controlled bar total is needed.

              :param returnObject: An object to be returned by display().

              Allows display() to be called within a comprehension:

              e.g.

              progBar = ProgBar(9)

              myList = [progBar.display(returnObject=i) for i in range(10)]"""
              if not self.timer.started:
                  self.timer.start()
              if counterOverride:
                  self.counter = counterOverride
              if totalOverride:
                  self.total = totalOverride
              # Don't wanna divide by 0 there, pal
              while self.total <= 0:
                  self.total += 1
              self.prefix = prefix
              self.suffix = suffix
              self._prepareBar()
              self._trimBar()
              pad = " " * (self.terminalWidth - len(self.bar))
              width = get_terminal_size().columns
              print(f"{self.bar}{pad}"[: width - 2], flush=True, end="\r")
              if self.counter >= self.total:
                  self.timer.stop()
                  if self.clearAfterCompletion:
                      clear()
                  if self.newLineAfterCompletion:
                      print()
              self.counter += 1
              return returnObject

  ### Methods

  `def display(self, prefix: str = '', suffix: str = '', counterOverride: float = None, totalOverride: float = None, returnObject: Any = None) ‑> Any`

    Writes the progress bar to the terminal.

    :param prefix: String affixed to the front of the progress bar.

    :param suffix: String appended to the end of the progress bar.

    :param counterOverride: When an externally incremented completion counter is needed.

    :param totalOverride: When an externally controlled bar total is needed.

    :param returnObject: An object to be returned by display().

    Allows display() to be called within a comprehension:

    e.g.

    progBar = ProgBar(9)

    myList = [progBar.display(returnObject=i) for i in range(10)]

    Expand source code

        def display(
            self,
            prefix: str = "",
            suffix: str = "",
            counterOverride: float = None,
            totalOverride: float = None,
            returnObject: Any = None,
        ) -> Any:
            """Writes the progress bar to the terminal.

            :param prefix: String affixed to the front of the progress bar.

            :param suffix: String appended to the end of the progress bar.

            :param counterOverride: When an externally incremented completion counter is needed.

            :param totalOverride: When an externally controlled bar total is needed.

            :param returnObject: An object to be returned by display().

            Allows display() to be called within a comprehension:

            e.g.

            progBar = ProgBar(9)

            myList = [progBar.display(returnObject=i) for i in range(10)]"""
            if not self.timer.started:
                self.timer.start()
            if counterOverride:
                self.counter = counterOverride
            if totalOverride:
                self.total = totalOverride
            # Don't wanna divide by 0 there, pal
            while self.total <= 0:
                self.total += 1
            self.prefix = prefix
            self.suffix = suffix
            self._prepareBar()
            self._trimBar()
            pad = " " * (self.terminalWidth - len(self.bar))
            width = get_terminal_size().columns
            print(f"{self.bar}{pad}"[: width - 2], flush=True, end="\r")
            if self.counter >= self.total:
                self.timer.stop()
                if self.clearAfterCompletion:
                    clear()
                if self.newLineAfterCompletion:
                    print()
            self.counter += 1
            return returnObject

  `def getPercent(self) ‑> str`

    Returns the percentage complete to two decimal places as a string without the %.

    Expand source code

        def getPercent(self) -> str:
            """Returns the percentage complete to two decimal places
            as a string without the %."""
            percent = str(round(100.0 * self.counter / self.total, 2))
            if len(percent.split(".")[1]) == 1:
                percent = percent + "0"
            if len(percent.split(".")[0]) == 1:
                percent = "0" + percent
            return percent

  `def reset(self)`
    Expand source code

        def reset(self):
            self.counter = 0
            self.percent = ""
            self.prefix = ""
            self.suffix = ""
            self.filled = ""
            self.unfilled = ""
            self.bar = ""