typing.ParamSpec

Author: orsinium

netlify.sh

@@ -1,4 +1,5 @@
 #!/bin/bash
-# This script is used by netlify
+# This script is used by cloud flare.
+# The name is a leftover from when we used Netlify to build the website.
 python3 -m pip install .
 python3 -m sdk html

posts/param-spec.md

@@ -0,0 +1,92 @@
+---
+author: orsinium
+topics:
+  - typing
+traces:
+  - [module: typing, type: ParamSpec]
+pep: 612
+python: "3.10"
+---
+
+# ParamSpec
+
+Let's say, you have a typical decorator that returns a new function. Something like this:
+
+```python {no-print}
+def debug(f):
+  name = f.__name__
+  def inner(*args, **kwargs):
+    print(f'called {name} with {args=} and {kwargs=}')
+    return f(*args, **kwargs)
+  return inner
+
+@debug
+def concat(a: str, b: str) -> str:
+  return a + b
+
+concat('hello ', 'world')
+# called concat with args=('hello ', 'world') and kwargs={}
+```
+
+If you check the type of `concat` using [reveal_type](https://t.me/pythonetc/712), you'll see that its type is unknown because of the decorator:
+
+```python {continue}
+reveal_type(concat)
+# Revealed type is "Any"
+```
+
+So, we need to properly annotate the decorator. But how?
+
+This is not precise enough (type errors like `x: int = concat(1, 2)` won't be detected):
+
+```python
+from typing import Callable
+def debug(f: Callable) -> Callable: ...
+```
+
+This is slightly better but function arguments are still untyped:
+
+```python {continue}
+from typing import TypeVar
+
+T = TypeVar('T')
+def debug(f: Callable[..., T]) -> Callable[..., T]: ...
+```
+
+This is type safe but it requres the decorated function to accept exactly 2 arguments:
+
+```python {continue}
+A = TypeVar('A')
+B = TypeVar('B')
+R = TypeVar('R')
+def debug(f: Callable[[A, B], R]) -> Callable[[A, B], R]: ...
+```
+
+This is type safe and works on any function but it will report type error because `inner` is not guaranteed to have the same type as the passed callable (for example, someone might pass a class that is callable but we return a function):
+
+```python {continue}
+F = TypeVar('F', bound=Callable)
+def debug(f: F) -> F: ...
+```
+
+[PEP 612](https://peps.python.org/pep-0612/) (landed in Python 3.10) introduced [typing.ParamSpec](https://docs.python.org/3/library/typing.html#typing.ParamSpec) which solves exactly this problem. You can use it to tell type checkers that the decorator returns a new function that accepts exactly the same arguments as the wrapped one:
+
+```python
+from typing import Callable, TypeVar, ParamSpec
+
+P = ParamSpec('P')
+R = TypeVar('R')
+
+def debug(f: Callable[P, R]) -> Callable[P, R]:
+  def inner(*args: P.args, **kwargs: P.kwargs) -> R:
+    ...
+    return f(*args, **kwargs)
+  return inner
+
+@debug
+def concat(a: str, b: str) -> str:
+  ...
+
+reveal_type(concat)
+# Revealed type is "def (a: str, b: str) -> str"
+```

sdk/post_markdown.py

@@ -3,7 +3,8 @@
 import dataclasses
 import enum
 from functools import cached_property
-from typing import Any, Iterator
+from types import MappingProxyType
+from typing import Any, Iterator, Mapping
 
 import markdown_it.token
 from markdown_it import MarkdownIt
@@ -22,6 +23,9 @@
     'ipython-native': 'ipython_native',
     'shield': 'shield',
 }
+_DEFAULT_GLOBALS: Mapping[str, object] = MappingProxyType(dict(
+    reveal_type=lambda x: x,
+))
 
 
 class Language(str, enum.Enum):
@@ -220,7 +224,7 @@ def to_telegram(self) -> None:
         self._remove_code_info()
 
     def run_code(self) -> None:
-        shared_globals: dict = {}
+        shared_globals: dict[str, object] = dict(_DEFAULT_GLOBALS)
         for paragraph in self._paragraphs():
 
             if (
@@ -235,12 +239,9 @@ def run_code(self) -> None:
                 continue
 
             if not paragraph.code.continue_code:
-                shared_globals = {}
-            shared_globals['print'] = (
-                (lambda *args, **kwargs: None)
-                if paragraph.code.no_print
-                else print
-            )
+                shared_globals = dict(_DEFAULT_GLOBALS)
+            if paragraph.code.no_print:
+                shared_globals['print'] = lambda *args, **kwargs: None
 
             code = paragraph.tokens[-1].content
             if paragraph.code.is_python: