qik 0.0.1__tar.gz

qik-0.0.1/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2024, Opus 10
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL OPUS 10 BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

qik-0.0.1/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.1
+Name: qik
+Version: 0.0.1
+Summary: Run cached commands in your modular monorepo.
+Home-page: https://github.com/Opus10/qik
+License: BSD-3-Clause
+Author: Opus 10 Engineering
+Requires-Python: >=3.10.0,<4
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Provides-Extra: dev
+Provides-Extra: graph
+Provides-Extra: s3
+Provides-Extra: watch
+Requires-Dist: boto3 (>=1) ; extra == "s3"
+Requires-Dist: grimp (>=3.4.1) ; extra == "graph" or extra == "dev"
+Requires-Dist: msgspec (>=0.18.6)
+Requires-Dist: rich (>=13)
+Requires-Dist: rustworkx (>=0.15.1) ; extra == "graph" or extra == "dev"
+Requires-Dist: typing-extensions (>=4.11.0)
+Requires-Dist: watchdog (>=4) ; extra == "watch" or extra == "dev"
+Requires-Dist: xxhash (>=3.4.1)
+Project-URL: Documentation, https://qik.readthedocs.io
+Project-URL: Repository, https://github.com/Opus10/qik
+Description-Content-Type: text/markdown
+
+<p align="center" style="padding-bottom: 1rem">
+  <a href="https://qik.build"><img src="docs/static/logo.webp" alt="qik" width="40%"></a>
+</p>
+
+Qik (*quick*) is a cached command runner for modular monorepos. Like [make](https://www.gnu.org/software/make/), but with hash-based caching and advanced dependencies such as globs, imports, external packages, and much more.
+
+Qik's command caching ensures you never do redundant work. Parametrize commands across modules, watch and re-run them reactively, or filter commands since a git hash. Qik can dramatically improve CI and local development time.
+
+Although qik has special functionality with Python repos, any git-based project can use qik as a command runner.
+
+[Read the docs here](https://qik.build).
+
+## Installation
+
+```bash
+pip install qik
+```
+
+For local development, we recommend installing most optional dependencies with:
+
+```bash
+pip install qik[dev]
+```
+
+Qik is compatible with Python 3.10 - 3.12, Linux, OSX, and WSL.
+
+## Quick Start
+
+### File and Glob Dependencies
+
+Here we use the `pip-compile` executable from [pip-tools](https://github.com/jazzband/pip-tools) to lock PyPI distributions. Create `qik.toml` with the following:
+
+```toml
+[commands.lock]
+exec = "pip-compile > requirements.txt"
+deps = ["requirements.in"]
+cache = "repo"
+```
+
+Running `qik lock` executes `pip-compile > requirements.txt`. Results are cached in your repo until `requirements.in` changes.
+
+### Distribution Dependencies
+
+Change `deps` to re-run this command if we upgrade `pip-tools`:
+
+```toml
+deps = ["requirements.in", {type = "dist", name = "pip-tools"}]
+```
+
+Installing a different version of `pip-tools` will break the command cache.
+
+### Modular Commands
+
+Parametrize commands over modules, for example, running the [ruff](https://docs.astral.sh/ruff/) code formatter:
+
+```toml
+modules = ["a_module", "b_module", "c_module"]
+
+[commands.format]
+exec = "ruff format {module.path}"
+deps = ["{module.path}/**.py"]
+cache = "repo"
+```
+
+Running `qik format` will parametrize `ruff format` in parallel over all available threads and configured modules. Use `-n` to adjust the number of threads and `-m` to supply modules:
+
+```bash
+qik format -n 2 -m b_module -m c_module
+```
+
+### Import Dependencies
+
+Some commands, such as [pyright](https://github.com/microsoft/pyright) type checking, should re-run whenever imports change:
+
+```toml
+modules = ["a_module", "b_module", "c_module"]
+plugins = ["qik.graph"]
+
+[commands.check_types]
+exec = "pyright {module.path}"
+deps = [{type = "module", name = "{module.name}"}]
+cache = "repo"
+```
+
+Running `qik check_types` will parametrize `pyright` over all modules. Modular commands will be cached unless the module's files or dependencies change.
+
+We use the `qik.graph` plugin, which provides commands that are automatically used for building and analyzing the import graph.
+
+### Command Dependencies
+
+Command dependencies help order execution. For example, change `deps` of `command.check_types` to run type checking only after code has been successfully formatted:
+
+```toml
+deps = [
+    {type = "module", name = "{module.name}"},
+    {type = "command", name = "format"}
+]
+```
+
+### Caching
+
+We've shown examples of the `repo` cache, which stores metadata of the most recent runs in the repo. Qik offers both local and remote caches to store all command runs and their output.
+
+To use these, first ensure commands have `artifacts` configured. For example, the `lock` command generates a `requirements.txt` file:
+
+```toml
+[commands.lock]
+exec = "pip-compile > requirements.txt"
+deps = ["requirements.in"]
+artifacts = ["requirements.txt"]
+cache = "local"
+```
+
+Above we're using the `local` cache. Versions of our `requirements.txt` will be stored in the `._qik/cache` folder. Qik supports [AWS S3](https://aws.amazon.com/pm/serv-s3/) as a [remote caching backend](caching.md).
+
+### Command Line Interface
+
+The core CLI functionality is as follows:
+
+- `qik` to run all commands.
+- `qik <cmd_name> <cmd_name>` to run specific commands.
+- `--watch` to reactively run selected commands.
+- `-f` to run without the cache.
+- `-m` to run against specific modules.
+- `-n` to set the number of threads.
+- `--ls` to list commands instead of running them.
+
+Some runtime behavior is configurable via the CLI:
+
+- `--cache` to set the default cache.
+- `--cache-when` to configure when to cache. Use `finished` to cache all results. By default only `success` runs are cached.
+- `--isolated` to not run dependent commands.
+
+These options are useful for selecting commands:
+
+- `--since` to select commands based on changes since a git SHA.
+- `--cache-type` to select commands by their cache type.
+- `--cache-status` to select commands by their cache status (`warm` or `cold`).
+- `--fail` to return a non-zero exit code if any commands are selected.
+
+Finally, use `-p` to set the qik [context](context.md).
+
+## Docs
+
+[Read the qik docs here](https://qik.build) for more information on:
+
+- Commands: A cookbook of common commands and creating module-specific commands.
+- Dependencies: All dependencies, including global dependencies, constants, and file parts.
+- Selectors: Selecting commands based on properties.
+- Context: Using environment-based context and runtime profiles.
+- Caching: How caching works and how to configure all cache types, including S3.
+- Continuous Integration: Patterns for optimizing CI time.
+- Plugins: How to create qik plugins, such as custom commands and cache backends.
+

qik-0.0.1/README.md

@@ -0,0 +1,153 @@
+<p align="center" style="padding-bottom: 1rem">
+  <a href="https://qik.build"><img src="docs/static/logo.webp" alt="qik" width="40%"></a>
+</p>
+
+Qik (*quick*) is a cached command runner for modular monorepos. Like [make](https://www.gnu.org/software/make/), but with hash-based caching and advanced dependencies such as globs, imports, external packages, and much more.
+
+Qik's command caching ensures you never do redundant work. Parametrize commands across modules, watch and re-run them reactively, or filter commands since a git hash. Qik can dramatically improve CI and local development time.
+
+Although qik has special functionality with Python repos, any git-based project can use qik as a command runner.
+
+[Read the docs here](https://qik.build).
+
+## Installation
+
+```bash
+pip install qik
+```
+
+For local development, we recommend installing most optional dependencies with:
+
+```bash
+pip install qik[dev]
+```
+
+Qik is compatible with Python 3.10 - 3.12, Linux, OSX, and WSL.
+
+## Quick Start
+
+### File and Glob Dependencies
+
+Here we use the `pip-compile` executable from [pip-tools](https://github.com/jazzband/pip-tools) to lock PyPI distributions. Create `qik.toml` with the following:
+
+```toml
+[commands.lock]
+exec = "pip-compile > requirements.txt"
+deps = ["requirements.in"]
+cache = "repo"
+```
+
+Running `qik lock` executes `pip-compile > requirements.txt`. Results are cached in your repo until `requirements.in` changes.
+
+### Distribution Dependencies
+
+Change `deps` to re-run this command if we upgrade `pip-tools`:
+
+```toml
+deps = ["requirements.in", {type = "dist", name = "pip-tools"}]
+```
+
+Installing a different version of `pip-tools` will break the command cache.
+
+### Modular Commands
+
+Parametrize commands over modules, for example, running the [ruff](https://docs.astral.sh/ruff/) code formatter:
+
+```toml
+modules = ["a_module", "b_module", "c_module"]
+
+[commands.format]
+exec = "ruff format {module.path}"
+deps = ["{module.path}/**.py"]
+cache = "repo"
+```
+
+Running `qik format` will parametrize `ruff format` in parallel over all available threads and configured modules. Use `-n` to adjust the number of threads and `-m` to supply modules:
+
+```bash
+qik format -n 2 -m b_module -m c_module
+```
+
+### Import Dependencies
+
+Some commands, such as [pyright](https://github.com/microsoft/pyright) type checking, should re-run whenever imports change:
+
+```toml
+modules = ["a_module", "b_module", "c_module"]
+plugins = ["qik.graph"]
+
+[commands.check_types]
+exec = "pyright {module.path}"
+deps = [{type = "module", name = "{module.name}"}]
+cache = "repo"
+```
+
+Running `qik check_types` will parametrize `pyright` over all modules. Modular commands will be cached unless the module's files or dependencies change.
+
+We use the `qik.graph` plugin, which provides commands that are automatically used for building and analyzing the import graph.
+
+### Command Dependencies
+
+Command dependencies help order execution. For example, change `deps` of `command.check_types` to run type checking only after code has been successfully formatted:
+
+```toml
+deps = [
+    {type = "module", name = "{module.name}"},
+    {type = "command", name = "format"}
+]
+```
+
+### Caching
+
+We've shown examples of the `repo` cache, which stores metadata of the most recent runs in the repo. Qik offers both local and remote caches to store all command runs and their output.
+
+To use these, first ensure commands have `artifacts` configured. For example, the `lock` command generates a `requirements.txt` file:
+
+```toml
+[commands.lock]
+exec = "pip-compile > requirements.txt"
+deps = ["requirements.in"]
+artifacts = ["requirements.txt"]
+cache = "local"
+```
+
+Above we're using the `local` cache. Versions of our `requirements.txt` will be stored in the `._qik/cache` folder. Qik supports [AWS S3](https://aws.amazon.com/pm/serv-s3/) as a [remote caching backend](caching.md).
+
+### Command Line Interface
+
+The core CLI functionality is as follows:
+
+- `qik` to run all commands.
+- `qik <cmd_name> <cmd_name>` to run specific commands.
+- `--watch` to reactively run selected commands.
+- `-f` to run without the cache.
+- `-m` to run against specific modules.
+- `-n` to set the number of threads.
+- `--ls` to list commands instead of running them.
+
+Some runtime behavior is configurable via the CLI:
+
+- `--cache` to set the default cache.
+- `--cache-when` to configure when to cache. Use `finished` to cache all results. By default only `success` runs are cached.
+- `--isolated` to not run dependent commands.
+
+These options are useful for selecting commands:
+
+- `--since` to select commands based on changes since a git SHA.
+- `--cache-type` to select commands by their cache type.
+- `--cache-status` to select commands by their cache status (`warm` or `cold`).
+- `--fail` to return a non-zero exit code if any commands are selected.
+
+Finally, use `-p` to set the qik [context](context.md).
+
+## Docs
+
+[Read the qik docs here](https://qik.build) for more information on:
+
+- Commands: A cookbook of common commands and creating module-specific commands.
+- Dependencies: All dependencies, including global dependencies, constants, and file parts.
+- Selectors: Selecting commands based on properties.
+- Context: Using environment-based context and runtime profiles.
+- Caching: How caching works and how to configure all cache types, including S3.
+- Continuous Integration: Patterns for optimizing CI time.
+- Plugins: How to create qik plugins, such as custom commands and cache backends.

qik-0.0.1/pyproject.toml

@@ -0,0 +1,106 @@
+[build-system]
+requires = ["poetry_core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.coverage.run]
+branch = true
+source = ["qik"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "pass",
+    "pytest.mark.skip",
+    "@(typing\\.)?overload",
+    "if TYPE_CHECKING:",
+]
+show_missing = true
+fail_under = 100
+
+[tool.poetry]
+name = "qik"
+packages = [
+  { include = "qik" }
+]
+exclude = [
+  "*/tests/"
+]
+version = "0.0.1"
+description = "Run cached commands in your modular monorepo."
+authors = ["Opus 10 Engineering"]
+classifiers = [
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3 :: Only",
+]
+license = "BSD-3-Clause"
+readme = "README.md"
+homepage = "https://github.com/Opus10/qik"
+repository = "https://github.com/Opus10/qik"
+documentation = "https://qik.readthedocs.io"
+
+[tool.poetry.scripts]
+qik = "qik.cli:main"
+
+[tool.poetry.dependencies]
+python = ">=3.10.0,<4"
+msgspec = ">=0.18.6"
+xxhash = ">=3.4.1"
+typing-extensions = ">=4.11.0"
+rich = { version = ">=13" }
+watchdog = { version = ">=4", optional = true }
+grimp = { version = ">=3.4.1", optional = true }
+rustworkx = { version = ">=0.15.1", optional = true }
+boto3 = { version = ">=1", optional = true }
+
+[tool.poetry.extras]
+watch = ["watchdog"]
+graph = ["grimp", "rustworkx"]
+dev = ["watchdog", "grimp", "rustworkx"]
+s3 = ["boto3"]
+
+[tool.poetry.dev-dependencies]
+git-tidy = "1.2.0"
+pytest = "7.4.2"
+pytest-cov = "4.1.0"
+pytest-dotenv = "0.5.2"
+tox = "4.11.3"
+ruff = "0.3.7"
+pyright = "1.1.360"
+mkdocs = "1.5.3"
+black = "24.4.0"
+mkdocs-material = "9.5.18"
+mkdocstrings-python = "1.9.2"
+footing = "*"
+setuptools = "*"
+poetry-core = "*"
+pytest-mock = "3.14.0"
+
+[tool.pytest.ini_options]
+xfail_strict = true
+testpaths = ["qik/tests"]
+norecursedirs = ".venv"
+
+[tool.ruff]
+lint.select = ["E", "F", "B", "I", "G", "C4"]
+lint.ignore = ["E501"]
+line-length = 99
+target-version = "py310"
+
+[tool.pyright]
+exclude = [
+    "**/node_modules",
+    "**/__pycache__",
+    "src/experimental",
+    "src/typestubs",
+    "**/migrations/**",
+    "**/tests/**",
+]
+pythonVersion = "3.10"
+typeCheckingMode = "standard"

qik-0.0.1/qik/__init__.py

@@ -0,0 +1,3 @@
+from qik.version import __version__
+
+__all__ = ["__version__"]

qik-0.0.1/qik/arch.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import platform
+from typing import TYPE_CHECKING, Literal, TypeAlias
+
+if TYPE_CHECKING:
+    ArchType: TypeAlias = Literal[
+        "win-64",
+        "win-32",
+        "linux-64",
+        "linux-aarch64",
+        "linux-ppc64le",
+        "linux-32",
+        "osx-arm64",
+        "osx-64",
+    ]
+
+
+def get() -> ArchType:
+    """Get the architecture of a machine."""
+    system = platform.system()
+    arch = platform.architecture()[0]
+    machine = platform.machine()
+
+    if system == "Windows":
+        return "win-64" if arch == "64bit" else "win-32"
+    elif system == "Linux":
+        if machine == "x86_64":
+            return "linux-64"
+        elif machine == "aarch64":
+            return "linux-aarch64"
+        elif machine == "ppc64le":
+            return "linux-ppc64le"
+        elif arch == "32bit":
+            return "linux-32"
+    elif system == "Darwin":
+        if arch == "64bit":
+            return "osx-arm64" if machine == "arm64" else "osx-64"
+
+    return "unknown"