Created initial program.

Author: Murdo B. Maclachlan

CHANGELOG.md

@@ -0,0 +1,5 @@
+### 0.1.0
+
+**New**
+
+- Created initial program and documentation. (@MurdoMaclachlan)

README.md

@@ -1,3 +1,77 @@
 # smooth_logger
 
-A simple logger made primarily for my own personal use. Was made out of a combination of necessity and being so lazy that I overflowed into being productive and instead of searching for a library that suited my needs, I wrote my own.
+A simple logger made primarily for my own personal use. Was made out of a combination of necessity and being so lazy that I overflowed into being productive and instead of searching for a library that suited my needs, I wrote my own.
+
+## Installation
+
+smooth-logger can be installed through pip. Either download the latest release from Codeberg/GitHub, or do `pip install smooth-logger` to install from PyPi. For the latest commits, check the `dev` branches on the repositories.
+
+smooth-logger was written in Python 3.9, but should work with Python 3.5 and up. A minimum of 3.5 is required due to the project's use of type hinting, which was introduced in that version.
+
+smooth-logger supports Linux, macOS and Windows.
+
+## Usage
+
+Usage of smooth-logger is, as it should be, quite simple.
+
+The `Logger` model provides a number of methods for your use:
+
+- `Logger.clean()` erases all log entries currently in memory.
+- `Logger.define_output_path()` is primarily intended as an internal method; it detects the user's operating system and home folder and, using the provided program name and creates a log folder in the appropriate location (`~/.config/{program_name}` on Linux and macOS, `AppData\Roaming\{program_name}` on Windows).
+- `Logger.get()` allows you to retrieve either the most recent log entry or all log entries, optionally filtered by scope.
+- `Logger.get_time()` returns the full date & time, or optionally just the date, in ISO-8601 formatting.
+- `Logger.init_bar()` initialises the `ProgressBar` model imported from the `smooth_progress` dependency.
+- `Logger.notify()` sends a desktop notification using the `plyer` dependency.
+- `Logger.new()` creates and, depending on scope, prints a new log entry.
+- `Logger.output()` saves all log entries of appropriate scope to the log file and cleans the log array for the next group of log entries. A new log file is created for each new day. This method only attempts to create or update the log file if there are entries of an appropriate scope to be written to it; if there are none, it just executes `Logger.clean()`.
+
+When initialising the Logger, you can optionally provide values to associate with each scope:
+
+- 0: disabled, do not print to console or save to log file
+- 1: enabled, print to console but do not save to log file
+- 2: maximum, print to console and save to log file
+
+The scopes available, along with their default values and suggested use cases, are:
+
+- DEBUG (0): Information for debugging the program.
+- ERROR (2): Errors that the program can recover from but impact functionality or performance.
+- FATAL (2): Errors that mean the program must continue; handled crashes.
+- INFO (1): General information for the user.
+- WARNING (2): Things that have no immediate impact to functionality but could cause errors later on.
+
+Here is a simple example showing the initialisation of the logger:
+
+```
+import smooth_logger
+
+Log = smooth_logger.Logger("Program")
+Log.new("This is a log message!", "INFO")
+```
+
+## Roadmap
+
+A roadmap of planned future improvements and features:
+
+- Allow the creation of custom scopes. These would be instance-specific and not hard saved in any way. Suggested format and example:
+
+  ```
+  Log.add_scope(name: str, description: str, default_value: int)
+  
+  Log.add_scope("NEWSCOPE", "A new scope of mine!", 1)
+  ```
+  
+  Potentially also allow removal of scopes. In this situation, default scopes should be removable, but doing so should log a warning.
+  
+
+- Allow editing of the values of existing scopes post-initialisation. For example:
+
+  ```
+  Log.edit_scope(name: str, new_value: int)
+  
+  Log.edit_scope("DEBUG", 1)
+  ```
+  
+  to temporarily enable debug statements. This feature would probably see the most use from custom scopes.
+  
+
+- Add an optional argument `notify: bool` to `Logger.new()` to allow log entries to be created and notified in one statement, rather than the two currently required.

setup.py

@@ -0,0 +1,36 @@
+from setuptools import setup, find_packages
+
+
+def readme():
+    return open('README.md', 'r').read()
+
+
+setup(
+    name="smooth_logger",
+    version="0.1.0",
+    author="Murdo Maclachlan",
+    author_email="[email protected]",
+    description=(
+        "A simple logger made primarily for my own personal use. Made from a"
+        + " combination of necessity and so much sloth that it overflowed into"
+        + " productivity."
+    ),
+    long_description=readme(),
+    long_description_content_type="text/markdown",
+    url="https://codeberg.org/MurdoMaclachlan/smooth_logger",
+    packages=find_packages(),
+    install_requires=[
+        "plyer",
+        "smooth_progress"
+    ],
+    classifiers=[
+        "Programming Language :: Python :: 3.5",
+        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+        "Operating System :: OS Independent",
+    ],
+    license='AGPLv3+'
+)

smooth_logger/__init__.py

@@ -0,0 +1,2 @@
+from .logger import Logger
+from .logger import LogEntry

smooth_logger/logger.py

@@ -0,0 +1,223 @@
+from datetime import datetime
+from os import environ, makedirs
+from os.path import expanduser, isdir
+from plyer import notification
+from smooth_progress import ProgressBar
+from sys import platform
+from time import time
+from typing import Dict, List, Union
+
+
+class Logger:
+    """Class for controlling the entirety of logging. The logging works on a scope-based
+    system where (almost) every message has a defined scope, and the scopes are each
+    associated with a specific value between 0 and 2 inclusive. The meanings of the
+    values are as follows:
+
+    0: disabled, do not print to console or save to log file
+    1: enabled, print to console but do not save to log file
+    2: maximum, print to console and save to log file
+    """
+    def __init__(
+        self: object, program_name: str, debug: int = 0, error: int = 2, fatal: int = 2,
+        info: int = 1, warning: int = 2
+    ) -> None:
+        self.bar: Union[ProgressBar, None] = None
+        self.__is_empty: bool = True
+        self.__log: List[LogEntry] = []
+        self.__notifier: object = notification
+        self.__program_name: str = program_name
+        self.__path: str = self.define_output_path(expanduser("~"), platform)
+        self.__scopes: Dict[str, int] = {
+            "DEBUG":   debug,   # information for debugging the program
+            "ERROR":   error,   # errors the program can recover from
+            "FATAL":   fatal,   # errors that mean the program cannot continue
+            "INFO":    info,    # general information for the user
+            "WARNING": warning  # things that could cause errors later on
+        }
+        self.__write_logs = False
+
+    def clean(self: object) -> None:
+        del self.__log[:]
+        self.__is_empty = True
+        self.__write_logs = False
+
+    def define_output_path(self: object, home: str, os: str) -> str:
+        """Detects OS and defines the appropriate save paths for the config and data.
+        Exits on detecting an unspported OS. Supported OSes are: Linux, MacOS, Windows.
+
+        :arg home: string; the user's home folder
+        :arg os: string; the user's operating system
+
+        :return: a single string dict containing the newly-defined output path
+        """
+        os = "".join(list(os)[:3])
+
+        # Route for a supported operating system
+        if os in ["dar", "lin", "win"]:
+
+            path = (
+                environ["APPDATA"] + f"\\{self.__program_name}\logs"
+                if os == "win" else
+                f"{home}/.config/{self.__program_name}/logs"
+            )
+
+            # Create any missing directories
+            if not isdir(path):
+                print(f"Making path: {path}")
+                makedirs(path, exist_ok=True)
+            return path
+
+        # Exit if the operating system is unsupported
+        else:
+            print(f"FATAL: Unsupported operating system: {os}, exiting.")
+            exit()
+
+    def get(
+            self: object, mode: str = "all", scope: str = None
+        ) -> Union[List[str], str, None]:
+        """Returns item(s) in the log. What entries are returned can be controlled by
+        passing optional arguments.
+
+        :arg mode: optional, string; options are 'all' and 'recent'.
+        :arg scope: optional, string; if passed, only entries with matching scope will
+          be returned.
+
+        :return: a single log entry (string), list of log entries (string array), or an
+          empty string on a failure.
+        """
+        if self.__is_empty:
+            pass
+        elif scope is None:
+            # Tuple indexing provides a succint way to determine what to return
+            return (self.__log, self.__log[len(self.__log)-1])[mode == "recent"]
+        else:
+            # Return all log entries with a matching scope
+            if mode == "all":
+                data = []
+                for i in self.__log:
+                    if i.scope == scope:
+                        data.append(i)
+                if data:
+                    return data
+            # Return the most recent log entry with a matching scope; for this purpose,
+            # we reverse the list then iterate through it.
+            elif mode == "recent":
+                for i in self.__log.reverse():
+                    if i.scope == scope:
+                        return self.__log[i]
+            else:
+                self.new("Unknown mode passed to Logger.get().", "WARNING")
+        # Return an empty string to indicate failure if no entries were found
+        return ""
+
+    def get_time(self: object, method: str = "time") -> str:
+        """Gets the current time and parses it to a human-readable format.
+
+        :arg method: string; the method to calculate the timestamp; either 'time' or
+          'date'.
+
+        :return: a single date string formatted either 'YYYY-MM-DD HH:MM:SS' or
+          'YYYY-MM-DD'
+        """
+        if method in ["time", "date"]:
+            return datetime.fromtimestamp(time()).strftime(
+                ("%Y-%m-%d", "%Y-%m-%d %H:%M:%S")[method == "time"]
+            )
+        else:
+            print("ERROR: Bad method passed to Logger.get_time().")
+            return ""
+
+    def init_bar(self: object, limit: int) -> None:
+        """Initiate and open the progress bar.
+
+        :arg limit: int; the number of increments it should take to fill the bar.
+        """
+        self.bar = ProgressBar(limit=limit)
+        self.bar.open()
+
+    def notify(self: object, message: str) -> None:
+        """Display a desktop notification with a given message.
+
+        :arg message: string; the message to display in the notification.
+        """
+        self.__notifier.notify(title=self.__program_name, message=message)
+
+    def new(
+            self: object,
+            message: str, scope: str, do_not_print: bool = False
+        ) -> bool:
+        """Initiates a new log entry and prints it to the console. Optionally, if
+        do_not_print is passed as True, it will only save the log and will not print
+        anything (unless the scope is 'NOSCOPE'; these messages are always printed).
+
+        :arg message: string; the messaage to log.
+        :arg scope: string; the scope of the message (e.g. debug, error, info).
+        :arg do_not_print: optional, bool; False by default.
+
+        :return: boolean success status.
+        """
+        if scope in self.__scopes or scope == "NOSCOPE":
+            # TODO: sperate some of this into submethods
+
+            # Setup variables
+            output = (self.__scopes[scope] == 2) if scope != "NOSCOPE" else False
+            isBar: bool = (self.bar is not None) and self.bar.opened
+
+            # Create and save the log entry
+            if isBar and len(message) < len(self.bar.state):
+                message += " " * (len(self.bar.state) - len(message))
+            entry = LogEntry(message, output, scope, self.get_time())
+            self.__log.append(entry)
+
+            # Print the message, if required
+            if scope == "NOSCOPE":
+                print(entry.rendered)
+            elif self.__scopes[scope]:
+                print(entry.rendered if not do_not_print else None)
+
+            # Re-print bar, if required
+            if isBar:
+                print(self.bar.state, end="\r", flush=True)
+
+            # Amend boolean states
+            if not self.__write_logs:
+                self.__write_logs = output
+            self.__is_empty = False
+
+            return True
+        else:
+            self.new("Unknown scope passed to Logger.new()", "WARNING")
+        return False
+
+    def output(self: object) -> None:
+        """Write all log entries with scopes set to save to a log file in a data folder
+        in the working directory, creating the folder and file if they do not exist.
+        The log files are marked with the date, so each new day, a new file will be
+        created.
+        """
+        if self.__write_logs:
+            with open(
+                f"{self.__path}/log-{self.get_time(method='date')}.txt", "at+"
+            ) as log_file:
+                for line in self.__log:
+                    if line.output:
+                        log_file.write(line.rendered + "\n")
+        self.clean()
+
+
+class LogEntry:
+    """Represents a single entry within the log, storing its timestamp, scope and
+    message. This makes it easier to select certain log entries using the
+    Logger.get() method.
+    """
+    def __init__(self: object, message: str, output: bool, scope: str, timestamp: str):
+        self.message = message
+        self.output = output
+        self.scope = scope
+        self.timestamp = timestamp
+        self.rendered = (
+            f"[{timestamp}] {scope}: {message}"
+            if scope != "NOSCOPE" else
+            f"{message}"
+        )