Tips on Making compose Beartype-Checkable

[mentalisttraceur]

I am hoping some of you beartype experts can just instantly answer this.

I've got this package which is a real pain for static type-checking: compose. The Python type-hinting system is particularly inhospitable to doing anything interesting with callables.

But there was popular demand for type checker support, so I provide almost-complete static type-checking support with brute-force @typing.overload for arities 1-16 (and every permutation of regular and awaitable return types, for the async composition variants). Truly, more elegant software has never been written. For a mix of reasons, I did this in separate stub files, in a separate package: compose-stubs.

For the purposes of runtime type-checking, we can do better.

1. When type-checking if callable arguments to a composition constructor are the right type, we could take beartype's randomized check-only-some-of-the-things approach: the single mandatory argument of one callable argument must match the return value of the next - for large argument lists we could sample some pairs of arguments rather than all.

2. When type-checking if a composed instance matches a callable signature, it's barely more than the checking which correctly covers any callable - the only thing that need to be different for composed instances is that the return type is checked on .functions[-1].

3. When type-checking if an object is a composed instance, a simple isinstance check is fine.

So, any tips on what my package should do to provide my users a great beartype type-checking experience?

[leycec]

I am hoping some of you beartype experts can just instantly answer this.

Possibly, I am a @beartype expert. Some may dispute this claim. I curse them all! </awkward>

I've got this package which is a real pain for static type-checking: compose.

...hoo, boy. Fascinating package! Thanks so much for directing our attention to this awesome thing you have made. From one Pythonista that abhors static type-checking to another such Pythonistia, I have possibly bad advice. Nobody likes advice – especially possibly bad advice. Prepare for such advice.

1. Possibly Bad Advice 1: Consider documenting up-front exactly what this suspicious tagline actually means: "The classic compose, with all the Pythonic features." What is this "classic compose" you speak of? This is probably a pure functional programming language thing I should already be familiar with, isn't it? I mean, I once knew Emacs Lisp several decades ago when I still had working pinkies, before Emacs permanently broke my pinkies and gave me Emacs pinky. Emacs, the cathartic vitriol I feel for you is real. Wait. What we were talking about again? Oh, right. Your awesome package. In short, I genuinely had no idea what your awesome package actually did until I parsed the code. Even then, it was a struggle. It wasn't until I parsed your static stubs that I finally got it. For dangerously ignorant devbros such as myself, consider expanding the introduction with additional clarification: e.g.,

The classic compose, with all the Pythonic features. The compose.compose function published by this package creates and returns a new callable functionally composing all user-defined callables passed to that function such that:

• The last callable passed to compose.compose may accept arbitrary arguments.
• Every other callable passed to compose.compose must accept:
  • Only positional arguments.
  • The same number and types of arguments as returned by the next callable passed to compose.compose.
• The new callable created and returned by compose.compose:
  • Accepts all arguments accepted by the first callable passed to compose.compose.
  • Returns the value returned by the last callable passed to compose.compose.
  • Iteratively calls each callable passed to compose.compose in the reverse order (i.e., starting with the last callable and ending with the first callable). Specifically, this new callable:
    1. Calls the last callable passed to compose.compose with all passed arguments.
    2. Calls the second-to-last callable passed to compose.compose with the value returned by the prior call to that last callable.
       ...
       N. Calls the first callable passed to compose.compose with the value returned by the prior call to that second callable passed to compose.compose.
       Examples or it didn't happen:

from compose import compose
from collections.abc import Callable
from numbers import Number

def multiply(a: Number, b: Number = 2) -> Number:
    '''
    Multiply the passed two numbers, defaulting the second passed number to 2
    as a fallback for a doubling operation. Why? *Because we can.*
    '''
    return a*b

def increment(z: Number) -> Number:
    '''
    Increment the passed number by 1. Look. Just do what I say, Python!
    '''
    return z+1

increment_then_multiply: Callable[[Number, Number], Number] = compose(multiply, increment)
'''
Callable first multiplying the passed two numbers and then incrementing
the resulting number by 1. Believe in the power of function composition.
'''

assert increment_then_multiply(a=1.2, b=42) == 51.4  # <-- *woah*

That is something that @leycec would actually understand. Anything less than that is nothing that @leycec would understand. Admittedly, I am beyond neuro-divergent. I have Asperger's and thus need algorithms to be explicitly laid out for me in literal terms that even a malignant sloth baby would understand.

