easy-exit-calls 1.0.0__tar.gz

easy_exit_calls-1.0.0/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (c) 2025 **Inspyre-Softworks**
+
+Permission is **hereby granted**, free of charge, to any person obtaining a copy
+of this software (*EasyExitCalls*) 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*, **sub***license*, **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.**

easy_exit_calls-1.0.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: easy-exit-calls
+Version: 1.0.0
+Summary: A Python library for managing exit handlers with enhanced features like decorators, UUID tracking, and LIFO execution.
+License-File: LICENSE.md
+Author: Taylor B.
+Author-email: tayjaybabee@gmail.com
+Requires-Python: >=3.12,<4.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Dist: inspy-logger (==3.2.3)
+Requires-Dist: inspyre-toolbox (>=1.5.3,<2.0.0)
+Requires-Dist: pytz (>=2025.1,<2026.0)
+Description-Content-Type: text/markdown
+
+# easy-exit-calls
+
+A Python library for managing exit handlers with enhanced features like decorators, UUID tracking, and LIFO execution.
+
+## Features
+
+- **Decorator Support**: Easily register functions as exit handlers using a decorator.
+- **LIFO Execution**: Handlers execute in Last-In-First-Out order by default (configurable).
+- **UUID Tracking**: Each handler is assigned a unique UUID for easy management.
+- **Thread Safety**: Uses threading locks to ensure safe registration/unregistration.
+- **Detailed Logging**: Integrated with a logging engine for debugging and tracking.
+- **Error Handling**: Captures exceptions during exit and logs them with tracebacks.
+
+## Installation
+
+This project requires **Python 3.12** or later.
+
+```bash
+pip install easy-exit-calls
+```
+
+## Usage
+
+### Basic Decorator Usage
+
+```python
+from easy_exit_calls import register_exit_handler
+
+@register_exit_handler
+def cleanup():
+    print("Cleaning up resources...")
+
+# Exiting the program will automatically trigger this handler.
+```
+
+### Decorator with Arguments
+
+```python
+from easy_exit_calls import register_exit_handler
+
+@register_exit_handler("arg1", key="value")
+def cleanup_with_args(arg1, key=None):
+    print(f"Cleaning up with {arg1} and {key}")
+
+# Handler called with provided args/kwargs on exit.
+```
+
+### Manual Registration
+
+```python
+from easy_exit_calls import ExitCallHandler
+
+def manual_cleanup():
+    print("Manual cleanup")
+
+ExitCallHandler().register_handler(manual_cleanup)
+
+# Exiting the program will manually trigger this handler.
+```
+
+### Unregistering Handlers
+
+```python 
+from easy_exit_calls import ExitCallHandler
+
+def cleanup():
+    print("Cleaning up resources...")
+
+handler_uuid = ExitCallHandler().register_handler(cleanup)
+
+# Unregister the handler by UUID.
+ExitCallHandler().unregister_by_uuid(handler_uuid)
+```
+
+### Execution Order
+
+```python
+from easy_exit_calls import register_exit_handler
+
+@register_exit_handler
+def first_handler():
+    print("First handler")
+
+@register_exit_handler
+def second_handler():
+    print("Second handler")
+
+# Output on exit:
+# Second handler
+# First handler
+# (LIFO execution order)
+```
+
+## API Reference
+
+### `ExitCallHandler`
+
+Singleton class managing exit handlers.
+
+#### Methods:
+
+- `register_handler(func: Callable, *args, **kwargs) -> str`:
+    Register a new exit handler with optional args/kwargs. Returns the UUID of the handler.<br><br>
+- `unregister_by_uuid(uuid)`:
+    Unregister a handler by UUID.<br><br>
+- `unregister_handler(func, *args, **kwargs)`:
+    Unregister a handler by function reference and optional args/kwargs.<br><br>
+- `call_handlers()`:
+    Manually call all registered handlers.<br><br>
+
+### `register_exit_handler`
+
+Decorator for registering a function as an exit handler.
+
+#### Parameters:
+
+- `*handler_args`:
+    Optional arguments to pass to the handler function.<br><br>
+- `**handler_kwargs`:
+    Optional keyword arguments to pass to the handler function.<br><br>
+
+
+## Running Tests
+
+Run the test suite with `pytest` from the project root:
+
+```bash
+pytest
+```
+
+## Contributing
+
+Contributions are welcome! Here's how you can get started:
+  1) Fork the repository.<br><br>
+  2) Create a new branch (`git checkout -b feature-branch`).<br><br>
+  3) Make your changes.<br><br>
+  4) Commit your changes (`git commit -m 'Add feature'`).<br><br>
+  5) Push your changes to your fork (`git push origin feature-branch`).<br><br>
+  6) Create a pull request.<br><br>
+
+
+## License
+
+This project is released under the [MIT License](LICENSE.md).
+

