dev4py.utils.joptional

The JOptional class provides a java like Optional class

  1"""The `JOptional` class provides a java like Optional class"""
  2
  3# Copyright 2022 the original author or authors (i.e.: St4rG00se for Dev4py).
  4#
  5# Licensed under the Apache License, Version 2.0 (the "License");
  6# you may not use this file except in compliance with the License.
  7# You may obtain a copy of the License at
  8#
  9#      https://www.apache.org/licenses/LICENSE-2.0
 10#
 11# Unless required by applicable law or agreed to in writing, software
 12# distributed under the License is distributed on an "AS IS" BASIS,
 13# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 14# See the License for the specific language governing permissions and
 15# limitations under the License.
 16
 17from __future__ import annotations
 18
 19from functools import partial
 20from typing import Generic, Optional, Final, Any, cast, Awaitable, Self
 21
 22from dev4py import utils
 23from dev4py.utils import objects
 24from dev4py.utils.awaitables import is_awaitable
 25from dev4py.utils.objects import to_self, to_none
 26from dev4py.utils.types import T, Supplier, Function, R, Consumer, Runnable, Predicate, SyncOrAsync
 27
 28
 29class JOptional(Generic[T]):
 30    """A class inspired by the java.util.Optional class"""
 31
 32    __EMPTY: JOptional[Any]
 33    __CREATE_KEY: Final[object] = object()
 34    __NO_VALUE_ERROR_MSG: Final[str] = "No value present"
 35
 36    @classmethod
 37    def of(cls, value: T) -> JOptional[T]:
 38        """
 39        Returns a JOptional describing the given non-None value
 40
 41        Args:
 42            value: The value to describe, which must be non-None
 43
 44        Returns:
 45            JOptional[T]: A JOptional of value T type with the value present
 46
 47        Raises:
 48            TypeError: Raises a TypeError if value is None
 49        """
 50        return JOptional(objects.require_non_none(value, cls.__NO_VALUE_ERROR_MSG), cls.__CREATE_KEY)
 51
 52    @classmethod
 53    def of_noneable(cls, value: Optional[T]) -> JOptional[T]:
 54        """
 55        Returns a JOptional describing the given value, if non-None, otherwise returns an empty JOptional
 56
 57        Args:
 58            value: The possibly-None value to describe
 59
 60        Returns:
 61            JOptional[T]: A JOptional of value T type with the value present if the specified value is non-None,
 62            otherwise an empty JOptional
 63        """
 64        return cls.empty() if objects.is_none(value) else cls.of(cast(T, value))
 65
 66    @classmethod
 67    def empty(cls) -> JOptional[T]:
 68        """Return an empty instance of JOptional"""
 69        return cls.__EMPTY
 70
 71    def __init__(self, value: Optional[T], create_key: object):
 72        """JOptional private constructor: Constructs an instance with the described value"""
 73        assert create_key == self.__CREATE_KEY, \
 74            "JOptional private constructor! Please use JOptional.of or JOptional.of_noneable"
 75        self._value: Optional[T] = value
 76
 77    def is_present(self) -> bool:
 78        """
 79        If a value is present, returns true, otherwise false
 80
 81        Returns:
 82            bool: true if a value is present, otherwise false
 83        """
 84        return objects.non_none(self._value)
 85
 86    def is_empty(self) -> bool:
 87        """
 88        If a value is not present, returns true, otherwise false.
 89
 90        Returns:
 91            bool: true if a value is not present, otherwise false
 92        """
 93        return objects.is_none(self._value)
 94
 95    def get(self) -> T:
 96        """
 97        If a value is present, returns the value, otherwise raises a ValueError
 98
 99        Returns:
100            value: The non-None value described by this JOptional
101
102        Raises:
103            ValueError: Raises a ValueError if no value is present
104        """
105        return self.or_else_raise()
106
107    def or_else(self, other: Optional[T] = None) -> Optional[T]:
108        """
109        If a value is present, returns the value, otherwise returns other
110        Args:
111            other: The value to be returned, if no value is present. May be None.
112
113        Returns:
114            value: The value, if present, otherwise other
115        """
116        return self.or_else_get(cast(Supplier[Optional[T]], partial(to_self, obj=other)))
117
118    def or_else_get(self, supplier: Supplier[Optional[T]] = to_none) -> Optional[T]:
119        """
120        If a value is present, returns the value, otherwise returns the result produced by the supplying function
121
122        Args:
123            supplier: The supplying function that produces a value to be returned
124
125        Returns:
126            value: The value, if present, otherwise the result produced by the supplying function
127
128        Raises:
129            TypeError: if the supplying function is None
130        """
131        objects.require_non_none(supplier)
132        return self._value if self.is_present() else supplier()
133
134    @staticmethod  # pragma: no mutate
135    def __or_else_raise_supplier_lambda() -> Exception:
136        """
137        private static method to replace or_else_raise lambda supplier by a function
138        Note: lambda are not used in order to be compatible with multiprocessing (lambda are not serializable)
139        """
140        # lambda: cast(Exception, ValueError(JOptional.__NO_VALUE_ERROR_MSG))
141        return cast(Exception, ValueError(JOptional.__NO_VALUE_ERROR_MSG))
142
143    def or_else_raise(
144            self, supplier: Supplier[Exception] = __or_else_raise_supplier_lambda
145    ) -> T:
146        """
147        If a value is present, returns the value, otherwise raises an exception produced by the exception supplying
148        function
149
150        Args:
151            supplier: The supplying function that produces an exception to be raised (default: ValueError)
152
153        Returns:
154            value: The value, if present
155
156        Raises:
157            Exception: if the supplying function is None
158            TypeError: if supplier is None
159        """
160        objects.require_non_none(supplier)
161        if self.is_empty():
162            raise supplier()
163        return cast(T, self._value)
164
165    def or_get(self, supplier: Supplier[JOptional[T]]) -> JOptional[T]:
166        """
167        This is the `or` equivalent in java Optional (Reminder: `or` is a python keyword)
168
169        If a value is present, returns a JOptional describing the value, otherwise returns a JOptional produced by the
170        supplying function
171
172        Args:
173            supplier: The supplying function that produces a JOptional to be returned
174
175        Returns:
176            JOptional[T]: Returns a JOptional describing the value of this JOptional, if a value is present, otherwise
177            a JOptional produced by the supplying function
178
179        Raises:
180            TypeError: if the supplying function is None
181        """
182        objects.require_non_none(supplier)
183        return self if self.is_present() else objects.require_non_none(supplier())
184
185    @staticmethod  # pragma: no mutate
186    def __map_lambda(v: T, mapper: Function[T, Optional[R]]) -> JOptional[R]:
187        """
188        private static method to replace inner map lambda supplier by a function
189        Note: lambda are not used in order to be compatible with multiprocessing (lambda are not serializable)
190        """
191        # lambda v: JOptional.of_noneable(mapper(v))
192        return JOptional.of_noneable(mapper(v))
193
194    def map(self, mapper: Function[T, Optional[R]]) -> JOptional[R]:
195        """
196        If a value is present, returns a JOptional describing (as if by of_noneable) the result of applying the given
197        mapping function to the value, otherwise returns an empty JOptional
198
199        If the mapping function returns a None result then this method returns an empty JOptional.
200
201        Args:
202            mapper: The mapping function to apply to a value, if present
203
204        Returns:
205            JOptional[R]: A JOptional describing the result of applying a mapping function to the value of this
206            JOptional, if a value is present, otherwise an empty JOptional
207
208        Raises:
209            TypeError: If the mapping function is None
210        """
211        objects.require_non_none(mapper)
212        return self.flat_map(partial(JOptional.__map_lambda, mapper=mapper))
213
214    def flat_map(self, mapper: Function[T, JOptional[R]]) -> JOptional[R]:
215        """
216        If a value is present, returns the result of applying the given JOptional-bearing mapping function to the value,
217        otherwise returns an empty JOptional
218
219        This method is similar to map(Function), but the mapping function is one whose result is already a JOptional,
220        and if invoked, flatMap does not wrap it within an additional JOptional
221
222        Args:
223            mapper: The mapping function to apply to a value, if present
224
225        Returns:
226            JOptional[R]: The result of applying a JOptional-bearing mapping function to the value of this JOptional,
227            if a value is present, otherwise an empty JOptional
228
229        Raises:
230            TypeError: if the mapping function is None
231        """
232        objects.require_non_none(mapper)
233        return JOptional.empty() if self.is_empty() else objects.require_non_none(mapper(cast(T, self._value)))
234
235    def if_present(self, consumer: Consumer[T]) -> None:
236        """
237        If a value is present, performs the given consumer with the value, otherwise does nothing
238
239        Args:
240            consumer: The consumer to be performed, if a value is present
241
242        Returns:
243            Nothing
244
245        Raises:
246            TypeError: if the consumer is None
247        """
248        objects.require_non_none(consumer)
249        # pylint: disable=W0106
250        self.is_present() and consumer(cast(T, self._value))
251
252    def if_empty(self, empty_action: Runnable) -> None:
253        """
254        If a value is not present, performs the given runnable, otherwise does nothing
255
256        Args:
257            empty_action: The runnable to be performed, if a value is not present
258
259        Returns:
260            Nothing
261
262        Raises:
263            TypeError: if the runnable is None
264        """
265        objects.require_non_none(empty_action)
266        # pylint: disable=W0106
267        self.is_empty() and empty_action()
268
269    def if_present_or_else(self, consumer: Consumer[T], empty_action: Runnable) -> None:
270        """
271        If a value is present, performs the given consumer with the value, otherwise performs the given empty_action
272
273        Args:
274            consumer: The consumer to be performed, if a value is present
275            empty_action: The runnable to be performed, if a value is not
276
277        Returns:
278            Nothing
279
280        Raises:
281            TypeError: if the consumer is None or if the runnable is None
282        """
283        objects.require_non_none(consumer)
284        objects.require_non_none(empty_action)
285        # pylint: disable=W0106
286        consumer(cast(T, self._value)) if self.is_present() else empty_action()
287
288    def filter(self, predicate: Predicate[T]) -> JOptional[T]:
289        """
290        If a value is present, and the value matches the given predicate, returns a JOptional describing the value,
291        otherwise returns an empty JOptional
292
293        Args:
294            predicate: The predicate to apply to a value, if present
295
296        Returns:
297            JOptional[T]: A JOptional describing the value of this JOptional, if a value is present and the value
298            matches the given predicate, otherwise an empty JOptional
299
300        Raises:
301            TypeError: if the predicate is None
302        """
303        objects.require_non_none(predicate)
304        return self if self.is_empty() or predicate(cast(T, self._value)) else JOptional.empty()
305
306    def peek(self, consumer: Consumer[T]) -> Self:
307        """
308        If a value is present, performs the given consumer with the value, otherwise does nothing and returns the
309        current JOptional
310
311        Args:
312            consumer: The consumer to be performed, if a value is present
313
314        Returns:
315             JOptional[T]: The current JOptional (self)
316
317        Raises:
318            TypeError: if the consumer is None
319        """
320        objects.require_non_none(consumer)
321        self.if_present(consumer)
322        return self
323
324    def is_awaitable(self) -> bool:
325        """
326        If the value is an Awaitable (Coroutine, Task or Future), returns true, otherwise false
327
328        Returns:
329            bool: true if the value is an Awaitable, otherwise false
330        """
331        return is_awaitable(self._value)
332
333    async def to_sync_value(self) -> JOptional[Any]:
334        """
335        If the value is an Awaitable (Coroutine, Task or Future), awaits and returns a JOptional with the obtained
336        value, otherwise if the value is not an Awaitable returns self
337
338        Note: can be useful in order to call is_present, is_empty, if_present, if_empty, ect. depending on the awaited
339        value result (otherwise, for example, is_present is always True with an 'Awaitable' value)
340
341        Returns:
342            JOptional: A JOptional with synchronized value (i.e. not an Awaitable value)
343        """
344        return JOptional.of_noneable(await cast(Awaitable[Any], self._value)) if self.is_awaitable() else self
345
346    def to_async_joptional(self) -> utils.AsyncJOptional[SyncOrAsync[T]]:
347        """
348        Convert the current JOptional to an AsyncJOptional
349
350        Note: It can be useful in order to use async mapper
351
352        Returns:
353            AsyncJOptional[T]: The corresponding AsyncJOptional
354        """
355        return utils.AsyncJOptional.of_noneable(self._value)
356
357
358# INIT STATIC VARIABLES
359# noinspection PyProtectedMember
360# noinspection PyUnresolvedReferences
361# pylint: disable=W0212
362JOptional._JOptional__EMPTY = JOptional(None, JOptional._JOptional__CREATE_KEY)  # type: ignore
class JOptional(typing.Generic[~T]): 
 30class JOptional(Generic[T]):
 31    """A class inspired by the java.util.Optional class"""
 32
 33    __EMPTY: JOptional[Any]
 34    __CREATE_KEY: Final[object] = object()
 35    __NO_VALUE_ERROR_MSG: Final[str] = "No value present"
 36
 37    @classmethod
 38    def of(cls, value: T) -> JOptional[T]:
 39        """
 40        Returns a JOptional describing the given non-None value
 41
 42        Args:
 43            value: The value to describe, which must be non-None
 44
 45        Returns:
 46            JOptional[T]: A JOptional of value T type with the value present
 47
 48        Raises:
 49            TypeError: Raises a TypeError if value is None
 50        """
 51        return JOptional(objects.require_non_none(value, cls.__NO_VALUE_ERROR_MSG), cls.__CREATE_KEY)
 52
 53    @classmethod
 54    def of_noneable(cls, value: Optional[T]) -> JOptional[T]:
 55        """
 56        Returns a JOptional describing the given value, if non-None, otherwise returns an empty JOptional
 57
 58        Args:
 59            value: The possibly-None value to describe
 60
 61        Returns:
 62            JOptional[T]: A JOptional of value T type with the value present if the specified value is non-None,
 63            otherwise an empty JOptional
 64        """
 65        return cls.empty() if objects.is_none(value) else cls.of(cast(T, value))
 66
 67    @classmethod
 68    def empty(cls) -> JOptional[T]:
 69        """Return an empty instance of JOptional"""
 70        return cls.__EMPTY
 71
 72    def __init__(self, value: Optional[T], create_key: object):
 73        """JOptional private constructor: Constructs an instance with the described value"""
 74        assert create_key == self.__CREATE_KEY, \
 75            "JOptional private constructor! Please use JOptional.of or JOptional.of_noneable"
 76        self._value: Optional[T] = value
 77
 78    def is_present(self) -> bool:
 79        """
 80        If a value is present, returns true, otherwise false
 81
 82        Returns:
 83            bool: true if a value is present, otherwise false
 84        """
 85        return objects.non_none(self._value)
 86
 87    def is_empty(self) -> bool:
 88        """
 89        If a value is not present, returns true, otherwise false.
 90
 91        Returns:
 92            bool: true if a value is not present, otherwise false
 93        """
 94        return objects.is_none(self._value)
 95
 96    def get(self) -> T:
 97        """
 98        If a value is present, returns the value, otherwise raises a ValueError
 99
100        Returns:
101            value: The non-None value described by this JOptional
102
103        Raises:
104            ValueError: Raises a ValueError if no value is present
105        """
106        return self.or_else_raise()
107
108    def or_else(self, other: Optional[T] = None) -> Optional[T]:
109        """
110        If a value is present, returns the value, otherwise returns other
111        Args:
112            other: The value to be returned, if no value is present. May be None.
113
114        Returns:
115            value: The value, if present, otherwise other
116        """
117        return self.or_else_get(cast(Supplier[Optional[T]], partial(to_self, obj=other)))
118
119    def or_else_get(self, supplier: Supplier[Optional[T]] = to_none) -> Optional[T]:
120        """
121        If a value is present, returns the value, otherwise returns the result produced by the supplying function
122
123        Args:
124            supplier: The supplying function that produces a value to be returned
125
126        Returns:
127            value: The value, if present, otherwise the result produced by the supplying function
128
129        Raises:
130            TypeError: if the supplying function is None
131        """
132        objects.require_non_none(supplier)
133        return self._value if self.is_present() else supplier()
134
135    @staticmethod  # pragma: no mutate
136    def __or_else_raise_supplier_lambda() -> Exception:
137        """
138        private static method to replace or_else_raise lambda supplier by a function
139        Note: lambda are not used in order to be compatible with multiprocessing (lambda are not serializable)
140        """
141        # lambda: cast(Exception, ValueError(JOptional.__NO_VALUE_ERROR_MSG))
142        return cast(Exception, ValueError(JOptional.__NO_VALUE_ERROR_MSG))
143
144    def or_else_raise(
145            self, supplier: Supplier[Exception] = __or_else_raise_supplier_lambda
146    ) -> T:
147        """
148        If a value is present, returns the value, otherwise raises an exception produced by the exception supplying
149        function
150
151        Args:
152            supplier: The supplying function that produces an exception to be raised (default: ValueError)
153
154        Returns:
155            value: The value, if present
156
157        Raises:
158            Exception: if the supplying function is None
159            TypeError: if supplier is None
160        """
161        objects.require_non_none(supplier)
162        if self.is_empty():
163            raise supplier()
164        return cast(T, self._value)
165
166    def or_get(self, supplier: Supplier[JOptional[T]]) -> JOptional[T]:
167        """
168        This is the `or` equivalent in java Optional (Reminder: `or` is a python keyword)
169
170        If a value is present, returns a JOptional describing the value, otherwise returns a JOptional produced by the
171        supplying function
172
173        Args:
174            supplier: The supplying function that produces a JOptional to be returned
175
176        Returns:
177            JOptional[T]: Returns a JOptional describing the value of this JOptional, if a value is present, otherwise
178            a JOptional produced by the supplying function
179
180        Raises:
181            TypeError: if the supplying function is None
182        """
183        objects.require_non_none(supplier)
184        return self if self.is_present() else objects.require_non_none(supplier())
185
186    @staticmethod  # pragma: no mutate
187    def __map_lambda(v: T, mapper: Function[T, Optional[R]]) -> JOptional[R]:
188        """
189        private static method to replace inner map lambda supplier by a function
190        Note: lambda are not used in order to be compatible with multiprocessing (lambda are not serializable)
191        """
192        # lambda v: JOptional.of_noneable(mapper(v))
193        return JOptional.of_noneable(mapper(v))
194
195    def map(self, mapper: Function[T, Optional[R]]) -> JOptional[R]:
196        """
197        If a value is present, returns a JOptional describing (as if by of_noneable) the result of applying the given
198        mapping function to the value, otherwise returns an empty JOptional
199
200        If the mapping function returns a None result then this method returns an empty JOptional.
201
202        Args:
203            mapper: The mapping function to apply to a value, if present
204
205        Returns:
206            JOptional[R]: A JOptional describing the result of applying a mapping function to the value of this
207            JOptional, if a value is present, otherwise an empty JOptional
208
209        Raises:
210            TypeError: If the mapping function is None
211        """
212        objects.require_non_none(mapper)
213        return self.flat_map(partial(JOptional.__map_lambda, mapper=mapper))
214
215    def flat_map(self, mapper: Function[T, JOptional[R]]) -> JOptional[R]:
216        """
217        If a value is present, returns the result of applying the given JOptional-bearing mapping function to the value,
218        otherwise returns an empty JOptional
219
220        This method is similar to map(Function), but the mapping function is one whose result is already a JOptional,
221        and if invoked, flatMap does not wrap it within an additional JOptional
222
223        Args:
224            mapper: The mapping function to apply to a value, if present
225
226        Returns:
227            JOptional[R]: The result of applying a JOptional-bearing mapping function to the value of this JOptional,
228            if a value is present, otherwise an empty JOptional
229
230        Raises:
231            TypeError: if the mapping function is None
232        """
233        objects.require_non_none(mapper)
234        return JOptional.empty() if self.is_empty() else objects.require_non_none(mapper(cast(T, self._value)))
235
236    def if_present(self, consumer: Consumer[T]) -> None:
237        """
238        If a value is present, performs the given consumer with the value, otherwise does nothing
239
240        Args:
241            consumer: The consumer to be performed, if a value is present
242
243        Returns:
244            Nothing
245
246        Raises:
247            TypeError: if the consumer is None
248        """
249        objects.require_non_none(consumer)
250        # pylint: disable=W0106
251        self.is_present() and consumer(cast(T, self._value))
252
253    def if_empty(self, empty_action: Runnable) -> None:
254        """
255        If a value is not present, performs the given runnable, otherwise does nothing
256
257        Args:
258            empty_action: The runnable to be performed, if a value is not present
259
260        Returns:
261            Nothing
262
263        Raises:
264            TypeError: if the runnable is None
265        """
266        objects.require_non_none(empty_action)
267        # pylint: disable=W0106
268        self.is_empty() and empty_action()
269
270    def if_present_or_else(self, consumer: Consumer[T], empty_action: Runnable) -> None:
271        """
272        If a value is present, performs the given consumer with the value, otherwise performs the given empty_action
273
274        Args:
275            consumer: The consumer to be performed, if a value is present
276            empty_action: The runnable to be performed, if a value is not
277
278        Returns:
279            Nothing
280
281        Raises:
282            TypeError: if the consumer is None or if the runnable is None
283        """
284        objects.require_non_none(consumer)
285        objects.require_non_none(empty_action)
286        # pylint: disable=W0106
287        consumer(cast(T, self._value)) if self.is_present() else empty_action()
288
289    def filter(self, predicate: Predicate[T]) -> JOptional[T]:
290        """
291        If a value is present, and the value matches the given predicate, returns a JOptional describing the value,
292        otherwise returns an empty JOptional
293
294        Args:
295            predicate: The predicate to apply to a value, if present
296
297        Returns:
298            JOptional[T]: A JOptional describing the value of this JOptional, if a value is present and the value
299            matches the given predicate, otherwise an empty JOptional
300
301        Raises:
302            TypeError: if the predicate is None
303        """
304        objects.require_non_none(predicate)
305        return self if self.is_empty() or predicate(cast(T, self._value)) else JOptional.empty()
306
307    def peek(self, consumer: Consumer[T]) -> Self:
308        """
309        If a value is present, performs the given consumer with the value, otherwise does nothing and returns the
310        current JOptional
311
312        Args:
313            consumer: The consumer to be performed, if a value is present
314
315        Returns:
316             JOptional[T]: The current JOptional (self)
317
318        Raises:
319            TypeError: if the consumer is None
320        """
321        objects.require_non_none(consumer)
322        self.if_present(consumer)
323        return self
324
325    def is_awaitable(self) -> bool:
326        """
327        If the value is an Awaitable (Coroutine, Task or Future), returns true, otherwise false
328
329        Returns:
330            bool: true if the value is an Awaitable, otherwise false
331        """
332        return is_awaitable(self._value)
333
334    async def to_sync_value(self) -> JOptional[Any]:
335        """
336        If the value is an Awaitable (Coroutine, Task or Future), awaits and returns a JOptional with the obtained
337        value, otherwise if the value is not an Awaitable returns self
338
339        Note: can be useful in order to call is_present, is_empty, if_present, if_empty, ect. depending on the awaited
340        value result (otherwise, for example, is_present is always True with an 'Awaitable' value)
341
342        Returns:
343            JOptional: A JOptional with synchronized value (i.e. not an Awaitable value)
344        """
345        return JOptional.of_noneable(await cast(Awaitable[Any], self._value)) if self.is_awaitable() else self
346
347    def to_async_joptional(self) -> utils.AsyncJOptional[SyncOrAsync[T]]:
348        """
349        Convert the current JOptional to an AsyncJOptional
350
351        Note: It can be useful in order to use async mapper
352
353        Returns:
354            AsyncJOptional[T]: The corresponding AsyncJOptional
355        """
356        return utils.AsyncJOptional.of_noneable(self._value)

