From c0ce1e9787962f072fc9fee7e0b19a06ccf44768 Mon Sep 17 00:00:00 2001 From: Khabib <136262760+Khabib73@users.noreply.github.com> Date: Wed, 7 Oct 2026 12:43:36 +0300 Subject: [PATCH 1/7] Change docs to a new format --- returns/context/requires_context.py | 22 +++++++++------ .../context/requires_context_future_result.py | 28 +++++++++---------- returns/context/requires_context_ioresult.py | 21 +++++++------- returns/context/requires_context_result.py | 19 +++++++------ returns/contrib/hypothesis/_entrypoint.py | 4 +-- returns/contrib/hypothesis/laws.py | 24 ++++++++-------- returns/contrib/mypy/_consts.py | 12 ++++---- returns/contrib/mypy/_features/curry.py | 2 +- returns/contrib/mypy/_structures/types.py | 2 +- returns/contrib/mypy/_typeops/analtype.py | 2 +- returns/contrib/mypy/_typeops/inference.py | 2 +- .../mypy/_typeops/transform_callable.py | 10 +++---- returns/contrib/mypy/returns_plugin.py | 9 +++--- returns/future.py | 14 ++++------ returns/interfaces/altable.py | 6 ++-- returns/interfaces/applicative.py | 8 +++--- returns/interfaces/bimappable.py | 4 +-- returns/interfaces/bindable.py | 6 ++-- returns/interfaces/container.py | 8 +++--- returns/interfaces/failable.py | 14 +++++----- returns/interfaces/lashable.py | 4 +-- returns/interfaces/mappable.py | 8 +++--- returns/interfaces/specific/future.py | 18 ++++++------ returns/interfaces/specific/future_result.py | 8 +++--- returns/interfaces/specific/io.py | 12 ++++---- returns/interfaces/specific/ioresult.py | 8 +++--- returns/interfaces/specific/maybe.py | 8 +++--- .../specific/reader_future_result.py | 4 +-- .../interfaces/specific/reader_ioresult.py | 4 +-- returns/interfaces/specific/reader_result.py | 4 +-- returns/interfaces/specific/result.py | 8 +++--- returns/interfaces/swappable.py | 4 +-- returns/io.py | 16 +++++------ returns/maybe.py | 7 +++-- returns/methods/cond.py | 3 +- returns/pointfree/bind_context.py | 2 +- returns/pointfree/modify_env.py | 2 +- returns/primitives/hkt.py | 14 +++++----- returns/primitives/laws.py | 6 ++-- returns/result.py | 13 ++++----- 40 files changed, 189 insertions(+), 181 deletions(-) diff --git a/returns/context/requires_context.py b/returns/context/requires_context.py index 369ae7e99..2202d97c6 100644 --- a/returns/context/requires_context.py +++ b/returns/context/requires_context.py @@ -27,17 +27,21 @@ _NewEnvType = TypeVar('_NewEnvType') _ReturnType_co = TypeVar('_ReturnType_co', covariant=True) _NewReturnType = TypeVar('_NewReturnType') +"""Context.""" _ValueType = TypeVar('_ValueType') _ErrorType = TypeVar('_ErrorType') -# Helpers: _FirstType = TypeVar('_FirstType') +"""Helpers.""" + -# Type Aliases: -#: Sometimes ``RequiresContext`` and other similar types might be used with -#: no explicit dependencies so we need to have this type alias for Any. NoDeps = Any +""" +Type Aliases. Sometimes ``RequiresContext`` and other similar types +might be used with no explicit dependencies so we need to +have this type alias for Any. +""" @final @@ -78,11 +82,13 @@ class RequiresContext( # type: ignore[type-var] __slots__ = () - #: This field has an extra 'RequiresContext' just because `mypy` needs it. _inner_value: Callable[[_EnvType_contra], _ReturnType_co] + """ + This field has an extra 'RequiresContext' + just because `mypy` needs it.""" - #: A convenient placeholder to call methods created by `.from_value()`: no_args: ClassVar[NoDeps] = object() + """A convenient placeholder to call methods created by `.from_value()`.""" def __init__( self, @@ -208,8 +214,8 @@ def bind( """ return RequiresContext(lambda deps: dekind(function(self(deps)))(deps)) - #: Alias for `bind_context` method, it is the same as `bind` here. bind_context = bind + """Alias for `bind_context` method, it is the same as `bind` here.""" def modify_env( self, @@ -445,5 +451,5 @@ def from_requires_context_future_result( # Aliases -#: Sometimes `RequiresContext` is too long to type. Reader: TypeAlias = RequiresContext +"""Sometimes `RequiresContext` is too long to type.""" diff --git a/returns/context/requires_context_future_result.py b/returns/context/requires_context_future_result.py index b93069f43..25f846bd4 100644 --- a/returns/context/requires_context_future_result.py +++ b/returns/context/requires_context_future_result.py @@ -20,18 +20,18 @@ ) from returns.context.requires_context_result import RequiresContextResult -# Context: _EnvType_contra = TypeVar('_EnvType_contra', contravariant=True) _NewEnvType = TypeVar('_NewEnvType') +"""Context.""" -# Result: _ValueType_co = TypeVar('_ValueType_co', covariant=True) _NewValueType = TypeVar('_NewValueType') _ErrorType_co = TypeVar('_ErrorType_co', covariant=True) _NewErrorType = TypeVar('_NewErrorType') +"""Result.""" -# Helpers: _FirstType = TypeVar('_FirstType') +"""Helpers.""" @final @@ -103,15 +103,15 @@ class RequiresContextFutureResult( # type: ignore[type-var] __slots__ = () - #: Inner value of `RequiresContext` - #: is just a function that returns `FutureResult`. - #: This field has an extra 'RequiresContext' just because `mypy` needs it. _inner_value: Callable[ [_EnvType_contra], FutureResult[_ValueType_co, _ErrorType_co] ] + """Inner value of `RequiresContext` is just a function + that returns `FutureResult`. This field has an extra + 'RequiresContext' just because `mypy` needs it.""" - #: A convenient placeholder to call methods created by `.from_value()`. no_args: ClassVar[NoDeps] = object() + """A convenient placeholder to call methods created by `.from_value()`.""" def __init__( self, @@ -319,9 +319,9 @@ def bind( ), ) - #: Alias for `bind_context_future_result` method, - #: it is the same as `bind` here. bind_context_future_result = bind + """Alias for `bind_context_future_result` method, + it is the same as `bind` here.""" def bind_async( self, @@ -377,9 +377,9 @@ def bind_async( ), ) - #: Alias for `bind_async_context_future_result` method, - #: it is the same as `bind_async` here. bind_async_context_future_result = bind_async + """Alias for `bind_async_context_future_result` method, + it is the same as `bind_async` here.""" def bind_awaitable( self, @@ -1460,19 +1460,19 @@ def from_failure( # Aliases: -#: Alias for a popular case when ``Result`` has ``Exception`` as error type. RequiresContextFutureResultE: TypeAlias = RequiresContextFutureResult[ _ValueType_co, Exception, _EnvType_contra, ] +"""Alias for a popular case when ``Result`` has ``Exception`` as error type.""" -#: Sometimes `RequiresContextFutureResult` is too long to type. ReaderFutureResult: TypeAlias = RequiresContextFutureResult +"""Sometimes `RequiresContextFutureResult` is too long to type.""" -#: Alias to save you some typing. Uses ``Exception`` as error type. ReaderFutureResultE: TypeAlias = RequiresContextFutureResult[ _ValueType_co, Exception, _EnvType_contra, ] +"""Alias to save you some typing. Uses ``Exception`` as error type.""" diff --git a/returns/context/requires_context_ioresult.py b/returns/context/requires_context_ioresult.py index 17a7b1925..aa7848490 100644 --- a/returns/context/requires_context_ioresult.py +++ b/returns/context/requires_context_ioresult.py @@ -14,15 +14,15 @@ from returns.context.requires_context import RequiresContext from returns.context.requires_context_result import RequiresContextResult -# Context: _EnvType_contra = TypeVar('_EnvType_contra', contravariant=True) _NewEnvType = TypeVar('_NewEnvType') +"""Context.""" -# Result: _ValueType_co = TypeVar('_ValueType_co', covariant=True) _NewValueType = TypeVar('_NewValueType') _ErrorType = TypeVar('_ErrorType') _NewErrorType = TypeVar('_NewErrorType') +"""Result.""" @final @@ -104,15 +104,15 @@ class RequiresContextIOResult( # type: ignore[type-var] __slots__ = () - #: Inner value of `RequiresContext` - #: is just a function that returns `IOResult`. - #: This field has an extra 'RequiresContext' just because `mypy` needs it. _inner_value: Callable[ [_EnvType_contra], IOResult[_ValueType_co, _ErrorType] ] + """Inner value of `RequiresContext`. Is just a function that + returns `IOResult`. This field has an extra 'RequiresContext' + just because `mypy` needs it.""" - #: A convenient placeholder to call methods created by `.from_value()`. no_args: ClassVar[NoDeps] = object() + """A convenient placeholder to call methods created by `.from_value()`.""" def __init__( self, @@ -296,8 +296,9 @@ def bind( ), ) - #: Alias for `bind_context_ioresult` method, it is the same as `bind` here. bind_context_ioresult = bind + """Alias for `bind_context_ioresult` method, + it is the same as `bind` here.""" def bind_result( self, @@ -915,19 +916,19 @@ def from_failure( # Aliases: -#: Alias for a popular case when ``Result`` has ``Exception`` as error type. RequiresContextIOResultE: TypeAlias = RequiresContextIOResult[ _ValueType_co, Exception, _EnvType_contra, ] +"""Alias for a popular case when ``Result`` has ``Exception`` as error type.""" -#: Alias to save you some typing. Uses original name from Haskell. ReaderIOResult: TypeAlias = RequiresContextIOResult +"""Alias to save you some typing. Uses original name from Haskell.""" -#: Alias to save you some typing. Uses ``Exception`` as error type. ReaderIOResultE: TypeAlias = RequiresContextIOResult[ _ValueType_co, Exception, _EnvType_contra, ] +"""Alias to save you some typing. Uses ``Exception`` as error type.""" diff --git a/returns/context/requires_context_result.py b/returns/context/requires_context_result.py index c835b87a7..775666b6b 100644 --- a/returns/context/requires_context_result.py +++ b/returns/context/requires_context_result.py @@ -12,18 +12,18 @@ if TYPE_CHECKING: from returns.context.requires_context import RequiresContext -# Context: _EnvType_contra = TypeVar('_EnvType_contra', contravariant=True) _NewEnvType = TypeVar('_NewEnvType') +"""Context.""" -# Result: _ValueType_co = TypeVar('_ValueType_co', covariant=True) _NewValueType = TypeVar('_NewValueType') _ErrorType_co = TypeVar('_ErrorType_co', covariant=True) _NewErrorType = TypeVar('_NewErrorType') +"""Result.""" -# Helpers: _FirstType = TypeVar('_FirstType') +"""Helpers.""" @final @@ -98,13 +98,14 @@ class RequiresContextResult( # type: ignore[type-var] __slots__ = () - #: This field has an extra 'RequiresContext' just because `mypy` needs it. _inner_value: Callable[ [_EnvType_contra], Result[_ValueType_co, _ErrorType_co] ] + """This field has an extra 'RequiresContext', + just because `mypy` needs it.""" - #: A convenient placeholder to call methods created by `.from_value()`. no_args: ClassVar[NoDeps] = object() + """A convenient placeholder to call methods created by `.from_value()`.""" def __init__( self, @@ -282,8 +283,8 @@ def bind( ), ) - #: Alias for `bind_context_result` method, it is the same as `bind` here. bind_context_result = bind + """Alias for `bind_context_result` method, it is the same as `bind` here.""" def bind_result( self, @@ -631,19 +632,19 @@ def from_failure( # Aliases: -#: Alias for a popular case when ``Result`` has ``Exception`` as error type. RequiresContextResultE: TypeAlias = RequiresContextResult[ _ValueType_co, Exception, _EnvType_contra, ] +"""Alias for a popular case when ``Result`` has ``Exception`` as error type.""" -#: Alias to save you some typing. Uses original name from Haskell. ReaderResult: TypeAlias = RequiresContextResult +"""Alias to save you some typing. Uses original name from Haskell.""" -#: Alias to save you some typing. Has ``Exception`` as error type. ReaderResultE: TypeAlias = RequiresContextResult[ _ValueType_co, Exception, _EnvType_contra, ] +"""Alias to save you some typing. Has ``Exception`` as error type.""" diff --git a/returns/contrib/hypothesis/_entrypoint.py b/returns/contrib/hypothesis/_entrypoint.py index d611eb455..bdd3de972 100644 --- a/returns/contrib/hypothesis/_entrypoint.py +++ b/returns/contrib/hypothesis/_entrypoint.py @@ -45,8 +45,6 @@ def decorator(thing: Any) -> st.SearchStrategy[_Inst]: return decorator - #: Our types that we register in hypothesis - #: to be working with ``st.from_type`` registered_types: Sequence[type[Lawful]] = ( Result, Maybe, @@ -59,6 +57,8 @@ def decorator(thing: Any) -> st.SearchStrategy[_Inst]: RequiresContextIOResult, RequiresContextFutureResult, ) + """Our types that we register in hypothesis to be + working with ``st.from_type``.""" # noqa: WPS484 for type_ in registered_types: st.register_type_strategy(type_, factory(type_)) diff --git a/returns/contrib/hypothesis/laws.py b/returns/contrib/hypothesis/laws.py index b8a74e8b9..476dc6feb 100644 --- a/returns/contrib/hypothesis/laws.py +++ b/returns/contrib/hypothesis/laws.py @@ -34,21 +34,23 @@ class Settings: :func:`default_settings`. """ - #: Settings directly passed on to `hypothesis`. We support all kwargs from - #: ``@settings``, see `@settings docs - #: `_. settings_kwargs: dict[str, Any] - #: Whether to create examples using ``__init__`` instead of the default . + """Settings directly passed on to `hypothesis`. We support all kwargs from + ``@settings``, see `@settings docs `_.""" + use_init: bool - #: Strategy for generating the container. By default, we generate examples - #: of a container using: - #: :func:`returns.contrib.hypothesis.containers.strategy_from_container`. + """Whether to create examples using ``__init__`` instead of the default .""" + container_strategy: StrategyFactory | None - #: Strategies for generating values of types other than the container and - #: its lawful interfaces. This can be useful for overriding ``TypeVar``, - #: ``Callable``, etc. in case you use certain types that ``hypothesis`` is - #: unable to find. + """Strategy for generating the container. By default, we generate examples + of a container using: + :func:`returns.contrib.hypothesis.containers.strategy_from_container`.""" + type_strategies: dict[type[object], StrategyFactory] + """Strategies for generating values of types other than the container and + its lawful interfaces. This can be useful for overriding ``TypeVar``, + ``Callable``, etc. in case you use certain types that ``hypothesis`` is + unable to find.""" def __post_init__(self) -> None: """Check that the settings are mutually compatible.""" diff --git a/returns/contrib/mypy/_consts.py b/returns/contrib/mypy/_consts.py index d5db58f12..69313b8d0 100644 --- a/returns/contrib/mypy/_consts.py +++ b/returns/contrib/mypy/_consts.py @@ -3,27 +3,26 @@ # Constant fullnames for typechecking # =================================== -#: Used for typed ``partial`` function. TYPED_PARTIAL_FUNCTION: Final = 'returns.curry.partial' +"""Used for typed ``partial`` function.""" -#: Used for typed ``curry`` decorator. TYPED_CURRY_FUNCTION: Final = 'returns.curry.curry' +"""Used for typed ``curry`` decorator.""" -#: Used for typed ``flow`` call. TYPED_FLOW_FUNCTION: Final = 'returns._internal.pipeline.flow.flow' +"""Used for typed ``flow`` call.""" -#: Used for typed ``pipe`` call. TYPED_PIPE_FUNCTION: Final = 'returns._internal.pipeline.pipe.pipe' TYPED_PIPE_METHOD: Final = 'returns._internal.pipeline.pipe._Pipe.__call__' +"""Used for typed ``pipe`` call.""" -#: Used for HKT emulation. TYPED_KINDN: Final = 'returns.primitives.hkt.KindN' TYPED_KINDN_ACCESS: Final = f'{TYPED_KINDN}.' TYPED_KIND_DEKIND: Final = 'returns.primitives.hkt.dekind' TYPED_KIND_KINDED_CALL: Final = 'returns.primitives.hkt.Kinded.__call__' TYPED_KIND_KINDED_GET: Final = 'returns.primitives.hkt.Kinded.__get__' +"""Used for HKT emulation.""" -#: Used for :ref:`do-notation`. DO_NOTATION_METHODS: Final = ( # Just validation: 'returns.io.IO.do', @@ -34,3 +33,4 @@ 'returns.io.IOResult.do', 'returns.future.FutureResult.do', ) +"""Used for :ref:`do-notation`.""" diff --git a/returns/contrib/mypy/_features/curry.py b/returns/contrib/mypy/_features/curry.py index 5feb55065..a34bf9801 100644 --- a/returns/contrib/mypy/_features/curry.py +++ b/returns/contrib/mypy/_features/curry.py @@ -21,8 +21,8 @@ proper_type, ) -#: Raw material to build `_ArgTree`. _RawArgTree = list[list[list[FuncArg]]] +"""Raw material to build `_ArgTree`.""" def analyze(ctx: FunctionContext) -> MypyType: diff --git a/returns/contrib/mypy/_structures/types.py b/returns/contrib/mypy/_structures/types.py index 5e1ea109c..3753708c8 100644 --- a/returns/contrib/mypy/_structures/types.py +++ b/returns/contrib/mypy/_structures/types.py @@ -2,5 +2,5 @@ from mypy.plugin import FunctionContext, MethodContext -#: We treat them equally when working with functions or methods. CallableContext: TypeAlias = FunctionContext | MethodContext +"""We treat them equally when working with functions or methods.""" diff --git a/returns/contrib/mypy/_typeops/analtype.py b/returns/contrib/mypy/_typeops/analtype.py index e95a999c7..c68353256 100644 --- a/returns/contrib/mypy/_typeops/analtype.py +++ b/returns/contrib/mypy/_typeops/analtype.py @@ -10,13 +10,13 @@ from returns.contrib.mypy._structures.args import FuncArg from returns.contrib.mypy._structures.types import CallableContext -#: Mapping for better `call || function` argument compatibility. _KIND_MAPPING: Final = MappingProxyType({ # We have to replace `ARG_OPT` to `ARG_NAMED`, # because `ARG_OPT` is only used in function defs, not calls. # And `ARG_NAMED` is the same thing for calls. ARG_OPT: ARG_NAMED, }) +"""Mapping for better `call || function` argument compatibility.""" @overload diff --git a/returns/contrib/mypy/_typeops/inference.py b/returns/contrib/mypy/_typeops/inference.py index a9bf1c5a0..d25b2cf3a 100644 --- a/returns/contrib/mypy/_typeops/inference.py +++ b/returns/contrib/mypy/_typeops/inference.py @@ -19,8 +19,8 @@ from returns.contrib.mypy._structures.types import CallableContext from returns.contrib.mypy._typeops.analtype import analyze_call -#: Mapping of `typevar` to real type. _Constraints: TypeAlias = Mapping[TypeVarId, MypyType] +"""Mapping of `typevar` to real type.""" @final diff --git a/returns/contrib/mypy/_typeops/transform_callable.py b/returns/contrib/mypy/_typeops/transform_callable.py index 47c8fd7f7..68b2e1351 100644 --- a/returns/contrib/mypy/_typeops/transform_callable.py +++ b/returns/contrib/mypy/_typeops/transform_callable.py @@ -23,18 +23,18 @@ from returns.contrib.mypy._structures.args import FuncArg -#: Kinds of arguments that consume the leftover positional or keyword -#: arguments (``*args`` and ``**kwargs``) and therefore cannot be applied. _VARIADIC_KINDS: Final = frozenset((ARG_STAR, ARG_STAR2)) +"""Kinds of arguments that consume the leftover positional or keyword +arguments (``*args`` and ``**kwargs``) and therefore cannot be applied.""" -#: Kinds of arguments that can be passed positionally. _POSITIONAL_KINDS: Final = frozenset((ARG_POS, ARG_OPT)) +"""Kinds of arguments that can be passed positionally.""" -#: Maps a positional argument kind onto its keyword-only counterpart. _KEYWORD_ONLY_KINDS: Final = MappingProxyType({ ARG_POS: ARG_NAMED, ARG_OPT: ARG_NAMED_OPT, }) +"""Maps a positional argument kind onto its keyword-only counterpart.""" def proper_type( @@ -55,12 +55,12 @@ class Intermediate: was already provided in caller. """ - #: Positional arguments can be of this kind. _positional_kinds: ClassVar[frozenset[ArgKind]] = frozenset(( ARG_POS, ARG_OPT, ARG_STAR, )) + """Positional arguments can be of this kind.""" def __init__(self, case_function: CallableType) -> None: """We only need a callable to work on.""" diff --git a/returns/contrib/mypy/returns_plugin.py b/returns/contrib/mypy/returns_plugin.py index 8b1fabb72..0d7772eb5 100644 --- a/returns/contrib/mypy/returns_plugin.py +++ b/returns/contrib/mypy/returns_plugin.py @@ -37,18 +37,17 @@ # Type aliases # ============ -#: Type for a function hook. _FunctionCallback: TypeAlias = Callable[[FunctionContext], MypyType] +"""Type for a function hook.""" -#: Type for attribute hook. _AttributeCallback: TypeAlias = Callable[[AttributeContext], MypyType] +"""Type for attribute hook.""" -#: Type for a method hook. _MethodCallback: TypeAlias = Callable[[MethodContext], MypyType] +"""Type for a method hook.""" -#: Type for a method signature hook. _MethodSigCallback: TypeAlias = Callable[[MethodSigContext], CallableType] - +"""Type for a method signature hook.""" # Interface # ========= diff --git a/returns/future.py b/returns/future.py index e0c755ebb..a670aa1e8 100644 --- a/returns/future.py +++ b/returns/future.py @@ -246,8 +246,8 @@ def bind( """ return Future(_future.async_bind(function, self._inner_value)) - #: Alias for `bind` method. Part of the `FutureBasedN` interface. bind_future = bind + """Alias for `bind` method. Part of the `FutureBasedN` interface.""" def bind_async( self, @@ -279,8 +279,8 @@ def bind_async( """ return Future(_future.async_bind_async(function, self._inner_value)) - #: Alias for `bind_async` method. Part of the `FutureBasedN` interface. bind_async_future = bind_async + """Alias for `bind_async` method. Part of the `FutureBasedN` interface.""" def bind_awaitable( self, @@ -812,9 +812,8 @@ def bind( ) ) - #: Alias for `bind` method. - #: Part of the `FutureResultBasedN` interface. bind_future_result = bind + """Alias for `bind` method. Part of the `FutureResultBasedN` interface.""" def bind_async( self, @@ -854,9 +853,9 @@ def bind_async( ) ) - #: Alias for `bind_async` method. - #: Part of the `FutureResultBasedN` interface. bind_async_future_result = bind_async + """Alias for `bind_async` method. + Part of the `FutureResultBasedN` interface.""" def bind_awaitable( self, @@ -1510,9 +1509,8 @@ def FutureFailure( # noqa: N802 return FutureResult.from_failure(inner_value) -#: Alias for ``FutureResult[_ValueType_co, Exception]``. FutureResultE: TypeAlias = FutureResult[_ValueType_co, Exception] - +"""Alias for ``FutureResult[_ValueType_co, Exception]``.""" _ExceptionType = TypeVar('_ExceptionType', bound=Exception) diff --git a/returns/interfaces/altable.py b/returns/interfaces/altable.py index 7ec606f0d..f0fc61ab6 100644 --- a/returns/interfaces/altable.py +++ b/returns/interfaces/altable.py @@ -21,9 +21,9 @@ _AltableType = TypeVar('_AltableType', bound='AltableN') -# Used in laws: _NewType1 = TypeVar('_NewType1') _NewType2 = TypeVar('_NewType2') +"""Used in laws""" @final @@ -77,8 +77,8 @@ def alt( """Allows to run a pure function over a container.""" -#: Type alias for kinds with two type arguments. Altable2 = AltableN[_FirstType, _SecondType, Never] +"""Type alias for kinds with two type arguments.""" -#: Type alias for kinds with three type arguments. Altable3 = AltableN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" diff --git a/returns/interfaces/applicative.py b/returns/interfaces/applicative.py index 1d60a3ffd..cc59fbc59 100644 --- a/returns/interfaces/applicative.py +++ b/returns/interfaces/applicative.py @@ -22,9 +22,9 @@ _ApplicativeType = TypeVar('_ApplicativeType', bound='ApplicativeN') -# Only used in laws: _NewType1 = TypeVar('_NewType1') _NewType2 = TypeVar('_NewType2') +"""Only used in laws""" @final @@ -162,11 +162,11 @@ def from_value( """Unit method to create new containers from any raw value.""" -#: Type alias for kinds with one type argument. Applicative1 = ApplicativeN[_FirstType, Never, Never] +"""Type alias for kinds with one type argument.""" -#: Type alias for kinds with two type arguments. Applicative2 = ApplicativeN[_FirstType, _SecondType, Never] +"""Type alias for kinds with two type arguments.""" -#: Type alias for kinds with three type arguments. Applicative3 = ApplicativeN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" diff --git a/returns/interfaces/bimappable.py b/returns/interfaces/bimappable.py index e44976543..eee81448e 100644 --- a/returns/interfaces/bimappable.py +++ b/returns/interfaces/bimappable.py @@ -24,8 +24,8 @@ class BiMappableN( __slots__ = () -#: Type alias for kinds with two type arguments. BiMappable2 = BiMappableN[_FirstType, _SecondType, Never] +"""Type alias for kinds with two type arguments.""" -#: Type alias for kinds with three type arguments. BiMappable3 = BiMappableN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" diff --git a/returns/interfaces/bindable.py b/returns/interfaces/bindable.py index cdf1f4027..5a3f568e0 100644 --- a/returns/interfaces/bindable.py +++ b/returns/interfaces/bindable.py @@ -41,11 +41,11 @@ def bind( """ -#: Type alias for kinds with one type argument. Bindable1 = BindableN[_FirstType, Never, Never] +"""Type alias for kinds with one type argument.""" -#: Type alias for kinds with two type arguments. Bindable2 = BindableN[_FirstType, _SecondType, Never] +"""Type alias for kinds with two type arguments.""" -#: Type alias for kinds with three type arguments. Bindable3 = BindableN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" diff --git a/returns/interfaces/container.py b/returns/interfaces/container.py index 84d77da56..9e8fd16de 100644 --- a/returns/interfaces/container.py +++ b/returns/interfaces/container.py @@ -17,9 +17,9 @@ _SecondType = TypeVar('_SecondType') _ThirdType = TypeVar('_ThirdType') -# Only used in laws: _NewType1 = TypeVar('_NewType1') _NewType2 = TypeVar('_NewType2') +"""Only used in laws.""" @final @@ -121,11 +121,11 @@ class ContainerN( ) -#: Type alias for kinds with one type argument. Container1 = ContainerN[_FirstType, Never, Never] +"""Type alias for kinds with one type argument.""" -#: Type alias for kinds with two type arguments. Container2 = ContainerN[_FirstType, _SecondType, Never] +"""Type alias for kinds with two type arguments.""" -#: Type alias for kinds with three type arguments. Container3 = ContainerN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" diff --git a/returns/interfaces/failable.py b/returns/interfaces/failable.py index e369944ae..6725478f8 100644 --- a/returns/interfaces/failable.py +++ b/returns/interfaces/failable.py @@ -23,8 +23,8 @@ _SingleFailableType = TypeVar('_SingleFailableType', bound='SingleFailableN') _DiverseFailableType = TypeVar('_DiverseFailableType', bound='DiverseFailableN') -# Used in laws: _NewFirstType = TypeVar('_NewFirstType') +"""Used in laws.""" @final @@ -72,11 +72,11 @@ class FailableN( ) -#: Type alias for kinds with two type arguments. Failable2 = FailableN[_FirstType, _SecondType, Never] +"""Type alias for kinds with two type arguments.""" -#: Type alias for kinds with three type arguments. Failable3 = FailableN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" @final @@ -153,11 +153,11 @@ def empty( """This property represents the failed value.""" -#: Type alias for kinds with two types arguments. SingleFailable2 = SingleFailableN[_FirstType, _SecondType, Never] +"""Type alias for kinds with two types arguments.""" -#: Type alias for kinds with three type arguments. SingleFailable3 = SingleFailableN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" @final @@ -257,8 +257,8 @@ def from_failure( """Unit method to create new containers from any raw value.""" -#: Type alias for kinds with two type arguments. DiverseFailable2 = DiverseFailableN[_FirstType, _SecondType, Never] +"""Type alias for kinds with two type arguments.""" -#: Type alias for kinds with three type arguments. DiverseFailable3 = DiverseFailableN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" diff --git a/returns/interfaces/lashable.py b/returns/interfaces/lashable.py index baf0310ea..06c670f59 100644 --- a/returns/interfaces/lashable.py +++ b/returns/interfaces/lashable.py @@ -41,8 +41,8 @@ def lash( """ -#: Type alias for kinds with two type arguments. Lashable2 = LashableN[_FirstType, _SecondType, Never] +"""Type alias for kinds with two type arguments.""" -#: Type alias for kinds with three type arguments. Lashable3 = LashableN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" diff --git a/returns/interfaces/mappable.py b/returns/interfaces/mappable.py index edf3ba0c9..893047418 100644 --- a/returns/interfaces/mappable.py +++ b/returns/interfaces/mappable.py @@ -21,9 +21,9 @@ _MappableType = TypeVar('_MappableType', bound='MappableN') -# Used in laws: _NewType1 = TypeVar('_NewType1') _NewType2 = TypeVar('_NewType2') +"""Used in laws.""" @final @@ -85,11 +85,11 @@ def map( """Allows to run a pure function over a container.""" -#: Type alias for kinds with one type argument. Mappable1 = MappableN[_FirstType, Never, Never] +"""Type alias for kinds with one type argument.""" -#: Type alias for kinds with two type arguments. Mappable2 = MappableN[_FirstType, _SecondType, Never] +"""Type alias for kinds with two type arguments.""" -#: Type alias for kinds with three type arguments. Mappable3 = MappableN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" diff --git a/returns/interfaces/specific/future.py b/returns/interfaces/specific/future.py index c0d2523c1..f3cfaf501 100644 --- a/returns/interfaces/specific/future.py +++ b/returns/interfaces/specific/future.py @@ -78,14 +78,14 @@ def from_future( """Unit method to create new containers from successful ``Future``.""" -#: Type alias for kinds with one type argument. FutureLike1 = FutureLikeN[_FirstType, Never, Never] +"""Type alias for kinds with one type argument.""" -#: Type alias for kinds with two type arguments. FutureLike2 = FutureLikeN[_FirstType, _SecondType, Never] +"""Type alias for kinds with two type arguments.""" -#: Type alias for kinds with three type arguments. FutureLike3 = FutureLikeN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" class AwaitableFutureN(Generic[_FirstType, _SecondType, _ThirdType]): @@ -114,14 +114,14 @@ async def awaitable( """Underling logic under ``await`` expression.""" -#: Type alias for kinds with one type argument. AsyncFuture1 = AwaitableFutureN[_FirstType, Never, Never] +"""Type alias for kinds with one type argument.""" -#: Type alias for kinds with two type arguments. AsyncFuture2 = AwaitableFutureN[_FirstType, _SecondType, Never] +"""Type alias for kinds with two type arguments.""" -#: Type alias for kinds with three type arguments. AsyncFuture3 = AwaitableFutureN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" class FutureBasedN( @@ -137,11 +137,11 @@ class FutureBasedN( __slots__ = () -#: Type alias for kinds with one type argument. FutureBased1 = FutureBasedN[_FirstType, Never, Never] +"""Type alias for kinds with one type argument.""" -#: Type alias for kinds with two type arguments. FutureBased2 = FutureBasedN[_FirstType, _SecondType, Never] +"""Type alias for kinds with two type arguments.""" -#: Type alias for kinds with three type arguments. FutureBased3 = FutureBasedN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" diff --git a/returns/interfaces/specific/future_result.py b/returns/interfaces/specific/future_result.py index eb4a75fd0..77862a240 100644 --- a/returns/interfaces/specific/future_result.py +++ b/returns/interfaces/specific/future_result.py @@ -81,11 +81,11 @@ def from_future_result( """Creates container from ``FutureResult`` instance.""" -#: Type alias for kinds with two type arguments. FutureResultLike2 = FutureResultLikeN[_FirstType, _SecondType, Never] +"""Type alias for kinds with two type arguments.""" -#: Type alias for kinds with three type arguments. FutureResultLike3 = FutureResultLikeN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" class FutureResultBasedN( @@ -102,8 +102,8 @@ class FutureResultBasedN( __slots__ = () -#: Type alias for kinds with two type arguments. FutureResultBased2 = FutureResultBasedN[_FirstType, _SecondType, Never] +"""Type alias for kinds with two type arguments.""" -#: Type alias for kinds with three type arguments. FutureResultBased3 = FutureResultBasedN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" diff --git a/returns/interfaces/specific/io.py b/returns/interfaces/specific/io.py index 0441f7270..666d1f769 100644 --- a/returns/interfaces/specific/io.py +++ b/returns/interfaces/specific/io.py @@ -46,14 +46,14 @@ def from_io( """Unit method to create new containers from successful ``IO``.""" -#: Type alias for kinds with one type argument. IOLike1 = IOLikeN[_FirstType, Never, Never] +"""Type alias for kinds with one type argument.""" -#: Type alias for kinds with two type arguments. IOLike2 = IOLikeN[_FirstType, _SecondType, Never] +"""Type alias for kinds with two type arguments.""" -#: Type alias for kinds with three type arguments. IOLike3 = IOLikeN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" class IOBasedN( @@ -75,11 +75,11 @@ class IOBasedN( __slots__ = () -#: Type alias for kinds with one type argument. IOBased1 = IOBasedN[_FirstType, Never, Never] +"""Type alias for kinds with one type argument.""" -#: Type alias for kinds with two type arguments. IOBased2 = IOBasedN[_FirstType, _SecondType, Never] +"""Type alias for kinds with two type arguments.""" -#: Type alias for kinds with three type arguments. IOBased3 = IOBasedN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" diff --git a/returns/interfaces/specific/ioresult.py b/returns/interfaces/specific/ioresult.py index 62581ab24..6dd515eb0 100644 --- a/returns/interfaces/specific/ioresult.py +++ b/returns/interfaces/specific/ioresult.py @@ -74,11 +74,11 @@ def from_failed_io( """Unit method to create new containers from failed ``IO``.""" -#: Type alias for kinds with two type arguments. IOResultLike2 = IOResultLikeN[_FirstType, _SecondType, Never] +"""Type alias for kinds with two type arguments.""" -#: Type alias for kinds with three type arguments. IOResultLike3 = IOResultLikeN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" class IOResultBasedN( @@ -102,8 +102,8 @@ class IOResultBasedN( __slots__ = () -#: Type alias for kinds with two type arguments. IOResultBased2 = IOResultBasedN[_FirstType, _SecondType, Never] +"""Type alias for kinds with two type arguments.""" -#: Type alias for kinds with three type arguments. IOResultBased3 = IOResultBasedN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" diff --git a/returns/interfaces/specific/maybe.py b/returns/interfaces/specific/maybe.py index 2dd556d27..465ff2112 100644 --- a/returns/interfaces/specific/maybe.py +++ b/returns/interfaces/specific/maybe.py @@ -140,11 +140,11 @@ def from_optional( """Unit method to create containers from ``Optional`` value.""" -#: Type alias for kinds with two type arguments. MaybeLike2 = MaybeLikeN[_FirstType, _SecondType, Never] +"""Type alias for kinds with two type arguments.""" -#: Type alias for kinds with three type arguments. MaybeLike3 = MaybeLikeN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" class MaybeBasedN( @@ -168,8 +168,8 @@ def or_else_call( """Calls a function in case there nothing to unwrap.""" -#: Type alias for kinds with two type arguments. MaybeBased2 = MaybeBasedN[_FirstType, _SecondType, Never] +"""Type alias for kinds with two type arguments.""" -#: Type alias for kinds with three type arguments. MaybeBased3 = MaybeBasedN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" diff --git a/returns/interfaces/specific/reader_future_result.py b/returns/interfaces/specific/reader_future_result.py index 65b60eb55..f6423f359 100644 --- a/returns/interfaces/specific/reader_future_result.py +++ b/returns/interfaces/specific/reader_future_result.py @@ -87,12 +87,12 @@ def from_future_result_context( """Unit method to create new containers from ``ReaderFutureResult``.""" -#: Type alias for kinds with three type arguments. ReaderFutureResultLike3 = ReaderFutureResultLikeN[ _FirstType, _SecondType, _ThirdType, ] +"""Type alias for kinds with three type arguments.""" @final @@ -145,9 +145,9 @@ class ReaderFutureResultBasedN( _laws: ClassVar[Sequence[Law]] = (Law2(_LawSpec.asking_law),) -#: Type alias for kinds with three type arguments. ReaderFutureResultBased3 = ReaderFutureResultBasedN[ _FirstType, _SecondType, _ThirdType, ] +"""Type alias for kinds with three type arguments.""" diff --git a/returns/interfaces/specific/reader_ioresult.py b/returns/interfaces/specific/reader_ioresult.py index 933092712..664e8b9c7 100644 --- a/returns/interfaces/specific/reader_ioresult.py +++ b/returns/interfaces/specific/reader_ioresult.py @@ -64,8 +64,8 @@ def from_ioresult_context( """Unit method to create new containers from ``ReaderIOResult``.""" -#: Type alias for kinds with three type arguments. ReaderIOResultLike3 = ReaderIOResultLikeN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" @final @@ -115,5 +115,5 @@ class ReaderIOResultBasedN( _laws: ClassVar[Sequence[Law]] = (Law2(_LawSpec.asking_law),) -#: Type alias for kinds with three type arguments. ReaderIOResultBased3 = ReaderIOResultBasedN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" diff --git a/returns/interfaces/specific/reader_result.py b/returns/interfaces/specific/reader_result.py index 3a442e38c..2b269adca 100644 --- a/returns/interfaces/specific/reader_result.py +++ b/returns/interfaces/specific/reader_result.py @@ -72,8 +72,8 @@ def from_result_context( """Unit method to create new containers from ``ReaderResult``.""" -#: Type alias for kinds with three type arguments. ReaderResultLike3 = ReaderResultLikeN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" @final @@ -134,5 +134,5 @@ class ReaderResultBasedN( ) -#: Type alias for kinds with three type arguments. ReaderResultBased3 = ReaderResultBasedN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" diff --git a/returns/interfaces/specific/result.py b/returns/interfaces/specific/result.py index 926c73cac..d77ff5ba5 100644 --- a/returns/interfaces/specific/result.py +++ b/returns/interfaces/specific/result.py @@ -60,11 +60,11 @@ def from_result( """Unit method to create new containers from any raw value.""" -#: Type alias for kinds with two type arguments. ResultLike2 = ResultLikeN[_FirstType, _SecondType, Never] +"""Type alias for kinds with two type arguments.""" -#: Type alias for kinds with three type arguments. ResultLike3 = ResultLikeN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" class UnwrappableResult( @@ -101,8 +101,8 @@ class ResultBasedN( __slots__ = () -#: Type alias for kinds with two type arguments. ResultBased2 = ResultBasedN[_FirstType, _SecondType, Never] +"""Type alias for kinds with two type arguments.""" -#: Type alias for kinds with three type arguments. ResultBased3 = ResultBasedN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" diff --git a/returns/interfaces/swappable.py b/returns/interfaces/swappable.py index 7f5318dec..ba72a8faa 100644 --- a/returns/interfaces/swappable.py +++ b/returns/interfaces/swappable.py @@ -59,8 +59,8 @@ def swap( """Swaps first and second types in ``SwappableN``.""" -#: Type alias for kinds with two type arguments. Swappable2 = SwappableN[_FirstType, _SecondType, Never] +"""Type alias for kinds with two type arguments.""" -#: Type alias for kinds with three type arguments. Swappable3 = SwappableN[_FirstType, _SecondType, _ThirdType] +"""Type alias for kinds with three type arguments.""" diff --git a/returns/io.py b/returns/io.py index ad77aa86e..f09159d8f 100644 --- a/returns/io.py +++ b/returns/io.py @@ -62,8 +62,8 @@ class IO( # type: ignore[type-var] _inner_value: _ValueType_co - #: Typesafe equality comparison with other `Result` objects. equals = container_equality + """Typesafe equality comparison with other `Result` objects.""" def __init__(self, inner_value: _ValueType_co) -> None: """ @@ -147,8 +147,8 @@ def bind( """ return dekind(function(self._inner_value)) - #: Alias for `bind` method. Part of the `IOLikeN` interface. bind_io = bind + """Alias for `bind` method. Part of the `IOLikeN` interface.""" def __iter__(self) -> Iterator[_ValueType_co]: """API for :ref:`do-notation`.""" @@ -334,8 +334,8 @@ class IOResult( # type: ignore[type-var] _inner_value: Result[_ValueType_co, _ErrorType_co] __match_args__ = ('_inner_value',) - #: Typesafe equality comparison with other `IOResult` objects. equals = container_equality + """Typesafe equality comparison with other `IOResult` objects.""" def __init__( self, inner_value: Result[_ValueType_co, _ErrorType_co] @@ -464,8 +464,9 @@ def bind( """ - #: Alias for `bind_ioresult` method. Part of the `IOResultBasedN` interface. bind_ioresult = bind + """Alias for `bind_ioresult` method. + Part of the `IOResultBasedN` interface.""" def bind_result( self, @@ -833,8 +834,8 @@ def bind(self, function): """Does nothing for ``IOFailure``.""" return self - #: Alias for `bind_ioresult` method. Part of the `IOResultBasedN` interface. # noqa: E501 bind_ioresult = bind + """Alias for `bind_ioresult` method. Part of the `IOResultBasedN` interface.""" # noqa: E501 WPS484 def bind_result(self, function): """Does nothing for ``IOFailure``.""" @@ -867,8 +868,8 @@ def bind(self, function): """Composes this container with a function returning ``IOResult``.""" # noqa: E501 return function(self._inner_value.unwrap()) - #: Alias for `bind_ioresult` method. Part of the `IOResultBasedN` interface. # noqa: E501 bind_ioresult = bind + """Alias for `bind_ioresult` method. Part of the `IOResultBasedN` interface.""" # noqa: E501 WPS484 def bind_result(self, function): """Binds ``Result`` returning function to current container.""" @@ -886,9 +887,8 @@ def lash(self, function): # Aliases: -#: Alias for ``IOResult[_ValueType_co, Exception]``. IOResultE: TypeAlias = IOResult[_ValueType_co, Exception] - +"""Alias for ``IOResult[_ValueType_co, Exception]``.""" # impure_safe decorator: diff --git a/returns/maybe.py b/returns/maybe.py index c2f512526..7c9bc90f1 100644 --- a/returns/maybe.py +++ b/returns/maybe.py @@ -14,6 +14,7 @@ _ValueType_co = TypeVar('_ValueType_co', covariant=True) _NewValueType = TypeVar('_NewValueType') + _FuncParams = ParamSpec('_FuncParams') @@ -40,11 +41,11 @@ class Maybe( # type: ignore[type-var] _inner_value: _ValueType_co | None __match_args__ = ('_inner_value',) - #: Alias for `Nothing` empty: ClassVar['Maybe[Any]'] + """Alias for `Nothing`.""" - #: Typesafe equality comparison with other `Result` objects. equals = container_equality + """Typesafe equality comparison with other `Result` objects.""" def map( self, @@ -452,8 +453,8 @@ def __bool__(self): return True -#: Public unit value of protected :class:`~_Nothing` type. Nothing: Maybe[Never] = _Nothing() +"""Public unit value of protected :class:`~_Nothing` type.""" Maybe.empty = Nothing diff --git a/returns/methods/cond.py b/returns/methods/cond.py index 432a6f17a..4d1fca14c 100644 --- a/returns/methods/cond.py +++ b/returns/methods/cond.py @@ -79,5 +79,6 @@ def internal_cond( return container_type.empty -#: Kinded version of :func:`~internal_cond`, use it to infer real return type. cond = kinded(internal_cond) +"""Kinded version of :func:`~internal_cond`, +use it to infer real return type.""" diff --git a/returns/pointfree/bind_context.py b/returns/pointfree/bind_context.py index d1c0ecfc0..b1d03dcf7 100644 --- a/returns/pointfree/bind_context.py +++ b/returns/pointfree/bind_context.py @@ -114,5 +114,5 @@ def factory( return factory -#: Useful alias for :func:`~bind_context3`. bind_context = bind_context3 +"""Useful alias for :func:`~bind_context3`.""" diff --git a/returns/pointfree/modify_env.py b/returns/pointfree/modify_env.py index 04a9cb190..cb20cb6eb 100644 --- a/returns/pointfree/modify_env.py +++ b/returns/pointfree/modify_env.py @@ -99,5 +99,5 @@ def factory( return factory -#: Useful alias for :func:`~modify_env3`. modify_env = modify_env3 +"""Useful alias for :func:`~modify_env3`.""" diff --git a/returns/primitives/hkt.py b/returns/primitives/hkt.py index 79207c27c..0d21847df 100644 --- a/returns/primitives/hkt.py +++ b/returns/primitives/hkt.py @@ -97,16 +97,16 @@ def __getattr__(self, attrname: str): """ -#: Type alias for kinds with one type argument. Kind1 = KindN[_InstanceType_co, _TypeArgType1_co, Any, Any] +"""Type alias for kinds with one type argument.""" -#: Type alias for kinds with two type arguments. Kind2 = KindN[_InstanceType_co, _TypeArgType1_co, _TypeArgType2_co, Any] +"""Type alias for kinds with two type arguments.""" -#: Type alias for kinds with three type arguments. Kind3 = KindN[ _InstanceType_co, _TypeArgType1_co, _TypeArgType2_co, _TypeArgType3_co ] +"""Type alias for kinds with three type arguments.""" class SupportsKindN(KindN[_InstanceType_co, *_TypeVars]): @@ -129,29 +129,29 @@ class SupportsKindN(KindN[_InstanceType_co, *_TypeVars]): __getattr__: None # type: ignore -#: Type alias used for inheritance with one type argument. SupportsKind1 = SupportsKindN[ _InstanceType_co, _TypeArgType1_co, Never, Never, ] +"""Type alias used for inheritance with one type argument.""" -#: Type alias used for inheritance with two type arguments. SupportsKind2 = SupportsKindN[ _InstanceType_co, _TypeArgType1_co, _TypeArgType2_co, Never, ] +"""Type alias used for inheritance with two type arguments.""" -#: Type alias used for inheritance with three type arguments. SupportsKind3 = SupportsKindN[ _InstanceType_co, _TypeArgType1_co, _TypeArgType2_co, _TypeArgType3_co, ] +"""Type alias used for inheritance with three type arguments.""" def dekind( @@ -208,8 +208,8 @@ class Kinded(Protocol[_FunctionDefType_co]): # type: ignore __slots__ = () - #: Used to translate `KindN` into real types. __call__: _FunctionDefType_co + """Used to translate `KindN` into real types.""" def __get__( self, diff --git a/returns/primitives/laws.py b/returns/primitives/laws.py index 765691e7d..dcbf14d97 100644 --- a/returns/primitives/laws.py +++ b/returns/primitives/laws.py @@ -9,8 +9,8 @@ _TypeArgType2 = TypeVar('_TypeArgType2') _TypeArgType3 = TypeVar('_TypeArgType3') -#: Special alias to define laws as functions even inside a class law_definition = staticmethod +"""Special alias to define laws as functions even inside a class.""" LAWS_ATTRIBUTE: Final = '_laws' @@ -25,8 +25,8 @@ class Law(Immutable): __slots__ = ('definition',) - #: Function used to define this law. definition: Callable + """Function used to define this law.""" def __init__(self, function) -> None: """Saves function to the inner state.""" @@ -111,8 +111,8 @@ class Lawful(Generic[_Caps]): __slots__ = () - #: Some classes and interfaces might have laws, some might not have any. _laws: ClassVar[Sequence[Law]] + """Some classes and interfaces might have laws, some might not have any.""" @final # noqa: WPS210 @classmethod diff --git a/returns/result.py b/returns/result.py index 6c3c951f9..c54d238a5 100644 --- a/returns/result.py +++ b/returns/result.py @@ -19,11 +19,11 @@ from returns.primitives.exceptions import UnwrapFailedError from returns.primitives.hkt import Kind2, SupportsKind2 -# Definitions: _ValueType_co = TypeVar('_ValueType_co', covariant=True) _NewValueType = TypeVar('_NewValueType') _ErrorType_co = TypeVar('_ErrorType_co', covariant=True) _NewErrorType = TypeVar('_NewErrorType') +"""Definitions.""" _FirstType = TypeVar('_FirstType') _FuncParams = ParamSpec('_FuncParams') @@ -53,8 +53,8 @@ class Result( # type: ignore[type-var] _inner_value: _ValueType_co | _ErrorType_co _trace: list[FrameInfo] | None - #: Typesafe equality comparison with other `Result` objects. equals = container_equality + """Typesafe equality comparison with other `Result` objects.""" @property def trace(self) -> list[FrameInfo] | None: @@ -148,8 +148,8 @@ def bind( """ - #: Alias for `bind_result` method, it is the same as `bind` here. bind_result = bind + """Alias for `bind_result` method, it is the same as `bind` here.""" def alt( self, @@ -374,8 +374,8 @@ def bind(self, function): """Does nothing for ``Failure``.""" return self - #: Alias for `bind` method. Part of the `ResultBasedN` interface. bind_result = bind + """Alias for `bind` method. Part of the `ResultBasedN` interface.""" # noqa: WPS484 def lash(self, function): """Composes this container with a function returning container.""" @@ -437,8 +437,8 @@ def bind(self, function): """Binds current container to a function that returns container.""" return function(self._inner_value) - #: Alias for `bind` method. Part of the `ResultBasedN` interface. bind_result = bind + """Alias for `bind` method. Part of the `ResultBasedN` interface.""" # noqa: WPS484 def lash(self, function): """Does nothing for ``Success``.""" @@ -469,9 +469,8 @@ def failure(self) -> Never: # Aliases: -#: Alias for ``Result[_ValueType_co, Exception]``. ResultE: TypeAlias = Result[_ValueType_co, Exception] - +"""Alias for ``Result[_ValueType_co, Exception]``.""" # Decorators: From 4ed44940207098f4388c9043ffc1cf42d5ff0fbf Mon Sep 17 00:00:00 2001 From: Khabib <136262760+Khabib73@users.noreply.github.com> Date: Wed, 7 Oct 2026 12:51:01 +0300 Subject: [PATCH 2/7] Add dots at the end --- returns/interfaces/altable.py | 2 +- returns/interfaces/applicative.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/returns/interfaces/altable.py b/returns/interfaces/altable.py index f0fc61ab6..1870f4ba4 100644 --- a/returns/interfaces/altable.py +++ b/returns/interfaces/altable.py @@ -23,7 +23,7 @@ _NewType1 = TypeVar('_NewType1') _NewType2 = TypeVar('_NewType2') -"""Used in laws""" +"""Used in laws.""" @final diff --git a/returns/interfaces/applicative.py b/returns/interfaces/applicative.py index cc59fbc59..fc45741ee 100644 --- a/returns/interfaces/applicative.py +++ b/returns/interfaces/applicative.py @@ -24,7 +24,7 @@ _NewType1 = TypeVar('_NewType1') _NewType2 = TypeVar('_NewType2') -"""Only used in laws""" +"""Only used in laws.""" @final From bfdb38b2fd4cc9bffaaf7a17d77db9996b42a2db Mon Sep 17 00:00:00 2001 From: Khabib <136262760+Khabib73@users.noreply.github.com> Date: Wed, 7 Oct 2026 12:58:54 +0300 Subject: [PATCH 3/7] Small fix --- returns/context/requires_context.py | 1 - 1 file changed, 1 deletion(-) diff --git a/returns/context/requires_context.py b/returns/context/requires_context.py index 2202d97c6..4435857c8 100644 --- a/returns/context/requires_context.py +++ b/returns/context/requires_context.py @@ -22,7 +22,6 @@ ) from returns.context.requires_context_result import RequiresContextResult -# Context: _EnvType_contra = TypeVar('_EnvType_contra', contravariant=True) _NewEnvType = TypeVar('_NewEnvType') _ReturnType_co = TypeVar('_ReturnType_co', covariant=True) From d911a9e12769f61d864edcdb28b26aeadeae22d5 Mon Sep 17 00:00:00 2001 From: Khabib <136262760+Khabib73@users.noreply.github.com> Date: Wed, 7 Oct 2026 15:57:55 +0300 Subject: [PATCH 4/7] Revert comments --- returns/context/requires_context.py | 6 +++--- returns/context/requires_context_future_result.py | 6 +++--- returns/context/requires_context_ioresult.py | 4 ++-- returns/context/requires_context_result.py | 6 +++--- returns/interfaces/altable.py | 2 +- returns/interfaces/applicative.py | 2 +- returns/interfaces/container.py | 2 +- returns/interfaces/failable.py | 2 +- returns/interfaces/mappable.py | 2 +- returns/result.py | 2 +- 10 files changed, 17 insertions(+), 17 deletions(-) diff --git a/returns/context/requires_context.py b/returns/context/requires_context.py index 4435857c8..8de9b19ab 100644 --- a/returns/context/requires_context.py +++ b/returns/context/requires_context.py @@ -22,11 +22,11 @@ ) from returns.context.requires_context_result import RequiresContextResult +# Context: _EnvType_contra = TypeVar('_EnvType_contra', contravariant=True) _NewEnvType = TypeVar('_NewEnvType') _ReturnType_co = TypeVar('_ReturnType_co', covariant=True) _NewReturnType = TypeVar('_NewReturnType') -"""Context.""" _ValueType = TypeVar('_ValueType') _ErrorType = TypeVar('_ErrorType') @@ -34,10 +34,10 @@ _FirstType = TypeVar('_FirstType') """Helpers.""" - +# Type Aliases: NoDeps = Any """ -Type Aliases. Sometimes ``RequiresContext`` and other similar types +Sometimes ``RequiresContext`` and other similar types might be used with no explicit dependencies so we need to have this type alias for Any. """ diff --git a/returns/context/requires_context_future_result.py b/returns/context/requires_context_future_result.py index 25f846bd4..c2fab8045 100644 --- a/returns/context/requires_context_future_result.py +++ b/returns/context/requires_context_future_result.py @@ -20,18 +20,18 @@ ) from returns.context.requires_context_result import RequiresContextResult +# Context: _EnvType_contra = TypeVar('_EnvType_contra', contravariant=True) _NewEnvType = TypeVar('_NewEnvType') -"""Context.""" +# Result: _ValueType_co = TypeVar('_ValueType_co', covariant=True) _NewValueType = TypeVar('_NewValueType') _ErrorType_co = TypeVar('_ErrorType_co', covariant=True) _NewErrorType = TypeVar('_NewErrorType') -"""Result.""" +# Helpers: _FirstType = TypeVar('_FirstType') -"""Helpers.""" @final diff --git a/returns/context/requires_context_ioresult.py b/returns/context/requires_context_ioresult.py index aa7848490..f3d66d7c7 100644 --- a/returns/context/requires_context_ioresult.py +++ b/returns/context/requires_context_ioresult.py @@ -14,15 +14,15 @@ from returns.context.requires_context import RequiresContext from returns.context.requires_context_result import RequiresContextResult +# Context: _EnvType_contra = TypeVar('_EnvType_contra', contravariant=True) _NewEnvType = TypeVar('_NewEnvType') -"""Context.""" +# Result: _ValueType_co = TypeVar('_ValueType_co', covariant=True) _NewValueType = TypeVar('_NewValueType') _ErrorType = TypeVar('_ErrorType') _NewErrorType = TypeVar('_NewErrorType') -"""Result.""" @final diff --git a/returns/context/requires_context_result.py b/returns/context/requires_context_result.py index 775666b6b..456d0f2da 100644 --- a/returns/context/requires_context_result.py +++ b/returns/context/requires_context_result.py @@ -12,18 +12,18 @@ if TYPE_CHECKING: from returns.context.requires_context import RequiresContext +# Context: _EnvType_contra = TypeVar('_EnvType_contra', contravariant=True) _NewEnvType = TypeVar('_NewEnvType') -"""Context.""" +# Result: _ValueType_co = TypeVar('_ValueType_co', covariant=True) _NewValueType = TypeVar('_NewValueType') _ErrorType_co = TypeVar('_ErrorType_co', covariant=True) _NewErrorType = TypeVar('_NewErrorType') -"""Result.""" +# Helpers: _FirstType = TypeVar('_FirstType') -"""Helpers.""" @final diff --git a/returns/interfaces/altable.py b/returns/interfaces/altable.py index 1870f4ba4..75bd650bc 100644 --- a/returns/interfaces/altable.py +++ b/returns/interfaces/altable.py @@ -21,9 +21,9 @@ _AltableType = TypeVar('_AltableType', bound='AltableN') +# Used in laws: _NewType1 = TypeVar('_NewType1') _NewType2 = TypeVar('_NewType2') -"""Used in laws.""" @final diff --git a/returns/interfaces/applicative.py b/returns/interfaces/applicative.py index fc45741ee..d602ad4d0 100644 --- a/returns/interfaces/applicative.py +++ b/returns/interfaces/applicative.py @@ -22,9 +22,9 @@ _ApplicativeType = TypeVar('_ApplicativeType', bound='ApplicativeN') +# Only used in laws: _NewType1 = TypeVar('_NewType1') _NewType2 = TypeVar('_NewType2') -"""Only used in laws.""" @final diff --git a/returns/interfaces/container.py b/returns/interfaces/container.py index 9e8fd16de..6cccfc76e 100644 --- a/returns/interfaces/container.py +++ b/returns/interfaces/container.py @@ -17,9 +17,9 @@ _SecondType = TypeVar('_SecondType') _ThirdType = TypeVar('_ThirdType') +# Only used in laws: _NewType1 = TypeVar('_NewType1') _NewType2 = TypeVar('_NewType2') -"""Only used in laws.""" @final diff --git a/returns/interfaces/failable.py b/returns/interfaces/failable.py index 6725478f8..ceaf1974d 100644 --- a/returns/interfaces/failable.py +++ b/returns/interfaces/failable.py @@ -23,8 +23,8 @@ _SingleFailableType = TypeVar('_SingleFailableType', bound='SingleFailableN') _DiverseFailableType = TypeVar('_DiverseFailableType', bound='DiverseFailableN') +# Used in laws: _NewFirstType = TypeVar('_NewFirstType') -"""Used in laws.""" @final diff --git a/returns/interfaces/mappable.py b/returns/interfaces/mappable.py index 893047418..99d14d6cc 100644 --- a/returns/interfaces/mappable.py +++ b/returns/interfaces/mappable.py @@ -21,9 +21,9 @@ _MappableType = TypeVar('_MappableType', bound='MappableN') +# Used in laws: _NewType1 = TypeVar('_NewType1') _NewType2 = TypeVar('_NewType2') -"""Used in laws.""" @final diff --git a/returns/result.py b/returns/result.py index c54d238a5..860bfa302 100644 --- a/returns/result.py +++ b/returns/result.py @@ -19,11 +19,11 @@ from returns.primitives.exceptions import UnwrapFailedError from returns.primitives.hkt import Kind2, SupportsKind2 +# Definitions: _ValueType_co = TypeVar('_ValueType_co', covariant=True) _NewValueType = TypeVar('_NewValueType') _ErrorType_co = TypeVar('_ErrorType_co', covariant=True) _NewErrorType = TypeVar('_NewErrorType') -"""Definitions.""" _FirstType = TypeVar('_FirstType') _FuncParams = ParamSpec('_FuncParams') From 0db03f11748089753242dcb6a7a81f6170560ec0 Mon Sep 17 00:00:00 2001 From: Khabib <136262760+Khabib73@users.noreply.github.com> Date: Wed, 7 Oct 2026 16:00:41 +0300 Subject: [PATCH 5/7] Small fix --- returns/context/requires_context.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/returns/context/requires_context.py b/returns/context/requires_context.py index 8de9b19ab..b96da6307 100644 --- a/returns/context/requires_context.py +++ b/returns/context/requires_context.py @@ -31,8 +31,8 @@ _ValueType = TypeVar('_ValueType') _ErrorType = TypeVar('_ErrorType') +# Helpers: _FirstType = TypeVar('_FirstType') -"""Helpers.""" # Type Aliases: NoDeps = Any From ab2ee8143dba0ebd80ce73015aef53f6e4baea89 Mon Sep 17 00:00:00 2001 From: Khabib <136262760+Khabib73@users.noreply.github.com> Date: Thu, 8 Oct 2026 22:59:44 +0300 Subject: [PATCH 6/7] docs format --- returns/context/requires_context.py | 12 ++++----- .../context/requires_context_future_result.py | 8 +++--- returns/context/requires_context_ioresult.py | 8 +++--- returns/contrib/hypothesis/laws.py | 25 ++++++++++++------- .../mypy/_typeops/transform_callable.py | 7 ++++-- returns/io.py | 6 +++-- 6 files changed, 41 insertions(+), 25 deletions(-) diff --git a/returns/context/requires_context.py b/returns/context/requires_context.py index b96da6307..b55708489 100644 --- a/returns/context/requires_context.py +++ b/returns/context/requires_context.py @@ -36,10 +36,9 @@ # Type Aliases: NoDeps = Any -""" -Sometimes ``RequiresContext`` and other similar types -might be used with no explicit dependencies so we need to -have this type alias for Any. +"""``RequiresContext`` and similar types may be used with no dependencies. + +So we need to have this type alias for Any. """ @@ -82,9 +81,10 @@ class RequiresContext( # type: ignore[type-var] __slots__ = () _inner_value: Callable[[_EnvType_contra], _ReturnType_co] + """This field has an extra ``RequiresContext``. + + Just because ``mypy`` needs it. """ - This field has an extra 'RequiresContext' - just because `mypy` needs it.""" no_args: ClassVar[NoDeps] = object() """A convenient placeholder to call methods created by `.from_value()`.""" diff --git a/returns/context/requires_context_future_result.py b/returns/context/requires_context_future_result.py index c2fab8045..5fd6d268d 100644 --- a/returns/context/requires_context_future_result.py +++ b/returns/context/requires_context_future_result.py @@ -106,9 +106,11 @@ class RequiresContextFutureResult( # type: ignore[type-var] _inner_value: Callable[ [_EnvType_contra], FutureResult[_ValueType_co, _ErrorType_co] ] - """Inner value of `RequiresContext` is just a function - that returns `FutureResult`. This field has an extra - 'RequiresContext' just because `mypy` needs it.""" + """Inner value of ``RequiresContext`` is a function. + + It returns ``FutureResult``. This field has an extra + ``RequiresContext`` just because ``mypy`` needs it. + """ no_args: ClassVar[NoDeps] = object() """A convenient placeholder to call methods created by `.from_value()`.""" diff --git a/returns/context/requires_context_ioresult.py b/returns/context/requires_context_ioresult.py index f3d66d7c7..a24c12327 100644 --- a/returns/context/requires_context_ioresult.py +++ b/returns/context/requires_context_ioresult.py @@ -107,9 +107,11 @@ class RequiresContextIOResult( # type: ignore[type-var] _inner_value: Callable[ [_EnvType_contra], IOResult[_ValueType_co, _ErrorType] ] - """Inner value of `RequiresContext`. Is just a function that - returns `IOResult`. This field has an extra 'RequiresContext' - just because `mypy` needs it.""" + """Inner value of ``RequiresContext`` is a function. + + It returns ``FutureResult``. This field has an extra + ``RequiresContext`` just because ``mypy`` needs it. + """ no_args: ClassVar[NoDeps] = object() """A convenient placeholder to call methods created by `.from_value()`.""" diff --git a/returns/contrib/hypothesis/laws.py b/returns/contrib/hypothesis/laws.py index 476dc6feb..bb1bc8599 100644 --- a/returns/contrib/hypothesis/laws.py +++ b/returns/contrib/hypothesis/laws.py @@ -35,22 +35,29 @@ class Settings: """ settings_kwargs: dict[str, Any] - """Settings directly passed on to `hypothesis`. We support all kwargs from - ``@settings``, see `@settings docs `_.""" + """Settings directly passed on to `hypothesis`. + + We support all kwargs from ``@settings``, see `@settings docs + `_. + """ use_init: bool """Whether to create examples using ``__init__`` instead of the default .""" container_strategy: StrategyFactory | None - """Strategy for generating the container. By default, we generate examples - of a container using: - :func:`returns.contrib.hypothesis.containers.strategy_from_container`.""" + """Strategy for generating the container. + + By default, we generate examples of a container using: + :func:`returns.contrib.hypothesis.containers.strategy_from_container`. + """ type_strategies: dict[type[object], StrategyFactory] - """Strategies for generating values of types other than the container and - its lawful interfaces. This can be useful for overriding ``TypeVar``, - ``Callable``, etc. in case you use certain types that ``hypothesis`` is - unable to find.""" + """Strategies for generating values of non-container types. + + Types other than the container and its lawful interfaces. This can + be useful for overriding ``TypeVar``, ``Callable``, etc. in case you + use certain types that ``hypothesis`` is unable to find. + """ def __post_init__(self) -> None: """Check that the settings are mutually compatible.""" diff --git a/returns/contrib/mypy/_typeops/transform_callable.py b/returns/contrib/mypy/_typeops/transform_callable.py index 68b2e1351..059ae652c 100644 --- a/returns/contrib/mypy/_typeops/transform_callable.py +++ b/returns/contrib/mypy/_typeops/transform_callable.py @@ -24,8 +24,11 @@ from returns.contrib.mypy._structures.args import FuncArg _VARIADIC_KINDS: Final = frozenset((ARG_STAR, ARG_STAR2)) -"""Kinds of arguments that consume the leftover positional or keyword -arguments (``*args`` and ``**kwargs``) and therefore cannot be applied.""" +"""Kinds of arguments that consume leftover arguments. + +These are ``*args`` and ``**kwargs``, which consume the leftover +positional or keyword arguments and therefore cannot be applied. +""" _POSITIONAL_KINDS: Final = frozenset((ARG_POS, ARG_OPT)) """Kinds of arguments that can be passed positionally.""" diff --git a/returns/io.py b/returns/io.py index f09159d8f..d9cd58735 100644 --- a/returns/io.py +++ b/returns/io.py @@ -465,8 +465,10 @@ def bind( """ bind_ioresult = bind - """Alias for `bind_ioresult` method. - Part of the `IOResultBasedN` interface.""" + """Alias for ``bind_ioresult`` method. + + Part of the ``IOResultBasedN`` interface. + """ def bind_result( self, From 0392a35f8adda4c4a3c1401e2024b4d75160d36e Mon Sep 17 00:00:00 2001 From: Khabib <136262760+Khabib73@users.noreply.github.com> Date: Thu, 8 Oct 2026 23:02:03 +0300 Subject: [PATCH 7/7] Small fix --- returns/contrib/hypothesis/laws.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/returns/contrib/hypothesis/laws.py b/returns/contrib/hypothesis/laws.py index bb1bc8599..12a289073 100644 --- a/returns/contrib/hypothesis/laws.py +++ b/returns/contrib/hypothesis/laws.py @@ -35,10 +35,10 @@ class Settings: """ settings_kwargs: dict[str, Any] - """Settings directly passed on to `hypothesis`. + """Settings directly passed on to ``hypothesis``. - We support all kwargs from ``@settings``, see `@settings docs - `_. + We support all kwargs from ``@settings``, see ``@settings docs + ``_. """ use_init: bool