3. Possibly Bad Advice 3: Consider dramatically restructuring this awesome package. While admirable in its tenacity and gluttonous penchant for self-inflicted sadomasochism, the current structure of compose is super-intense and (arguably) overkill. I know overkill when I sees overkill. I play video games, where genocidally overkilling everything that bleeds happens alot. Notably:
   • All older Python versions preceding Python < 3.8 have already hit their official End-of-Life (EOL). Those versions constitute extreme security risks. As an open-source author already devoting your valuable lifeblood and precious time to the just cause of free-as-in-everything software, you absolutely do not need to and should not care about any older Python versions. @beartype certainly doesn't. Neither does anything else. Neither should compose. Abandon insecure Python versions immediately. This is the way. Thus spake @leycec and the bear. Instead:
     • Consider removing the obsolete no_positional_only_arguments.py and no_async.py modules. Since all Python ≥ 3.8 versions fully support both positional-only arguments and async, those modules are no longer relevant and only complicating an already complicated usage pattern.
     • Likewise, consider renaming normal.py to simply compose.py.
   • Stub files violate Don't Repeat Yourself (DRY) and are largely obsolete in the modern Python ecosystem. You've additionally complicated matters here by requiring users install yet another dependency just to enable static type-checking, which isn't a great look. Really, the only valid use case for stub files in 2023 is the official Python typeshed. For space and time complexity reasons, CPython (perhaps justifiably) prefers to externalize type hints to a third-party package. But those reasons generally don't apply to other packages. They sure don't apply to compose. Instead:
     • Consider generalizing your single compose.py module into a full-blown compose/ package with an internal directory structure resembling:
       • A top-level compose/ directory, which contains...

         • An __init__.py file, which resembles:

           __all__ = ('compose', 'acompose', 'sacompose',)
           
           from typing import TYPE_CHECKING
           
           # If performing pure static type-checking (e.g., from within an IDE),
           # do *NOT* even bother importing anything from this package. Instead,
           # simply define brute-force @typing.overload for arities 1-16 (and
           # every permutation of regular and awaitable return types, for the
           # async composition variants).
           #
           # Truly, more elegant software has never been written.
           if TYPE_CHECKING:
               from typing import Awaitable, Callable, ParamSpec, TypeVar, Union, overload
               P = ParamSpec('P')
               R1 = TypeVar('R1')
               R2 = TypeVar('R2')
               R3 = TypeVar('R3')
               R4 = TypeVar('R4')
               R5 = TypeVar('R5')
               R6 = TypeVar('R6')
               R7 = TypeVar('R7')
               R8 = TypeVar('R8')
               R9 = TypeVar('R9')
               R10 = TypeVar('R10')
               R11 = TypeVar('R11')
               R12 = TypeVar('R12')
               R13 = TypeVar('R13')
               R14 = TypeVar('R14')
               R15 = TypeVar('R15')
               @overload
               def compose(f1: Callable[P, R1], /) -> Callable[P, R1]:
                   ...
               @overload
               def compose(f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R2]:
                   ...
               @overload
               def compose(f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R3]:
                   ...
               @overload
               def compose(f4: Callable[[R3], R4], f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R4]:
                   ...
               @overload
               def compose(f5: Callable[[R4], R5], f4: Callable[[R3], R4], f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R5]:
                   ...
               @overload
               def compose(f6: Callable[[R5], R6], f5: Callable[[R4], R5], f4: Callable[[R3], R4], f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R6]:
                   ...
               @overload
               def compose(f7: Callable[[R6], R7], f6: Callable[[R5], R6], f5: Callable[[R4], R5], f4: Callable[[R3], R4], f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R7]:
                   ...
               @overload
               def compose(f8: Callable[[R7], R8], f7: Callable[[R6], R7], f6: Callable[[R5], R6], f5: Callable[[R4], R5], f4: Callable[[R3], R4], f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R8]:
                   ...
               @overload
               def compose(f9: Callable[[R8], R9], f8: Callable[[R7], R8], f7: Callable[[R6], R7], f6: Callable[[R5], R6], f5: Callable[[R4], R5], f4: Callable[[R3], R4], f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R9]:
                   ...
               @overload
               def compose(f10: Callable[[R9], R10], f9: Callable[[R8], R9], f8: Callable[[R7], R8], f7: Callable[[R6], R7], f6: Callable[[R5], R6], f5: Callable[[R4], R5], f4: Callable[[R3], R4], f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R10]:
                   ...
               @overload
               def compose(f11: Callable[[R10], R11], f10: Callable[[R9], R10], f9: Callable[[R8], R9], f8: Callable[[R7], R8], f7: Callable[[R6], R7], f6: Callable[[R5], R6], f5: Callable[[R4], R5], f4: Callable[[R3], R4], f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R11]:
                   ...
               @overload
               def compose(f12: Callable[[R11], R12], f11: Callable[[R10], R11], f10: Callable[[R9], R10], f9: Callable[[R8], R9], f8: Callable[[R7], R8], f7: Callable[[R6], R7], f6: Callable[[R5], R6], f5: Callable[[R4], R5], f4: Callable[[R3], R4], f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R12]:
                   ...
               @overload
               def compose(f13: Callable[[R12], R13], f12: Callable[[R11], R12], f11: Callable[[R10], R11], f10: Callable[[R9], R10], f9: Callable[[R8], R9], f8: Callable[[R7], R8], f7: Callable[[R6], R7], f6: Callable[[R5], R6], f5: Callable[[R4], R5], f4: Callable[[R3], R4], f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R13]:
                   ...
               @overload
               def compose(f14: Callable[[R13], R14], f13: Callable[[R12], R13], f12: Callable[[R11], R12], f11: Callable[[R10], R11], f10: Callable[[R9], R10], f9: Callable[[R8], R9], f8: Callable[[R7], R8], f7: Callable[[R6], R7], f6: Callable[[R5], R6], f5: Callable[[R4], R5], f4: Callable[[R3], R4], f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R14]:
                   ...
               @overload
               def compose(f15: Callable[[R14], R15], f14: Callable[[R13], R14], f13: Callable[[R12], R13], f12: Callable[[R11], R12], f11: Callable[[R10], R11], f10: Callable[[R9], R10], f9: Callable[[R8], R9], f8: Callable[[R7], R8], f7: Callable[[R6], R7], f6: Callable[[R5], R6], f5: Callable[[R4], R5], f4: Callable[[R3], R4], f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R15]:
                   ...
               @overload
               def acompose(f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R1]]:
                   ...
               @overload
               def acompose(f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R2]]:
                   ...
               @overload
               def acompose(f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R3]]:
                   ...
               @overload
               def acompose(f4: Callable[[R3], Union[R4, Awaitable[R4]]], f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R4]]:
                   ...
               @overload
               def acompose(f5: Callable[[R4], Union[R5, Awaitable[R5]]], f4: Callable[[R3], Union[R4, Awaitable[R4]]], f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R5]]:
                   ...
               @overload
               def acompose(f6: Callable[[R5], Union[R6, Awaitable[R6]]], f5: Callable[[R4], Union[R5, Awaitable[R5]]], f4: Callable[[R3], Union[R4, Awaitable[R4]]], f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R6]]:
                   ...
               @overload
               def acompose(f7: Callable[[R6], Union[R7, Awaitable[R7]]], f6: Callable[[R5], Union[R6, Awaitable[R6]]], f5: Callable[[R4], Union[R5, Awaitable[R5]]], f4: Callable[[R3], Union[R4, Awaitable[R4]]], f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R7]]:
                   ...
               @overload
               def acompose(f8: Callable[[R7], Union[R8, Awaitable[R8]]], f7: Callable[[R6], Union[R7, Awaitable[R7]]], f6: Callable[[R5], Union[R6, Awaitable[R6]]], f5: Callable[[R4], Union[R5, Awaitable[R5]]], f4: Callable[[R3], Union[R4, Awaitable[R4]]], f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R8]]:
                   ...
               @overload
               def acompose(f9: Callable[[R8], Union[R9, Awaitable[R9]]], f8: Callable[[R7], Union[R8, Awaitable[R8]]], f7: Callable[[R6], Union[R7, Awaitable[R7]]], f6: Callable[[R5], Union[R6, Awaitable[R6]]], f5: Callable[[R4], Union[R5, Awaitable[R5]]], f4: Callable[[R3], Union[R4, Awaitable[R4]]], f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R9]]:
                   ...
               @overload
               def acompose(f10: Callable[[R9], Union[R10, Awaitable[R10]]], f9: Callable[[R8], Union[R9, Awaitable[R9]]], f8: Callable[[R7], Union[R8, Awaitable[R8]]], f7: Callable[[R6], Union[R7, Awaitable[R7]]], f6: Callable[[R5], Union[R6, Awaitable[R6]]], f5: Callable[[R4], Union[R5, Awaitable[R5]]], f4: Callable[[R3], Union[R4, Awaitable[R4]]], f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R10]]:
                   ...
               @overload
               def acompose(f11: Callable[[R10], Union[R11, Awaitable[R11]]], f10: Callable[[R9], Union[R10, Awaitable[R10]]], f9: Callable[[R8], Union[R9, Awaitable[R9]]], f8: Callable[[R7], Union[R8, Awaitable[R8]]], f7: Callable[[R6], Union[R7, Awaitable[R7]]], f6: Callable[[R5], Union[R6, Awaitable[R6]]], f5: Callable[[R4], Union[R5, Awaitable[R5]]], f4: Callable[[R3], Union[R4, Awaitable[R4]]], f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R11]]:
                   ...
               @overload
               def acompose(f12: Callable[[R11], Union[R12, Awaitable[R12]]], f11: Callable[[R10], Union[R11, Awaitable[R11]]], f10: Callable[[R9], Union[R10, Awaitable[R10]]], f9: Callable[[R8], Union[R9, Awaitable[R9]]], f8: Callable[[R7], Union[R8, Awaitable[R8]]], f7: Callable[[R6], Union[R7, Awaitable[R7]]], f6: Callable[[R5], Union[R6, Awaitable[R6]]], f5: Callable[[R4], Union[R5, Awaitable[R5]]], f4: Callable[[R3], Union[R4, Awaitable[R4]]], f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R12]]:
                   ...
               @overload
               def acompose(f13: Callable[[R12], Union[R13, Awaitable[R13]]], f12: Callable[[R11], Union[R12, Awaitable[R12]]], f11: Callable[[R10], Union[R11, Awaitable[R11]]], f10: Callable[[R9], Union[R10, Awaitable[R10]]], f9: Callable[[R8], Union[R9, Awaitable[R9]]], f8: Callable[[R7], Union[R8, Awaitable[R8]]], f7: Callable[[R6], Union[R7, Awaitable[R7]]], f6: Callable[[R5], Union[R6, Awaitable[R6]]], f5: Callable[[R4], Union[R5, Awaitable[R5]]], f4: Callable[[R3], Union[R4, Awaitable[R4]]], f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R13]]:
                   ...
               @overload
               def acompose(f14: Callable[[R13], Union[R14, Awaitable[R14]]], f13: Callable[[R12], Union[R13, Awaitable[R13]]], f12: Callable[[R11], Union[R12, Awaitable[R12]]], f11: Callable[[R10], Union[R11, Awaitable[R11]]], f10: Callable[[R9], Union[R10, Awaitable[R10]]], f9: Callable[[R8], Union[R9, Awaitable[R9]]], f8: Callable[[R7], Union[R8, Awaitable[R8]]], f7: Callable[[R6], Union[R7, Awaitable[R7]]], f6: Callable[[R5], Union[R6, Awaitable[R6]]], f5: Callable[[R4], Union[R5, Awaitable[R5]]], f4: Callable[[R3], Union[R4, Awaitable[R4]]], f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R14]]:
                   ...
               @overload
               def acompose(f15: Callable[[R14], Union[R15, Awaitable[R15]]], f14: Callable[[R13], Union[R14, Awaitable[R14]]], f13: Callable[[R12], Union[R13, Awaitable[R13]]], f12: Callable[[R11], Union[R12, Awaitable[R12]]], f11: Callable[[R10], Union[R11, Awaitable[R11]]], f10: Callable[[R9], Union[R10, Awaitable[R10]]], f9: Callable[[R8], Union[R9, Awaitable[R9]]], f8: Callable[[R7], Union[R8, Awaitable[R8]]], f7: Callable[[R6], Union[R7, Awaitable[R7]]], f6: Callable[[R5], Union[R6, Awaitable[R6]]], f5: Callable[[R4], Union[R5, Awaitable[R5]]], f4: Callable[[R3], Union[R4, Awaitable[R4]]], f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R15]]:
                   ...
               @overload
               def sacompose(f1: Callable[P, R1], /) -> Callable[P, R1]:
                   ...
               @overload
               def sacompose(f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R2]:
                   ...
               @overload
               def sacompose(f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R3]:
                   ...
               @overload
               def sacompose(f4: Callable[[R3], R4], f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R4]:
                   ...
               @overload
               def sacompose(f5: Callable[[R4], R5], f4: Callable[[R3], R4], f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R5]:
                   ...
               @overload
               def sacompose(f6: Callable[[R5], R6], f5: Callable[[R4], R5], f4: Callable[[R3], R4], f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R6]:
                   ...
               @overload
               def sacompose(f7: Callable[[R6], R7], f6: Callable[[R5], R6], f5: Callable[[R4], R5], f4: Callable[[R3], R4], f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R7]:
                   ...
               @overload
               def sacompose(f8: Callable[[R7], R8], f7: Callable[[R6], R7], f6: Callable[[R5], R6], f5: Callable[[R4], R5], f4: Callable[[R3], R4], f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R8]:
                   ...
               @overload
               def sacompose(f9: Callable[[R8], R9], f8: Callable[[R7], R8], f7: Callable[[R6], R7], f6: Callable[[R5], R6], f5: Callable[[R4], R5], f4: Callable[[R3], R4], f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R9]:
                   ...
               @overload
               def sacompose(f10: Callable[[R9], R10], f9: Callable[[R8], R9], f8: Callable[[R7], R8], f7: Callable[[R6], R7], f6: Callable[[R5], R6], f5: Callable[[R4], R5], f4: Callable[[R3], R4], f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R10]:
                   ...
               @overload
               def sacompose(f11: Callable[[R10], R11], f10: Callable[[R9], R10], f9: Callable[[R8], R9], f8: Callable[[R7], R8], f7: Callable[[R6], R7], f6: Callable[[R5], R6], f5: Callable[[R4], R5], f4: Callable[[R3], R4], f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R11]:
                   ...
               @overload
               def sacompose(f12: Callable[[R11], R12], f11: Callable[[R10], R11], f10: Callable[[R9], R10], f9: Callable[[R8], R9], f8: Callable[[R7], R8], f7: Callable[[R6], R7], f6: Callable[[R5], R6], f5: Callable[[R4], R5], f4: Callable[[R3], R4], f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R12]:
                   ...
               @overload
               def sacompose(f13: Callable[[R12], R13], f12: Callable[[R11], R12], f11: Callable[[R10], R11], f10: Callable[[R9], R10], f9: Callable[[R8], R9], f8: Callable[[R7], R8], f7: Callable[[R6], R7], f6: Callable[[R5], R6], f5: Callable[[R4], R5], f4: Callable[[R3], R4], f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R13]:
                   ...
               @overload
               def sacompose(f14: Callable[[R13], R14], f13: Callable[[R12], R13], f12: Callable[[R11], R12], f11: Callable[[R10], R11], f10: Callable[[R9], R10], f9: Callable[[R8], R9], f8: Callable[[R7], R8], f7: Callable[[R6], R7], f6: Callable[[R5], R6], f5: Callable[[R4], R5], f4: Callable[[R3], R4], f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R14]:
                   ...
               @overload
               def sacompose(f15: Callable[[R14], R15], f14: Callable[[R13], R14], f13: Callable[[R12], R13], f12: Callable[[R11], R12], f11: Callable[[R10], R11], f10: Callable[[R9], R10], f9: Callable[[R8], R9], f8: Callable[[R7], R8], f7: Callable[[R6], R7], f6: Callable[[R5], R6], f5: Callable[[R4], R5], f4: Callable[[R3], R4], f3: Callable[[R2], R3], f2: Callable[[R1], R2], f1: Callable[P, R1], /) -> Callable[P, R15]:
                   ...
               @overload
               def sacompose(f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R1]]:
                   ...
               @overload
               def sacompose(f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R2]]:
                   ...
               @overload
               def sacompose(f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R3]]:
                   ...
               @overload
               def sacompose(f4: Callable[[R3], Union[R4, Awaitable[R4]]], f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R4]]:
                   ...
               @overload
               def sacompose(f5: Callable[[R4], Union[R5, Awaitable[R5]]], f4: Callable[[R3], Union[R4, Awaitable[R4]]], f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R5]]:
                   ...
               @overload
               def sacompose(f6: Callable[[R5], Union[R6, Awaitable[R6]]], f5: Callable[[R4], Union[R5, Awaitable[R5]]], f4: Callable[[R3], Union[R4, Awaitable[R4]]], f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R6]]:
                   ...
               @overload
               def sacompose(f7: Callable[[R6], Union[R7, Awaitable[R7]]], f6: Callable[[R5], Union[R6, Awaitable[R6]]], f5: Callable[[R4], Union[R5, Awaitable[R5]]], f4: Callable[[R3], Union[R4, Awaitable[R4]]], f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R7]]:
                   ...
               @overload
               def sacompose(f8: Callable[[R7], Union[R8, Awaitable[R8]]], f7: Callable[[R6], Union[R7, Awaitable[R7]]], f6: Callable[[R5], Union[R6, Awaitable[R6]]], f5: Callable[[R4], Union[R5, Awaitable[R5]]], f4: Callable[[R3], Union[R4, Awaitable[R4]]], f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R8]]:
                   ...
               @overload
               def sacompose(f9: Callable[[R8], Union[R9, Awaitable[R9]]], f8: Callable[[R7], Union[R8, Awaitable[R8]]], f7: Callable[[R6], Union[R7, Awaitable[R7]]], f6: Callable[[R5], Union[R6, Awaitable[R6]]], f5: Callable[[R4], Union[R5, Awaitable[R5]]], f4: Callable[[R3], Union[R4, Awaitable[R4]]], f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R9]]:
                   ...
               @overload
               def sacompose(f10: Callable[[R9], Union[R10, Awaitable[R10]]], f9: Callable[[R8], Union[R9, Awaitable[R9]]], f8: Callable[[R7], Union[R8, Awaitable[R8]]], f7: Callable[[R6], Union[R7, Awaitable[R7]]], f6: Callable[[R5], Union[R6, Awaitable[R6]]], f5: Callable[[R4], Union[R5, Awaitable[R5]]], f4: Callable[[R3], Union[R4, Awaitable[R4]]], f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R10]]:
                   ...
               @overload
               def sacompose(f11: Callable[[R10], Union[R11, Awaitable[R11]]], f10: Callable[[R9], Union[R10, Awaitable[R10]]], f9: Callable[[R8], Union[R9, Awaitable[R9]]], f8: Callable[[R7], Union[R8, Awaitable[R8]]], f7: Callable[[R6], Union[R7, Awaitable[R7]]], f6: Callable[[R5], Union[R6, Awaitable[R6]]], f5: Callable[[R4], Union[R5, Awaitable[R5]]], f4: Callable[[R3], Union[R4, Awaitable[R4]]], f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R11]]:
                   ...
               @overload
               def sacompose(f12: Callable[[R11], Union[R12, Awaitable[R12]]], f11: Callable[[R10], Union[R11, Awaitable[R11]]], f10: Callable[[R9], Union[R10, Awaitable[R10]]], f9: Callable[[R8], Union[R9, Awaitable[R9]]], f8: Callable[[R7], Union[R8, Awaitable[R8]]], f7: Callable[[R6], Union[R7, Awaitable[R7]]], f6: Callable[[R5], Union[R6, Awaitable[R6]]], f5: Callable[[R4], Union[R5, Awaitable[R5]]], f4: Callable[[R3], Union[R4, Awaitable[R4]]], f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R12]]:
                   ...
               @overload
               def sacompose(f13: Callable[[R12], Union[R13, Awaitable[R13]]], f12: Callable[[R11], Union[R12, Awaitable[R12]]], f11: Callable[[R10], Union[R11, Awaitable[R11]]], f10: Callable[[R9], Union[R10, Awaitable[R10]]], f9: Callable[[R8], Union[R9, Awaitable[R9]]], f8: Callable[[R7], Union[R8, Awaitable[R8]]], f7: Callable[[R6], Union[R7, Awaitable[R7]]], f6: Callable[[R5], Union[R6, Awaitable[R6]]], f5: Callable[[R4], Union[R5, Awaitable[R5]]], f4: Callable[[R3], Union[R4, Awaitable[R4]]], f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R13]]:
                   ...
               @overload
               def sacompose(f14: Callable[[R13], Union[R14, Awaitable[R14]]], f13: Callable[[R12], Union[R13, Awaitable[R13]]], f12: Callable[[R11], Union[R12, Awaitable[R12]]], f11: Callable[[R10], Union[R11, Awaitable[R11]]], f10: Callable[[R9], Union[R10, Awaitable[R10]]], f9: Callable[[R8], Union[R9, Awaitable[R9]]], f8: Callable[[R7], Union[R8, Awaitable[R8]]], f7: Callable[[R6], Union[R7, Awaitable[R7]]], f6: Callable[[R5], Union[R6, Awaitable[R6]]], f5: Callable[[R4], Union[R5, Awaitable[R5]]], f4: Callable[[R3], Union[R4, Awaitable[R4]]], f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R14]]:
                   ...
               @overload
               def sacompose(f15: Callable[[R14], Union[R15, Awaitable[R15]]], f14: Callable[[R13], Union[R14, Awaitable[R14]]], f13: Callable[[R12], Union[R13, Awaitable[R13]]], f12: Callable[[R11], Union[R12, Awaitable[R12]]], f11: Callable[[R10], Union[R11, Awaitable[R11]]], f10: Callable[[R9], Union[R10, Awaitable[R10]]], f9: Callable[[R8], Union[R9, Awaitable[R9]]], f8: Callable[[R7], Union[R8, Awaitable[R8]]], f7: Callable[[R6], Union[R7, Awaitable[R7]]], f6: Callable[[R5], Union[R6, Awaitable[R6]]], f5: Callable[[R4], Union[R5, Awaitable[R5]]], f4: Callable[[R3], Union[R4, Awaitable[R4]]], f3: Callable[[R2], Union[R3, Awaitable[R3]]], f2: Callable[[R1], Union[R2, Awaitable[R2]]], f1: Callable[P, Union[R1, Awaitable[R1]]], /) -> Callable[P, Awaitable[R15]]:
                   ...
           # Else, this package is actually being imported at runtime. In this common case,
           # actually do import all public attributes from this private submodule into this
           # public package namespace.
           else:
               # Optionally, runtime type-check your entire package with @beartype! Yay!
               try:
                   from beartype.claw import beartype_this_package
                   beartype_this_package()  # <-- *DONE.*
               # ...or don't. You know. Totally up to you, awesome dev.
               except ImportError:
                   pass
           
               from compose._main import compose, acompose, sacompose

         • A _main.py file. This is just your existing normal.py module renamed to compose/_main.py. That's it. Congrats, bro! You no longer need to maintain a separate hideous stubs package that is surely crushing your will to live code even as we speak.

4. Possibly Bad Advice 4: Consider dropping setup.py entirely for pyproject.toml + Hatch, the officially sanctioned modern replacement for setuptools. I've swapped out setuptools for Hatch everywhere except @beartype, where technical debt and crippling laziness have momentarily prevented @beartype from transitioning to Hatch. setuptools is insane. Choose sanity. Choose Hatch.
5. Possibly Bad Advice 6: There's some kinda crazy class stuff going on in normal.py. Rather than define a genuine abstract base class (ABC)-driven class hierarchy, you've instead opted to manually monkey-patch methods from what is basically your root ABC (i.e., the compose.compose class) into each of what is basically your subclasses (i.e., the compose.acompose and compose.sacompose classes). This isn't just a semantic dispute, however. By failing to leverage inheritance, you've also prevented users from reliably detecting composed callables. Although your documentation claims that "When programmatically inspecting arbitrary callables, we can check if we are looking at a compose instance...", that doesn't actually work for callables composed with either acompose() or sacompose(). Right? Right. So, the solution is to heavily refactor normal.py to leverage a proper class hierarchy: e.g.,

class ComposeType(object):
    '''
    Abstract base class (ABC) of all composed functions.
    '''

    def __init__(self, *functions):
        """Initialize the composed function.

        Arguments:
            *functions: Functions (or other callables) to compose.

        Raises:
            TypeError:
                If no arguments are given.
                If any argument is not callable.
        """
        if not functions:
            raise TypeError(_name(self) + '() needs at least one argument')
        _functions = []
        for function in reversed(functions):
            if not callable(function):
                raise TypeError(_name(self) + '() arguments must be callable')
            if isinstance(function, ComposeType):
                _functions.extend(function.functions)
            else:
                _functions.append(function)
        self.__wrapped__ = _functions[0]
        self._wrappers = tuple(_functions[1:])

    def __get__(self, obj, objtype=None):
        """Get the composed function as a bound method."""
        wrapped = self.__wrapped__
        try:
            bind = type(wrapped).__get__
        except AttributeError:
            return self
        bound_wrapped = bind(wrapped, obj, objtype)
        if bound_wrapped is wrapped:
            return self
        bound_self = type(self)(bound_wrapped)
        bound_self._wrappers = self._wrappers
        return bound_self