A class inspired by the java.util.Optional class

JOptional(value: Optional[~T], create_key: object) 
72    def __init__(self, value: Optional[T], create_key: object):
73        """JOptional private constructor: Constructs an instance with the described value"""
74        assert create_key == self.__CREATE_KEY, \
75            "JOptional private constructor! Please use JOptional.of or JOptional.of_noneable"
76        self._value: Optional[T] = value

JOptional private constructor: Constructs an instance with the described value

@classmethod
def of(cls, value: ~T) -> JOptional[~T]: 
37    @classmethod
38    def of(cls, value: T) -> JOptional[T]:
39        """
40        Returns a JOptional describing the given non-None value
41
42        Args:
43            value: The value to describe, which must be non-None
44
45        Returns:
46            JOptional[T]: A JOptional of value T type with the value present
47
48        Raises:
49            TypeError: Raises a TypeError if value is None
50        """
51        return JOptional(objects.require_non_none(value, cls.__NO_VALUE_ERROR_MSG), cls.__CREATE_KEY)

Returns a JOptional describing the given non-None value

Arguments:
  • value: The value to describe, which must be non-None
Returns:

JOptional[T]: A JOptional of value T type with the value present

Raises:
  • TypeError: Raises a TypeError if value is None
@classmethod
def of_noneable(cls, value: Optional[~T]) -> JOptional[~T]: 
53    @classmethod
54    def of_noneable(cls, value: Optional[T]) -> JOptional[T]:
55        """
56        Returns a JOptional describing the given value, if non-None, otherwise returns an empty JOptional
57
58        Args:
59            value: The possibly-None value to describe
60
61        Returns:
62            JOptional[T]: A JOptional of value T type with the value present if the specified value is non-None,
63            otherwise an empty JOptional
64        """
65        return cls.empty() if objects.is_none(value) else cls.of(cast(T, value))

Returns a JOptional describing the given value, if non-None, otherwise returns an empty JOptional

Arguments:
  • value: The possibly-None value to describe
Returns:

JOptional[T]: A JOptional of value T type with the value present if the specified value is non-None, otherwise an empty JOptional

@classmethod
def empty(cls) -> JOptional[~T]: 
67    @classmethod
68    def empty(cls) -> JOptional[T]:
69        """Return an empty instance of JOptional"""
70        return cls.__EMPTY

Return an empty instance of JOptional

def is_present(self) -> bool: 
78    def is_present(self) -> bool:
79        """
80        If a value is present, returns true, otherwise false
81
82        Returns:
83            bool: true if a value is present, otherwise false
84        """
85        return objects.non_none(self._value)

If a value is present, returns true, otherwise false

Returns:

bool: true if a value is present, otherwise false

def is_empty(self) -> bool: 
87    def is_empty(self) -> bool:
88        """
89        If a value is not present, returns true, otherwise false.
90
91        Returns:
92            bool: true if a value is not present, otherwise false
93        """
94        return objects.is_none(self._value)

If a value is not present, returns true, otherwise false.

Returns:

bool: true if a value is not present, otherwise false

def get(self) -> ~T: 
 96    def get(self) -> T:
 97        """
 98        If a value is present, returns the value, otherwise raises a ValueError
 99
100        Returns:
101            value: The non-None value described by this JOptional
102
103        Raises:
104            ValueError: Raises a ValueError if no value is present
105        """
106        return self.or_else_raise()

