Pre - Release 0.2.0 (#2)

* added new subprocess method, changed logs to now show the module name instead of the logger name (helps with explicit stack traces), added a new type of exception for internal problems, and added _internal to distro

* added to_bool method for utility purposes

* fixed a bunch of bugs waiting to happen, added some other stuff, bumped the required python version, linting, and testing out CI pipeline

* added some tests and began trying to have a somewhat decent looking doc

* caught a few things when looking over PR diff, added in some constants (and docstrings), made `cleanup` param available to all subprocess methods

* linting

* bumped release version. I should really make a script do this for me

.github/workflows/launch-container.yaml

@@ -0,0 +1,30 @@
+name: Container Launcher
+
+on:
+  workflow_call:
+    inputs:
+      command:
+        required: true
+        description: The command to run
+        type: string
+      args:
+        required: false
+        description: Arguments to pass to the command
+        type: string
+
+jobs:
+  execute:
+    name: Execute Command in Container
+    runs-on: ubuntu-latest
+    env:
+      image_tag: hephaestus-dev:latest
+      app_dir: /dev/hephaestus
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v4
+
+      - name: Build Container
+        run: docker build --file docker/Dockerfile --tag $image_tag .
+
+      - name: Run Command Using Container
+        run: docker run --rm --volume .:$app_dir --workdir $app_dir $image_tag ${{ inputs.command }} ${{ inputs.args }}

.github/workflows/run-tests.yaml

@@ -1 +1,17 @@
-# TODO
+name: Run Python Tests
+
+on:
+  push:
+    branches:
+      - develop
+  pull_request:
+    branches:
+      - develop
+
+jobs:
+  test:
+    name: Setup and Run Test Suite
+    uses: ./.github/workflows/launch-container.yaml
+    with:
+      command: scripts/run_pytest
+

README.md

@@ -30,7 +30,7 @@ All modules are still referenced like so:
 ```
 # myfile.py
 
-from hephaestus.common.colors import Colors
+from hephaestus.common.constants import AnsiColors
 from hephaestus.testing.pytest.fixtures import *
 
 ```

config/sphinx/source/conf.py

@@ -11,23 +11,28 @@
 
 sys.path.append(str(Path(__file__).parents[3]))
 
-project = 'Hephaestus'
-copyright = '2024, Malakai Spann'
-author = 'Malakai Spann'
-release = '0.1.0'
+project = "Hephaestus"
+copyright = "2025, Malakai Spann"
+author = "Malakai Spann"
+release = "0.1.0"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx.ext.todo", "sphinx.ext.viewcode"]
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
+]
 
-templates_path = ['_templates']
+templates_path = ["_templates"]
 exclude_patterns = []
 add_module_names = False
 
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'sphinx_rtd_theme'
-html_static_path = ['_static']
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]

docker/Dockerfile

@@ -1,17 +1,18 @@
-FROM python:3.6.15-slim-buster
+FROM python:3.10.16-slim-bullseye
 
 LABEL author "Malakai Spann"
 LABEL maintainers ["malakaispann@gmail.com",]
 LABEL title "Hephaestus Dev"
 LABEL description "The official Docker Image for developing, testing, and building the Hephaestus library."
 
 # IMPORTANT: All instructions assume the build context is from the root of the repo.
+COPY config/dev.requirements.txt /tmp/requirements.txt
 
 # Upgrade Package Management OS
 RUN apt-get update && \
     apt-get upgrade --assume-yes
 
 # Install Python packages
 RUN pip install --upgrade pip && \
-    pip install --requirements config/dev.requirements.txt
+    pip install --requirement /tmp/requirements.txt
 

hephaestus/_internal/meta.py

@@ -1,7 +1,18 @@
 from pathlib import Path
 
+PROJECT_NAME: str = "Hephaestus"
+PROJECT_SOURCE_URL: str = "https://github.com/KayDVC/hephaestus/"
+
+# TODO
+PROJECT_DOCUMENTATION_URL: str = ""
+
 
 class Paths:
+    """A collection of paths in the Hephaestus repo.
+
+    Literally, not helpful to anyone but Hephaestus devs.
+    """
+
     ROOT = Path(__file__).parents[2].resolve()
     LOGS = Path(ROOT, "logs")
     LIB = Path(ROOT, "hephaestus")

hephaestus/common/constants.py