easy_exit_calls-1.0.0/README.md

@@ -0,0 +1,144 @@
+# easy-exit-calls
+
+A Python library for managing exit handlers with enhanced features like decorators, UUID tracking, and LIFO execution.
+
+## Features
+
+- **Decorator Support**: Easily register functions as exit handlers using a decorator.
+- **LIFO Execution**: Handlers execute in Last-In-First-Out order by default (configurable).
+- **UUID Tracking**: Each handler is assigned a unique UUID for easy management.
+- **Thread Safety**: Uses threading locks to ensure safe registration/unregistration.
+- **Detailed Logging**: Integrated with a logging engine for debugging and tracking.
+- **Error Handling**: Captures exceptions during exit and logs them with tracebacks.
+
+## Installation
+
+This project requires **Python 3.12** or later.
+
+```bash
+pip install easy-exit-calls
+```
+
+## Usage
+
+### Basic Decorator Usage
+
+```python
+from easy_exit_calls import register_exit_handler
+
+@register_exit_handler
+def cleanup():
+    print("Cleaning up resources...")
+
+# Exiting the program will automatically trigger this handler.
+```
+
+### Decorator with Arguments
+
+```python
+from easy_exit_calls import register_exit_handler
+
+@register_exit_handler("arg1", key="value")
+def cleanup_with_args(arg1, key=None):
+    print(f"Cleaning up with {arg1} and {key}")
+
+# Handler called with provided args/kwargs on exit.
+```
+
+### Manual Registration
+
+```python
+from easy_exit_calls import ExitCallHandler
+
+def manual_cleanup():
+    print("Manual cleanup")
+
+ExitCallHandler().register_handler(manual_cleanup)
+
+# Exiting the program will manually trigger this handler.
+```
+
+### Unregistering Handlers
+
+```python 
+from easy_exit_calls import ExitCallHandler
+
+def cleanup():
+    print("Cleaning up resources...")
+
+handler_uuid = ExitCallHandler().register_handler(cleanup)
+
+# Unregister the handler by UUID.
+ExitCallHandler().unregister_by_uuid(handler_uuid)
+```
+
+### Execution Order
+
+```python
+from easy_exit_calls import register_exit_handler
+
+@register_exit_handler
+def first_handler():
+    print("First handler")
+
+@register_exit_handler
+def second_handler():
+    print("Second handler")
+
+# Output on exit:
+# Second handler
+# First handler
+# (LIFO execution order)
+```
+
+## API Reference
+
+### `ExitCallHandler`
+
+Singleton class managing exit handlers.
+
+#### Methods:
+
+- `register_handler(func: Callable, *args, **kwargs) -> str`:
+    Register a new exit handler with optional args/kwargs. Returns the UUID of the handler.<br><br>
+- `unregister_by_uuid(uuid)`:
+    Unregister a handler by UUID.<br><br>
+- `unregister_handler(func, *args, **kwargs)`:
+    Unregister a handler by function reference and optional args/kwargs.<br><br>
+- `call_handlers()`:
+    Manually call all registered handlers.<br><br>
+
+### `register_exit_handler`
+
+Decorator for registering a function as an exit handler.
+
+#### Parameters:
+
+- `*handler_args`:
+    Optional arguments to pass to the handler function.<br><br>
+- `**handler_kwargs`:
+    Optional keyword arguments to pass to the handler function.<br><br>
+
+
+## Running Tests
+
+Run the test suite with `pytest` from the project root:
+
+```bash
+pytest
+```
+
+## Contributing
+
+Contributions are welcome! Here's how you can get started:
+  1) Fork the repository.<br><br>
+  2) Create a new branch (`git checkout -b feature-branch`).<br><br>
+  3) Make your changes.<br><br>
+  4) Commit your changes (`git commit -m 'Add feature'`).<br><br>
+  5) Push your changes to your fork (`git push origin feature-branch`).<br><br>
+  6) Create a pull request.<br><br>
+
+
+## License
+
+This project is released under the [MIT License](LICENSE.md).

easy_exit_calls-1.0.0/easy_exit_calls/__init__.py

@@ -0,0 +1,33 @@
+"""
+This module provides a simple way to register exit handlers for your Python applications.
+
+The main class is ExitCallHandler, which is used to register and manage exit handlers.
+
+Included is a decorator, register_exit_handler, which can be used to register an exit handler for a function. This is a
+convenient way to register exit handlers for functions.
+
+Example:
+    >>> from easy_exit_calls import register_exit_handler, ExitCallHandler
+    >>>
+    >>> @register_exit_handler()
+    ... def my_exit_handler():
+    ...     print("Exiting...")
+    ...
+    >>> # Create an instance of ExitCallHandler
+    >>> eh = ExitCallHandler()
+    >>>
+    >>> # Register an exit handler
+    >>> eh.register_handler(my_exit_handler)
+    >>>
+    >>> # Call the exit handlers
+    >>> eh.call_handlers()
+    Exiting...
+"""
+
+from easy_exit_calls.classes import ExitCallHandler
+from easy_exit_calls.decorator import register_exit_handler
+
+__all__ = [
+    'ExitCallHandler',
+    'register_exit_handler',
+]