If a value is present, returns the value, otherwise raises a ValueError

Returns:

value: The non-None value described by this JOptional

Raises:
  • ValueError: Raises a ValueError if no value is present
def or_else(self, other: Optional[~T] = None) -> Optional[~T]: 
108    def or_else(self, other: Optional[T] = None) -> Optional[T]:
109        """
110        If a value is present, returns the value, otherwise returns other
111        Args:
112            other: The value to be returned, if no value is present. May be None.
113
114        Returns:
115            value: The value, if present, otherwise other
116        """
117        return self.or_else_get(cast(Supplier[Optional[T]], partial(to_self, obj=other)))

If a value is present, returns the value, otherwise returns other

Arguments:
  • other: The value to be returned, if no value is present. May be None.
Returns:

value: The value, if present, otherwise other

def or_else_get( self, supplier: Callable[[], Optional[~T]] = <function to_none>) -> Optional[~T]: 
119    def or_else_get(self, supplier: Supplier[Optional[T]] = to_none) -> Optional[T]:
120        """
121        If a value is present, returns the value, otherwise returns the result produced by the supplying function
122
123        Args:
124            supplier: The supplying function that produces a value to be returned
125
126        Returns:
127            value: The value, if present, otherwise the result produced by the supplying function
128
129        Raises:
130            TypeError: if the supplying function is None
131        """
132        objects.require_non_none(supplier)
133        return self._value if self.is_present() else supplier()

