From ff50b194abde461efc86d38ae1499dafc9a8019f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Wed, 18 Sep 2024 12:19:53 +0200 Subject: [PATCH 01/12] Add basic CI configuration --- .github/workflows/ci.yml | 83 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 .github/workflows/ci.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..e71c4d9 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,83 @@ +name: CI + +on: + workflow_dispatch: + pull_request: + push: + branches: + - main + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +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 + +jobs: + pre-commit: + name: pre-commit + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: actions/setup-python@v5 + with: + python-version: "3.x" + - uses: pre-commit/action@v3.0.1 + with: + extra_args: --hook-stage manual --all-files + + checks: + name: Test with Python ${{ matrix.python-version }} on ${{ matrix.runs-on }} + runs-on: ${{ matrix.runs-on }} + needs: [pre-commit] + strategy: + fail-fast: false + matrix: + python-version: ["3.9", "3.13"] + runs-on: [ubuntu-latest, windows-latest, macos-14] + include: + - python-version: "pypy-3.10" + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + allow-prereleases: true + + - name: Install package + run: python -m pip install .[test,optional] + + - name: Run pytest + run: >- + python -m pytest -ra --cov --cov-report=xml --cov-report=term + --durations=20 + + - name: Upload coverage report + uses: codecov/codecov-action@v4.5.0 + with: + token: ${{ secrets.CODECOV_TOKEN }} + + - name: Compare example stubs + run: | + python -m docstub -v example/example_pkg + git diff --exit-code example/ + + - name: Generate docstub stubs + run: | + python -m docstub -v src/docstub + + - name: Upload docstub stubs + uses: actions/upload-artifact@v4 + with: + name: docstub-stubs + path: ./src/docstub-stubs From a28133426cff758cd32d60504d7fc80cd95e4c73 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Wed, 18 Sep 2024 12:23:51 +0200 Subject: [PATCH 02/12] Use Python 3.12 as lowest bound in test matrix --- .github/workflows/ci.yml | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e71c4d9..8d7db17 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -32,17 +32,14 @@ jobs: extra_args: --hook-stage manual --all-files checks: - name: Test with Python ${{ matrix.python-version }} on ${{ matrix.runs-on }} + name: Test on ${{ matrix.runs-on }} Python ${{ matrix.python-version }} runs-on: ${{ matrix.runs-on }} needs: [pre-commit] strategy: fail-fast: false matrix: - python-version: ["3.9", "3.13"] + python-version: ["3.12", "3.13"] runs-on: [ubuntu-latest, windows-latest, macos-14] - include: - - python-version: "pypy-3.10" - runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 From 22370db47f255d113ed0258c39c8197845042686 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Wed, 18 Sep 2024 12:28:06 +0200 Subject: [PATCH 03/12] Shrink test matrix No need to be wasteful. --- .github/workflows/ci.yml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8d7db17..201f402 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -38,8 +38,12 @@ jobs: strategy: fail-fast: false matrix: - python-version: ["3.12", "3.13"] runs-on: [ubuntu-latest, windows-latest, macos-14] + python-version: ["3.12"] + + include: + - runs-on: ubuntu-latest + python-version: "3.13" steps: - uses: actions/checkout@v4 From c8f80163eaf75aeaad2ff64874406eb6d66851ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Wed, 18 Sep 2024 12:30:27 +0200 Subject: [PATCH 04/12] Include pytest-cov --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 74a584f..b1fd226 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -44,7 +44,7 @@ dev = [ ] test = [ "pytest >=5.0.0", - "coverage >=7.5.0", + "pytest-cov >= 5.0.0", ] [project.urls] From 550d1360d76c76e219bf48aaa549ececf5968c43 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Wed, 18 Sep 2024 12:43:10 +0200 Subject: [PATCH 05/12] Fix paths and other tweaks --- .github/workflows/ci.yml | 12 ++++-------- pyproject.toml | 2 ++ 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 201f402..93a33c4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -60,18 +60,14 @@ jobs: - name: Run pytest run: >- - python -m pytest -ra --cov --cov-report=xml --cov-report=term - --durations=20 + python -m pytest --showlocals -ra --cov --cov-report=term - - name: Upload coverage report - uses: codecov/codecov-action@v4.5.0 - with: - token: ${{ secrets.CODECOV_TOKEN }} + # TODO upload coverage statistics, and fail on decrease? - name: Compare example stubs run: | - python -m docstub -v example/example_pkg - git diff --exit-code example/ + python -m docstub -v examples/example_pkg + git diff --exit-code examples/ - name: Generate docstub stubs run: | diff --git a/pyproject.toml b/pyproject.toml index b1fd226..8ff97fc 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -91,5 +91,7 @@ ignore = [ [tool.docstub.docnames] +[tool.coverage] +run.source = ["src/docstub"] cst = {import = "libcst", as="cst"} lark = {import = "lark"} From 4063436d20e7f0d107806f09bf931581e6caefae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Wed, 18 Sep 2024 12:48:22 +0200 Subject: [PATCH 06/12] Report positive comparison with example stubs --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 93a33c4..69fa9cc 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -67,7 +67,7 @@ jobs: - name: Compare example stubs run: | python -m docstub -v examples/example_pkg - git diff --exit-code examples/ + git diff --exit-code examples/ && echo "Stubs for example_pkg did not change" - name: Generate docstub stubs run: | From a62cbe19aaf337241b585727f4380962cf484148 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Wed, 18 Sep 2024 12:49:34 +0200 Subject: [PATCH 07/12] Fix tool.docstub section Got scrambled by an earlier partial commit. --- pyproject.toml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 8ff97fc..3add4f8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -90,8 +90,10 @@ ignore = [ ] -[tool.docstub.docnames] [tool.coverage] run.source = ["src/docstub"] + + +[tool.docstub.known_imports] cst = {import = "libcst", as="cst"} lark = {import = "lark"} From 072a1b386eb86f21e90ac082b6ef52587a0ef53d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Wed, 18 Sep 2024 13:56:06 +0200 Subject: [PATCH 08/12] Add basic statistics --- README.md | 5 +++-- src/docstub/_cli.py | 11 +++++------ 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 40f9505..6eb71e9 100644 --- a/README.md +++ b/README.md @@ -20,9 +20,10 @@ pip install 'docstub [optional] @ git+https://github.com/scientific-python/docst ## Usage & configuration ```shell -docstub example/example_pkg/ +cd examples/ +docstub example_pkg/ ``` -will create stub files for `example_pkg/` in `example/example_pkg-stubs/`. +will create stub files for `example_pkg/` in `examples/example_pkg-stubs/`. For now, refer to `docstub --help` for more. diff --git a/src/docstub/_cli.py b/src/docstub/_cli.py index e5c4402..8008597 100644 --- a/src/docstub/_cli.py +++ b/src/docstub/_cli.py @@ -17,12 +17,11 @@ logger = logging.getLogger(__name__) -def _find_configuration(source_dir, config_path): - """Find and load configuration from multiple possible sources. +def _load_configuration(config_path=None): + """Load and merge configuration from CWD and optional files. Parameters ---------- - source_dir : Path config_path : Path Returns @@ -31,13 +30,13 @@ def _find_configuration(source_dir, config_path): """ config = Config.from_toml(Config.DEFAULT_CONFIG_PATH) - pyproject_toml = source_dir.parent / "pyproject.toml" + pyproject_toml = Path.cwd() / "pyproject.toml" if pyproject_toml.is_file(): logger.info("using %s", pyproject_toml) add_config = Config.from_toml(pyproject_toml) config = config.merge(add_config) - docstub_toml = source_dir.parent / "docstub.toml" + docstub_toml = Path.cwd() / "docstub.toml" if docstub_toml.is_file(): logger.info("using %s", docstub_toml) add_config = Config.from_toml(docstub_toml) @@ -87,7 +86,7 @@ def main(source_dir, out_dir, config_path, verbose): _setup_logging(verbose=verbose) source_dir = Path(source_dir) - config = _find_configuration(source_dir, config_path) + config = _load_configuration(config_path) # Build map of known imports known_imports = common_known_imports() From 3d1b583e09b239d7e86213d4604d8080d63c2082 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Wed, 18 Sep 2024 13:57:29 +0200 Subject: [PATCH 09/12] Use "~" in doctype of Py2StubTransformer --- src/docstub/_stubs.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docstub/_stubs.py b/src/docstub/_stubs.py index ce84c2d..1927f63 100644 --- a/src/docstub/_stubs.py +++ b/src/docstub/_stubs.py @@ -572,7 +572,7 @@ def _annotations_from_node(self, node): Returns ------- - annotations : DocstringAnnotations + annotations : ~.DocstringAnnotations """ annotations = None docstring = node.get_docstring() From 318721829476fd2449820273e50ac0f0a4ee44f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Wed, 18 Sep 2024 14:00:14 +0200 Subject: [PATCH 10/12] Use correct config file for example_pkg --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 69fa9cc..f63de8e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -66,7 +66,7 @@ jobs: - name: Compare example stubs run: | - python -m docstub -v examples/example_pkg + python -m docstub -v --config=examples/docstub.toml examples/example_pkg git diff --exit-code examples/ && echo "Stubs for example_pkg did not change" - name: Generate docstub stubs From 2f7e420d0a08cb8153298513f955080cb70e0458 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Wed, 18 Sep 2024 14:13:48 +0200 Subject: [PATCH 11/12] Match editable and normal install for test coverage --- pyproject.toml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 3add4f8..2206737 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -91,8 +91,7 @@ ignore = [ [tool.coverage] -run.source = ["src/docstub"] - +run.source = ["docstub"] [tool.docstub.known_imports] cst = {import = "libcst", as="cst"} From 2fe035f415f7e0f082b09ba0b58b8ceb00fb1c30 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Wed, 18 Sep 2024 14:15:49 +0200 Subject: [PATCH 12/12] Don't upload docstub-stubs These multiple jobs conflict and I have no real use for these right now. --- .github/workflows/ci.yml | 6 ------ 1 file changed, 6 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f63de8e..9bacae9 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -72,9 +72,3 @@ jobs: - name: Generate docstub stubs run: | python -m docstub -v src/docstub - - - name: Upload docstub stubs - uses: actions/upload-artifact@v4 - with: - name: docstub-stubs - path: ./src/docstub-stubs