@@ -1 +1,31 @@
-EMPTY_STRING = ""
+class AnsiColors:
+    """ANSI escape codes representing various colors."""
+
+    CYAN = "\033[36m"
+    GREEN = "\033[32m"
+    RED = "\033[31m"
+    YELLOW = "\033[33m"
+    MAGENTA = "\033[35m"
+    RESET = "\033[0m"
+
+
+class CharConsts:
+    """Common characters."""
+
+    NULL = ""
+    SPACE = " "
+    UNDERSCORE = "_"
+
+
+class StrConsts:
+    """Common strings."""
+
+    EMPTY_STRING = CharConsts.NULL
+
+
+class Emojis:
+    """Common graphical symbols that represent various states or ideas."""
+
+    GREEN_CHECK = "✅"
+    RED_CROSS = "❌"
+    GOLD_MEDAL = "🏅"

hephaestus/common/exceptions.py

@@ -1,15 +1,51 @@
-from logging import getLogger
+import textwrap
+import logging
+
+from typing import Any
+
+from hephaestus._internal.meta import PROJECT_SOURCE_URL
 
 
 class LoggedException(Exception):
     """An exception whose message is logged at the error level.
 
     This class is meant to be used as the base class for any other custom
     exceptions. It logs the error message for later viewing.
+    There is only one argument added to the basic Exception `__init__` method; see args below.
+
+    Args:
+
     """
 
-    _logger = getLogger(__name__)
+    _logger = logging.getLogger(__name__)
+
+    def __init__(
+        self,
+        msg: Any = None,
+        log_level: int = logging.ERROR,
+        stack_level: int = 2,
+        *args,
+    ):
+        """
+        Args:
+            msg: the error message to log. Defaults to None.
+            log_level: the level to log the message at. Defaults to ERROR.
+            stack_level: the number of calls to peek back in the stack trace for
+                log info such as method name, line number, etc. Defaults to 2.
+        """
+        self._logger.log(level=log_level, msg=msg, stacklevel=stack_level)
+        super().__init__(msg, *args)
+
+
+class _InternalError(LoggedException):
+    """Indicates a problem with the library's code was encountered."""
 
-    def __init__(self, msg: str = None):
-        self._logger.error(msg)
-        super().__init__(msg)
+    def __init__(self, msg: Any = None, *args):
+        msg = textwrap.dedent(
+            f"""\
+        Encountered an internal error with the Hephaestus Library:
+        \t{msg}
+        \tPlease report this issue here: {PROJECT_SOURCE_URL}
+        """
+        )
+        super().__init__(msg, stack_level=3, *args)

hephaestus/common/types.py

@@ -1,7 +1,24 @@
 import os
 
-from typing import Union
+from typing import Any, Union
 from pathlib import Path
 
 
 PathLike = Union[str, Path, os.PathLike]
+
+
+def to_bool(obj: Any):
+    """Converts any object to a boolean.
+
+    Args:
+        obj: the object to convert.
+
+    Returns:
+        True if the object has a sane truthy value; False otherwise.
+    """
+    if not isinstance(obj, str):
+        return bool(obj)
+
+    obj = obj.lower()
+
+    return obj in ["true", "t", "yes", "y", "enable"]

hephaestus/decorators/reference.py

@@ -30,7 +30,7 @@ def __init__(self, getter: Callable = None, ignores: list[Callable] = []):
 
 
 def __return_none() -> None:
-    """Empty function used to always get None on call.
+    """Empty method used to always get None on call.
 
     Returns:
         None
@@ -42,12 +42,12 @@ def __method_wrapper(getter: Callable, if_none: Callable, method_name: str) -> C
     """Wraps methods, ensuring calls go to object stored by reference.
 
     Args:
-        getter: the function to use a "getter" for the stored object.
-        if_none: the function to use should the stored object be Null.
+        getter: the method to use a "getter" for the stored object.
+        if_none: the method to use should the stored object be Null.
         method_name: the name of method to wrap.
 
     Returns:
-        A callable function that acts as a proxy for the method to wrap.
+        A callable method that acts as a proxy for the method to wrap.
 
     Note:
         Any args passed to the wrapped method will be passed to the stored object's
@@ -131,7 +131,7 @@ def reference_getter(method: Callable) -> Callable:
 
     # Set modifier indicators for this method. Here, we want this method to have
     # both the getter and ignore indicator so that our reference logic will skip wrapping the
-    # function without adding an extra conditional check.
+    # method without adding an extra conditional check.
     setattr(method, __getter_id, True)
     cls_map.getter = method_name
     setattr(method, __ignore_id, True)
@@ -186,7 +186,7 @@ def __new__(cls: Type, *args, **kwargs):
         if (not cls_map) or (not cls_map.getter) or (not hasattr(cls, cls_map.getter)):
             raise ReferenceError("Could not find getter for class.")
 
-        # Get the function objects to pass to the wrapper methods.
+        # Get the "getter" method to pass to the wrapper methods.
         getter_ = getattr(cls, cls_map.getter)
         if_none_method_ = __return_none  # TODO: make configurable as a param?