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

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",)
 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 transpose(self) -> T | None:
104        """Convert `Option[T]` into `T | None`.
105
106        Examples
107        --------
108        ```py
109        opt = Some('char')
110        x = opt.transpose()
111        assert x == 'char'
112
113        opt = Some(None)
114        assert opt.transpose() 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("Called `Option.unwrap()` on `None`.") from None
143
144        return self._value
145
146    def unwrap_or(self, default: T, /) -> T:
147        """Unwrap the inner value either returning if its not `None` or returning `default`.
148
149        Example
150        -------
151        ```py
152        value = Some(5)
153        print(value.unwrap_or(10))
154        # 5
155
156        # Type hint is required here.
157        value: Option[int] = Some(None)
158        print(value.unwrap_or(10))
159        # 10
160        ```
161        """
162        if self._value is None:
163            return default
164
165        return self._value
166
167    def unwrap_or_else(self, f: FnOnce[T], /) -> T:
168        """Unwrap the inner value either returning if its not `None` or calling `f` to get a default value.
169
170        Example
171        -------
172        ```py
173        value = Some(5)
174        print(value.unwrap_or_else(lambda: 10))
175        # 5
176
177        value: Option[bool] = Some(None)
178        print(value.unwrap_or_else(lambda: True))
179        # True
180        ```
181        """
182        if self._value is None:
183            return f()
184
185        return self._value
186
187    @macros.unsafe
188    def unwrap_unchecked(self) -> T:
189        """Returns the contained Some value without checking that the value is not None.
190
191        Example
192        -------
193        ```py
194        v: Option[float] = Some(1.2)
195        v.unwrap_unchecked() # 1.2
196
197        v: Option[float] = Some(None)
198        print(v.unwrap_unchecked()) # Undefined Behavior
199        ```
200        """
201        #! SAFETY: The caller guarantees that the value is not None.
202        return self._value  # pyright: ignore
203
204    def expect(self, message: str, /) -> T:
205        """Returns the contained value if it is not `None` otherwise raises a `RuntimeError`.
206
207        Example
208        -------
209        ```py
210        value = Some("Hello")
211
212        print(value.expect("Value is None"))
213        # "Hello"
214
215        value: Option[str] = Some(None)
216        print(value.expect("Value is None"))
217        # RuntimeError("Value is None")
218        ```
219        """
220        if self._value is None:
221            raise RuntimeError(message)
222
223        return self._value
224
225    # *- object transformation -*
226
227    def map(self, f: Fn[T, U], /) -> Option[U]:
228        """Map the inner value to another type. Returning `Some(None)` if `T` is `None`.
229
230        Example
231        -------
232        ```py
233        value = Some(5.0)
234
235        print(value.map(lambda x: x * 2.0))
236        # Some(10.0)
237
238        value: Option[bool] = Some(None)
239        print(value)
240        # Some(None)
241        ```
242        """
243        if self._value is None:
244            return NOTHING  # pyright: ignore
245
246        return Some(f(self._value))
247
248    def map_or(self, default: U, f: Fn[T, U], /) -> U:
249        """Map the inner value to another type or return `default` if its `None`.
250
251        Example
252        -------
253        ```py
254        value: Option[float] = Some(5.0)
255
256        # map to int.
257        print(value.map_or(0, int))
258        # 6
259
260        value: Option[float] = Some(None)
261        print(value.map_or(0, int)
262        # 0
263        ```
264        """
265        if self._value is None:
266            return default
267
268        return f(self._value)
269
270    def map_or_else(self, default: FnOnce[U], f: Fn[T, U], /) -> U:
271        """Map the inner value to another type, or return `default()` if its `None`.
272
273        Example
274        -------
275        ```py
276        def default() -> int:
277            return sys.getsizeof(object())
278
279        value: Option[float] = Some(5.0)
280
281        # map to int.
282        print(value.map_or_else(default, int))
283        # 6
284
285        value: Option[float] = Some(None)
286        print(value.map_or_else(default, int)
287        # 28 <- size of object()
288        ```
289        """
290        if self._value is None:
291            return default()
292
293        return f(self._value)
294
295    def filter(self, predicate: Fn[T, bool]) -> Option[T]:
296        """Returns `Some(None)` if the contained value is `None`,
297
298        otherwise calls the predicate and returns `Some(T)` if the predicate returns `True`.
299
300        Example
301        -------
302        ```py
303        value = Some([1, 2, 3])
304
305        print(value.filter(lambda x: 1 in x))
306        # Some([1, 2, 3])
307
308        value: Option[int] = Some([1, 2, 3]) # or Some(None)
309        print(value.filter(lambda x: 1 not in x))
310        # None
311        ```
312        """
313        if (value := self._value) is not None:
314            if predicate(value):
315                return Some(value)
316
317        return NOTHING  # pyright: ignore
318
319    def ok_or(self, err: U) -> _result.Result[T, U]:
320        """Transforms the `Option<T>` into a `Result<T, E>`, mapping `Some(v)` to `Ok(v)` and `None` to `Err(err)`.
321
322        Example
323        -------
324        ```py
325        xyz: Option[str] = Some("foo")
326        assert xyz.ok_or(None) == Ok("foo")
327
328        xyz: Option[str] = Some(None)
329        assert xyz.ok_or(None) == Err(None)
330        ```
331        """
332        if self._value is None:
333            return _result.Err(err)
334
335        return _result.Ok(self._value)
336
337    def ok_or_else(self, err: FnOnce[U]) -> _result.Result[T, U]:
338        """Transforms the `Option<T>` into a `Result<T, E>`, mapping `Some(v)` to `Ok(v)` and `None` to `Err(err())`.
339
340        Example
341        -------
342        ```py
343        xyz: Option[str] = Some("foo")
344        assert xyz.ok_or(None) == Ok("foo")
345
346        xyz: Option[str] = Some(None)
347        assert xyz.ok_or(None) == Err(None)
348        ```
349        """
350        if self._value is None:
351            return _result.Err(err())
352
353        return _result.Ok(self._value)
354
355    def zip(self, other: Option[U]) -> Option[tuple[T, U]]:
356        """Zips `self` with `other`.
357
358        if `self` is `Some(s)` and other is `Some(o)`, this returns `Some((s, o))` otherwise `None`.
359
360        Example
361        -------
362        ```py
363        x = Some(1)
364        y = Some("hi")
365        z: Option[str] = Some(None)
366
367        assert x.zip(y) == Some((1, "hi"))
368        assert x.zip(z) == Some(None)
369        ```
370        """
371        if self._value is not None and other._value is not None:
372            return Some((self._value, other._value))
373
374        return NOTHING  # type: ignore
375
376    def zip_with(
377        self, other: Option[U], f: collections.Callable[[T, U], T_co]
378    ) -> Option[T_co]:
379        """Zips `self` with `other` using function `f`.
380
381        if `self` is `Some(s)` and other is `Some(o)`, this returns `Some(f(s, o))` otherwise `None`.
382
383        Example
384        -------
385        ```py
386        @dataclass
387        class Point:
388            x: float
389            y: float
390
391        x, y = Some(32.1), Some(42.4)
392        assert x.zip_with(y, Point) == Some(Point(32.1, 42.4))
393        ```
394        """
395        if self._value is not None and other._value is not None:
396            return Some(f(self._value, other._value))
397
398        return NOTHING  # type: ignore
399
400    # *- Inner operations *-
401
402    def take(self) -> Option[T]:
403        """Take the value from `Self`, Setting it to `None`.
404
405        Example
406        -------
407        ```py
408        original = Some("Hi")
409        new = original.take()
410
411        print(original, new)
412        # None, Some("Hi")
413        ```
414        """
415        if self._value is None:
416            return NOTHING  # pyright: ignore
417
418        val = self._value
419        self._value = None
420        return Some(val)
421
422    def take_if(self, predicate: collections.Callable[[T], bool]) -> Option[T]:
423        """Take the value from `Self`, Setting it to `None` only if predicate returns `True`.
424
425        Example
426        -------
427        ```py
428        def validate(email: str) -> bool:
429            # you can obviously validate this better.
430            return email.find('@') == 1
431
432        original = Some("flex@gg.com")
433        valid = original.take_if(validate)
434        assert is_allowed.is_some() and original.is_none()
435
436        original = Some("mail.example.com")
437        invalid = original.take_if(validate)
438        assert invalid.is_none() and original.is_some()
439        ```
440        """
441        if self.map_or(False, predicate):
442            return self.take()
443
444        return NOTHING  # pyright: ignore
445
446    def replace(self, value: T) -> Option[T]:
447        """Replace the contained value with another value.
448
449        Use `Option.insert` if you want to return the original value
450        that got inserted instead of `self`
451
452        Example
453        -------
454        ```py
455        value: Option[str] = Some(None)
456        value.replace("Hello")
457        # Some("Hello")
458        ```
459        """
460        self._value = value
461        return self
462
463    def insert(self, value: T) -> T:
464        """Insert a value into the option, and then return a reference to it.
465
466        This will overwrite the old value if it was already contained.
467
468        Example
469        -------
470        ```py
471        flag: Option[bool] = Some(None)
472        flag_ref = flag.insert(True)
473        assert flag_ref == True
474        assert flag.unwrap() == True
475        ```
476        """
477        self._value = value
478        return value
479
480    def get_or_insert(self, value: T) -> T:
481        """Insert a value into the option if it was `None`,
482        and then return a reference to it.
483
484        Example
485        -------
486        ```py
487        state: Option[bool] = Some(None)
488        assert state.get_or_insert(True) is True
489        assert state.get_or_insert(False) is True
490        ```
491        """
492        if self._value is not None:
493            return self._value
494
495        self._value = value
496        return value
497
498    def get_or_insert_with(self, f: FnOnce[T]) -> T:
499        """Insert a value into the option computed from `f()` if it was `None`,
500        and then return a reference to it.
501
502        Example
503        -------
504        ```py
505        flag: Option[bool] = Some(None)
506        flag_ref = flag.insert(True)
507        assert flag_ref == True
508        assert flag.unwrap() == True
509        ```
510        """
511        if self._value is not None:
512            return self._value
513
514        v = self._value = f()
515        return v
516
517    def and_ok(self, optb: Option[T]) -> Option[T]:
518        """Returns `None` if `self` or `optb` is `None`, otherwise return `optb`.
519
520        aliases: `Option::and`
521
522        Example
523        -------
524        ```py
525        x = Some(1)
526        y: Option[str] = Some(None)
527        assert x.and_ok(y) == Some(None)
528
529        x: Option[str] = Some(None)
530        y = Some(1)
531        assert x.and_ok(y) == Some(None)
532
533        y: Option[str] = Some("hi")
534        y = Some(100)
535        assert x.and_ok(y) == Some(100)
536        ```
537        """
538        if self._value is None or optb._value is None:
539            return optb
540
541        return NOTHING  # pyright: ignore
542
543    def and_then(self, f: Fn[T, Option[T]]) -> Option[T]:
544        """Returns `Some(None)` if the contained value is `None`, otherwise call `f()`
545        on `T` and return `Option[T]`.
546
547        Example
548        -------
549        ```py
550        value = Some(5)
551        print(value.and_then(lambda x: Some(x * 2)))
552        # Some(10)
553
554        value: Option[int] = Some(None)
555        print(value.and_then(lambda x: Some(x * 2)))
556        # Some(None)
557        ```
558        """
559        if self._value is None:
560            return NOTHING  # pyright: ignore
561
562        return f(self._value)
563
564    def inspect(self, f: Fn[T, typing.Any]) -> Option[T]:
565        """Calls `f()` on the contained value if it was `Some(v)`, otherwise does nothing.
566
567        Example
568        -------
569        ```py
570        def debug(x: str) -> None:
571            print("Debugging:", x)
572
573        value = Some("foo")
574        inner = value.inspect(debug).expect("no value to debug")
575        # prints: Debugging: "foo"
576
577        value: Option[str] = Some(None)
578        value.inspect(debug) # prints nothing
579        """
580        if self._value is not None:
581            f(self._value)
582
583        return self
584
585    # *- Builder methods *-
586
587    def iter(self) -> _iter.Iterator[T]:
588        """Returns an iterator over the contained value.
589
590        Example
591        -------
592        ```py
593        from sain import Some
594        value = Some("gg").iter()
595        assert value.next() == Some("gg")
596
597        value: Option[int] = Some(None)
598        assert value.iter().next().is_none()
599        ```
600        """
601        if self._value is None:
602            return _iter.empty()
603
604        return _iter.once(self._value)
605
606    # *- Boolean checks *-
607
608    def is_some(self) -> bool:
609        """Returns `True` if the contained value is not `None`, otherwise returns `False`.
610
611        Example
612        -------
613        ```py
614        value = Some(5)
615        print(value.is_some())
616        # True
617
618        value: Option[int] = Some(None)
619        print(value.is_some())
620        # False
621        ```
622        """
623        return self._value is not None
624
625    def is_some_and(self, predicate: Fn[T, bool]) -> bool:
626        """Returns `True` if the contained value is not `None` and
627        the predicate returns `True`, otherwise returns `False`.
628
629        Example
630        -------
631        ```py
632        value = Some(5)
633        print(value.is_some_and(lambda x: x > 3))
634        # True
635
636        value: Option[int] = Some(None)
637        print(value.is_some_and(lambda x: x > 3))
638        # False
639        ```
640        """
641        return self._value is not None and predicate(self._value)
642
643    def is_none(self) -> bool:
644        """Returns `True` if the contained value is `None`, otherwise returns `False`.
645
646        Example
647        -------
648        ```py
649        value = Some(5)
650        print(value.is_none())
651        # False
652
653        value: Option[int] = Some(None)
654        print(value.is_none())
655        # True
656        ```
657        """
658        return self._value is None
659
660    def is_none_or(self, f: Fn[T, bool]) -> bool:
661        """Returns `True` if the contained value is `None` or the predicate returns `True`,
662        otherwise returns `False`.
663
664        Example
665        -------
666        ```py
667        value = Some(5)
668        print(value.is_none_or(lambda x: x > 3))
669        # False
670
671        value: Option[int] = Some(None)
672        print(value.is_none_or(lambda x: x > 3))
673        # True
674        ```
675        """
676        match self._value:
677            case None:
678                return True
679            case x:
680                return f(x)
681
682    def __repr__(self) -> str:
683        if self._value is None:
684            return "None"
685        return f"Some({self._value!r})"
686
687    __str__ = __repr__
688
689    def __invert__(self) -> T:
690        return self.unwrap()
691
692    def __or__(self, other: T) -> T:
693        return self.unwrap_or(other)
694
695    def __bool__(self) -> bool:
696        return self.is_some()
697
698    def __eq__(self, other: object) -> bool:
699        if not isinstance(other, Some):
700            return NotImplemented
701
702        return self._value == other._value  # pyright: ignore[reportUnknownVariableType, reportUnknownMemberType]
703
704    def __ne__(self, other: object) -> bool:
705        return not self.__eq__(other)
706
707    def __hash__(self) -> int:
708        return hash(self._value)