If a value is present, returns the value, otherwise returns the result produced by the supplying function

Arguments:
  • supplier: The supplying function that produces a value to be returned
Returns:

value: The value, if present, otherwise the result produced by the supplying function

Raises:
  • TypeError: if the supplying function is None
def or_else_raise( self, supplier: Callable[[], Exception] = <staticmethod(<function JOptional.__or_else_raise_supplier_lambda>)>) -> ~T: 
144    def or_else_raise(
145            self, supplier: Supplier[Exception] = __or_else_raise_supplier_lambda
146    ) -> T:
147        """
148        If a value is present, returns the value, otherwise raises an exception produced by the exception supplying
149        function
150
151        Args:
152            supplier: The supplying function that produces an exception to be raised (default: ValueError)
153
154        Returns:
155            value: The value, if present
156
157        Raises:
158            Exception: if the supplying function is None
159            TypeError: if supplier is None
160        """
161        objects.require_non_none(supplier)
162        if self.is_empty():
163            raise supplier()
164        return cast(T, self._value)

If a value is present, returns the value, otherwise raises an exception produced by the exception supplying function

Arguments:
  • supplier: The supplying function that produces an exception to be raised (default: ValueError)
Returns:

value: The value, if present

Raises:
  • Exception: if the supplying function is None
  • TypeError: if supplier is None
def or_get( self, supplier: Callable[[], JOptional[~T]]) -> JOptional[~T]: 
166    def or_get(self, supplier: Supplier[JOptional[T]]) -> JOptional[T]:
167        """
168        This is the `or` equivalent in java Optional (Reminder: `or` is a python keyword)
169
170        If a value is present, returns a JOptional describing the value, otherwise returns a JOptional produced by the
171        supplying function
172
173        Args:
174            supplier: The supplying function that produces a JOptional to be returned
175
176        Returns:
177            JOptional[T]: Returns a JOptional describing the value of this JOptional, if a value is present, otherwise
178            a JOptional produced by the supplying function
179
180        Raises:
181            TypeError: if the supplying function is None
182        """
183        objects.require_non_none(supplier)
184        return self if self.is_present() else objects.require_non_none(supplier())

This is the or equivalent in java Optional (Reminder: or is a python keyword)

If a value is present, returns a JOptional describing the value, otherwise returns a JOptional produced by the supplying function

Arguments:
  • supplier: The supplying function that produces a JOptional to be returned
Returns:

JOptional[T]: Returns a JOptional describing the value of this JOptional, if a value is present, otherwise a JOptional produced by the supplying function

Raises:
  • TypeError: if the supplying function is None
def map( self, mapper: Callable[[~T], Optional[~R]]) -> JOptional[~R]: 
195    def map(self, mapper: Function[T, Optional[R]]) -> JOptional[R]:
196        """
197        If a value is present, returns a JOptional describing (as if by of_noneable) the result of applying the given
198        mapping function to the value, otherwise returns an empty JOptional
199
200        If the mapping function returns a None result then this method returns an empty JOptional.
201
202        Args:
203            mapper: The mapping function to apply to a value, if present
204
205        Returns:
206            JOptional[R]: A JOptional describing the result of applying a mapping function to the value of this
207            JOptional, if a value is present, otherwise an empty JOptional
208
209        Raises:
210            TypeError: If the mapping function is None
211        """
212        objects.require_non_none(mapper)
213        return self.flat_map(partial(JOptional.__map_lambda, mapper=mapper))

If a value is present, returns a JOptional describing (as if by of_noneable) the result of applying the given mapping function to the value, otherwise returns an empty JOptional

If the mapping function returns a None result then this method returns an empty JOptional.

Arguments:
  • mapper: The mapping function to apply to a value, if present
Returns:

JOptional[R]: A JOptional describing the result of applying a mapping function to the value of this JOptional, if a value is present, otherwise an empty JOptional

Raises:
  • TypeError: If the mapping function is None
def flat_map( self, mapper: Callable[[~T], JOptional[~R]]) -> JOptional[~R]: 
215    def flat_map(self, mapper: Function[T, JOptional[R]]) -> JOptional[R]:
216        """
217        If a value is present, returns the result of applying the given JOptional-bearing mapping function to the value,
218        otherwise returns an empty JOptional
219
220        This method is similar to map(Function), but the mapping function is one whose result is already a JOptional,
221        and if invoked, flatMap does not wrap it within an additional JOptional
222
223        Args:
224            mapper: The mapping function to apply to a value, if present
225
226        Returns:
227            JOptional[R]: The result of applying a JOptional-bearing mapping function to the value of this JOptional,
228            if a value is present, otherwise an empty JOptional
229
230        Raises:
231            TypeError: if the mapping function is None
232        """
233        objects.require_non_none(mapper)
234        return JOptional.empty() if self.is_empty() else objects.require_non_none(mapper(cast(T, self._value)))

If a value is present, returns the result of applying the given JOptional-bearing mapping function to the value, otherwise returns an empty JOptional

This method is similar to map(Function), but the mapping function is one whose result is already a JOptional, and if invoked, flatMap does not wrap it within an additional JOptional

Arguments:
  • mapper: The mapping function to apply to a value, if present
Returns:

JOptional[R]: The result of applying a JOptional-bearing mapping function to the value of this JOptional, if a value is present, otherwise an empty JOptional

Raises:
  • TypeError: if the mapping function is None
def if_present(self, consumer: Callable[[~T], NoneType]) -> None: 
236    def if_present(self, consumer: Consumer[T]) -> None:
237        """
238        If a value is present, performs the given consumer with the value, otherwise does nothing
239
240        Args:
241            consumer: The consumer to be performed, if a value is present
242
243        Returns:
244            Nothing
245
246        Raises:
247            TypeError: if the consumer is None
248        """
249        objects.require_non_none(consumer)
250        # pylint: disable=W0106
251        self.is_present() and consumer(cast(T, self._value))

If a value is present, performs the given consumer with the value, otherwise does nothing

Arguments:
  • consumer: The consumer to be performed, if a value is present
Returns:

Nothing

Raises:
  • TypeError: if the consumer is None
def if_empty(self, empty_action: Callable[[], NoneType]) -> None: 
253    def if_empty(self, empty_action: Runnable) -> None:
254        """
255        If a value is not present, performs the given runnable, otherwise does nothing
256
257        Args:
258            empty_action: The runnable to be performed, if a value is not present
259
260        Returns:
261            Nothing
262
263        Raises:
264            TypeError: if the runnable is None
265        """
266        objects.require_non_none(empty_action)
267        # pylint: disable=W0106
268        self.is_empty() and empty_action()

If a value is not present, performs the given runnable, otherwise does nothing

Arguments:
  • empty_action: The runnable to be performed, if a value is not present
Returns:

Nothing

Raises:
  • TypeError: if the runnable is None
def if_present_or_else( self, consumer: Callable[[~T], NoneType], empty_action: Callable[[], NoneType]) -> None: 
270    def if_present_or_else(self, consumer: Consumer[T], empty_action: Runnable) -> None:
271        """
272        If a value is present, performs the given consumer with the value, otherwise performs the given empty_action
273
274        Args:
275            consumer: The consumer to be performed, if a value is present
276            empty_action: The runnable to be performed, if a value is not
277
278        Returns:
279            Nothing
280
281        Raises:
282            TypeError: if the consumer is None or if the runnable is None
283        """
284        objects.require_non_none(consumer)
285        objects.require_non_none(empty_action)
286        # pylint: disable=W0106
287        consumer(cast(T, self._value)) if self.is_present() else empty_action()

If a value is present, performs the given consumer with the value, otherwise performs the given empty_action

Arguments:
  • consumer: The consumer to be performed, if a value is present
  • empty_action: The runnable to be performed, if a value is not
Returns:

Nothing

Raises:
  • TypeError: if the consumer is None or if the runnable is None
def filter( self, predicate: Callable[[~T], bool]) -> JOptional[~T]: 
289    def filter(self, predicate: Predicate[T]) -> JOptional[T]:
290        """
291        If a value is present, and the value matches the given predicate, returns a JOptional describing the value,
292        otherwise returns an empty JOptional
293
294        Args:
295            predicate: The predicate to apply to a value, if present
296
297        Returns:
298            JOptional[T]: A JOptional describing the value of this JOptional, if a value is present and the value
299            matches the given predicate, otherwise an empty JOptional
300
301        Raises:
302            TypeError: if the predicate is None
303        """
304        objects.require_non_none(predicate)
305        return self if self.is_empty() or predicate(cast(T, self._value)) else JOptional.empty()

If a value is present, and the value matches the given predicate, returns a JOptional describing the value, otherwise returns an empty JOptional

Arguments:
  • predicate: The predicate to apply to a value, if present
Returns:

JOptional[T]: A JOptional describing the value of this JOptional, if a value is present and the value matches the given predicate, otherwise an empty JOptional

Raises:
  • TypeError: if the predicate is None
def peek(self, consumer: Callable[[~T], NoneType]) -> Self: 
307    def peek(self, consumer: Consumer[T]) -> Self:
308        """
309        If a value is present, performs the given consumer with the value, otherwise does nothing and returns the
310        current JOptional
311
312        Args:
313            consumer: The consumer to be performed, if a value is present
314
315        Returns:
316             JOptional[T]: The current JOptional (self)
317
318        Raises:
319            TypeError: if the consumer is None
320        """
321        objects.require_non_none(consumer)
322        self.if_present(consumer)
323        return self

If a value is present, performs the given consumer with the value, otherwise does nothing and returns the current JOptional

Arguments:
  • consumer: The consumer to be performed, if a value is present
Returns:

JOptional[T]: The current JOptional (self)

Raises:
  • TypeError: if the consumer is None
def is_awaitable(self) -> bool: 
325    def is_awaitable(self) -> bool:
326        """
327        If the value is an Awaitable (Coroutine, Task or Future), returns true, otherwise false
328
329        Returns:
330            bool: true if the value is an Awaitable, otherwise false
331        """
332        return is_awaitable(self._value)

If the value is an Awaitable (Coroutine, Task or Future), returns true, otherwise false

Returns:

bool: true if the value is an Awaitable, otherwise false

async def to_sync_value(self) -> JOptional[typing.Any]: 
334    async def to_sync_value(self) -> JOptional[Any]:
335        """
336        If the value is an Awaitable (Coroutine, Task or Future), awaits and returns a JOptional with the obtained
337        value, otherwise if the value is not an Awaitable returns self
338
339        Note: can be useful in order to call is_present, is_empty, if_present, if_empty, ect. depending on the awaited
340        value result (otherwise, for example, is_present is always True with an 'Awaitable' value)
341
342        Returns:
343            JOptional: A JOptional with synchronized value (i.e. not an Awaitable value)
344        """
345        return JOptional.of_noneable(await cast(Awaitable[Any], self._value)) if self.is_awaitable() else self

If the value is an Awaitable (Coroutine, Task or Future), awaits and returns a JOptional with the obtained value, otherwise if the value is not an Awaitable returns self

Note: can be useful in order to call is_present, is_empty, if_present, if_empty, ect. depending on the awaited value result (otherwise, for example, is_present is always True with an 'Awaitable' value)

Returns:

JOptional: A JOptional with synchronized value (i.e. not an Awaitable value)

def to_async_joptional( self) -> dev4py.utils.async_joptional.AsyncJOptional[typing.Union[typing.Awaitable[~T], ~T]]: 
347    def to_async_joptional(self) -> utils.AsyncJOptional[SyncOrAsync[T]]:
348        """
349        Convert the current JOptional to an AsyncJOptional
350
351        Note: It can be useful in order to use async mapper
352
353        Returns:
354            AsyncJOptional[T]: The corresponding AsyncJOptional
355        """
356        return utils.AsyncJOptional.of_noneable(self._value)

Convert the current JOptional to an AsyncJOptional

Note: It can be useful in order to use async mapper

Returns:

AsyncJOptional[T]: The corresponding AsyncJOptional