class compose(ComposeType):
    """Function composition: compose(f, g)(...) is equivalent to f(g(...))."""

    def __call__(self, /, *args, **kwargs):
        """Call the composed function."""
        result = self.__wrapped__(*args, **kwargs)
        for function in self._wrappers:
            result = function(result)
        return result

...

7. Possibly Bad Advice 7: I'm kinda unclear whether even the @typing.overload stubs you've defined are correct. User-defined callables can return multiple parameters. If I'm reading your code correctly (...I'm probably not), compose.compose() appears to possibly already support composing callables that return multiple parameters? Possibly? If it doesn't already, it should probably be improved to do that. Probably? Do those @typing.overload stubs support that? Sadly, I don't use TypeVar type hints in my own personal code much. Heresy! I know. But TypeVar type hints are largely useless at runtime, so... I am dumb. In short, I don't actually know whether they can bind to arbitrary variadic returns like Tuple[int, ...] in the way that your code appears to support. It is a conundrum.
8. Possibly Bad Advice 8: You absolutely could do this:

1. When type-checking if callable arguments to a composition constructor are the right type, we could take beartype's randomized check-only-some-of-the-things approach: the single mandatory argument of one callable argument must match the return value of the next - for large argument lists we could sample some pairs of arguments rather than all.

But that's probably overkill too, right? Python isn't that slow. Okay. Python is disastrously slow. But the only reason @beartype opted for O(1)-style RNGesus is that @beartype (A) cannot predict the size of input containers and (B) is commonly deployed in machine learning (ML) stacks, where the size of input containers is effectively infinitely large.

Those same constraints don't really apply to compose. The number of functions passed to compose is almost certainly maybe always going to be less than 100 or so, right? Efficiency isn't particularly a concern here – especially as the efficiency cost of type-checking the correctness of the signatures of these functions is paid at function-composition time, which typically only occurs at global scope and thus once-per-Python-process. compose.compose() isn't something being routinely called in tight inner loops, right? Right.

Moreover, the efficiency cost of type-checking correctness is way less than the QA cost of not type-checking correctness. You pretty much always want to type-check correctness in your case. Since the compose.compose() class has a fairly non-intuitive API, it's pivotal that callers be immediately informed at runtime when they violate that API.

The easiest way to enforce your API at runtime is probably with inline type hints + the standard inspect.signature() function in normal.py. Assuming you previously called beartype_this_package(), you no longer need to validate that passed objects are actually callable. Sadly, you do need to validate that passed callables satisfy your requisite parameter-return chaining API: e.g.,

from collections.abc import Callable
from inspect import signature

class ComposeType(object):
    '''
    Abstract base class (ABC) of all composed functions.
    '''

    def __init__(self, *functions: Callable) -> None:
        """Initialize the composed function.

        Arguments:
            *functions: Functions (or other callables) to compose.

        Raises:
            TypeError:
                If no arguments are given.
                If any argument is not callable.
        """
        if not functions:
            raise TypeError(_name(self) + '() needs at least one argument')
        _functions = []

        # "inspect.Signature" objects introspecting the currently and previously
        # visited callables in the passed tuple of callables (respectively).
        func_curr_signature = None
        func_prev_signature = None

        for function in reversed(functions):
            if isinstance(function, ComposeType):
                _functions.extend(function.functions)
            else:
                _functions.append(function)

            func_curr_signature = signature(function)

            if func_prev_signature:
                if not len(func_curr_signature.parameters) == 1:
                    raise TypeError(
                        f'{func_curr_signature} accepts '
                        f'{len(func_curr_signature.parameters)} arguments '
                        f'rather than exactly one argument.'
                    )

                # "inspect.Parameter" object introspecting the only argument
                # accepted by this callable. Just trust us on this one. Yikes!
                func_arg = next(iter(func_curr_signature.parameters.values()))

                if func_arg.annotation != func_prev_signature.return_annotation:
                    raise TypeError(
                        f'{func_curr_signature} argument '
                        f'"{func_arg.name}" type {repr(func_arg.annotation)} != '
                        f'{func_prev_signature} return type '
                        f'{repr(func_prev_signature.return_annotation)}.'
                    )

                #FIXME: Check for everything else, too. For example, you'll want
                #to prohibit variadic arguments, keyword-only arguments...
                #yadda, yadda! *sigh*

            func_prev_signature = func_curr_signature

        self.__wrapped__ = _functions[0]
        self._wrappers = tuple(_functions[1:])

As the above sample code demonstrates (and as you yourself already astutely realized), what you want to do is well outside of Python's existing litany of Python Enhancement Proposals (PEPs). But @beartype is based almost entirely on PEPs! This means what you think it means: because PEPs cannot help you much here, @beartype cannot help you much here. I mean, @beartype can validate a few things of interest to both you and your users – but alot less than you'll like.

You'll have to do most of the heavy lifting yourself. Thankfully, the standard inspect.signature() class should make that mostly trivial and not so heavy after all.

And... there goes Wednesday evening. How did this happen to us, @beartype!?!? 😮‍💨

[mentalisttraceur]

Wow that is a very extensive response, with a whole lot of work put into it, thank you.

Quick answers to the things that have quick answers:

• This has given me good perspective on what an unfamiliar dev should be told in my docs (both as a user and as a prospective contributor).

• Re: advice 1: when I have time to revisit the explanation/docs, this will really help out!

  My original target was people who already know compose as a functional programming primitive, and want it without a larger functional-programming library, or want a better one than those libraries offer (for some opinionated definitions of "better").

  Eventually it might be good for me to include a full tutorial/explanation of function composition for the unfamiliar in the package docs, or at least link to one. I appreciate the full example of what kind of explanation would've helped you.

• Could you describe the path you took from deciding to look at the source to figuring out that normal.py is the canonical source and the others are fallback source for older Pythons?

  (I'd like to identify the first/best place where I could helpfully clarify/direct that for someone who is intending to look at the source.)

• Re: advice 6: compose, acompose, and sacompose are unrelated classes on purpose - it would be wrong for most code to treat them as interchangeable without consciously understanding and opting into the ramifications. And if I ever come across an isinstance check or type hint which allows more than one of them, that's the kind of thing I want to see explicitly.

  Because most code either only works with regular callables or async callables, not both, and almost no code is ready to handle callables which might be either sync or async where you technically won't know for sure until after you've called it.)

  (I could've still moved the functionality into a common base class and just kept that class private, but at that point it starts to seem like taking on a couple of tiny downsides just for the sake of sharing behavior in a more familiar (but possibly misleading) way.)

• Re: advice 7: The type hints reflect the limitation (conventional/standard among Python function composition implementations) that if you return a tuple, it will not be unpacked - the next function will receive it as one tuple argument.

  (Aside: I believe that the right solution to this is something like the "starcall" function (and a dedicated Arguments class for cases where you want to return both args and kwargs, or just be more explicit with intent), as sketched out for example in Feature request: unpack pytoolz/toolz#486 .)

• Re: portability, package structure, setup.py vs hatch, etc: all this is true and good practice and that's basically what I would've done by now if I was ready to drop support for old Pythons.

  Sadly, I have a terminal (for my software's clarity to others) mental illness which compels me to make certain packages usable on old and incomplete Pythons. I'm slowly recovering, but compose predates my recovery and I am not yet recovered enough to drop extreme portability from those of my libraries which have it. (For example, last I checked, PyPy is supporting its 2.7 flavor indefinitely, so older Python versions aren't entirely dead yet.)

• You're absolutely right about not needing to scale compose type checking for hot loops and effectively infinite sizes - If such a need exists, it hasn't yet been invented as far as I know. If there was an easy way to achieve it, like if there was a way I could define a walk+sampling+check to plug into your "RNGesus" approach I would have been happy to do it, but I'm totally fine with not doing it since it seems there isn't.

• I love your suggestion for how to inline the type stubs! That's great, and might solve some of the issues that forced me to do separate stubs in the first place (I don't remember off the top of my head, but iirc MyPy couldn't handle seeing both the class definitions and the function overloads - that conditional check might be exactly what I needed to solve that!)

• Big thanks for the pointers that just beartyping the package covers the callable part and then it's just a signature check in my code.

[leycec]

Wowza! Thanks so much for the extensive response. I detect a mind like mine. You exhaustively responded to each of my audacious concerns in bullet-point form, which is both impressive and gratifying.

Sadly, I can't return the favour just yet. I apologize! Python 3.12 just dropped a few weeks ago. Since @beartype currently fails to support all the new syntactic goodness bundled in Python 3.12 (e.g., type alias syntax), I'm furiously typing my fingers to the bone to support that goodness. My cats weep. 😿

For the moment, let's quietly downgrade this to a discussion topic. This is an incredibly engaging discussion, though. I hope to revisit this in a week or two. When I inevitably fail to live up to my promises, please summon me with @leycec. Oh, and...

I Thought of Something Else

Ah, ha! That's right. More (ob)noxious fodder for your awesome compose framework. First...

Stubs, Bro

I realized that you can probably globally substitute TypeVar in your stubs with TypeVarTuple from PEP 646: e.g.,

    R1 = TypeVarTuple('R1')
    R2 = TypeVarTuple('R2')
    ...

    @overload
    def compose(f2: Callable[[*R1], *R2], f1: Callable[P, *R1], /) -> Callable[P, *R2]:
        ...

Pretty sure that does what you want. Notably, that should transparently cover these two common cases:

• User-defined callables that return only a single value.
• User-defined callables that return two or more values.

What's the catch? You'll need to refactor your code to support that. Namely, you'll need to refactor your __call__() methods to:

1. Explicitly detect when a return has been annotated as returning a fixed-length tuple (e.g., def foo() -> tuple[int, str]) rather than a variadic tuple (e.g., def bar() -> tuple[int, str, ...]). I do not recommend attempting to manually detect fixed-length tuple annotations on your own. Instead, do this with our own homegrown beartype.door.TypeHint API – the gold-standard for object-oriented introspection of type hints. ^{Would I lie? ducks}
2. When you detect that a return has been annotated as returning a fixed-length tuple, unpack that return.

This is what I am saying:

    def __call__(self, /, *args, **kwargs):
        """Call the composed function."""
        # Current callable to be called.
        func_curr = None

        # Prior callable that was just called.
        func_prev = self.__wrapped__
        result = func_prev(*args, **kwargs)

        for func_curr in self._wrappers:
            # Type hint annotating the return of the prior callable if any
            # *OR* "None" otherwise.
            func_prev_return_hint = func_prev.__annotations__.get('return')

            #FIXME: This is just pseudo-code. Pretend the is_hint_tuple_fixed()
            #function exists. Nobody ever said Python was easy. If they did, they lied.

            # If the prior function was annotated as returning a fixed-length
            # tuple, unpack the fixed-length tuple returned by the prior call
            # to that function and pass the resulting values as positional
            # parameters to the current callable.
            if func_prev_return_hint and is_hint_tuple_fixed(func_prev_return_hint):
                 result = function(*result)
            # Else, pass this return as a single parameter to this callable.
            else:
                 result = function(result)

            func_prev = func_curr

        return result

New __new__(), Yo

I belatedly realized after I'd typed my prior response up that you can probably dramatically simplify instantiation for your growing userbase.

Currently, users must manually instantiate either:

• compose.compose for synchronous callables.
• compose.acompose for async callables.
• compose.sacompose for "sometimes" async callables.

That's kinda non-ideal. Instead, an API should abstract away those sorts of low-level considerations. Ideally, there should be just a single public compose.compose class that internally does the right thing for all possible use cases – regardless of whether the underlying callables are async or not. Right?

There are a few ways you can accomplish that. The simplest would probably be to just:

1. Remove both compose.compose and compose.acompose.
2. Rename compose.sacompose to compose.compose.

Or am I missing something? Currently, compose.sacompose appears to be the superset of both compos.compose and compose.acompose – a strictly more powerful class than those two lower-level classes that always does the right thing.

I'm probably missing something. If I am, consider instead:

1. Privatizing all of currently public classes: e.g.,
   • Rename compose to _compose.
   • Rename acompose to _acompose.
   • Rename sacompose to _sacompose.
2. Defining the __new__() dunder method in your public compose.compose class. This __new__() method should then instantiate and return a new instance of either _compose, _acompose, or _sacompose depending on the types of the passed callables.

Thus spake @leycec-thustra. Wait! I thought I said I wasn't gonna say anything, above. You can't even trust GitHub comments you personally write yourself, anymore. 😮‍💨