172def cfg(
173    target_os: System | None = None,
174    python_version: tuple[int, int, int] | None = None,
175    target_arch: Arch | None = None,
176    impl: Python | None = None,
177) -> bool:
178    """A function that will run the code only if all predicate attributes returns `True`.
179
180    The difference between this function and `cfg_attr` is that this function will not raise an exception.
181    Instead it will return `False` if any of the attributes fails.
182
183    Example
184    -------
185    ```py
186    import sain
187
188    if cfg(target_os="windows"):
189        print("Windows")
190    elif cfg(target_os="linux", target_arch="arm64"):
191        print("Linux")
192    else:
193        print("Something else")
194    ```
195
196    Parameters
197    ----------
198    target_os : `str | None`
199        The targeted operating system thats required for the object to be ran.
200    python_version : `tuple[int, int, int] | None`
201        The targeted Python version thats required for the object to be ran. Format must be `(3, 9, 5)``
202    target_arch : `str | None`
203        The CPU targeted architecture thats required for the object to be ran.
204    impl : `str | None`
205        The Python implementation thats required for the object to be ran.
206
207    Returns
208    -------
209    `bool`
210        The condition that was checked.
211    """
212    checker = _AttrCheck(
213        lambda: None,
214        no_raise=True,
215        target_os=target_os,
216        python_version=python_version,
217        target_arch=target_arch,
218        impl=impl,
219    )
220    return checker.internal_check()

 99def cfg_attr(
100    *,
101    target_os: System | None = None,
102    python_version: tuple[int, int, int] | None = None,
103    target_arch: Arch | None = None,
104    impl: Python | None = None,
105) -> collections.Callable[[F], F]:
106    """Conditional runtime object configuration based on passed arguments.
107
108    If the decorated object gets called and one of the attributes returns `False`,
109    `RuntimeError` will be raised and the object will not run.
110
111    Example
112    -------
113    ```py
114    import sain
115
116    @cfg_attr(target_os="windows")
117    def windows_only():
118        # Do stuff with Windows's API.
119        ...
120
121    # Mut be PyPy Python implementation or `RuntimeError` will be raised
122    # when creating the instance.
123    @cfg_attr(impl="PyPy")
124    class Zoo:
125        @sain.cfg_attr(target_os="linux")
126        def bark(self) -> None:
127            windows_only()  # RuntimeError("Windows OS only!)
128
129    # An instance will not be created if raised.
130    zoo = Zoo()
131    # RuntimeError("class Zoo requires PyPy implementation")
132    zoo.bark()
133    # Whats zoo??
134    ```
135
136    Parameters
137    ----------
138    target_os : `str | None`
139        The targeted operating system thats required for the object.
140    python_version : `tuple[int, int, int] | None`
141        The targeted Python version thats required for the object. Format must be `(3, 9, 5)`.
142    target_arch : `str | None`
143        The CPU targeted architecture thats required for the object.
144    impl : `str | None`
145        The Python implementation thats required for the object.
146
147    Raises
148    ------
149    `RuntimeError`
150        This fails if any of the attributes returns `False`.
151    `ValueError`
152        If the passed Python implementation is unknown.
153    """
154
155    def decorator(callback: F) -> F:
156        @functools.wraps(callback)
157        def wrapper(*args: typing.Any, **kwargs: typing.Any) -> F:
158            checker = _AttrCheck(
159                callback,
160                target_os=target_os,
161                python_version=python_version,
162                target_arch=target_arch,
163                impl=impl,
164            )
165            return checker(*args, **kwargs)
166
167        return typing.cast(F, wrapper)
168
169    return decorator

57@typing.runtime_checkable
58class Default(typing.Protocol[_T_co]):
59    """An interface for an object that has a default value.
60
61    Example
62    -------
63    ```py
64    from sain import Default
65
66    class Cache(Default[dict[str, Any]]):
67
68        @staticmethod
69        def default() -> dict[str, Any]:
70            return {}
71
72    cache = Cache.default()
73    print(cache)
74    assert isinstance(cache, Default)
75    # {}
76    ```
77    """
78
79    __slots__ = ()
80
81    @staticmethod
82    def default() -> _T_co:
83        """Return the default value of the object."""
84        raise NotImplementedError

 55@typing.final
 56class Some(typing.Generic[T], _default.Default["Option[None]"]):
 57    """The `Option` type. An object that might be `T` or `None`.
 58
 59    It is a drop-in replacement for `typing.Optional[T]`, But has proper methods to handle the contained value.
 60
 61    Example
 62    -------
 63    ```py
 64    value = Some("Hello")
 65    print(value)
 66    # Some("Hello")
 67
 68    # This will unwrap the contained value as long as
 69    # it is not `None` otherwise this will raise an error.
 70    print(value.unwrap())
 71    # "Hello"
 72
 73    none_value = Some(None)
 74    while none_value.unwrap():
 75        # Never unreachable!
 76
 77    # Solving it with `unwrap_or` method to unwrap the value or return a default value.
 78    print(none_value.unwrap_or(10))
 79    # 10
 80    ```
 81    """
 82
 83    __slots__ = ("_value", "__default")
 84    __match_args__ = ("_value",)
 85
 86    def __init__(self, value: T | None, /) -> None:
 87        self._value = value
 88
 89    @staticmethod
 90    def default() -> Option[None]:
 91        """Default value for `Some`. Returns `None` wrapped in `Some`.
 92
 93        Example
 94        -------
 95        ```py
 96        assert Some.default() == NOTHING
 97        ```
 98        """
 99        return NOTHING