easy_exit_calls-1.0.0/easy_exit_calls/classes.py

@@ -0,0 +1,479 @@
+import atexit
+import threading
+import traceback
+from uuid import uuid4, UUID
+from easy_exit_calls.log_engine import ROOT_LOGGER, Loggable
+from easy_exit_calls.helpers.handler_list import HandlerList
+
+MOD_LOGGER = ROOT_LOGGER.get_child('components.exit_calls')
+
+
+class ExitCallHandler(Loggable):
+    """
+    A singleton class for managing exit handlers that are executed when the program terminates.
+
+    This class allows registration, execution, and removal of exit handlers. Handlers can be executed in
+    **either** LIFO (Last-In-First-Out) or FIFO (First-In-First-Out) order. It integrates with Python's `atexit`
+    module to ensure handlers are executed upon normal program termination.
+
+    Properties:
+        fifo (bool):
+            If True, handlers execute in FIFO order; otherwise, LIFO.
+
+        handler_keys (list):
+            A list of unique keys representing registered handlers.
+
+        handlers (list):
+            A list of registered handlers.
+
+        handler_uuids (list):
+            A list of UUIDs for registered handlers.
+
+        lifo (bool):
+            Indicates whether handlers execute in LIFO order.
+
+        registered_with_atexit (bool):
+            Indicates whether the handler is registered with `atexit`.
+
+    Methods:
+        call_handlers():
+            Executes all registered exit handlers.
+
+        clear_handlers():
+            Removes all registered exit handlers.
+
+        find_handler_by_uuid(uuid):
+            Retrieves a handler by its UUID.
+
+        function_registered(func):
+            Checks if a function is already registered as an exit handler.
+
+        has_key(key):
+            Determines if a handler with a given key exists.
+
+        has_uuid(uuid):
+            Determines if a handler with a given UUID exists.
+
+        register_handler(func, *args, return_func=False, **kwargs):
+            Registers a function as an exit handler.
+
+        register_self_with_atexit():
+            Registers the handler with Python’s `atexit` module.
+
+        unregister_all():
+            Unregisters all exit handlers.
+
+        unregister_all_with_name(name):
+            Unregisters all handlers with a specific name.
+
+        unregister_by_uuid(uuid):
+            Removes a registered handler by UUID.
+
+        unregister_handler(func, *args, **kwargs):
+            Unregisters a specific exit handler by function reference and arguments.
+
+        unregister_self_with_atexit():
+            Removes this handler from Python’s `atexit` module.
+
+    Example Usage:
+        ```python
+        handler = ExitCallHandler()
+
+        def cleanup():
+            print("Cleaning up!")
+
+        handler.register_handler(cleanup)
+        ```
+    """
+    _instance = None
+
+    def __new__(cls, *args, **kwargs):
+        if cls._instance is None:
+            cls._instance = super(ExitCallHandler, cls).__new__(cls, *args, **kwargs)
+            # Use a list to store handler dictionaries
+            cls._instance._handlers = HandlerList(
+                on_empty=cls._instance.unregister_self_with_atexit,
+                on_non_empty=cls._instance.register_self_with_atexit
+            )
+
+            cls._instance._lifo = True
+            cls._instance._lock = threading.Lock()
+
+        return cls._instance
+
+    def __init__(self, fifo=False):
+
+        self.__registered_with_atexit = False
+
+        if isinstance(fifo, bool) and fifo:
+            self._lifo = False
+
+
+        if not hasattr(self, '_initialized'):
+            super().__init__(MOD_LOGGER)
+            self._initialized = True
+
+    def _check_for_key(self, key):
+        """
+        Checks if a key already exists in the registered handlers.
+
+        Parameters:
+            key (tuple):
+            A tuple containing the function, arguments, and keyword arguments of the handler.
+
+        Returns:
+            bool:
+                True if the key exists, False otherwise.
+        """
+        for entry in self.handlers:
+            existing_key = self._get_key(entry['func'], entry['args'], entry['kwargs'])
+            if existing_key == key:
+                return True
+
+    def _cleanup(self):
+        """
+        Executes all registered exit handlers.
+        """
+        log = self.method_logger
+
+        handlers = reversed(self._handlers) if self.lifo else self._handlers
+
+        for entry in list(handlers):
+            name = ''
+            if 'handler_info' in entry:
+                info = entry['handler_info']
+                # Build a name based on module and function name
+                name = f"{info.get('module', '')}."
+                if info.get('name'):
+                    name += info['name']
+                else:
+                    name = "Unknown"
+
+            log.debug(f"Running exit handler {name}")
+
+            func = entry['func']
+            args = entry['args']
+            kwargs = entry['kwargs']
+
+            log.debug(f"Running exit handler {name} | Function: {func} | Args: {args} | Kwargs: {kwargs}")
+
+            try:
+                func(*args, **kwargs)
+            except Exception as e:
+                log.error(f"Error while running exit handler {func}: {e}")
+                log.debug(f"Traceback:\n{traceback.format_exc()}")
+                raise e from e
+
+    def _get_key(self, func: callable, args: tuple, kwargs: dict):
+        """
+        Create a unique key from a function, its arguments, and keyword arguments.
+
+        Parameters:
+            func (callable):
+                The function to be called.
+
+            args (tuple):
+                Positional arguments to be passed to the function.
+
+            kwargs (dict):
+                Keyword arguments to be passed to the function.
+
+        Returns:
+            tuple:
+                A tuple containing the function, arguments, and keyword arguments.
+        """
+        return (func, args, frozenset(kwargs.items()))
+
+    @property
+    def fifo(self) -> bool:
+        """
+        Get the FIFO mode for the handler.
+
+        Returns:
+            bool:
+                True if FIFO mode is enabled, False otherwise.
+
+        """
+        return not self._lifo
+
+    @fifo.setter
+    def fifo(self, new: bool) -> None:
+        """
+        Set the FIFO mode for the handler.
+
+        Parameters:
+            new (bool):
+                True to set FIFO mode, False to set LIFO mode.
+
+        Returns:
+            None
+
+        Raises:
+            TypeError:
+                If the new value is not a boolean.
+        """
+        if not isinstance(new, bool):
+            raise TypeError("fifo must be a boolean")
+
+        self._lifo = not new
+
+    @property
+    def handler_keys(self) -> list[tuple]:
+        """
+        Returns a list of tuples containing the keys for all registered handlers.
+
+        Returns:
+            list[tuple]:
+                A list of tuples containing the keys for all registered handlers;
+                each tuple contains the function, arguments, and keyword arguments.
+        """
+        return [self._get_key(entry['func'], entry['args'], entry['kwargs']) for entry in self.handlers]
+
+    @property
+    def handlers(self) -> HandlerList:
+        """
+        Returns a list of dictionaries representing the registered exit handlers.
+
+        Returns:
+            HandlerList:
+                A list of dictionaries representing the registered exit handlers.
+        """
+        return self._handlers
+
+    @property
+    def handler_uuids(self) -> list[UUID]:
+        """
+        Returns a list of UUIDs for all registered handlers.
+
+        Returns:
+            list[UUID]:
+                A list of UUIDs for all registered handlers.
+        """
+        return [entry.get('uuid') for entry in self.handlers]
+
+    @property
+    def lifo(self):
+        """
+        Get the LIFO status of the exit call handler.
+
+        Returns:
+            bool: True if the exit call handler is in LIFO mode, False otherwise.
+        """
+        return self._lifo
+
+    @lifo.setter
+    def lifo(self, new) -> None:
+        """
+        Set the LIFO status of the exit call handler.
+
+        If the value is True, handlers will execute in LIFO order. If False, handlers will execute in FIFO order.
+
+        Parameters:
+            new (bool):
+                The new LIFO status to set.
+
+        Returns:
+            None
+        """
+        if not isinstance(new,bool):
+            raise ValueError("lifo must be a boolean")
+
+        self._lifo = new
+
+    @property
+    def registered_with_atexit(self) -> bool:
+        """
+        Indicates whether the handler is registered with the `atexit` module.
+
+        Returns:
+            bool:
+                True if the handler is registered with `atexit`, False otherwise.
+        """
+        return self.__registered_with_atexit
+
+    def call_handlers(self) -> None:
+        """
+        Calls all registered exit handlers.
+
+        Returns:
+            None
+        """
+        log = self.method_logger
+
+        if not self.handlers:
+            log.warning("No exit handlers registered")
+            return
+
+        log.debug("Calling exit handlers")
+        self._cleanup()
+
+    def clear_handlers(self) -> None:
+        """
+        Removes all registered exit handlers.
+
+        Note:
+            Once all handlers are removed, the handler unregisters itself from the `atexit` module.
+
+        Returns:
+            None
+        """
+        log = self.method_logger
+
+        log.debug("Clearing all exit handlers")
+        self._handlers.clear()
+        log.debug("All exit handlers cleared")
+
+    def find_handler_by_uuid(self, uuid):
+        log = self.method_logger
+
+        if not isinstance(uuid, (UUID, str)):
+            log.error("UUID must be a UUID object or a string")
+            raise ValueError("UUID must be a UUID object or a string")
+
+        if isinstance(uuid, str):
+            uuid = UUID(uuid)
+
+        for entry in self.handlers:
+            if entry.get('uuid') and entry['uuid'] == uuid:
+                return entry
+
+    def function_registered(self, func):
+        return any([entry['func'] == func for entry in self.handlers])
+
+    def has_key(self, key):
+        return key in self.handler_keys
+
+    def has_uuid(self, uuid):
+        return any([entry.get('uuid') == uuid for entry in self.handlers])
+
+    def register_handler(self, func, *args, return_func=False, **kwargs):
+        log = self.method_logger
+
+        log.debug(f"Registering exit handler {func} | Args: {args} | Kwargs: {kwargs}")
+
+        # Check if the function is already registered
+        log.debug(f"Checking if handler {func} is already registered")
+
+        # Create a unique key from the function, its args, and kwargs
+        new_key = self._get_key(func, args, kwargs)
+
+        log.debug(f"New key: {new_key}")
+
+        if self.has_key(new_key):
+            log.warning(f"Handler {func} is already registered")
+            return func
+
+
+        info = {
+            'handler_info': {
+                'module': func.__module__,
+                'name': func.__name__,
+            },
+            'func': func,
+            'args': args,
+            'kwargs': kwargs,
+            'uuid': uuid4()
+        }
+
+        with self._lock:
+            # Otherwise, add the handler
+            self.handlers.append(info)
+            log.debug(f"Handler {func} registered successfully")
+
+        return info['uuid']
+
+    def register_self_with_atexit(self):
+        log = self.method_logger
+
+        log.debug('Checking if registered with atexit already...')
+
+        if not self.registered_with_atexit:
+            log.debug('Registering with atexit...')
+            atexit.register(self._cleanup)
+            self.__registered_with_atexit = True
+
+    def unregister_all(self):
+        self.clear_handlers()
+
+    def unregister_all_with_name(self, name: str) -> None:
+        """
+        Unregister all exit handlers with a specific name.
+
+        Parameters:
+            name (str):
+                The name of the exit handlers to unregister.
+
+        Returns:
+            None
+        """
+        log = self.method_logger
+
+        log.debug(f"Unregistering all exit handlers with name {name}")
+
+        to_remove = []
+        for entry in list(self._handlers):
+            info = entry.get('handler_info', {})
+            if info.get('name') == name:
+                log.debug(
+                    f"Removing handler {info.get('module', '')}.{info.get('name')}"
+                )
+                to_remove.append(entry)
+
+        for entry in to_remove:
+            self._handlers.remove(entry)
+
+        log.debug(f"All handlers with name {name} unregistered successfully")
+
+    def unregister_by_uuid(self, uuid):
+        log = self.method_logger
+
+        log.debug(f"Unregistering exit handler with UUID {uuid}")
+
+        handler = self.find_handler_by_uuid(uuid)
+
+        if handler:
+            log.debug(f"Removing handler {handler['func']}")
+            self._handlers.remove(handler)
+            log.debug(f"Handler with UUID {uuid} unregistered successfully")
+            return True
+
+        log.warning(f"Handler with UUID {uuid} not found")
+
+        return False
+
+    def unregister_handler(self, func, *args, **kwargs):
+        log = self.method_logger
+
+        log.debug(f"Unregistering exit handler {func} | Args: {args} | Kwargs: {kwargs}")
+
+        # Create a unique key from the function, its args, and kwargs
+        key = (func, args, frozenset(kwargs.items()))
+
+        log.debug(f"Key: {key}")
+
+        for entry in self._handlers:
+            existing_key = (entry['func'], entry['args'], frozenset(entry['kwargs'].items()))
+            if existing_key == key:
+                log.debug(f"Removing handler {func}")
+                self._handlers.remove(entry)
+                log.debug(f"Handler {func} unregistered successfully")
+                return func
+
+        log.warning(f"Handler {func} not found")
+        return None
+
+    def unregister_self_with_atexit(self):
+        log = self.method_logger
+
+        log.debug('Checking if registered with atexit already...')
+
+        if self.registered_with_atexit:
+            log.debug('Unregistering with atexit...')
+            atexit.unregister(self._cleanup)
+            self.__registered_with_atexit = False
+            return True
+        else:
+            log.warning('ExitCallHandler is not registered with atexit!')
+
+        return False
+

easy_exit_calls-1.0.0/easy_exit_calls/common/__init__.py

@@ -0,0 +1,5 @@
+"""Common utilities and metadata for :mod:`easy_exit_calls`."""
+
+from . import meta
+
+__all__ = ["meta"]

easy_exit_calls-1.0.0/easy_exit_calls/common/meta/__init__.py

@@ -0,0 +1,9 @@
+from easy_exit_calls.common.meta.author import AUTHOR, SOFTWARE_ORG_URLS
+from easy_exit_calls.common.meta.package import PACKAGE_NAME, VERSION
+
+__all__ = [
+    'AUTHOR',
+    'PACKAGE_NAME',
+    'SOFTWARE_ORG_URLS',
+    'VERSION',
+]

easy_exit_calls-1.0.0/easy_exit_calls/common/meta/author/__init__.py

@@ -0,0 +1,10 @@
+from easy_exit_calls.common.meta.author.software_org import SOFTWARE_ORG_NAME, SOFTWARE_ORG_URLS
+
+
+AUTHOR = SOFTWARE_ORG_NAME
+
+
+__all__ = [
+    'AUTHOR',
+    'SOFTWARE_ORG_URLS'
+]

easy_exit_calls-1.0.0/easy_exit_calls/common/meta/author/contributors/CONTRIB_TEMPLATE.json

@@ -0,0 +1,52 @@
+{
+  "contributor": {
+    "preferred_name": "Example S. Developer",
+    "email_addresses": [
+      {
+        "user_handle": "example.s.developer",
+        "domain": "example.com"
+      }
+    ],
+    "code_social": {
+      "github": [
+        {
+          "user_handle": "example_coder",
+          "on_behalf_of": [
+            {
+              "group_name": "Software Developer Inc.",
+              "group_handle": "software_developer_inc"
+            }
+          ]
+        }
+      ],
+      "gitlab": [
+        {
+          "user_handle": "example_dev",
+          "on_behalf_of": []
+        }
+      ],
+      "bitbucket": [
+        {
+          "user_handle": "example_bb",
+          "on_behalf_of": []
+        }
+      ]
+    },
+    "roles": [
+      "Developer",
+      "Maintainer",
+      "Contributor"
+    ],
+    "contributions": {
+      "code": true,
+      "documentation": true,
+      "design": false,
+      "testing": true,
+      "bug_reports": true,
+      "community_support": false
+    },
+    "preferred_contact_method": "email",
+    "timezone": "America/Chicago",
+    "additional_notes": "Happy to contribute to open-source projects!"
+  }
+}

easy_exit_calls-1.0.0/easy_exit_calls/common/meta/author/contributors/__init__.py

