docs: some documentation/thoughts on properly implementing overlay packages

doc/overlays/install_packages.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+set -eux
+pip3 install --user -e overlay/
+pip3 install --user -e main/

doc/overlays/main/setup.py

@@ -0,0 +1,17 @@
+from setuptools import setup, find_namespace_packages # type: ignore
+
+
+def main() -> None:
+    pkgs = find_namespace_packages('src')
+    pkg = min(pkgs)
+    setup(
+        name='hpi-main',
+        zip_safe=False,
+        packages=pkgs,
+        package_dir={'': 'src'},
+        package_data={pkg: ['py.typed']},
+    )
+
+
+if __name__ == '__main__':
+    main()

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

doc/overlays/overlay/setup.py

@@ -0,0 +1,17 @@
+from setuptools import setup, find_namespace_packages # type: ignore
+
+
+def main() -> None:
+    pkgs = find_namespace_packages('src')
+    pkg = min(pkgs)
+    setup(
+        name='hpi-overlay',
+        zip_safe=False,
+        packages=pkgs,
+        package_dir={'': 'src'},
+        package_data={pkg: ['py.typed']},
+    )
+
+
+if __name__ == '__main__':
+    main()

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

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

doc/overlays/overlay/src/my/twitter/talon.py

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