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

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

59@rustc_diagnostic_item("Default")
60@typing.runtime_checkable
61class Default(typing.Protocol[_T_co]):
62    """An interface for an object that has a default value.
63
64    Example
65    -------
66    ```py
67    from sain import Default
68
69    class Cache(Default[dict[str, Any]]):
70
71        @staticmethod
72        def default() -> dict[str, Any]:
73            return {}
74
75    cache = Cache.default()
76    print(cache)
77    assert isinstance(cache, Default)
78    # {}
79    ```
80    """
81
82    __slots__ = ()
83
84    # FIXME: `impl Default for String` knows the type of `Self` is `String` but we can't do that.
85    # So generics is the only way to achieve the same effect. But `Default` in Rust is not generic.
86    # in the future we just swap to `Self`.
87    @staticmethod
88    @rustc_diagnostic_item("default_fn")
89    def default() -> _T_co:
90        """Return the default value of the object."""
91        raise NotImplementedError

 56@rustc_diagnostic_item("Option")
 57@typing.final
 58class Some(
 59    typing.Generic[T],
 60    _default.Default["Option[T]"],
 61):
 62    """The `Option` type represents optional value, higher-level abstraction over the `None` type.
 63
 64    It combines union of `T | None` in one convenient structure, allowing the users to manipulate and propagate
 65    the contained value idiomatically.
 66
 67    An `Option` value have multiple use cases:
 68
 69    * Initial values.
 70    * Return value for functions that may or may not contain a return value.
 71    * Optional parameters, class fields.
 72    * Swapping values.
 73
 74    Example
 75    -------
 76    ```py
 77    # the actual implementation of the object.
 78    from sain import Some
 79    # Here `Option` is used for type-hints only, you can include it under `TYPE_CHECKING` if you'd like.
 80    from sain import Option
 81
 82    def divide(numerator: float, denominator: float) -> Option[float]:
 83        if denominator == 0.0:
 84            return Some(None)
 85        return Some(numerator / denominator)
 86
 87    # Returns Option[float]
 88    result = divide(2.0, 3.0)
 89
 90    # Pattern match to retrieve the value
 91    match result:
 92        # The division is valid.
 93        case Some(x):
 94            print("Result:", x)
 95        # Invalid division, this is Some(None)
 96        case _:
 97            print("cannot divide by 0")
 98    ```
 99
100    ### Converting `None`s into `RuntimeError`s
101
102    Sometimes we want to extract the value and cause an error to the caller if it doesn't exist,
103
104    because handling `Some/None` can be tedious, luckily we have several ways to deal with this.
105
106    ```py
107    def ipaddr(s: str) -> Option[tuple[int, int, int, int]]:
108        match s.split('.'):
109            case [a, b, c, d]:
110                return Some((int(a), int(b), int(c), int(d)))
111            case _:
112                return Some(None)
113
114    # calls `unwrap()` for you.
115    ip = ~ipaddr("192.168.1.19")
116    # causes a `RuntimeError` if it returns `None`.
117    ip = ipaddr("192.168.1.19").unwrap()
118    # causes a `RuntimeError` if it returns `None`, with a context message.
119    ip = ipaddr("192.168.1.19").expect("i need an ip address :<")
120    ```
121
122    The `~` operator will result in `tuple[int, int, int, int]` if the parsing succeed.
123    unless the contained value is `None`, it will cause a `RuntimeError`.
124
125    If the value must be present, use `unwrap_or`, which takes a default parameter
126    and returns it in-case `ipaddr` returns `None`
127    ```py
128    ip = ipaddr("blah blah blah").unwrap_or("192.168.1.255")
129    # Results: 192.168.1.255
130    ```
131
132    Overall, this type provides many other functional methods such as `map`, `filter`.
133
134    boolean checks such as `is_some`, `is_none`, converting between `Option` and `Result` using `ok_or`, and many more.
135    """
136
137    __slots__ = ("_value",)
138    __match_args__ = ("_value",)
139
140    def __init__(self, value: T | None, /) -> None:
141        self._value = value
142
143    @staticmethod
144    def default() -> Option[T]:
145        """Default value for `Option<T>`. Returns `None` wrapped in `Some`.
146
147        Example
148        -------
149        ```py
150        assert Some[int].default() is NOTHING
151        ```
152        """
153        return NOTHING
154
155    # *- Reading the value -*
156
157    def transpose(self) -> T | None:
158        """Convert `Option[T]` into `T | None`.
159
160        Examples
161        --------
162        ```py
163        opt = Some('char')
164        x = opt.transpose()
165        assert x == 'char'
166
167        opt = Some(None)
168        assert opt.transpose() is None
169        ```
170        """
171        return self._value
172
173    def unwrap(self) -> T:
174        """Unwrap the inner value either returning if its not `None` or raising a `RuntimeError`.
175
176        It's usually not recommended to use this method in production code, and instead use safer options such as `unwrap_or` or match patterns.
177
178        Example
179        -------
180        ```py
181        value = Some(5)
182        print(value.unwrap())
183        # 5
184
185        value = Some(None)
186        print(value.unwrap())
187        # RuntimeError
188        ```
189
190        Raises
191        ------
192        `RuntimeError`
193            If the inner value is `None`.
194        """
195        if self._value is None:
196            raise RuntimeError("Called `Option.unwrap()` on `None`.") from None
197
198        return self._value
199
200    def unwrap_or(self, default: T, /) -> T:
201        """Unwrap the inner value either returning if its not `None` or returning `default`.
202
203        Example
204        -------
205        ```py
206        value = Some(5)
207        print(value.unwrap_or(10))
208        # 5
209
210        # Type hint is required here.
211        value: Option[int] = Some(None)
212        print(value.unwrap_or(10))
213        # 10
214        ```
215        """
216        if self._value is None:
217            return default
218
219        return self._value
220
221    def unwrap_or_else(self, f: FnOnce[T], /) -> T:
222        """Unwrap the inner value either returning if its not `None` or calling `f` to get a default value.
223
224        Example
225        -------
226        ```py
227        value = Some(5)
228        print(value.unwrap_or_else(lambda: 10))
229        # 5
230
231        value: Option[bool] = Some(None)
232        print(value.unwrap_or_else(lambda: True))
233        # True
234        ```
235        """
236        if self._value is None:
237            return f()
238
239        return self._value
240
241    @macros.unsafe
242    def unwrap_unchecked(self) -> T:
243        """Returns the contained Some value without checking that the value is not None.
244
245        Example
246        -------
247        ```py
248        v: Option[float] = Some(1.2)
249        v.unwrap_unchecked() # 1.2
250
251        v: Option[float] = Some(None)
252        print(v.unwrap_unchecked()) # Undefined Behavior
253        ```
254        """
255        #! SAFETY: The caller guarantees that the value is not None.
256        return self._value  # pyright: ignore
257
258    def expect(self, message: str, /) -> T:
259        """Returns the contained `Some` value.
260
261        raises if the value is `None` with a custom provided `message`.
262
263        Example
264        -------
265        ```py
266        value = Some("Hello")
267
268        print(value.expect("Value is None"))
269        # "Hello"
270
271        value: Option[str] = Some(None)
272        print(value.expect("Value is None"))
273        # RuntimeError("Value is None")
274        ```
275        """
276        if self._value is None:
277            raise RuntimeError(message)
278
279        return self._value
280
281    # *- object transformation -*
282
283    def map(self, f: Fn[T, U], /) -> Option[U]:
284        """Map the inner value to another type. Returning `Some(None)` if `T` is `None`.
285
286        Example
287        -------
288        ```py
289        value = Some(5.0)
290
291        print(value.map(lambda x: x * 2.0))
292        # Some(10.0)
293
294        value: Option[bool] = Some(None)
295        print(value)
296        # Some(None)
297        ```
298        """
299        if self._value is None:
300            return NOTHING
301
302        return Some(f(self._value))
303
304    def map_or(self, default: U, f: Fn[T, U], /) -> U:
305        """Map the inner value to another type or return `default` if its `None`.
306
307        Example
308        -------
309        ```py
310        value: Option[float] = Some(5.0)
311
312        # map to int.
313        print(value.map_or(0, int))
314        # 6
315
316        value: Option[float] = Some(None)
317        print(value.map_or(0, int)
318        # 0
319        ```
320        """
321        if self._value is None:
322            return default
323
324        return f(self._value)
325
326    def map_or_else(self, default: FnOnce[U], f: Fn[T, U], /) -> U:
327        """Map the inner value to another type, or return `default()` if its `None`.
328
329        Example
330        -------
331        ```py
332        def default() -> int:
333            return sys.getsizeof(object())
334
335        value: Option[float] = Some(5.0)
336
337        # map to int.
338        print(value.map_or_else(default, int))
339        # 6
340
341        value: Option[float] = Some(None)
342        print(value.map_or_else(default, int)
343        # 28 <- size of object()
344        ```
345        """
346        if self._value is None:
347            return default()
348
349        return f(self._value)
350
351    def filter(self, predicate: Fn[T, bool]) -> Option[T]:
352        """Returns `Some(None)` if the contained value is `None`,
353
354        otherwise calls the predicate and returns `Some(T)` if the predicate returns `True`.
355
356        Example
357        -------
358        ```py
359        value = Some([1, 2, 3])
360
361        print(value.filter(lambda x: 1 in x))
362        # Some([1, 2, 3])
363
364        value: Option[int] = Some([1, 2, 3]) # or Some(None)
365        print(value.filter(lambda x: 1 not in x))
366        # None
367        ```
368        """
369        if (value := self._value) is not None:
370            if predicate(value):
371                return Some(value)
372
373        return NOTHING
374
375    def ok_or(self, err: U) -> _result.Result[T, U]:
376        """Transforms the `Option<T>` into a `Result<T, E>`, mapping `Some(v)` to `Ok(v)` and `None` to `Err(err)`.
377
378        Example
379        -------
380        ```py
381        xyz: Option[str] = Some("foo")
382        assert xyz.ok_or(None) == Ok("foo")
383
384        xyz: Option[str] = Some(None)
385        assert xyz.ok_or(None) == Err(None)
386        ```
387        """
388        if self._value is None:
389            return _result.Err(err)
390
391        return _result.Ok(self._value)
392
393    def ok_or_else(self, err: FnOnce[U]) -> _result.Result[T, U]:
394        """Transforms the `Option<T>` into a `Result<T, E>`, mapping `Some(v)` to `Ok(v)` and `None` to `Err(err())`.
395
396        Example
397        -------
398        ```py
399        xyz: Option[str] = Some("foo")
400        assert xyz.ok_or(None) == Ok("foo")
401
402        xyz: Option[str] = Some(None)
403        assert xyz.ok_or(None) == Err(None)
404        ```
405        """
406        if self._value is None:
407            return _result.Err(err())
408
409        return _result.Ok(self._value)
410
411    def zip(self, other: Option[U]) -> Option[tuple[T, U]]:
412        """Zips `self` with `other`.
413
414        if `self` is `Some(s)` and other is `Some(o)`, this returns `Some((s, o))` otherwise `None`.
415
416        Example
417        -------
418        ```py
419        x = Some(1)
420        y = Some("hi")
421        z: Option[str] = Some(None)
422
423        assert x.zip(y) == Some((1, "hi"))
424        assert x.zip(z) == Some(None)
425        ```
426        """
427        if self._value is not None and other._value is not None:
428            return Some((self._value, other._value))
429
430        return NOTHING
431
432    def zip_with(
433        self, other: Option[U], f: collections.Callable[[T, U], T_co]
434    ) -> Option[T_co]:
435        """Zips `self` with `other` using function `f`.
436
437        if `self` is `Some(s)` and other is `Some(o)`, this returns `Some(f(s, o))` otherwise `None`.
438
439        Example
440        -------
441        ```py
442        @dataclass
443        class Point:
444            x: float
445            y: float
446
447        x, y = Some(32.1), Some(42.4)
448        assert x.zip_with(y, Point) == Some(Point(32.1, 42.4))
449        ```
450        """
451        if self._value is not None and other._value is not None:
452            return Some(f(self._value, other._value))
453
454        return NOTHING
455
456    # *- Inner operations *-
457
458    def take(self) -> Option[T]:
459        """Take the value from `self` Setting it to `None`, and then return `Some(v)`.
460
461        If you don't care about the original value, use `Option.clear()` instead.
462
463        Example
464        -------
465        ```py
466        original = Some("Hi")
467        new = original.take()
468
469        print(original, new)
470        # None, Some("Hi")
471        ```
472        """
473        if self._value is None:
474            return NOTHING
475
476        val = self._value
477        self._value = None
478        return Some(val)
479
480    def take_if(self, predicate: collections.Callable[[T], bool]) -> Option[T]:
481        """Take the value from `Self`, Setting it to `None` only if predicate returns `True`.
482
483        If you don't care about the original value, use `Option.clear_if()` instead.
484
485        Example
486        -------
487        ```py
488        def validate(email: str) -> bool:
489            # you can obviously validate this better.
490            return email.find('@') == 1
491
492        original = Some("flex@gg.com")
493        valid = original.take_if(validate)
494        assert is_allowed.is_some() and original.is_none()
495
496        original = Some("mail.example.com")
497        invalid = original.take_if(validate)
498        assert invalid.is_none() and original.is_some()
499        ```
500        """
501        if self.map_or(False, predicate):
502            return self.take()
503
504        return NOTHING
505
506    def clear(self) -> None:
507        """Clear the inner value, setting it to `None`.
508
509        If you care about the original value, use `Option.take()` instead.
510
511        Example
512        -------
513        ```py
514        value = Some("Hello")
515        value.clear()
516        assert value.is_none()
517        ```
518        """
519        self._value = None
520
521    def clear_if(self, predicate: Fn[T, bool]) -> None:
522        """Clear the inner value, setting it to `None` if the predicate returns `True`.
523
524        If you care about the original value, use `Option.take_if()` instead.
525
526        Example
527        -------
528        ```py
529        value = Some("Hello")
530        value.clear_if(lambda x: x == "Hello")
531        assert value.is_none()
532        ```
533        """
534        if self._value is not None and predicate(self._value):
535            self._value = None
536
537    def replace(self, value: T) -> Option[T]:
538        """Replace the contained value with another value.
539
540        Use `Option.insert` if you want to return the original value
541        that got inserted instead of `self`
542
543        Example
544        -------
545        ```py
546        value: Option[str] = Some(None)
547        value.replace("Hello")
548        # Some("Hello")
549        ```
550        """
551        self._value = value
552        return self
553
554    def insert(self, value: T) -> T:
555        """Insert a value into the option, and then return a reference to it.
556
557        This will overwrite the old value if it was already contained.
558
559        Example
560        -------
561        ```py
562        flag: Option[bool] = Some(None)
563        flag_ref = flag.insert(True)
564        assert flag_ref == True
565        assert flag.unwrap() == True
566        ```
567        """
568        self._value = value
569        return value
570
571    def get_or_insert(self, value: T) -> T:
572        """Insert a value into the option if it was `None`,
573        and then return a reference to it.
574
575        Example
576        -------
577        ```py
578        state: Option[bool] = Some(None)
579        assert state.get_or_insert(True) is True
580        assert state.get_or_insert(False) is True
581        ```
582        """
583        if self._value is not None:
584            return self._value
585
586        self._value = value
587        return value
588
589    def get_or_insert_with(self, f: FnOnce[T]) -> T:
590        """Insert a value into the option computed from `f()` if it was `None`,
591        and then return a reference to it.
592
593        Example
594        -------
595        ```py
596        flag: Option[bool] = Some(None)
597        flag_ref = flag.insert(True)
598        assert flag_ref == True
599        assert flag.unwrap() == True
600        ```
601        """
602        if self._value is not None:
603            return self._value
604
605        v = self._value = f()
606        return v
607
608    def and_ok(self, optb: Option[T]) -> Option[T]:
609        """Returns `None` if `self` or `optb` is `None`, otherwise return `optb`.
610
611        aliases: `Option::and`
612
613        Example
614        -------
615        ```py
616        x = Some(1)
617        y: Option[str] = Some(None)
618        assert x.and_ok(y) == Some(None)
619
620        x: Option[str] = Some(None)
621        y = Some(1)
622        assert x.and_ok(y) == Some(None)
623
624        x: Option[str] = Some("hi")
625        y = Some(100)
626        assert x.and_ok(y) == Some(100)
627        ```
628        """
629        if self._value is None or optb._value is None:
630            return optb
631
632        return NOTHING
633
634    def and_then(self, f: Fn[T, Option[T]]) -> Option[T]:
635        """Returns `Some(None)` if the contained value is `None`, otherwise call `f()`
636        on `T` and return `Option[T]`.
637
638        Example
639        -------
640        ```py
641        value = Some(5)
642        print(value.and_then(lambda x: Some(x * 2)))
643        # Some(10)
644
645        value: Option[int] = Some(None)
646        print(value.and_then(lambda x: Some(x * 2)))
647        # Some(None)
648        ```
649        """
650        if self._value is None:
651            return NOTHING
652
653        return f(self._value)
654
655    def inspect(self, f: Fn[T, typing.Any]) -> Option[T]:
656        """Calls `f()` on the contained value if it was `Some(v)`, otherwise does nothing.
657
658        Example
659        -------
660        ```py
661        def debug(x: str) -> None:
662            print("Debugging:", x)
663
664        value = Some("foo")
665        inner = value.inspect(debug).expect("no value to debug")
666        # prints: Debugging: "foo"
667
668        value: Option[str] = Some(None)
669        value.inspect(debug) # prints nothing
670        """
671        if self._value is not None:
672            f(self._value)
673
674        return self
675
676    # *- Builder methods *-
677
678    def iter(self) -> _iter.ExactSizeIterator[T]:
679        """Returns an iterator over the contained value.
680
681        Example
682        -------
683        ```py
684        from sain import Some
685        value = Some("gg").iter()
686        assert value.next() == Some("gg")
687
688        value: Option[int] = Some(None)
689        assert value.iter().next().is_none()
690        ```
691        """
692        if self._value is None:
693            return _iter.empty()
694
695        return _iter.once(self._value)
696
697    # *- Boolean checks *-
698
699    def is_some(self) -> bool:
700        """Returns `True` if the contained value is not `None`, otherwise returns `False`.
701
702        Example
703        -------
704        ```py
705        value = Some(5)
706        print(value.is_some())
707        # True
708
709        value: Option[int] = Some(None)
710        print(value.is_some())
711        # False
712        ```
713        """
714        return self._value is not None
715
716    def is_some_and(self, predicate: Fn[T, bool]) -> bool:
717        """Returns `True` if the contained value is not `None` and
718        the predicate returns `True`, otherwise returns `False`.
719
720        Example
721        -------
722        ```py
723        value = Some(5)
724        print(value.is_some_and(lambda x: x > 3))
725        # True
726
727        value: Option[int] = Some(None)
728        print(value.is_some_and(lambda x: x > 3))
729        # False
730        ```
731        """
732        return self._value is not None and predicate(self._value)
733
734    def is_none(self) -> bool:
735        """Returns `True` if the contained value is `None`, otherwise returns `False`.
736
737        Example
738        -------
739        ```py
740        value = Some(5)
741        print(value.is_none())
742        # False
743
744        value: Option[int] = Some(None)
745        print(value.is_none())
746        # True
747        ```
748        """
749        return self._value is None
750
751    def is_none_or(self, f: Fn[T, bool]) -> bool:
752        """Returns `True` if the contained value is `None` or the predicate returns `True`,
753        otherwise returns `False`.
754
755        Example
756        -------
757        ```py
758        value = Some(5)
759        print(value.is_none_or(lambda x: x > 3))
760        # False
761
762        value: Option[int] = Some(None)
763        print(value.is_none_or(lambda x: x > 3))
764        # True
765        ```
766        """
767        match self._value:
768            case None:
769                return True
770            case x:
771                return f(x)
772
773    def __repr__(self) -> str:
774        if self._value is None:
775            return "None"
776        return f"Some({self._value!r})"
777
778    __str__ = __repr__
779
780    def __invert__(self) -> T:
781        return self.unwrap()
782
783    def __or__(self, other: T) -> T:
784        return self._value if self._value is not None else other
785
786    def __bool__(self) -> bool:
787        return self._value is not None
788
789    def __eq__(self, other: None | object) -> bool:
790        if other is None:
791            return self._value is None
792
793        if not isinstance(other, Some):
794            return NotImplemented
795
796        return self._value == other._value  # pyright: ignore[reportUnknownVariableType, reportUnknownMemberType]
797
798    def __ne__(self, other: object) -> bool:
799        return not self.__eq__(other)
800
801    def __hash__(self) -> int:
802        return hash(self._value)