@@ -0,0 +1,2 @@
+"""Information about project contributors."""
+

easy_exit_calls-1.0.0/easy_exit_calls/common/meta/author/main/__init__.py

@@ -0,0 +1,2 @@
+"""Primary author information for :mod:`easy_exit_calls`."""
+

easy_exit_calls-1.0.0/easy_exit_calls/common/meta/author/software_org/__init__.py

@@ -0,0 +1,8 @@
+SOFTWARE_ORG_NAME = 'Inspyre-Softworks'
+
+SOFTWARE_ORG_URLS = {
+    'github':  'https://github.com/Inspyre-Softworks',
+    'website': 'https://inspyre.tech',
+    'RTFD':    'https://inspyre-softworks.readthedocs.io',
+}
+

easy_exit_calls-1.0.0/easy_exit_calls/common/meta/package/__init__.py

@@ -0,0 +1,7 @@
+"""Package metadata for :mod:`easy_exit_calls`."""
+
+from .version import VERSION
+
+PACKAGE_NAME = "easy_exit_calls"
+
+__all__ = ["PACKAGE_NAME", "VERSION"]

easy_exit_calls-1.0.0/easy_exit_calls/common/meta/package/version/__VERSION__

@@ -0,0 +1,2 @@
+1.0.0
+

easy_exit_calls-1.0.0/easy_exit_calls/common/meta/package/version/__init__.py

@@ -0,0 +1,13 @@
+from inspyre_toolbox.ver_man import PyPiVersionInfo, VersionParser
+from inspyre_toolbox.ver_man.helpers import read_version_file
+from pathlib import Path
+
+
+CWD = Path(__file__).parent
+
+
+VERSION_FILE_PATH = CWD / '__VERSION__'
+
+VERSION_PARSER = VersionParser(read_version_file(VERSION_FILE_PATH))
+
+VERSION = VERSION_PARSER.version_str

easy_exit_calls-1.0.0/easy_exit_calls/decorator.py

