From 717c664d321753e23f5a978476fe4549cda5d321 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Fri, 24 Oct 2025 14:00:51 +0200 Subject: [PATCH 1/6] Automatically add py.typed file to generated stubs Remove docstub-stubs in CI before regenerating them. This tests that the `py.typed` is actually regenerted by docstub. --- .github/workflows/ci.yml | 1 + src/docstub/_cli.py | 5 +++++ 2 files changed, 6 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e99fe4f..7f110c5 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -91,6 +91,7 @@ jobs: # Check that stubs for docstub are up-to-date by regenerating them # with docstub and looking for differences. run: | + rm -rf src/docstub-stubs python -m docstub run -v src/docstub -o src/docstub-stubs .github/scripts/assert-unchanged.sh src/docstub-stubs/ diff --git a/src/docstub/_cli.py b/src/docstub/_cli.py index 77ee55c..e89874d 100644 --- a/src/docstub/_cli.py +++ b/src/docstub/_cli.py @@ -399,6 +399,11 @@ def run( logger.info("Wrote %s", stub_path) fo.write(stub_content) + py_typed_out = out_dir / "py.typed" + if not py_typed_out.exists(): + py_typed_out.touch() + logger.info("Created %s", py_typed_out) + # Reporting -------------------------------------------------------------- if group_errors: From f0a017bbf81f1886312017ceedaa91aef8f4bab4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Fri, 24 Oct 2025 14:02:11 +0200 Subject: [PATCH 2/6] Add distribution section and mention py.typed in docs --- docs/introduction.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/introduction.md b/docs/introduction.md index 5d81f29..dd3542c 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -204,3 +204,13 @@ class Foo: If all of the above does not solve your issue, you can fall back to writing a correct stub file by hand. Docstub will preserve this file and integrated it with other automatically generated stubs. + + +## Distributing stub files + +The simplest option is to include generated stubs in the [distribution package](https://packaging.python.org/en/latest/glossary/#term-Distribution-Package) alongside your source files. +For more complex setups please consult the official guide on [Packaging Type Information](https://typing.python.org/en/latest/spec/distributing.html#packaging-type-information). + +As required, Docstub will automatically place an empty `py.typed` file in the root directory of generated stubs to support type checking. +If you need to [mark your stubs as partial](https://typing.python.org/en/latest/spec/distributing.html#partial-stub-packages), create the `py.typed` file beforehand. +Docstub will not overwrite it. From 0ad60a812abceb5e68a4c3f5eaf866ff98157800 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Fri, 24 Oct 2025 14:23:46 +0200 Subject: [PATCH 3/6] Avoid early exit in assert-unchanged.sh and also show git status as a summary on failure. --- .github/scripts/assert-unchanged.sh | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/.github/scripts/assert-unchanged.sh b/.github/scripts/assert-unchanged.sh index ef32496..4a2168d 100755 --- a/.github/scripts/assert-unchanged.sh +++ b/.github/scripts/assert-unchanged.sh @@ -9,18 +9,19 @@ CHECK_DIR=$1 # Find untracked files UNTRACKED=$(git ls-files --others --exclude-standard "$CHECK_DIR") -# and display their content by comparing with '/dev/null' -echo "$UNTRACKED" | xargs -I _ git --no-pager diff --no-index /dev/null _ + +# Display diff of each untracked file by comparing with '/dev/null' +# Hide exit code of `git diff` to avoid early exit due to `set -e` +echo "$UNTRACKED" | xargs -I _ git --no-pager diff /dev/null _ || true # Display changes in tracked files and capture non-zero exit code if so -set +e -git diff --exit-code HEAD "$CHECK_DIR" +git diff --exit-code HEAD "$CHECK_DIR" || true GIT_DIFF_HEAD_EXIT_CODE=$? -set -e # Display changes in tracked files and capture exit status if [ $GIT_DIFF_HEAD_EXIT_CODE -ne 0 ] || [ -n "$UNTRACKED" ]; then echo "::error::Uncommited changes in directory '$CHECK_DIR'" + git status --porcelain exit 1 else echo "::notice::No Uncommited changes, directory '$CHECK_DIR' is clean" From 78e914a6d4d746da2aaa8f27967213f124efd6af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Fri, 24 Oct 2025 14:26:03 +0200 Subject: [PATCH 4/6] Add missing py.typed to example_pkg-stubs --- examples/example_pkg-stubs/py.typed | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 examples/example_pkg-stubs/py.typed diff --git a/examples/example_pkg-stubs/py.typed b/examples/example_pkg-stubs/py.typed new file mode 100644 index 0000000..e69de29 From a36fd39a63d0f83ced46aa25a163fa0df544d3fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Fri, 24 Oct 2025 14:27:57 +0200 Subject: [PATCH 5/6] Also remove examples/example_pkg-stubs before regeneration --- .github/workflows/ci.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7f110c5..f351735 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -81,6 +81,7 @@ jobs: # Check that stubs for example_pkg are up-to-date by regenerating them # with docstub and looking for differences. run: | + rm -rf examples/example_pkg-stubs python -m docstub run -v \ --config=examples/docstub.toml \ --out-dir=examples/example_pkg-stubs \ From 9b2c1b45693141640b80001bf4f40ee9a3b66d74 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Fri, 24 Oct 2025 14:34:26 +0200 Subject: [PATCH 6/6] Disable pip's progress bar during installation --- .github/workflows/ci.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f351735..4ebec38 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -17,6 +17,7 @@ env: # Many color libraries just need this to be set to any value, but at least # one distinguishes color depth, where "3" -> "256-bit color". FORCE_COLOR: 3 + PIP_PROGRESS_BAR: "off" defaults: run: