# -*- coding: utf-8 -*-
'''
Module
factory_class.py
Copyright
Copyright (C) 2017 - 2026 Vladimir Roncevic <elektron.ronca@gmail.com>
ats_utilities is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
ats_utilities is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along
with this program. If not, see <http://www.gnu.org/licenses/>.
Info
Factory universally injects instances, gets private instances and setup instance string representation.
Encapsulates core utilities to minimize constructor overhead.
Provides a simple factory mechanism for dependency injection.
'''
from typing import Any
from collections.abc import Callable
from functools import wraps
from ats_utilities.exceptions.ats_value_error import ATSValueError
__author__: str = 'Vladimir Roncevic'
__copyright__: str = '(C) 2026, https://vroncevic.github.io/ats_utilities'
__credits__: list[str] = ['Vladimir Roncevic', 'Python Software Foundation']
__license__: str = 'https://github.com/vroncevic/ats_utilities/blob/dev/LICENSE'
__version__: str = '3.3.8'
__maintainer__: str = 'Vladimir Roncevic'
__email__: str = 'elektron.ronca@gmail.com'
__status__: str = 'Updated'
[docs]
def inject(instance: Any, *dependencies: tuple[str, Any, Any, str | list[str] | tuple[str, ...] | None]) -> None:
'''
Universally injects system or domain components into a class instance.
Adheres to SOLID principles by avoiding hardcoded component names or classes.
Dynamically handles multi-dependency relationship chains between sequence steps.
:param instance: The object instance (self) to inject attributes into.
:type instance: <Any>
:param dependencies: Variadic sequence of tuples containing injection rules.
Format: ('attr_name', value, fallback, 'depends_on_attr')
The 'depends_on_attr' can be a string, list, or tuple.
:type dependencies: <tuple[str, Any, Any, str | list[str] | tuple[str, ...] | None]>
:exceptions: None.
'''
prefix = '_'
for tuple_data in dependencies:
attr_name: str = tuple_data[0]
passed_val: Any = tuple_data[1]
fallback: Any = tuple_data[2]
depends_on: str | list[str] | tuple[str, ...] | None = tuple_data[3] if len(tuple_data) > 3 else None
full_attr_name = f'{prefix}{attr_name}'
if passed_val is not None:
resolved_val = passed_val
else:
if isinstance(fallback, type):
if depends_on:
if isinstance(depends_on, str):
dep_list = [depends_on]
else:
dep_list = list(depends_on)
factory_kwargs = {}
for dep in dep_list:
target_dep_name = f'{prefix}{dep}'
dependency_obj = instance.__dict__.get(target_dep_name)
if dependency_obj is not None:
factory_kwargs[dep] = dependency_obj
resolved_val = fallback(**factory_kwargs)
else:
resolved_val = fallback()
else:
resolved_val = fallback
setattr(instance, full_attr_name, resolved_val)
[docs]
def get_private_attr(instance: Any, attr_name: str) -> Any:
'''
Dynamically retrieves a private attribute from an instance.
:param instance: The class instance (self) containing the attribute.
:type instance: <Any>
:param attr_name: The target private attribute name (e.g., '_checker').
:type attr_name: <str>
:return: The resolved attribute value.
:rtype: <Any>
:exceptions: AttributeError.
'''
clean_attr = attr_name.lstrip('_')
return getattr(instance, f'_{clean_attr}')
[docs]
def require_attributes(*attr_names: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
'''
Checks if instance attribute is defined and has value or not.
In case attribute value is not defined set default value to None.
In case attribute value is not defined and not empty, raise ATSValueError exception.
:param attr_names: Tuple of attribute names to check.
:type attr_names: <tuple[str, ...]>
:return: Decorated function.
:rtype: <Callable[..., Any]>
:exceptions: ATSValueError.
'''
def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
@wraps(func)
def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
for attr in attr_names:
# In case attribute value is not defined set default value to None
value = getattr(self, attr, None)
if not value:
raise ATSValueError(f"Missing or empty attribute: '{attr}'")
return func(self, *args, **kwargs)
return wrapper
return decorator
[docs]
def get_class_name(instance: Any) -> str:
'''
Returns the class name of an instance.
:param instance: The class instance.
:type instance: <Any>
:return: The class name in string format.
:rtype: <str>
:exceptions: None.
'''
return instance.__class__.__name__