@@ -0,0 +1,50 @@
+"""
+This module contains the decorator function to register an exit handler with the ExitCallHandler.
+
+The decorator function is register_exit_handler, which can be used to register an exit handler for a function. This is a
+convenient way to register exit handlers for functions.
+
+Example:
+    >>> from easy_exit_calls import register_exit_handler
+    >>>
+    >>> @register_exit_handler()
+    ... def my_exit_handler():
+    ...     print("Exiting...")
+    ...
+    >>> # Call the exit handlers
+    >>> # Press Ctrl+D
+    Exiting...
+
+Since:
+    1.0.0
+"""
+
+
+def register_exit_handler(*args, **kwargs):
+    """
+    Register an exit handler with the ExitCallHandler.
+
+    Parameters:
+        *handler_args:
+            Positional arguments to pass to the handler function.
+
+        **handler_kwargs:
+            Keyword arguments to pass to the handler function.
+    """
+    from easy_exit_calls import ExitCallHandler
+
+    # Case 1: Decorator used without parentheses (@register_exit_handler)
+    if len(args) == 1 and callable(args[0]):
+        func = args[0]  # Get the function being decorated
+        ExitCallHandler().register_handler(func)  # Register with no arguments
+        return func
+
+    # Case 2: Decorator used with arguments (@register_exit_handler(*args, **kwargs))
+    def decorator(func):
+        ExitCallHandler().register_handler(func, *args, **kwargs)
+        return func
+
+    return decorator
+
+
+__all__ = ['register_exit_handler']

easy_exit_calls-1.0.0/easy_exit_calls/example_helpers.py

@@ -0,0 +1,71 @@
+from os import system
+from os import name
+import time
+import sys
+
+
+def clear_screen() -> None:
+    """
+    Clear the screen.
+
+    This function will clear the screen of the terminal or command prompt. It will use the 'cls' command on Windows and
+    the 'clear' command on Unix-based systems.
+
+    Returns:
+         None
+    """
+    if name == 'nt':
+        system('cls')
+    else:
+        system('clear')
+
+    return
+
+
+# Create a function that can print 'Exiting...' to the screen where the ellipsis is animated.
+def print_exit_message(
+        max_dots: int   = 3,
+        interval: float = 0.5,
+        run_time: float = 5.0,
+) -> None:
+    """
+    Print an animated 'Exiting...' message to the screen.
+
+    This function will print the message 'Exiting...' to the screen with an animated ellipsis. The ellipsis will
+    animate by adding a period to the end of the message every 0.5 seconds. The message will be printed to the screen
+    until the function is interrupted by the user.
+
+    Parameters:
+        max_dots:
+            The maximum number of dots to display in the animated ellipsis. Defaults to 3.
+
+        interval:
+            The interval between each dot addition in seconds. Defaults to 0.5.
+
+        run_time:
+            The maximum amount of time to run the function in seconds. Defaults to 5.0.
+
+    Returns:
+        None
+    """
+    start_time = time.time()
+    dots = 0
+    while time.time() - start_time < run_time:
+        # Cycle through 1 to max_dots dots.
+        dots = (dots % max_dots) + 1
+        # Build the display string with padding to avoid leftover characters.
+        display_str = f'\rExiting{"." * dots}{" " * (max_dots - dots)}'
+        sys.stdout.write(display_str)
+        sys.stdout.flush()
+        time.sleep(interval)
+    # Final display to ensure the full ellipsis is visible.
+    sys.stdout.write(f'\rExiting{"." * max_dots}\n')
+    sys.stdout.flush()
+
+    return
+
+
+def simple_example_handler() -> None:
+    print_exit_message()
+
+    return

easy_exit_calls-1.0.0/easy_exit_calls/helpers/__init__.py

@@ -0,0 +1,6 @@
+"""Helper utilities used by :mod:`easy_exit_calls`."""
+
+from .decorator import register_exit_handler
+from .handler_list import HandlerList
+
+__all__ = ["register_exit_handler", "HandlerList"]

easy_exit_calls-1.0.0/easy_exit_calls/helpers/decorator.py

@@ -0,0 +1,50 @@
+"""
+This module contains the decorator function to register an exit handler with the ExitCallHandler.
+
+The decorator function is register_exit_handler, which can be used to register an exit handler for a function. This is a
+convenient way to register exit handlers for functions.
+
+Example:
+    >>> from easy_exit_calls import register_exit_handler
+    >>>
+    >>> @register_exit_handler()
+    ... def my_exit_handler():
+    ...     print("Exiting...")
+    ...
+    >>> # Call the exit handlers
+    >>> # Press Ctrl+D
+    Exiting...
+
+Since:
+    1.0.0
+"""
+
+
+def register_exit_handler(*args, **kwargs):
+    """
+    Register an exit handler with the ExitCallHandler.
+
+    Parameters:
+        *handler_args:
+            Positional arguments to pass to the handler function.
+
+        **handler_kwargs:
+            Keyword arguments to pass to the handler function.
+    """
+    from easy_exit_calls import ExitCallHandler
+
+    # Case 1: Decorator used without parentheses (@register_exit_handler)
+    if len(args) == 1 and callable(args[0]):
+        func = args[0]  # Get the function being decorated
+        ExitCallHandler().register_handler(func)  # Register with no arguments
+        return func
+
+    # Case 2: Decorator used with arguments (@register_exit_handler(*args, **kwargs))
+    def decorator(func):
+        ExitCallHandler().register_handler(func, *args, **kwargs)
+        return func
+
+    return decorator
+
+
+__all__ = ['register_exit_handler']

easy_exit_calls-1.0.0/easy_exit_calls/helpers/handler_list.py

@@ -0,0 +1,123 @@
+from collections import UserList
+from typing import Optional
+
+
+class HandlerList(UserList):
+    """
+    A list-like object that triggers a callback when the list either becomes empty or non-empty.
+    """
+    def __init__(self, *args, on_empty=None, on_non_empty=None):
+        super().__init__(*args)
+        self.__on_empty = on_empty if callable(on_empty) else None
+        self.__on_non_empty = on_non_empty if callable(on_non_empty) else None
+        self.__was_empty = not bool(self.data)
+
+    def _check_state(self) -> None:
+        """
+        Check the current state of the list and trigger the appropriate callback.
+
+        Returns:
+             None
+        """
+        is_empty = not bool(self.data)
+
+        if is_empty and not self.was_empty:
+            self.on_empty()
+        elif not is_empty and self.was_empty:
+            self.on_non_empty()
+
+        self.__was_empty = is_empty
+
+    @property
+    def on_empty(self) -> Optional[callable]:
+        return self.__on_empty
+
+    @property
+    def on_non_empty(self) -> Optional[callable]:
+        return self.__on_non_empty
+
+    @property
+    def was_empty(self) -> bool:
+        return self.__was_empty
+
+    def append(self, item) -> None:
+        """
+        Append an item to the list and check the state.
+
+        Parameters:
+            item:
+                The item to be appended.
+
+        Returns:
+            None
+        """
+        super().append(item)
+        self._check_state()
+
+    def clear(self) -> None:
+        """
+        Clear the list and check the state.
+
+        Returns:
+            None
+        """
+        super().clear()
+        self._check_state()
+
+    def extend(self, other: list) -> None:
+        """
+        Extend the list with another iterable and check the state.
+
+        Parameters:
+            other:
+                The iterable to extend the list with.
+
+        Returns:
+            None
+        """
+        super().extend(other)
+        self._check_state()
+
+    def insert(self, index: int, item: any) -> None:
+        """
+        Insert an item at the specified index and check the state.
+
+        Parameters:
+            index (int):
+                The index at which to insert the item.
+            item (any):
+                The item to be inserted.
+
+        Returns:
+            None
+        """
+        super().insert(index, item)
+        self._check_state()
+
+    def pop(self, index: int = -1) -> any:
+        """
+        Remove and return the item at the specified index and check the state.
+
+        Parameters:
+            index (int, optional):
+                The index of the item to be removed. Defaults to the last item.
+        """
+        item = super().pop(index)
+        self._check_state()
+
+        return item
+
+    def remove(self, item: any) -> None:
+        """
+        Remove the first occurrence of the specified item and check the state.
+
+        Parameters:
+            item (any):
+                The item to be removed.
+
+        Returns:
+            None
+        """
+        super().remove(item)
+        self._check_state()
+

easy_exit_calls-1.0.0/easy_exit_calls/log_engine.py

@@ -0,0 +1,12 @@
+from inspy_logger import InspyLogger, Loggable
+
+
+ROOT_LOGGER = InspyLogger('EasyExitCalls', console_level='info', no_file_logging=True)
+
+LOG_LEVELS = ROOT_LOGGER.LEVELS
+
+__all__ = [
+    'Loggable',
+    'LOG_LEVELS',
+    'ROOT_LOGGER'
+]

easy_exit_calls-1.0.0/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "easy-exit-calls"
+version = "1.0.0"
+description = "A Python library for managing exit handlers with enhanced features like decorators, UUID tracking, and LIFO execution."
+authors = [
+    {name = "Taylor B.",email = "tayjaybabee@gmail.com"}
+]
+readme = "README.md"
+requires-python = ">=3.12,<4.0"
+dependencies = [
+    "inspyre-toolbox (>=1.5.3,<2.0.0)",
+    "inspy-logger (==3.2.3)",
+    "pytz (>=2025.1,<2026.0)"
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+    "Typing :: Typed"
+]
+
+[[tool.poetry.source]]
+name = "test-pypi"
+url = "https://test.pypi.org/simple/"
+priority = "explicit"
+
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"