From a3aaebb2b01211863e44a4d847ce4cd2e7d633c3 Mon Sep 17 00:00:00 2001 From: Kyle King Date: Tue, 13 Aug 2024 20:22:00 -0400 Subject: [PATCH] docs: improve migration guide --- docs/docs/CHANGELOG.md | 14 ++++++++++++ docs/docs/CODE_TAG_SUMMARY.md | 15 +++++++------ docs/docs/DEVELOPER_GUIDE.md | 10 ++++----- docs/docs/MIGRATION.md | 40 ++++++++++++++++++++++++++++++++--- 4 files changed, 64 insertions(+), 15 deletions(-) diff --git a/docs/docs/CHANGELOG.md b/docs/docs/CHANGELOG.md index bb945c5f..874d1678 100644 --- a/docs/docs/CHANGELOG.md +++ b/docs/docs/CHANGELOG.md @@ -2,6 +2,20 @@ ### Fix +- handle when dev-dependencies are missing +- minimize calcipy extras when testing in nox +- handle git, path, and other complex versions for sync task +- pinning urllib3 for Python 3.11 wasn't necessary + +### Refactor + +- minor logging improvements for pack.sync + +## 4.0.0 (2024-07-06) + +### Fix + +- add timeout to httpx requests - don't sync versions when a maximum version is specified - prevent installing urllib3 in Python 3.10 - add missing pylint extra diff --git a/docs/docs/CODE_TAG_SUMMARY.md b/docs/docs/CODE_TAG_SUMMARY.md index cb14c4e8..1c19b45e 100644 --- a/docs/docs/CODE_TAG_SUMMARY.md +++ b/docs/docs/CODE_TAG_SUMMARY.md @@ -1,12 +1,13 @@ # Collected Code Tags -| Type | Comment | Last Edit | Source File | -|------|----------------------------------------------------------------------------------------------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| TODO | Add unit test | 2024-07-06 | [calcipy/tasks/pack.py:57](https://github.com/KyleKing/calcipy/blame/e45ecadfa5b994d9c0a2a47138fa0e083261e3eb/calcipy/tasks/pack.py#L57) | -| TODO | Add unit test | 2024-07-06 | [calcipy/tasks/pack.py:91](https://github.com/KyleKing/calcipy/blame/e45ecadfa5b994d9c0a2a47138fa0e083261e3eb/calcipy/tasks/pack.py#L91) | -| TODO | Look into running tasks from within other tasks to support '--continue' and more readable logs --> | 2023-02-19 | [docs/docs/MIGRATION.md:112](https://github.com/KyleKing/calcipy/blame/d95eb85ab7f6d45459ed7b3ff2dc99ae3c92fa61/docs/docs/MIGRATION.md#L42) | -| TODO | Capture logging output and check... | 2023-02-19 | [tests/check_for_stale_packages/test_check_for_stale_packages.py:64](https://github.com/KyleKing/calcipy/blame/a8b69e7b04d9b15eabff8897f2de7703898c2afc/tests/check_for_stale_packages/test_check_for_stale_packages.py#L63) | -| TODO | Capture logging output and check... | 2023-02-19 | [tests/check_for_stale_packages/test_check_for_stale_packages.py:88](https://github.com/KyleKing/calcipy/blame/3f42ad855eb7024ff48af35d496633a87d4a14ac/tests/check_for_stale_packages/test_check_for_stale_packages.py#L26) | +| Type | Comment | Last Edit | Source File | +|------|-------------------------------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| TODO | How to capture output? | 2024-08-14 | [calcipy/collection.py:38](https://github.com/KyleKing/calcipy/blame/main +/calcipy/collection.py#L38) | +| TODO | Add unit test | 2024-07-06 | [calcipy/tasks/pack.py:57](https://github.com/KyleKing/calcipy/blame/e45ecadfa5b994d9c0a2a47138fa0e083261e3eb/calcipy/tasks/pack.py#L57) | +| TODO | Add unit test | 2024-07-06 | [calcipy/tasks/pack.py:91](https://github.com/KyleKing/calcipy/blame/e45ecadfa5b994d9c0a2a47138fa0e083261e3eb/calcipy/tasks/pack.py#L91) | +| TODO | Capture logging output and check... | 2023-02-19 | [tests/check_for_stale_packages/test_check_for_stale_packages.py:64](https://github.com/KyleKing/calcipy/blame/a8b69e7b04d9b15eabff8897f2de7703898c2afc/tests/check_for_stale_packages/test_check_for_stale_packages.py#L63) | +| TODO | Capture logging output and check... | 2023-02-19 | [tests/check_for_stale_packages/test_check_for_stale_packages.py:88](https://github.com/KyleKing/calcipy/blame/3f42ad855eb7024ff48af35d496633a87d4a14ac/tests/check_for_stale_packages/test_check_for_stale_packages.py#L26) | Found code tags for TODO (5) diff --git a/docs/docs/DEVELOPER_GUIDE.md b/docs/docs/DEVELOPER_GUIDE.md index 61d3524d..7d9c24b7 100644 --- a/docs/docs/DEVELOPER_GUIDE.md +++ b/docs/docs/DEVELOPER_GUIDE.md @@ -55,20 +55,20 @@ poetry config pypi-token.pypi ... | `calcipy/check_for_stale_packages/_check_for_stale_packages.py` | 126 | 13 | 3 | 86.7% | | `calcipy/cli.py` | 34 | 1 | 75 | 92.9% | | `calcipy/code_tag_collector/__init__.py` | 5 | 2 | 0 | 60.0% | -| `calcipy/code_tag_collector/_collector.py` | 129 | 2 | 0 | 96.6% | +| `calcipy/code_tag_collector/_collector.py` | 129 | 1 | 0 | 98.3% | | `calcipy/collection.py` | 33 | 0 | 52 | 97.5% | | `calcipy/dot_dict/__init__.py` | 5 | 2 | 0 | 60.0% | | `calcipy/dot_dict/_dot_dict.py` | 6 | 0 | 0 | 100.0% | | `calcipy/experiments/__init__.py` | 0 | 0 | 0 | 100.0% | | `calcipy/experiments/bump_programmatically.py` | 22 | 22 | 0 | 0.0% | | `calcipy/experiments/check_duplicate_test_names.py` | 33 | 0 | 2 | 98.2% | -| `calcipy/experiments/sync_package_dependencies.py` | 40 | 40 | 0 | 0.0% | +| `calcipy/experiments/sync_package_dependencies.py` | 46 | 46 | 0 | 0.0% | | `calcipy/file_search.py` | 32 | 0 | 2 | 100.0% | | `calcipy/invoke_helpers.py` | 27 | 4 | 0 | 83.8% | | `calcipy/md_writer/__init__.py` | 5 | 2 | 0 | 60.0% | | `calcipy/md_writer/_writer.py` | 91 | 6 | 0 | 89.6% | | `calcipy/noxfile/__init__.py` | 5 | 2 | 0 | 60.0% | -| `calcipy/noxfile/_noxfile.py` | 38 | 2 | 50 | 91.3% | +| `calcipy/noxfile/_noxfile.py` | 39 | 2 | 51 | 91.5% | | `calcipy/scripts.py` | 5 | 0 | 37 | 100.0% | | `calcipy/tasks/__init__.py` | 0 | 0 | 0 | 100.0% | | `calcipy/tasks/all_tasks.py` | 46 | 0 | 0 | 94.8% | @@ -83,7 +83,7 @@ poetry config pypi-token.pypi ... | `calcipy/tasks/tags.py` | 18 | 1 | 0 | 90.9% | | `calcipy/tasks/test.py` | 43 | 1 | 2 | 90.2% | | `calcipy/tasks/types.py` | 11 | 0 | 0 | 93.3% | -| **Totals** | 1005 | 122 | 259 | 84.0% | +| **Totals** | 1012 | 127 | 260 | 83.6% | -Generated on: 2024-07-06 +Generated on: 2024-08-13 diff --git a/docs/docs/MIGRATION.md b/docs/docs/MIGRATION.md index 77938173..9d4d40c2 100644 --- a/docs/docs/MIGRATION.md +++ b/docs/docs/MIGRATION.md @@ -1,6 +1,31 @@ # Migration Guide -## `calcipy 1.0.0` +## `v4` + +The total number of dependencies was reduce even further by replacing flake8, isort, and other tooling with ruff; fewer mkdocs plugins; and fewer steps in the `main` run task to speed up normal usage. + +The only breaking [change impacted `recipes`](https://github.com/KyleKing/recipes/commit/b3fcf8136af77ccf1bd3ee1fb4297b79dd7e86ea#diff-4bf564fcd9dbaec9e9807f16f649791c1e333f89db8160ad715d3c0c09a1a65c) when `write_autoformatted_md_sections` was renamed to `write_template_formatted_md_sections`. + +### Speed Test + +Following up on performance checks from the `v2` migration. The performance is comparable, but you will see savings in cache size and poetry install and when running `main` (`./run main` for Calcipy, currently takes ~20s) + +```sh +> hyperfine -m 20 --warmup 5 ./run +Benchmark 1: ./run +Time (mean ± σ): 863.9 ms ± 10.0 ms [User: 550.7 ms, System: 102.3 ms] +Range (min … max): 848.5 ms … 885.3 ms 20 runs +> hyperfine -m 20 --warmup 5 "poetry run calcipy-tags" +Benchmark 1: poetry run calcipy-tags +Time (mean ± σ): 770.5 ms ± 5.7 ms [User: 470.6 ms, System: 89.5 ms] +Range (min … max): 760.1 ms … 780.3 ms 20 runs +``` + +## `v3` + +Replaced features from flake8 and plugins with corresponding checks from ruff, however both are still used in parallel. + +## `v2` ### Background @@ -22,6 +47,17 @@ While refactoring, the global configuration was mostly removed (`DoitGlobals`) a It turns out that switching to `invoke` appears to have only saved 100ms +```sh +> hyperfine -m 20 --warmup 5 ./run +Benchmark 1: ./run +Time (mean ± σ): 863.9 ms ± 10.0 ms [User: 550.7 ms, System: 102.3 ms] +Range (min … max): 848.5 ms … 885.3 ms 20 runs +> hyperfine -m 20 --warmup 5 "poetry run calcipy-tags" +Benchmark 1: poetry run calcipy-tags +Time (mean ± σ): 770.5 ms ± 5.7 ms [User: 470.6 ms, System: 89.5 ms] +Range (min … max): 760.1 ms … 780.3 ms 20 runs +``` + ```sh > hyperfine -m 20 --warmup 5 "poetry run python -c 'print(1)'" Benchmark 1: poetry run python -c 'print(1)' @@ -109,8 +145,6 @@ SUM: 7 37 15 71 ### doit output - - I would like to restore the `doit` task summary, but `invoke`'s architecture doesn't really make this possible. The `--continue` option was extremely useful, but that also might not be achievable. ```sh