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

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

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

 56@rustc_diagnostic_item("Option")
 57@typing.final
 58class Some(typing.Generic[T], _default.Default["Option[None]"]):
 59    """The `Option` type. An object that might be `T` or `None`.
 60
 61    It is a replacement for `typing.Optional[T]`, with more convenient methods to handle the contained value.
 62
 63    Example
 64    -------
 65    ```py
 66    value = Some("Hello")
 67    print(value)
 68    # Some("Hello")
 69
 70    # This will unwrap the contained value as long as
 71    # it is not `None` otherwise this will raise an error.
 72    print(value.unwrap())
 73    # "Hello"
 74
 75    none_value = Some(None)
 76    while none_value.unwrap():
 77        # Never unreachable!
 78
 79    # Solving it with `unwrap_or` method to unwrap the value or return a default value.
 80    print(none_value.unwrap_or(10))
 81    # 10
 82    ```
 83    """
 84
 85    __slots__ = ("_value",)
 86    __match_args__ = ("_value",)
 87
 88    def __init__(self, value: T | None, /) -> None:
 89        self._value = value
 90
 91    @staticmethod
 92    def default() -> Option[None]:
 93        """Default value for `Some`. Returns `None` wrapped in `Some`.
 94
 95        Example
 96        -------
 97        ```py
 98        assert Some.default() == NOTHING
 99        ```
100        """
101        return NOTHING
102
103    # *- Reading the value -*
104
105    def transpose(self) -> T | None:
106        """Convert `Option[T]` into `T | None`.
107
108        Examples
109        --------
110        ```py
111        opt = Some('char')
112        x = opt.transpose()
113        assert x == 'char'
114
115        opt = Some(None)
116        assert opt.transpose() is None
117        ```
118        """
119        return self._value
120
121    def unwrap(self) -> T:
122        """Unwrap the inner value either returning if its not `None` or raising a `RuntimeError`.
123
124        It's usually not recommended to use this method in production code, since it raises.
125
126        Example
127        -------
128        ```py
129        value = Some(5)
130        print(value.unwrap())
131        # 5
132
133        value = Some(None)
134        print(value.unwrap())
135        # RuntimeError
136        ```
137
138        Raises
139        ------
140        `RuntimeError`
141            If the inner value is `None`.
142        """
143        if self._value is None:
144            raise RuntimeError("Called `Option.unwrap()` on `None`.") 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  # pyright: 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    # *- object transformation -*
228
229    def map(self, f: Fn[T, U], /) -> Option[U]:
230        """Map the inner value to another type. Returning `Some(None)` if `T` is `None`.
231
232        Example
233        -------
234        ```py
235        value = Some(5.0)
236
237        print(value.map(lambda x: x * 2.0))
238        # Some(10.0)
239
240        value: Option[bool] = Some(None)
241        print(value)
242        # Some(None)
243        ```
244        """
245        if self._value is None:
246            return NOTHING  # pyright: ignore
247
248        return Some(f(self._value))
249
250    def map_or(self, default: U, f: Fn[T, U], /) -> U:
251        """Map the inner value to another type or return `default` if its `None`.
252
253        Example
254        -------
255        ```py
256        value: Option[float] = Some(5.0)
257
258        # map to int.
259        print(value.map_or(0, int))
260        # 6
261
262        value: Option[float] = Some(None)
263        print(value.map_or(0, int)
264        # 0
265        ```
266        """
267        if self._value is None:
268            return default
269
270        return f(self._value)
271
272    def map_or_else(self, default: FnOnce[U], f: Fn[T, U], /) -> U:
273        """Map the inner value to another type, or return `default()` if its `None`.
274
275        Example
276        -------
277        ```py
278        def default() -> int:
279            return sys.getsizeof(object())
280
281        value: Option[float] = Some(5.0)
282
283        # map to int.
284        print(value.map_or_else(default, int))
285        # 6
286
287        value: Option[float] = Some(None)
288        print(value.map_or_else(default, int)
289        # 28 <- size of object()
290        ```
291        """
292        if self._value is None:
293            return default()
294
295        return f(self._value)
296
297    def filter(self, predicate: Fn[T, bool]) -> Option[T]:
298        """Returns `Some(None)` if the contained value is `None`,
299
300        otherwise calls the predicate and returns `Some(T)` if the predicate returns `True`.
301
302        Example
303        -------
304        ```py
305        value = Some([1, 2, 3])
306
307        print(value.filter(lambda x: 1 in x))
308        # Some([1, 2, 3])
309
310        value: Option[int] = Some([1, 2, 3]) # or Some(None)
311        print(value.filter(lambda x: 1 not in x))
312        # None
313        ```
314        """
315        if (value := self._value) is not None:
316            if predicate(value):
317                return Some(value)
318
319        return NOTHING  # pyright: ignore
320
321    def ok_or(self, err: U) -> _result.Result[T, U]:
322        """Transforms the `Option<T>` into a `Result<T, E>`, mapping `Some(v)` to `Ok(v)` and `None` to `Err(err)`.
323
324        Example
325        -------
326        ```py
327        xyz: Option[str] = Some("foo")
328        assert xyz.ok_or(None) == Ok("foo")
329
330        xyz: Option[str] = Some(None)
331        assert xyz.ok_or(None) == Err(None)
332        ```
333        """
334        if self._value is None:
335            return _result.Err(err)
336
337        return _result.Ok(self._value)
338
339    def ok_or_else(self, err: FnOnce[U]) -> _result.Result[T, U]:
340        """Transforms the `Option<T>` into a `Result<T, E>`, mapping `Some(v)` to `Ok(v)` and `None` to `Err(err())`.
341
342        Example
343        -------
344        ```py
345        xyz: Option[str] = Some("foo")
346        assert xyz.ok_or(None) == Ok("foo")
347
348        xyz: Option[str] = Some(None)
349        assert xyz.ok_or(None) == Err(None)
350        ```
351        """
352        if self._value is None:
353            return _result.Err(err())
354
355        return _result.Ok(self._value)
356
357    def zip(self, other: Option[U]) -> Option[tuple[T, U]]:
358        """Zips `self` with `other`.
359
360        if `self` is `Some(s)` and other is `Some(o)`, this returns `Some((s, o))` otherwise `None`.
361
362        Example
363        -------
364        ```py
365        x = Some(1)
366        y = Some("hi")
367        z: Option[str] = Some(None)
368
369        assert x.zip(y) == Some((1, "hi"))
370        assert x.zip(z) == Some(None)
371        ```
372        """
373        if self._value is not None and other._value is not None:
374            return Some((self._value, other._value))
375
376        return NOTHING  # type: ignore
377
378    def zip_with(
379        self, other: Option[U], f: collections.Callable[[T, U], T_co]
380    ) -> Option[T_co]:
381        """Zips `self` with `other` using function `f`.
382
383        if `self` is `Some(s)` and other is `Some(o)`, this returns `Some(f(s, o))` otherwise `None`.
384
385        Example
386        -------
387        ```py
388        @dataclass
389        class Point:
390            x: float
391            y: float
392
393        x, y = Some(32.1), Some(42.4)
394        assert x.zip_with(y, Point) == Some(Point(32.1, 42.4))
395        ```
396        """
397        if self._value is not None and other._value is not None:
398            return Some(f(self._value, other._value))
399
400        return NOTHING  # type: ignore
401
402    # *- Inner operations *-
403
404    def take(self) -> Option[T]:
405        """Take the value from `Self`, Setting it to `None`.
406
407        Example
408        -------
409        ```py
410        original = Some("Hi")
411        new = original.take()
412
413        print(original, new)
414        # None, Some("Hi")
415        ```
416        """
417        if self._value is None:
418            return NOTHING  # pyright: ignore
419
420        val = self._value
421        self._value = None
422        return Some(val)
423
424    def take_if(self, predicate: collections.Callable[[T], bool]) -> Option[T]:
425        """Take the value from `Self`, Setting it to `None` only if predicate returns `True`.
426
427        Example
428        -------
429        ```py
430        def validate(email: str) -> bool:
431            # you can obviously validate this better.
432            return email.find('@') == 1
433
434        original = Some("flex@gg.com")
435        valid = original.take_if(validate)
436        assert is_allowed.is_some() and original.is_none()
437
438        original = Some("mail.example.com")
439        invalid = original.take_if(validate)
440        assert invalid.is_none() and original.is_some()
441        ```
442        """
443        if self.map_or(False, predicate):
444            return self.take()
445
446        return NOTHING  # pyright: ignore
447
448    def replace(self, value: T) -> Option[T]:
449        """Replace the contained value with another value.
450
451        Use `Option.insert` if you want to return the original value
452        that got inserted instead of `self`
453
454        Example
455        -------
456        ```py
457        value: Option[str] = Some(None)
458        value.replace("Hello")
459        # Some("Hello")
460        ```
461        """
462        self._value = value
463        return self
464
465    def insert(self, value: T) -> T:
466        """Insert a value into the option, and then return a reference to it.
467
468        This will overwrite the old value if it was already contained.
469
470        Example
471        -------
472        ```py
473        flag: Option[bool] = Some(None)
474        flag_ref = flag.insert(True)
475        assert flag_ref == True
476        assert flag.unwrap() == True
477        ```
478        """
479        self._value = value
480        return value
481
482    def get_or_insert(self, value: T) -> T:
483        """Insert a value into the option if it was `None`,
484        and then return a reference to it.
485
486        Example
487        -------
488        ```py
489        state: Option[bool] = Some(None)
490        assert state.get_or_insert(True) is True
491        assert state.get_or_insert(False) is True
492        ```
493        """
494        if self._value is not None:
495            return self._value
496
497        self._value = value
498        return value
499
500    def get_or_insert_with(self, f: FnOnce[T]) -> T:
501        """Insert a value into the option computed from `f()` if it was `None`,
502        and then return a reference to it.
503
504        Example
505        -------
506        ```py
507        flag: Option[bool] = Some(None)
508        flag_ref = flag.insert(True)
509        assert flag_ref == True
510        assert flag.unwrap() == True
511        ```
512        """
513        if self._value is not None:
514            return self._value
515
516        v = self._value = f()
517        return v
518
519    def and_ok(self, optb: Option[T]) -> Option[T]:
520        """Returns `None` if `self` or `optb` is `None`, otherwise return `optb`.
521
522        aliases: `Option::and`
523
524        Example
525        -------
526        ```py
527        x = Some(1)
528        y: Option[str] = Some(None)
529        assert x.and_ok(y) == Some(None)
530
531        x: Option[str] = Some(None)
532        y = Some(1)
533        assert x.and_ok(y) == Some(None)
534
535        y: Option[str] = Some("hi")
536        y = Some(100)
537        assert x.and_ok(y) == Some(100)
538        ```
539        """
540        if self._value is None or optb._value is None:
541            return optb
542
543        return NOTHING  # pyright: ignore
544
545    def and_then(self, f: Fn[T, Option[T]]) -> Option[T]:
546        """Returns `Some(None)` if the contained value is `None`, otherwise call `f()`
547        on `T` and return `Option[T]`.
548
549        Example
550        -------
551        ```py
552        value = Some(5)
553        print(value.and_then(lambda x: Some(x * 2)))
554        # Some(10)
555
556        value: Option[int] = Some(None)
557        print(value.and_then(lambda x: Some(x * 2)))
558        # Some(None)
559        ```
560        """
561        if self._value is None:
562            return NOTHING  # pyright: ignore
563
564        return f(self._value)
565
566    def inspect(self, f: Fn[T, typing.Any]) -> Option[T]:
567        """Calls `f()` on the contained value if it was `Some(v)`, otherwise does nothing.
568
569        Example
570        -------
571        ```py
572        def debug(x: str) -> None:
573            print("Debugging:", x)
574
575        value = Some("foo")
576        inner = value.inspect(debug).expect("no value to debug")
577        # prints: Debugging: "foo"
578
579        value: Option[str] = Some(None)
580        value.inspect(debug) # prints nothing
581        """
582        if self._value is not None:
583            f(self._value)
584
585        return self
586
587    # *- Builder methods *-
588
589    def iter(self) -> _iter.Iterator[T]:
590        """Returns an iterator over the contained value.
591
592        Example
593        -------
594        ```py
595        from sain import Some
596        value = Some("gg").iter()
597        assert value.next() == Some("gg")
598
599        value: Option[int] = Some(None)
600        assert value.iter().next().is_none()
601        ```
602        """
603        if self._value is None:
604            return _iter.empty()
605
606        return _iter.once(self._value)
607
608    # *- Boolean checks *-
609
610    def is_some(self) -> bool:
611        """Returns `True` if the contained value is not `None`, otherwise returns `False`.
612
613        Example
614        -------
615        ```py
616        value = Some(5)
617        print(value.is_some())
618        # True
619
620        value: Option[int] = Some(None)
621        print(value.is_some())
622        # False
623        ```
624        """
625        return self._value is not None
626
627    def is_some_and(self, predicate: Fn[T, bool]) -> bool:
628        """Returns `True` if the contained value is not `None` and
629        the predicate returns `True`, otherwise returns `False`.
630
631        Example
632        -------
633        ```py
634        value = Some(5)
635        print(value.is_some_and(lambda x: x > 3))
636        # True
637
638        value: Option[int] = Some(None)
639        print(value.is_some_and(lambda x: x > 3))
640        # False
641        ```
642        """
643        return self._value is not None and predicate(self._value)
644
645    def is_none(self) -> bool:
646        """Returns `True` if the contained value is `None`, otherwise returns `False`.
647
648        Example
649        -------
650        ```py
651        value = Some(5)
652        print(value.is_none())
653        # False
654
655        value: Option[int] = Some(None)
656        print(value.is_none())
657        # True
658        ```
659        """
660        return self._value is None
661
662    def is_none_or(self, f: Fn[T, bool]) -> bool:
663        """Returns `True` if the contained value is `None` or the predicate returns `True`,
664        otherwise returns `False`.
665
666        Example
667        -------
668        ```py
669        value = Some(5)
670        print(value.is_none_or(lambda x: x > 3))
671        # False
672
673        value: Option[int] = Some(None)
674        print(value.is_none_or(lambda x: x > 3))
675        # True
676        ```
677        """
678        match self._value:
679            case None:
680                return True
681            case x:
682                return f(x)
683
684    def __repr__(self) -> str:
685        if self._value is None:
686            return "None"
687        return f"Some({self._value!r})"
688
689    __str__ = __repr__
690
691    def __invert__(self) -> T:
692        return self.unwrap()
693
694    def __or__(self, other: T) -> T:
695        return self.unwrap_or(other)
696
697    def __bool__(self) -> bool:
698        return self.is_some()
699
700    def __eq__(self, other: object) -> bool:
701        if not isinstance(other, Some):
702            return NotImplemented
703
704        return self._value == other._value  # pyright: ignore[reportUnknownVariableType, reportUnknownMemberType]
705
706    def __ne__(self, other: object) -> bool:
707        return not self.__eq__(other)
708
709    def __hash__(self) -> int:
710        return hash(self._value)