qkrun 2.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (154) hide show
  1. qkrun-2.0.0/.editorconfig +27 -0
  2. qkrun-2.0.0/.github/workflows/ci.yml +39 -0
  3. qkrun-2.0.0/.gitignore +28 -0
  4. qkrun-2.0.0/.pre-commit-config.yaml +42 -0
  5. qkrun-2.0.0/.readthedocs.yaml +19 -0
  6. qkrun-2.0.0/CHANGELOG.md +340 -0
  7. qkrun-2.0.0/CONTRIBUTING.md +59 -0
  8. qkrun-2.0.0/LICENSE +21 -0
  9. qkrun-2.0.0/PKG-INFO +101 -0
  10. qkrun-2.0.0/README.md +53 -0
  11. qkrun-2.0.0/docs/Makefile +20 -0
  12. qkrun-2.0.0/docs/make.bat +35 -0
  13. qkrun-2.0.0/docs/source/accepting_arguments.rst +102 -0
  14. qkrun-2.0.0/docs/source/api.rst +59 -0
  15. qkrun-2.0.0/docs/source/cli.rst +36 -0
  16. qkrun-2.0.0/docs/source/command.rst +199 -0
  17. qkrun-2.0.0/docs/source/conditions.rst +176 -0
  18. qkrun-2.0.0/docs/source/conf.py +41 -0
  19. qkrun-2.0.0/docs/source/dependencies_and_cleanup.rst +65 -0
  20. qkrun-2.0.0/docs/source/generated/qkrun.Arg.rst +24 -0
  21. qkrun-2.0.0/docs/source/generated/qkrun.Namespace.rst +25 -0
  22. qkrun-2.0.0/docs/source/generated/qkrun.command.rst +6 -0
  23. qkrun-2.0.0/docs/source/generated/qkrun.commands.autocomplete.rst +12 -0
  24. qkrun-2.0.0/docs/source/generated/qkrun.commands.base.rst +12 -0
  25. qkrun-2.0.0/docs/source/generated/qkrun.commands.init.rst +12 -0
  26. qkrun-2.0.0/docs/source/generated/qkrun.commands.list_.rst +12 -0
  27. qkrun-2.0.0/docs/source/generated/qkrun.commands.rst +18 -0
  28. qkrun-2.0.0/docs/source/generated/qkrun.commands.run.rst +12 -0
  29. qkrun-2.0.0/docs/source/generated/qkrun.commands.watch.rst +12 -0
  30. qkrun-2.0.0/docs/source/generated/qkrun.completion.BaseCompleter.rst +23 -0
  31. qkrun-2.0.0/docs/source/generated/qkrun.completion.PathCompleter.rst +25 -0
  32. qkrun-2.0.0/docs/source/generated/qkrun.completion.base.rst +12 -0
  33. qkrun-2.0.0/docs/source/generated/qkrun.completion.python.PytestCompleter.rst +25 -0
  34. qkrun-2.0.0/docs/source/generated/qkrun.completion.python.rst +12 -0
  35. qkrun-2.0.0/docs/source/generated/qkrun.completion.rst +20 -0
  36. qkrun-2.0.0/docs/source/generated/qkrun.conditions.FilesModified.rst +24 -0
  37. qkrun-2.0.0/docs/source/generated/qkrun.conditions.FirstRun.rst +22 -0
  38. qkrun-2.0.0/docs/source/generated/qkrun.conditions.PathsExist.rst +22 -0
  39. qkrun-2.0.0/docs/source/generated/qkrun.conditions.base.BaseCondition.rst +22 -0
  40. qkrun-2.0.0/docs/source/generated/qkrun.conditions.base.rst +12 -0
  41. qkrun-2.0.0/docs/source/generated/qkrun.conditions.condition.rst +6 -0
  42. qkrun-2.0.0/docs/source/generated/qkrun.conditions.rst +28 -0
  43. qkrun-2.0.0/docs/source/generated/qkrun.config.App.rst +49 -0
  44. qkrun-2.0.0/docs/source/generated/qkrun.config.rst +22 -0
  45. qkrun-2.0.0/docs/source/generated/qkrun.context.Context.rst +31 -0
  46. qkrun-2.0.0/docs/source/generated/qkrun.context.resolve_wd.rst +6 -0
  47. qkrun-2.0.0/docs/source/generated/qkrun.context.rst +19 -0
  48. qkrun-2.0.0/docs/source/generated/qkrun.errors.QkrunError.rst +6 -0
  49. qkrun-2.0.0/docs/source/generated/qkrun.errors.Stop.rst +6 -0
  50. qkrun-2.0.0/docs/source/generated/qkrun.errors.TaskNotFoundError.rst +6 -0
  51. qkrun-2.0.0/docs/source/generated/qkrun.errors.TasksModuleNotFoundError.rst +6 -0
  52. qkrun-2.0.0/docs/source/generated/qkrun.errors.rst +19 -0
  53. qkrun-2.0.0/docs/source/generated/qkrun.factories.command.rst +6 -0
  54. qkrun-2.0.0/docs/source/generated/qkrun.factories.group.rst +6 -0
  55. qkrun-2.0.0/docs/source/generated/qkrun.factories.rst +30 -0
  56. qkrun-2.0.0/docs/source/generated/qkrun.factories.script.rst +6 -0
  57. qkrun-2.0.0/docs/source/generated/qkrun.factories.task.rst +6 -0
  58. qkrun-2.0.0/docs/source/generated/qkrun.factories.task_factory_helper.rst +6 -0
  59. qkrun-2.0.0/docs/source/generated/qkrun.factories.thread_group.rst +6 -0
  60. qkrun-2.0.0/docs/source/generated/qkrun.group.rst +6 -0
  61. qkrun-2.0.0/docs/source/generated/qkrun.load_env_file.rst +6 -0
  62. qkrun-2.0.0/docs/source/generated/qkrun.mcp.rst +14 -0
  63. qkrun-2.0.0/docs/source/generated/qkrun.rst +22 -0
  64. qkrun-2.0.0/docs/source/generated/qkrun.script.rst +6 -0
  65. qkrun-2.0.0/docs/source/generated/qkrun.task.rst +6 -0
  66. qkrun-2.0.0/docs/source/generated/qkrun.task_factory_helper.rst +6 -0
  67. qkrun-2.0.0/docs/source/generated/qkrun.tasks.Command.rst +81 -0
  68. qkrun-2.0.0/docs/source/generated/qkrun.tasks.Group.rst +62 -0
  69. qkrun-2.0.0/docs/source/generated/qkrun.tasks.Script.rst +78 -0
  70. qkrun-2.0.0/docs/source/generated/qkrun.tasks.Task.rst +60 -0
  71. qkrun-2.0.0/docs/source/generated/qkrun.tasks.ThreadGroup.rst +64 -0
  72. qkrun-2.0.0/docs/source/generated/qkrun.tasks.rst +30 -0
  73. qkrun-2.0.0/docs/source/generated/qkrun.thread_group.rst +6 -0
  74. qkrun-2.0.0/docs/source/generated/qkrun.utils.argparser.Arg.rst +24 -0
  75. qkrun-2.0.0/docs/source/generated/qkrun.utils.argparser.rst +12 -0
  76. qkrun-2.0.0/docs/source/generated/qkrun.utils.console.QkConsole.rst +84 -0
  77. qkrun-2.0.0/docs/source/generated/qkrun.utils.console.rst +12 -0
  78. qkrun-2.0.0/docs/source/generated/qkrun.utils.imports.import_from_path.rst +6 -0
  79. qkrun-2.0.0/docs/source/generated/qkrun.utils.imports.rst +18 -0
  80. qkrun-2.0.0/docs/source/generated/qkrun.utils.rst +15 -0
  81. qkrun-2.0.0/docs/source/how_tos/custom_factories.rst +69 -0
  82. qkrun-2.0.0/docs/source/how_tos/index.rst +8 -0
  83. qkrun-2.0.0/docs/source/how_tos/task_autocompletion.rst +40 -0
  84. qkrun-2.0.0/docs/source/how_tos/task_repository.rst +64 -0
  85. qkrun-2.0.0/docs/source/how_tos/watch_mode.rst +163 -0
  86. qkrun-2.0.0/docs/source/index.rst +40 -0
  87. qkrun-2.0.0/docs/source/introduction.rst +210 -0
  88. qkrun-2.0.0/docs/source/license.rst +5 -0
  89. qkrun-2.0.0/docs/source/mcp.rst +138 -0
  90. qkrun-2.0.0/docs/source/namespaces.rst +230 -0
  91. qkrun-2.0.0/docs/source/private_tasks.rst +19 -0
  92. qkrun-2.0.0/docs/source/running_tasks_in_parallel.rst +72 -0
  93. qkrun-2.0.0/docs/source/running_tasks_in_sequence.rst +37 -0
  94. qkrun-2.0.0/docs/source/script.rst +213 -0
  95. qkrun-2.0.0/docs/source/task.rst +82 -0
  96. qkrun-2.0.0/docs/source/task_names_and_aliases.rst +69 -0
  97. qkrun-2.0.0/pyproject.toml +106 -0
  98. qkrun-2.0.0/src/qkrun/__init__.py +106 -0
  99. qkrun-2.0.0/src/qkrun/__main__.py +16 -0
  100. qkrun-2.0.0/src/qkrun/_argparser.py +226 -0
  101. qkrun-2.0.0/src/qkrun/_cache.py +212 -0
  102. qkrun-2.0.0/src/qkrun/_cli.py +207 -0
  103. qkrun-2.0.0/src/qkrun/_launcher.py +313 -0
  104. qkrun-2.0.0/src/qkrun/_meta.py +7 -0
  105. qkrun-2.0.0/src/qkrun/_namespace.py +392 -0
  106. qkrun-2.0.0/src/qkrun/_sentinels.py +17 -0
  107. qkrun-2.0.0/src/qkrun/_version.py +5 -0
  108. qkrun-2.0.0/src/qkrun/_watcher.py +208 -0
  109. qkrun-2.0.0/src/qkrun/commands/__init__.py +30 -0
  110. qkrun-2.0.0/src/qkrun/commands/autocomplete.py +60 -0
  111. qkrun-2.0.0/src/qkrun/commands/base.py +29 -0
  112. qkrun-2.0.0/src/qkrun/commands/init.py +52 -0
  113. qkrun-2.0.0/src/qkrun/commands/list_.py +125 -0
  114. qkrun-2.0.0/src/qkrun/commands/run.py +92 -0
  115. qkrun-2.0.0/src/qkrun/commands/watch.py +156 -0
  116. qkrun-2.0.0/src/qkrun/completion/__init__.py +68 -0
  117. qkrun-2.0.0/src/qkrun/completion/_internal.py +47 -0
  118. qkrun-2.0.0/src/qkrun/completion/base.py +53 -0
  119. qkrun-2.0.0/src/qkrun/completion/python.py +90 -0
  120. qkrun-2.0.0/src/qkrun/conditions/__init__.py +231 -0
  121. qkrun-2.0.0/src/qkrun/conditions/base.py +111 -0
  122. qkrun-2.0.0/src/qkrun/config.py +353 -0
  123. qkrun-2.0.0/src/qkrun/context.py +180 -0
  124. qkrun-2.0.0/src/qkrun/errors.py +173 -0
  125. qkrun-2.0.0/src/qkrun/factories.py +635 -0
  126. qkrun-2.0.0/src/qkrun/mcp.py +399 -0
  127. qkrun-2.0.0/src/qkrun/tasks.py +1325 -0
  128. qkrun-2.0.0/src/qkrun/utils/__init__.py +1 -0
  129. qkrun-2.0.0/src/qkrun/utils/argparser.py +82 -0
  130. qkrun-2.0.0/src/qkrun/utils/console.py +81 -0
  131. qkrun-2.0.0/src/qkrun/utils/imports.py +72 -0
  132. qkrun-2.0.0/tests/__init__.py +0 -0
  133. qkrun-2.0.0/tests/_qk_test/.qkrun_cache/.gitignore +1 -0
  134. qkrun-2.0.0/tests/_qk_test/.qkrun_cache/task_names.json +1 -0
  135. qkrun-2.0.0/tests/_qk_test/__init__.py +38 -0
  136. qkrun-2.0.0/tests/_qk_test/nested.py +14 -0
  137. qkrun-2.0.0/tests/conftest.py +26 -0
  138. qkrun-2.0.0/tests/test_cache.py +287 -0
  139. qkrun-2.0.0/tests/test_cli.py +1321 -0
  140. qkrun-2.0.0/tests/test_completion.py +209 -0
  141. qkrun-2.0.0/tests/test_config.py +265 -0
  142. qkrun-2.0.0/tests/test_context.py +129 -0
  143. qkrun-2.0.0/tests/test_launcher_integration.py +487 -0
  144. qkrun-2.0.0/tests/test_main.py +23 -0
  145. qkrun-2.0.0/tests/test_mcp.py +773 -0
  146. qkrun-2.0.0/tests/test_namespace.py +618 -0
  147. qkrun-2.0.0/tests/test_task_arguments.py +259 -0
  148. qkrun-2.0.0/tests/test_tasks.py +1735 -0
  149. qkrun-2.0.0/tests/test_utils/test_argparser.py +53 -0
  150. qkrun-2.0.0/tests/test_utils/test_cli.py +62 -0
  151. qkrun-2.0.0/tests/test_utils/test_conditions.py +229 -0
  152. qkrun-2.0.0/tests/test_utils/test_imports.py +40 -0
  153. qkrun-2.0.0/tests/test_watcher.py +586 -0
  154. qkrun-2.0.0/uv.lock +2461 -0
