MetricWrapperBase labels() method static typing for label names

まず MetricWrapperBase とその labels メソッド、および issue で説明されている TypeVarTuple と typing_extensions の考え方を確認します。型チェック可能なアプローチによって、既存の label とキーワード引数の使用方法を維持できるか判断します。選択した設計が、後方互換性を損なうことなく一致しない label 引数を検出できれば完了です。

Hi, recently I was thinking about possible improvement for MetricWrapperBase and friends labels method.

Very common use case is described even in Counter's docstring:

from prometheus_client import Counter

c = Counter('my_requests_total', 'HTTP Failures', ['method', 'endpoint'])
c.labels('get', '/').inc()
c.labels('post', '/submit').inc()

But when having N different counters, especially with different number of label names, and legacy large codebase or just very hard to test edge cases in your code (or the effort to test them all is not acceptable for some reason) where you use metrics, after some time you end up with typo errors when number of arguments do not match those specified, for example with above example counter:

try:
    do_something()
except VeryRareException:
    if int(time.time()) % 99999 == 0: 
          c.labels('get').inc() # Surprise!!! ValueError

Maybe we can do better somehow? This would be extra useful if we could pass label names like ['method', 'endpoint'] in a way that type checkers could understand and yield errors even before actually running code. Ideally with 100% backward compability with existing implementations (that one will be hard).

To just give some silly ideas, there is for example TypeVarTuple https://docs.python.org/3/library/typing.html#typing.TypeVarTuple that could at least do the job but only with partial backward compability, here PoC for MetricWrapperBase:

Disclaimer both TypeVarTuple and Self are Python 3.11+

from typing import TypeVarTuple, Self

...

LabelNames = TypeVarTuple("LabelNames")

class MetricWrapperBase(Collector,Generic[*LabelNames]):
    ...
    def __init__(self,
                 name: str,
                 documentation: str,
                 labelnames: tuple[*LabelNames] = (),
                 namespace: str = '',
                 subsystem: str = '',
                 unit: str = '',
                 registry: Optional[CollectorRegistry] = REGISTRY,
                 _labelvalues: Optional[Sequence[str]] = None,
                 ) -> None:
                 ...

    def labels(self: T, *labelvalues: *LabelNames) -> Self:
        ... # breaking changes there, only args

With that we have desire result

x = MetricWrapperBase("x", "y", ("short name", "data"))
x.labels("Ok name", "Ok data")
x.labels("Forgot second arg")

Of course this is very far from perfect, note only tuples could be used (no list) and in labels only args not kwargs. Also Python 3.11 is questionable but there is typing_extensions lib plus that could always live as a optional stubs only or some nasty overloads.

I am not by any means python typing ninja, but maybe someone could come up with better ideas! Or have some thoughts on this topic, I am observing new typing features on every python release, there may be now solutions that didn't exist couple of years ago.