100
101    # *- Reading the value -*
102
103    def into_inner(self) -> T | None:
104        """Consume `Self`, returning the wrapped value as `T | None`.
105
106        Examples
107        --------
108        ```py
109        opt = Some('char')
110        x = opt.into_inner()
111        assert x is not None
112
113        opt = Some(None)
114        assert opt.into_inner() is None
115        ```
116        """
117        return self._value
118
119    def unwrap(self) -> T:
120        """Unwrap the inner value either returning if its not `None` or raising a `RuntimeError`.
121
122        It's usually not recommended to use this method in production code, since it raises.
123
124        Example
125        -------
126        ```py
127        value = Some(5)
128        print(value.unwrap())
129        # 5
130
131        value = Some(None)
132        print(value.unwrap())
133        # RuntimeError
134        ```
135
136        Raises
137        ------
138        `RuntimeError`
139            If the inner value is `None`.
140        """
141        if self._value is None:
142            raise RuntimeError(
143                f"Called `Option.unwrap()` on {type(self._value).__name__}."
144            ) from None
145
146        return self._value
147
148    def unwrap_or(self, default: T, /) -> T:
149        """Unwrap the inner value either returning if its not `None` or returning `default`.
150
151        Example
152        -------
153        ```py
154        value = Some(5)
155        print(value.unwrap_or(10))
156        # 5
157
158        # Type hint is required here.
159        value: Option[int] = Some(None)
160        print(value.unwrap_or(10))
161        # 10
162        ```
163        """
164        if self._value is None:
165            return default
166
167        return self._value
168
169    def unwrap_or_else(self, f: FnOnce[T], /) -> T:
170        """Unwrap the inner value either returning if its not `None` or calling `f` to get a default value.
171
172        Example
173        -------
174        ```py
175        value = Some(5)
176        print(value.unwrap_or_else(lambda: 10))
177        # 5
178
179        value: Option[bool] = Some(None)
180        print(value.unwrap_or_else(lambda: True))
181        # True
182        ```
183        """
184        if self._value is None:
185            return f()
186
187        return self._value
188
189    @macros.unsafe
190    def unwrap_unchecked(self) -> T:
191        """Returns the contained Some value without checking that the value is not None.
192
193        Example
194        -------
195        ```py
196        v: Option[float] = Some(1.2)
197        v.unwrap_unchecked() # 1.2
198
199        v: Option[float] = Some(None)
200        print(v.unwrap_unchecked()) # Undefined Behavior
201        ```
202        """
203        #! SAFETY: The caller guarantees that the value is not None.
204        return self._value  # type: ignore
205
206    def expect(self, message: str, /) -> T:
207        """Returns the contained value if it is not `None` otherwise raises a `RuntimeError`.
208
209        Example
210        -------
211        ```py
212        value = Some("Hello")
213
214        print(value.expect("Value is None"))
215        # "Hello"
216
217        value: Option[str] = Some(None)
218        print(value.expect("Value is None"))
219        # RuntimeError("Value is None")
220        ```
221        """
222        if self._value is None:
223            raise RuntimeError(message)
224
225        return self._value
226
227    # *- Functional operations -*
228    def map(self, f: Fn[T, U], /) -> Some[U]:
229        """Map the inner value to another type. Returning `Some(None)` if `T` is `None`.
230
231        Example
232        -------
233        ```py
234        value = Some(5.0)
235
236        print(value.map(lambda x: x * 2.0))
237        # Some(10.0)
238
239        value: Option[bool] = Some(None)
240        print(value)
241        # Some(None)
242        ```
243        """
244        if self._value is None:
245            return nothing_unchecked()
246
247        return Some(f(self._value))
248
249    def map_or(self, default: U, f: Fn[T, U], /) -> U:
250        """Map the inner value to another type or return `default` if its `None`.
251
252        Example
253        -------
254        ```py
255        value: Option[float] = Some(5.0)
256
257        # map to int.
258        print(value.map_or(0, int))
259        # 6
260
261        value: Option[float] = Some(None)
262        print(value.map_or(0, int)
263        # 0
264        ```
265        """
266        if self._value is None:
267            return default
268
269        return f(self._value)
270
271    def map_or_else(self, default: FnOnce[U], f: Fn[T, U], /) -> U:
272        """Map the inner value to another type, or return `default()` if its `None`.
273
274        Example
275        -------
276        ```py
277        def default() -> int:
278            return sys.getsizeof(object())
279
280        value: Option[float] = Some(5.0)
281
282        # map to int.
283        print(value.map_or_else(default, int))
284        # 6
285
286        value: Option[float] = Some(None)
287        print(value.map_or_else(default, int)
288        # 28 <- size of object()
289        ```
290        """
291        if self._value is None:
292            return default()
293
294        return f(self._value)
295
296    def filter(self, predicate: Fn[T, bool]) -> Some[T]:
297        """Returns `Some(None)` if the contained value is `None`,
298
299        otherwise calls the predicate and returns `Some(T)` if the predicate returns `True`.
300
301        Example
302        -------
303        ```py
304        value = Some([1, 2, 3])
305
306        print(value.filter(lambda x: 1 in x))
307        # Some([1, 2, 3])
308
309        value: Option[int] = Some([1, 2, 3]) # or Some(None)
310        print(value.filter(lambda x: 1 not in x))
311        # None
312        ```
313        """
314        if (value := self._value) is not None:
315            if predicate(value):
316                return Some(value)
317
318        return nothing_unchecked()
319
320    # *- Inner operations *-
321
322    def take(self) -> Option[T]:
323        """Take the value from `Self`, Setting it to `None`.
324
325        Example
326        -------
327        ```py
328        original = Some("Hi")
329        new = original.take()
330
331        print(original, new)
332        # None, Some("Hi")
333        ```
334        """
335        if self._value is None:
336            return nothing_unchecked()
337
338        val = self._value
339        self._value = None
340        return Some(val)
341
342    def take_if(self, predicate: collections.Callable[[T], bool]) -> Option[T]:
343        """Take the value from `Self`, Setting it to `None` only if predicate returns `True`.
344
345        Example
346        -------
347        ```py
348        def validate(email: str) -> bool:
349            # you can obviously validate this better.
350            return email.find('@') == 1
351
352        original = Some("flex@gg.com")
353        valid = original.take_if(validate)
354        assert is_allowed.is_some() and original.is_none()
355
356        original = Some("mail.example.com")
357        invalid = original.take_if(validate)
358        assert invalid.is_none() and original.is_some()
359        ```
360        """
361        if self.map_or(False, predicate):
362            return self.take()
363
364        return nothing_unchecked()
365
366    def replace(self, value: T) -> Some[T]:
367        """Replace the contained value with another value.
368
369        Example
370        -------
371        ```py
372        value: Option[str] = Some(None)
373        value = value.replace("Hello")
374        # Some("Hello")
375        ```
376        """
377        self._value = value
378        return self
379
380    def and_ok(self, optb: Some[T]) -> Some[T]:
381        """Returns `Some(None)` if either contained value is `None`,
382
383        Otherwise return `optb`.
384
385        Example
386        -------
387        ```py
388        x: Option[int] = Some(None)
389        y: Option[str] = Some("bye")
390        assert x.and_ok(y).is_none()
391
392        x: Option[int] = Some(10)
393        y: Option[str] = Some("bye")
394        assert value.and_ok(y) == Some("bye")
395        ```
396        """
397        if self._value is None or optb.is_none():
398            return nothing_unchecked()
399
400        return optb
401
402    def and_then(self, f: Fn[T, Some[T]]) -> Some[T]:
403        """Returns `Some(None)` if the contained value is `None`, otherwise call `f()`
404        on `T` and return `Option[T]` if it's value not `None`.
405
406        Example
407        -------
408        ```py
409        value = Some(5)
410        print(value.and_then(lambda x: Some(x * 2)))
411        # Some(10)
412
413        value: Option[int] = Some(10)
414        print(value.and_then(lambda x: Some(None)))
415        # Some(None)
416        ```
417        """
418        if self._value is None:
419            return nothing_unchecked()
420
421        return f(self._value)
422
423    # *- Builder methods *-
424
425    def iter(self) -> _iter.Iterator[T]:
426        """Returns an iterator over the contained value.
427
428        Example
429        -------
430        ```py
431        from sain import Some
432        value = Some("gg")
433        value.next() == Some("gg")
434
435        value: Option[int] = Some(None)
436        value.next().is_none()
437        ```
438        """
439        if self._value is None:
440            #! SAFETY: We know the value is None here.
441            return _iter.empty()
442
443        return _iter.once(self._value)
444
445    def as_ref(self) -> Some[cell.Cell[T]]:
446        """Returns immutable `Some[sain.cell.Cell[T]]` if the contained value is not `None`,
447
448        Otherwise returns `Some(None)`.
449
450        Example
451        -------
452        ```py
453        value = Some(5).as_ref().unwrap()
454        value.object = 0 # FrozenError!
455
456        owned = value.object
457        print(owned) # 5
458
459        # Create a copy of object.
460        clone = value.copy()
461        clone = 0  # Thats fine.
462        print(clone == owned) # False, 0 != 5
463
464        # None object.
465        value: Option[int] = Some(None)
466        print(value.as_ref())
467        # Some(None)
468        ```
469
470        Raises
471        ------
472        `dataclasses.FrozenInstanceError`
473            When attempting to modify the contained value. Use `sain.AsRef.copy()` method to create a copy.
474
475            Or just use `.as_mut()` if you're dealing with mutable objects.
476        """
477        if self._value is not None:
478            return Some(cell.Cell(self._value))
479
480        # SAFETY: self._value is None.
481        return NOTHING  # pyright: ignore
482
483    def as_mut(self) -> Some[cell.RefCell[T]]:
484        """Returns mutable `Some[sain.cell.RefCell[T]]` if the contained value is not `None`,
485
486        Otherwise returns `Some(None)`.
487
488        Example
489        -------
490        ```py
491        value = Some(5).as_mut().unwrap()
492        value.object = 0
493        print(value) # Some(RefCell(0))
494
495        # None object.
496        value: Option[int] = Some(None)
497        print(value.as_mut())
498        # Some(None)
499        ```
500        """
501        if self._value is not None:
502            return Some(cell.RefCell(self._value))
503
504        # SAFETY: self._value is None.
505        return NOTHING  # pyright: ignore
506
507    # *- Boolean checks *-
508
509    def is_some(self) -> bool:
510        """Returns `True` if the contained value is not `None`, otherwise returns `False`.
511
512        Example
513        -------
514        ```py
515        value = Some(5)
516        print(value.is_some())
517        # True
518
519        value: Option[int] = Some(None)
520        print(value.is_some())
521        # False
522        ```
523        """
524        return self._value is not None
525
526    def is_some_and(self, predicate: Fn[T, bool]) -> bool:
527        """Returns `True` if the contained value is not `None` and
528        the predicate returns `True`, otherwise returns `False`.
529
530        Example
531        -------
532        ```py
533        value = Some(5)
534        print(value.is_some_and(lambda x: x > 3))
535        # True
536
537        value: Option[int] = Some(None)
538        print(value.is_some_and(lambda x: x > 3))
539        # False
540        ```
541        """
542        return self._value is not None and predicate(self._value)
543
544    def is_none(self) -> bool:
545        """Returns `True` if the contained value is `None`, otherwise returns `False`.
546
547        Example
548        -------
549        ```py
550        value = Some(5)
551        print(value.is_none())
552        # False
553
554        value: Option[int] = Some(None)
555        print(value.is_none())
556        # True
557        ```
558        """
559        return self._value is None
560
561    def __repr__(self) -> str:
562        if self._value is None:
563            return "None"
564        return f"Some({self._value!r})"
565
566    __str__ = __repr__
567
568    def __invert__(self) -> T:
569        return self.unwrap()
570
571    def __or__(self, other: T) -> T:
572        return self.unwrap_or(other)
573
574    def __bool__(self) -> bool:
575        return self.is_some()
576
577    def __eq__(self, other: object) -> bool:
578        if not isinstance(other, Some):
579            return NotImplemented
580
581        return self._value == other._value  # pyright: ignore[reportUnknownVariableType, reportUnknownMemberType]
582
583    def __ne__(self, other: object) -> bool:
584        return not self.__eq__(other)
585
586    def __hash__(self) -> int:
587        return hash(self._value)