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