docs: some documentation/thoughts on properly implementing overlay packages

doc/overlays/main/src/my/reddit.py

@@ -0,0 +1,11 @@
+print(f'[main] {__name__} hello')
+
+
+def upvotes() -> list[str]:
+    return [
+        'reddit upvote1',
+        'reddit upvote2',
+    ]
+
+
+trigger_mypy_error: str = 123

doc/overlays/main/src/my/twitter/all.py

@@ -0,0 +1,7 @@
+print(f'[main] {__name__} hello')
+
+from .common import merge
+
+def tweets() -> list[str]:
+    from . import gdpr
+    return merge(gdpr)

doc/overlays/main/src/my/twitter/common.py

@@ -0,0 +1,11 @@
+print(f'[main] {__name__} hello')
+
+from typing import Protocol
+
+class Source(Protocol):
+    def tweets(self) -> list[str]:
+        ...
+
+def merge(*sources: Source) -> list[str]:
+    from itertools import chain
+    return list(chain.from_iterable(src.tweets() for src in sources))

doc/overlays/main/src/my/twitter/gdpr.py

@@ -0,0 +1,9 @@
+print(f'[main] {__name__} hello')
+
+def tweets() -> list[str]:
+    return [
+        'gdpr tweet 1',
+        'gdpr tweet 2',
+    ]
+
+trigger_mypy_error: str = 123