@@ -0,0 +1,27 @@
1
+ # http://editorconfig.org
2
+
3
+ root = true
4
+
5
+ [*]
6
+ charset = utf-8
7
+ end_of_line = lf
8
+ insert_final_newline = true
9
+ trim_trailing_whitespace = true
10
+
11
+ [*.{py,rst,ini}]
12
+ indent_style = space
13
+ indent_size = 4
14
+
15
+ [*.{html,css,scss,json,yml,xml}]
16
+ indent_style = space
17
+ indent_size = 2
18
+
19
+ [*.md]
20
+ trim_trailing_whitespace = false
21
+
22
+ [Makefile]
23
+ indent_style = tab
24
+
25
+ [nginx.conf]
26
+ indent_style = space
27
+ indent_size = 2
@@ -0,0 +1,39 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ jobs:
9
+ test:
10
+ name: Test (Python ${{ matrix.python-version }})
11
+ runs-on: ubuntu-latest
12
+ strategy:
13
+ fail-fast: false
14
+ matrix:
15
+ python-version: ["3.12"]
16
+
17
+ steps:
18
+ - name: Checkout
19
+ uses: actions/checkout@v4
20
+
21
+ - name: Install uv
22
+ uses: astral-sh/setup-uv@v5
23
+ with:
24
+ enable-cache: true
25
+ cache-dependency-glob: "uv.lock"
26
+
27
+ - name: Set up Python ${{ matrix.python-version }}
28
+ uses: actions/setup-python@v5
29
+ with:
30
+ python-version: ${{ matrix.python-version }}
31
+
32
+ - name: Install dependencies
33
+ run: uv sync --dev
34
+
35
+ - name: Run tests with coverage
36
+ run: uv run pytest --cov --cov-report=term-missing --cov-fail-under=95
37
+
38
+ - name: Run pre-commit (lint, format, and other checks)
39
+ run: uv run pre-commit run --all-files
qkrun-2.0.0/.gitignore ADDED
@@ -0,0 +1,28 @@
1
+
2
+ qkrun.code-workspace
3
+
4
+ .coverage
5
+ .DS_Store
6
+ htmlcov/
7
+
8
+ ## Python ##
9
+ # Byte-compiled / optimized / DLL files
10
+ __pycache__/
11
+
12
+ ### VisualStudioCode ###
13
+ .vscode/*
14
+ build/
15
+ dist/
16
+ *.egg-info
17
+
18
+ # Ignore .log, .log1, etc files
19
+ *.log
20
+
21
+ ## Tooling caches ##
22
+ .pytest_cache/
23
+ .ruff_cache/
24
+ .venv/
25
+
26
+ ## Documentation build output ##
27
+ docs/build/
28
+ AGENTS.md
@@ -0,0 +1,42 @@
1
+ default_stages: [pre-commit]
2
+
3
+ default_language_version:
4
+ python: python3.12 # Change if we upgrade python
5
+
6
+ repos:
7
+ - repo: https://github.com/pre-commit/pre-commit-hooks
8
+ rev: v5.0.0
9
+ hooks:
10
+ - id: trailing-whitespace
11
+ exclude: ^docs/source/generated/
12
+ - id: end-of-file-fixer
13
+ exclude: ^docs/source/generated/
14
+ - id: check-json
15
+ - id: check-toml
16
+ - id: check-xml
17
+ - id: check-yaml
18
+ - id: debug-statements
19
+ - id: check-builtin-literals
20
+ - id: check-case-conflict
21
+ - id: check-merge-conflict
22
+ - id: detect-private-key
23
+
24
+ - repo: https://github.com/asottile/pyupgrade
25
+ rev: v3.19.1
26
+ hooks:
27
+ - id: pyupgrade
28
+ args: [--py312-plus] # Change if we upgrade python
29
+ exclude: hooks/
30
+
31
+ - repo: https://github.com/astral-sh/ruff-pre-commit
32
+ rev: v0.16.2
33
+ hooks:
34
+ # Run the linter.
35
+ - id: ruff
36
+ args: ["--fix", "--select", "F401", "F811"]
37
+ - id: ruff-format
38
+
39
+ ci:
40
+ autoupdate_schedule: weekly
41
+ skip: []
42
+ submodules: false
@@ -0,0 +1,19 @@
1
+ version: "2"
2
+
3
+ build:
4
+ os: "ubuntu-lts-latest"
5
+ tools:
6
+ python: "3.12"
7
+ jobs:
8
+ post_install:
9
+ - pip install uv
10
+ - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv sync --all-extras --dev --link-mode=copy
11
+
12
+
13
+ sphinx:
14
+ configuration: docs/source/conf.py
15
+
16
+
17
+ formats:
18
+ - pdf
19
+ - epub
@@ -0,0 +1,340 @@
1
+ # qkrun Change Log
2
+
3
+ ## 2.0.0
4
+
5
+ ### Migrating to qkrun
6
+
7
+ - Replace `quickie-runner` with `qkrun` in dependency files and installation
8
+ commands. If switching in an existing environment, uninstall `quickie-runner`
9
+ first, then install `qkrun` with the same package manager. Both distributions
10
+ provide `qk` and `qk-mcp`, so installing them together can overwrite those
11
+ commands.
12
+ - Update Python imports from `quickie` to `qkrun`, use `python -m qkrun`
13
+ instead of `python -m quickie`, and replace `QuickieError` with `QkrunError`.
14
+ - Rename `QUICKIE_RUNNER_{INFO,WARNING,ERROR,SUCCESS}_STYLE` settings to
15
+ `QKRUN_{INFO,WARNING,ERROR,SUCCESS}_STYLE`.
16
+ - The MCP server now identifies itself as `qkrun`. The `qk` and `qk-mcp`
17
+ commands and `_qk` task discovery are unchanged.
18
+
19
+ ## Release 1.0.0
20
+
21
+ ### Fixed
22
+
23
+ - Nested namespaces now preserve their parent path when tasks are discovered.
24
+ - Task listings no longer fail when a task has no invocation path matching its
25
+ declared name; the lexicographically first invocation path is used instead.
26
+ - Task listings now wrap long source locations and make them clickable in
27
+ terminals that support hyperlinks.
28
+
29
+ ### Changed
30
+
31
+ - Replaced action flags such as `-l`, `--watch`, and `--init` with native
32
+ colon-prefixed subcommands: `:list`, `:watch`, `:init`, and
33
+ `:autocomplete`. The former flag-based forms are no longer supported.
34
+ - Command-specific options are now scoped to their subcommands. For example,
35
+ watch options use `qk :watch --paths ...` instead of `--watch-paths`.
36
+ - Improved `qk -h` with separate command and direct-task sections, clearer
37
+ positional argument descriptions, usage forms, and examples.
38
+ - Improved shell completion for task names and colon-prefixed subcommands.
39
+
40
+ ## Release 0.11.0
41
+
42
+ ### Added
43
+
44
+ - Added `--list-filter` to filter task listings by invocation name or alias.
45
+ Passing the option without a value lists all tasks.
46
+
47
+ ### Changed
48
+
49
+ - Watch configuration now separates watched directories, ignored directories,
50
+ included file patterns, and ignored file patterns, matching
51
+ ``watchmedo log`` semantics.
52
+ - Watch paths are treated as literal directory values, while pattern options
53
+ support repeatable and semicolon-separated watchdog wildcard patterns.
54
+ - Added recursive watching and consistent resolution of relative watch paths
55
+ against the task's effective working directory.
56
+ - Watch mode now runs the initial task before starting the observer and prints
57
+ the paths that triggered each re-run, making watcher configuration easier to
58
+ diagnose.
59
+ - Watch mode now waits for debounced filesystem changes directly instead of
60
+ polling, and stopping the watcher wakes any blocked wait immediately.
61
+ - Removed the obsolete ``--watch-interval`` option and task configuration;
62
+ ``watch_debounce`` is now the only watch timing control.
63
+ - Task listings now show each task once, using the declared task name as the
64
+ canonical name. Namespaced invocations are shown as aliases unless the task
65
+ is only available through a namespace, in which case the declared name is
66
+ shown with its namespace prefix.
67
+ - Human-readable task listings now include bordered rows. MCP task listings
68
+ expose the same canonical-name and alias behavior.
69
+
70
+ ## Release 0.10.1
71
+
72
+ ### Changed
73
+
74
+ - Watch configuration passed to ``@task``, ``@script``, ``@command``, and other
75
+ task decorators is now forwarded consistently through the shared task factory.
76
+ - Project-root discovery now tolerates filesystem errors while checking marker
77
+ directories and files.
78
+ - Task usage generation is compatible with Python versions whose
79
+ ``argparse.ArgumentParser`` does not support the ``color`` keyword.
80
+
81
+ ### Fixed
82
+
83
+ - Fixed ``TypeError`` when using ``watch_paths`` and related watch options with
84
+ ``@script`` or other decorators backed by the shared task factory.
85
+
86
+ ## Release 0.10.0
87
+
88
+ ### Changed
89
+
90
+ - Paths prefixed with ``./`` (e.g. ``"./subdir"``) in task ``wd`` and
91
+ ``PathCompleter`` now resolve relative to the tasks module parent directory
92
+ (the project root), independently of the current working directory. This
93
+ aligns ``./`` with the existing ``"."`` (bare dot) behaviour.
94
+ - Improved ``import quickie`` startup time by deferring heavy imports
95
+ until first use, via lazy ``__init__`` loading and inline imports in
96
+ ``_cli``, ``context``, and ``config``.
97
+
98
+ ### Added
99
+
100
+ - Watch mode (``-w``/``--watch``): re-runs a task automatically when files change.
101
+ Uses `watchdog` for OS-native file watching (FSEvents on macOS, inotify on Linux). Supports
102
+ ``--watch-paths``, ``--watch-exclude``, ``--watch-debounce``, and
103
+ ``--watch-interval`` for fine-grained control. Tasks can declare watch
104
+ configuration via class attributes or the ``@task`` decorator
105
+ (``watch=True``, ``watch_paths=[...]``, etc.) so that ``qk --watch <task>``
106
+ works without repeating paths on the command line.
107
+ - `PathCompleter` now accepts an optional `wd` parameter to control the
108
+ directory paths are resolved relative to, following the same rules as task
109
+ working directories.
110
+ - Added `resolve_wd()` function in `quickie.context` that encapsulates the
111
+ working directory resolution logic, shared by `_BaseSubprocessTask` and
112
+ `PathCompleter`.
113
+ - Added a disk-based task metadata cache (`.quickie_cache/task_names.json`)
114
+ that speeds up CLI tab-completion by avoiding full module imports. The
115
+ cache stores task names, help text, and argument metadata and is
116
+ automatically invalidated when any ``.py`` file in the tasks directory
117
+ changes. Completers that can be rebuilt from cache (``PathCompleter``,
118
+ ``PytestCompleter``) are reconstructed lazily; tasks with unknown
119
+ completers gracefully fall back to a full import.
120
+ - Added mtime-based caching to ``Launcher.discover_project_root()`` to
121
+ avoid redundant directory walks when discovering the project root.
122
+
123
+ ## Release 0.9.1
124
+
125
+ ### Changed
126
+
127
+ - Upgraded dependencies
128
+
129
+ ## Release 0.9.0
130
+
131
+ ### Changed
132
+
133
+ - `qk-mcp`: replaced per-call `module` path resolution with a static project
134
+ registry. Projects are now declared at server startup via `--project NAME:PATH`
135
+ or `--config FILE`; they cannot be changed by clients at runtime.
136
+ - `qk-mcp`: `list_tasks` and `run_task` now accept a `project` parameter
137
+ (alias or path) instead of `module`. `list_tasks` returns one entry per
138
+ project with keys `project`, `project_root`, and `tasks`.
139
+ - `qk-mcp`: `list_tasks` returns tasks for **all** registered projects when
140
+ `project` is omitted (previously returned only the default project).
141
+ - `qk-mcp`: removed `--module` / `-m` and `--global` / `-g` flags (still
142
+ supported by the `qk` CLI). Use `--project` to register a project path.
143
+
144
+
145
+ ## Release 0.8.1
146
+
147
+ ### Fixed
148
+
149
+ - Fixed `qk-mcp` subprocess resolution to prefer project-local `qk` executable/venv when available.
150
+ - Ensure `run_task` forwards `--module`/`--global` flags and isolates subprocess config.
151
+ - Tests: fixed asyncio mocks and added tests for MCP venv resolution.
152
+
153
+
154
+ ## Release 0.8.0
155
+
156
+ ### Added
157
+
158
+ - Added `qk-mcp` MCP stdio server.
159
+
160
+
161
+ ## Release 0.7.0
162
+
163
+ ### Added
164
+
165
+ - Added `load_env_file(path)` helper that loads a `.env` file and returns a `dict[str, str]` (variables without a value are omitted; empty values are kept). Exported from the top-level `quickie` package.
166
+ - Added `Context.from_env_file(path, *, wd, base_dir, env, inherit_env)` classmethod to build a `Context` pre-populated from a `.env` file. Explicit `env` values take precedence over file-loaded values. Exported from the top-level `quickie` package.
167
+ - Command and script tasks (and their subclasses) now accept an `env_file` attribute and constructor/decorator argument. The `.env` file is loaded lazily at execution time; relative paths are resolved from the quickie tasks root. Explicit `env` values override keys loaded from the file.
168
+ - Command and script tasks now fail fast on unexpected non-zero subprocess exit codes.
169
+ - Command and script tasks now support `expected_exit_codes` to allow non-zero results explicitly or disable exit code validation.
170
+ - Command and script tasks now support `timeout` (seconds per attempt), `retries` (additional attempts on failure), and `retry_delay` (seconds between attempts). Timeouts raise `SubprocessTimeoutError` (exit code 124). Both exit-code and timeout errors trigger the retry loop; warnings are logged for each failed attempt and retry.
171
+ - Command and script tasks now expose an `output_mode` parameter (and class attribute) accepting `OutputMode.STREAM` (default), `OutputMode.CAPTURE`, or `OutputMode.TEE`. `CAPTURE` silences the terminal and populates `CompletedProcess.stdout`/`.stderr` as bytes. `TEE` streams to the terminal *and* captures. String literals `"stream"`, `"capture"`, `"tee"` are accepted and coerced automatically. `OutputMode` is exported from the top-level `quickie` package.
172
+ - Added `@namespace` decorator that converts a plain function into a `Namespace` instance at module level. The function must return a list or dict of tasks/modules; the function name is used as the path prefix by default. Supports `@namespace(path=..., separator=...)` for explicit configuration.
173
+ - `TaskNotFoundError` now suggests close matches when the task name is similar to a registered key.
174
+ - Naming a `@namespace`-decorated function `_` now registers its tasks at the root (no prefix), removing the need to write `@namespace(path="")` explicitly.
175
+ - `Namespace` now supports a `factory` parameter (a zero-argument callable returning a list or dict). The factory is executed **lazily** — only when the namespace's tasks are first needed. `@namespace`-decorated functions automatically use this mechanism, so imports inside the function body are deferred until the namespace is actually accessed.
176
+
177
+ ### Changed
178
+
179
+ - `QuickieError` now declares `exit_code` as a class-level attribute (default `1`); subclasses override it declaratively. The `__init__` `exit_code` parameter is now optional and only used when a per-instance override is needed.
180
+ - `TaskNotFoundError` exit code changed from `1` to `127` (POSIX shell "command not found" convention).
181
+ - `TasksModuleNotFoundError` exit code changed from `2` to `78` (`EX_CONFIG` from sysexits.h — configuration/environment problem).
182
+ - `SubprocessTimeoutError` exit code `124` is now a class-level attribute (previously passed at instance construction).
183
+ - `Task.__call__`, `Task.full_run`, and `Task.run` now carry explicit return-type annotations (`Any`). `Command.run` and `Script.run` are annotated `subprocess.CompletedProcess[bytes]`.
184
+ - `Group.run` now returns `list[Any]` of sub-task results in definition order (previously returned `None`).
185
+ - `ThreadGroup.run` now returns `list[Any]` of sub-task results in **definition order**, not completion order (previously returned `None`).
186
+ - `ThreadGroup` now collects **all** sub-task exceptions and raises them together as an `ExceptionGroup` (previously only the first exception was surfaced; the rest were silently dropped). Use `except*` to handle individual exception types.
187
+ - `Namespace` now accepts a `separator` parameter (default `":"`); the separator is forwarded through all path-building helpers so sub-paths within a namespace use a consistent, per-instance separator.
188
+ - Circular-reference detection in namespace resolution now uses back-edge (DFS ancestry) tracking instead of global-visit tracking, correctly allowing the same object to appear under multiple namespace keys (shared references / DAGs) while still raising `CircularDependencyError` for genuine cycles.
189
+ - `RootNamespace.load()` is now **shallow**: `Task` objects found directly on the module are registered immediately, while `Namespace` objects are stored in a pending queue and resolved on demand.
190
+
191
+ ### Fixed
192
+
193
+ - Documented direct task-to-task composition pattern: call a task instance from within another task's `run()` to receive its result.
194
+
195
+ ## Release 0.6.0
196
+
197
+ ### Added
198
+
199
+ - **Smart launcher for unified qk command**: The global `qk` command now automatically discovers project-local quickie installations and delegates to them, eliminating the need for manual venv activation. Each project can pin its own version while using the same `qk` command.
200
+ - `--global` flag to `qk` command to explicitly use global tasks from `~/_qkg` without project discovery.
201
+ - Project discovery algorithm that searches for `_qk` directory or `_qk.py` file starting from the current directory and traversing parent directories.
202
+ - Environment detection supporting uv-managed virtual environments, generic venv paths, and explicit path override via `QK_EXECUTABLE` environment variable.
203
+ - Recursion guard to prevent infinite delegation loops when project environment is misconfigured.
204
+ - Comprehensive error messages with attempted paths and setup guidance when project or executable cannot be found.
205
+
206
+ ### Changed
207
+
208
+ - `qk` is now the primary entry point with smart launcher behavior. It first attempts to discover and delegate to a project-local quickie installation before falling back to the local CLI logic.
209
+ - `--global` flag is now the recommended way to access global tasks instead of requiring separate `qkg` command.
210
+ - Installation documentation updated to emphasize the automatic launcher flow as the recommended usage pattern.
211
+ - Default task names are transformed to lowercase, contiguous or single underscores are replaced with a single dash, and leading and trailing underscores/dashes are removed.
212
+
213
+ ### Removed
214
+
215
+ - `quickie-runner-global` package and the `qkg` command have been removed. Use `qk --global` or `qk -g` instead.
216
+
217
+ ### Fixed
218
+
219
+ - Can retrieve the file and line of tasks defined from functions wrapped with `functools.wraps`.
220
+ - `FilesModified` condition now takes a cache id explicitly.
221
+ - `Command` now falls back to `sys.executable` or `python3` when the `python` binary is not found in PATH.
222
+
223
+ ### Migration Notes
224
+
225
+ - **For project users**: No changes required. Running `qk` from anywhere in your project will automatically use the project-specific version without manual venv activation.
226
+ - **For global task users**: Migrate from `qkg` to `qk --global` or `qk -g`. The `quickie-runner-global` package and `qkg` command are no longer available.
227
+ - **For users with multiple project versions**: Your setup is now natively supported. Each project can pin its own quickie version, and `qk` will automatically delegate to the correct version.
228
+
229
+ ## Release 0.5.1
230
+
231
+ ### Changed
232
+ - Only show error tracebacks when verbosity is set to 2 or higher.
233
+
234
+ ## Release 0.5.0
235
+
236
+ ### Removed
237
+ - Removed `partial_task`. `functools.partial` can be used instead.
238
+ - Removed `lazy_task`. `lambda: task()` can be used in most cases.
239
+ - Removed other proxy task types.
240
+
241
+ ### Changed
242
+
243
+ - Replace NAMESPACES with Namespace class.
244
+ - Pretty printing and input can be done via a separate global console instance instead of through the task.
245
+ - Improved configuration.
246
+ - Parent process env variables are now passed to the child process even if some variables are overwritten.
247
+ - Changed the way command line arguments are defined in the task.
248
+ - Some task properties are now cached and evaluated when needed instead of at task initialization time, potentially
249
+ improving performance in some cases.
250
+ - Using task instances instead of task classes for the task registry.
251
+ - Before, after and cleanup tasks can now be any callable, not just a task.
252
+ - Moved more task class attributes to initialization time, so that they can be overridden by the task instance.
253
+ - Changed project and user folders to `_qk` and `_qkg` respectively.
254
+
255
+ ### Fixed
256
+ - Fix type hinting for task decorators.
257
+ - Fix bug causing the autocomplete to suggest files when calling `qk` with no arguments.
258
+
259
+ ### Added
260
+
261
+ - Tasks can be skipped without stopping all pending tasks.
262
+ - Can skip logging for a task, to exclude sensitive information.
263
+ - Add logging and logging levels.
264
+ - Documentation for custom task factories.
265
+ - Can define the working directory for a command or script to be the parent of the tasks directory.
266
+
267
+
268
+ ## Release 0.4.0
269
+
270
+ ### Changed
271
+
272
+ - NAMESPACES now accepts and ignores null values.
273
+ - Command now accepts unix style command strings.
274
+ - Script now allows defining the executable
275
+ - Cleaner exit on keyboard interrupt.
276
+ - Changed command from `qck` and `qckg` to `qk` and `qkg`.
277
+
278
+ ## Release 0.3.3
279
+
280
+ ### Changed
281
+
282
+ - Tasks are listed sorted by location, and grouped by class, creating a new table for aliases.
283
+
284
+ ## Release 0.3.2
285
+
286
+ ### Added
287
+
288
+ - Listing tasks also shows the file and line where the task is defined.
289
+
290
+ ### Fixed
291
+
292
+ - Fix bug causing tasks the help message for tasks to not include the docstring.
293
+
294
+ ## Release 0.3.1
295
+
296
+ ### Changed
297
+
298
+ - fix quickie-runner-global dependencies
299
+
300
+ ## Release 0.3.0
301
+
302
+ ### Changed
303
+
304
+ - Removed Task.Meta and Task.DefaultMeta in favor of configuration in the task class.
305
+ - Task names inferred from class name preserve the case.
306
+ - Refactored and moved things around.
307
+ - Task classes starting with an underscore are now considered private by default.
308
+ - Namespace tasks using the `NAMESPACES` attribute instead of `QCK_NAMESPACES`.
309
+ - `NAMESPACES` (previously `QCK_NAMESPACES`) now also accepts a list of modules to load for
310
+ a single namespace.
311
+
312
+ ## Release 0.2.2
313
+
314
+ Fixes for global runner.
315
+
316
+ ## Release 0.2.1
317
+
318
+ Fixes for global runner.
319
+
320
+ ## Release 0.2.0
321
+
322
+ ### Added
323
+
324
+ - Create tasks from functions.
325
+ - Add arguments to the parser of tasks via decorators.
326
+ - Define tasks that must run before or after another task.
327
+ - Define cleanup tasks for a task.
328
+ - Allow conditions for running tasks.
329
+ - Define partial tasks.
330
+ - Load from another task by name.
331
+
332
+ ### Changed
333
+
334
+ - Renamed classes and parameters for clarity.
335
+ - Removed support for file-based configuration in favor of environment variables.
336
+ - Removed `-g` argument in favor of separate global runner.
337
+
338
+ ## Release 0.1.0
339
+
340
+ - Initial release.
@@ -0,0 +1,59 @@
1
+ # Contributing to qkrun
2
+
3
+ Thanks for your interest in contributing! This guide covers how to set up the project, run the checks that are enforced in CI, and submit changes.
4
+
5
+ ## Development setup
6
+
7
+ The project uses [uv](https://docs.astral.sh/uv/) for dependency management and requires **Python 3.12+**.
8
+
9
+ ```bash
10
+ # Fork the repository on GitHub, then clone your fork:
11
+ git clone https://github.com/<your-username>/qkrun.git
12
+ cd qkrun
13
+
14
+ # Install dependencies
15
+ uv sync --dev
16
+
17
+ # Install the pre-commit hooks
18
+ uv run pre-commit install
19
+ ```
20
+
21
+ ## Commands
22
+
23
+ | Task | Command |
24
+ | ---- | ------- |
25
+ | Run the test suite | `uv run pytest` |
26
+ | Run tests with coverage | `uv run pytest --cov --cov-report=term-missing --cov-fail-under=95` |
27
+ | Lint | `uv run ruff check . --select F401,F811` |
28
+ | Format (write) | `uv run ruff format .` |
29
+ | Format (check) | `uv run ruff format --check .` |
30
+ | Pre-commit (all files) | `uv run pre-commit run --all-files` |
31
+
32
+ ## Checks enforced in CI
33
+
34
+ GitHub Actions runs the following on every push and pull request (see `.github/workflows/ci.yml`):
35
+
36
+ 1. **Tests** — `pytest` with coverage; the build fails if total coverage drops below **95%**.
37
+ 2. **Linting** — `ruff check . --select F401,F811` (unused imports and redefinitions).
38
+ 3. **Formatting** — `ruff format --check .`.
39
+ 4. **Pre-commit** — `pre-commit run --all-files`.
40
+
41
+ ## Coverage
42
+
43
+ New code should be covered by tests. `src/qkrun/__main__.py` is a thin wrapper around `qkrun._cli.main`; the relevant tests live in `tests/test_main.py`.
44
+
45
+ To see the coverage report:
46
+
47
+ ```bash
48
+ uv run pytest --cov --cov-report=html
49
+ ```
50
+
51
+ ## Submitting changes
52
+
53
+ 1. Fork the repository on GitHub.
54
+ 2. Clone your fork and create a branch off `main`.
55
+ 3. Make your changes, adding or updating tests as appropriate.
56
+ 4. Run the checks listed above and make sure they pass.
57
+ 5. Push your branch to your fork and open a pull request against the upstream `main` branch. CI will run the full suite automatically.
58
+
59
+ If CI fails, the `Checks` tab of the pull request will show which step (tests, lint, format, or pre-commit) needs attention.
qkrun-2.0.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ The MIT License
2
+
3
+ Copyright 2024 Adrian Martinez Rodriguez <adrianmrit@gmail.com>
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
+ THE SOFTWARE.
qkrun-2.0.0/PKG-INFO ADDED
@@ -0,0 +1,101 @@
1
+ Metadata-Version: 2.5
2
+ Name: qkrun
3
+ Version: 2.0.0
4
+ Summary: A CLI tool for quick tasks.
5
+ Project-URL: Homepage, https://github.com/adrianmrit/qkrun
6
+ Project-URL: Documentation, https://qkrun.readthedocs.io
7
+ Project-URL: Repository, https://github.com/adrianmrit/qkrun.git
8
+ Project-URL: Issues, https://github.com/adrianmrit/qkrun/issues
9
+ Project-URL: Changelog, https://github.com/adrianmrit/qkrun/blob/main/CHANGELOG.md
10
+ Author-email: Adrian Martinez Rodriguez <adrianmrit@gmail.com>
11
+ License: The MIT License
12
+
13
+ Copyright 2024 Adrian Martinez Rodriguez <adrianmrit@gmail.com>
14
+
15
+ Permission is hereby granted, free of charge, to any person obtaining a copy
16
+ of this software and associated documentation files (the "Software"), to deal
17
+ in the Software without restriction, including without limitation the rights
18
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
19
+ copies of the Software, and to permit persons to whom the Software is
20
+ furnished to do so, subject to the following conditions:
21
+
22
+ The above copyright notice and this permission notice shall be included in
23
+ all copies or substantial portions of the Software.
24
+
25
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
26
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
27
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
28
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
29
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
30
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
31
+ THE SOFTWARE.
32
+ License-File: LICENSE
33
+ Keywords: CLI,quick,tasks
34
+ Classifier: Development Status :: 3 - Alpha
35
+ Classifier: Environment :: Console
36
+ Classifier: Intended Audience :: Developers
37
+ Classifier: License :: OSI Approved :: MIT License
38
+ Classifier: Programming Language :: Python :: 3.12
39
+ Requires-Python: >=3.12
40
+ Requires-Dist: argcomplete>=3.6
41
+ Requires-Dist: fastmcp>=3.4
42
+ Requires-Dist: frozendict>=2.4
43
+ Requires-Dist: oslex>=2.0
44
+ Requires-Dist: python-dotenv>=1.2
45
+ Requires-Dist: rich>=15.0
46
+ Requires-Dist: watchdog>=5.0
47
+ Description-Content-Type: text/markdown
48
+
49
+ # qkrun - A CLI Tool for Quick Tasks
50
+
51
+ [![License](https://img.shields.io/github/license/adrianmrit/qkrun)](https://github.com/adrianmrit/qkrun/blob/main/LICENSE)
52
+
53
+ qkrun is a powerful and flexible command-line tool designed to simplify task automation. It supports both per-project and global task configurations, making it ideal for developers and teams.
54
+
55
+ Documentation is available at [qkrun.readthedocs.io](https://qkrun.readthedocs.io/en/latest/).
56
+
57
+ Upgrading from `quickie-runner`? See the [migration notes](CHANGELOG.md#2.0.0).
58
+
59
+ ## Development
60
+
61
+ This project uses [uv](https://docs.astral.sh/uv/) for dependency management.
62
+
63
+ ### Setup
64
+
65
+ ```bash
66
+ uv sync --dev
67
+ pre-commit install
68
+ ```
69
+
70
+ ### Running tests
71
+
72
+ ```bash
73
+ uv run pytest
74
+ ```
75
+
76
+ Run the tests with coverage and enforce the project's coverage threshold:
77
+
78
+ ```bash
79
+ uv run pytest --cov --cov-report=term-missing --cov-fail-under=95
80
+ ```
81
+
82
+ ### Linting and formatting
83
+
84
+ ```bash
85
+ uv run ruff check .
86
+ uv run ruff format .
87
+ ```
88
+
89
+ ### Pre-commit
90
+
91
+ Hooks are configured in `.pre-commit-config.yaml` and run automatically on commit. To run them manually:
92
+
93
+ ```bash
94
+ uv run pre-commit run --all-files
95
+ ```
96
+
97
+ ### Continuous integration
98
+
99
+ CI runs on GitHub Actions for every push and pull request (see `.github/workflows/ci.yml`). It runs the test suite with coverage, linting, formatting checks, and pre-commit.
100
+
101
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.