dev4py.utils.objects

  1"""
  2The `objects` module provides a set of utility functions to simplify objects/variables operations or checks
  3"""
  4
  5# Copyright 2022 the original author or authors (i.e.: St4rG00se for Dev4py).
  6#
  7# Licensed under the Apache License, Version 2.0 (the "License");
  8# you may not use this file except in compliance with the License.
  9# You may obtain a copy of the License at
 10#
 11#      https://www.apache.org/licenses/LICENSE-2.0
 12#
 13# Unless required by applicable law or agreed to in writing, software
 14# distributed under the License is distributed on an "AS IS" BASIS,
 15# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 16# See the License for the specific language governing permissions and
 17# limitations under the License.
 18
 19from typing import Any, Optional, cast, Awaitable
 20
 21from dev4py.utils.awaitables import is_awaitable
 22from dev4py.utils.types import Supplier, T, SyncOrAsync
 23
 24
 25def is_none(obj: Any) -> bool:
 26    """
 27    Checks if the given object is None
 28
 29    Args:
 30        obj: The object to check
 31
 32    Returns:
 33        object: True if obj is None, False otherwise
 34    """
 35    return obj is None
 36
 37
 38def non_none(obj: Any) -> bool:
 39    """
 40    Checks if the given object is not None
 41
 42    Args:
 43        obj: The object to check
 44
 45    Returns:
 46        object: True if obj is NOT None, False otherwise
 47    """
 48    return obj is not None
 49
 50
 51def require_non_none(obj: Optional[T], message: str = "None object error") -> T:
 52    """
 53    Checks if the given object is not None or raises an error
 54
 55    Args:
 56        obj: The object to check
 57        message: The error message is case of obj is None
 58
 59    Returns:
 60        object: obj if obj is not None
 61
 62    Raises:
 63        TypeError: Raises a TypeError if obj is None
 64    """
 65    if is_none(obj):
 66        raise TypeError(message)
 67    return cast(T, obj)
 68
 69
 70def require_non_none_else(obj: Optional[T], default: T) -> T:
 71    """
 72    Checks if the given object is not None and returns it or returns the default one
 73
 74    Args:
 75        obj: The object to check and return
 76        default: The default object to return if obj is None
 77
 78    Returns:
 79        object: obj if not None, default_obj otherwise
 80
 81    Raises:
 82        TypeError: Raises a TypeError if obj and default_obj are None
 83    """
 84    return cast(T, obj) if non_none(obj) else require_non_none(default)
 85
 86
 87def require_non_none_else_get(obj: Optional[T], supplier: Supplier[T]) -> T:
 88    """
 89    Checks if the given object is not None and returns it or returns the object from the given supplier
 90
 91    Args:
 92        obj: The object to check and return
 93        supplier: The supplier to call if obj is None
 94
 95    Returns:
 96        object: obj if not None, the supplier call result otherwise
 97
 98    Raises:
 99        TypeError: Raises a TypeError if obj and supplier or supplied object are None
100    """
101    return cast(T, obj) if non_none(obj) else require_non_none(require_non_none(supplier, "Supplier cannot be None")())
102
103
104def to_string(obj: Any, default_str: Optional[str] = None) -> str:
105    """
106    Returns the result of calling str function for the given object if not null or default_str otherwise
107
108    Args:
109        obj: The object to stringify
110        default_str: The str value to return if obj is None
111
112    Returns:
113        str: A str representing obj, default_str otherwise
114    """
115    return str(obj if non_none(obj) else default_str)
116
117
118async def async_require_non_none(obj: SyncOrAsync[T], message: str = "None async object error") -> T:
119    """
120    Checks if the given object or awaitable object result is not None or raises an error
121
122    Args:
123        obj: The object or awaitable object to check
124        message: The error message is case of obj or awaitable obj is None
125
126    Returns:
127        object: obj if obj is not None and not an Awaitable or Awaitable result if obj is an awaitable and the result is
128        not None
129
130    Raises:
131        TypeError: Raises a TypeError if obj is None or if obj is an awaitable with None result
132    """
133    return require_non_none(await cast(Awaitable[T], obj) if is_awaitable(obj) else cast(T, obj), message)
134
135
136async def async_require_non_none_else(obj: SyncOrAsync[Optional[T]], default: T) -> T:
137    """
138    Checks if the given object or awaitable object result is not None and returns it or returns the default one
139
140    Args:
141        obj: The object or awaitable object to check
142        default: The default object to return if obj is None
143
144    Returns:
145        object:obj if obj is not None and not an Awaitable or Awaitable result if obj is an awaitable and the result is
146        not None, default_obj otherwise
147
148    Raises:
149        TypeError: Raises a TypeError if obj (or await obj) and default_obj are None
150    """
151    return require_non_none_else(
152        await cast(Awaitable[Optional[T]], obj) if is_awaitable(obj) else cast(Optional[T], obj),
153        default
154    )
155
156
157async def async_require_non_none_else_get(obj: SyncOrAsync[Optional[T]], supplier: Supplier[T]) -> T:
158    """
159    Checks if the given object or awaitable object result is not None and returns it or returns the object from the
160    given supplier
161
162    Args:
163        obj: The object or awaitable object to check
164        supplier: The supplier to call if obj or awaitable obj result is None
165
166    Returns:
167        object: obj if not None and not an Awaitable or Awaitable result if obj is an awaitable and the result is
168        not None, the supplier call result otherwise
169
170    Raises:
171        TypeError: Raises a TypeError if obj (or await obj)  and supplier or supplied object are None
172    """
173    return require_non_none_else_get(
174        await cast(Awaitable[Optional[T]], obj) if is_awaitable(obj) else cast(Optional[T], obj),
175        supplier
176    )
177
178
179def to_none(*args: Any, **kwargs: Any) -> None:  # pylint: disable=W0613
180    """
181    Returns None whatever the parameters
182
183    Args:
184        *args: positional parameters
185        **kwargs: named parameters
186
187    Returns:
188        None: None whatever the parameters
189    """
190    return None
191
192
193def to_self(obj: T) -> T:
194    """
195    Returns the given parameter
196    Note: can be useful with multiprocessing where lambda cannot be used (lambda are not serializable)
197
198    Args:
199        obj: The object to return
200
201    Returns:
202        obj (T): The given parameter
203    """
204    return obj