hydrust 0.5.0__py3-none-win_amd64.whl

hydrust/__init__.py

@@ -0,0 +1,81 @@
+"""Locate the `hydrust` executable installed alongside this package."""
+
+from __future__ import annotations
+
+import os
+import sys
+import sysconfig
+
+__all__ = ["find_hydrust_bin"]
+
+
+def find_hydrust_bin() -> str:
+    """Return the path to the `hydrust` binary installed with this package."""
+
+    hydrust_exe = "hydrust" + sysconfig.get_config_var("EXE")
+
+    # The scripts directory of the environment this package is installed into.
+    scripts_path = os.path.join(sysconfig.get_path("scripts"), hydrust_exe)
+    if os.path.isfile(scripts_path):
+        return scripts_path
+
+    # A `pip install --user` install.
+    if sys.version_info >= (3, 10):
+        user_scheme = sysconfig.get_preferred_scheme("user")
+    elif os.name == "nt":
+        user_scheme = "nt_user"
+    elif sys.platform == "darwin" and getattr(sys, "_framework", ""):
+        user_scheme = "osx_framework_user"
+    else:
+        user_scheme = "posix_user"
+
+    user_path = os.path.join(
+        sysconfig.get_path("scripts", scheme=user_scheme), hydrust_exe
+    )
+    if os.path.isfile(user_path):
+        return user_path
+
+    # A `pip install --target` install, where the scripts land in `bin/` next
+    # to the package directory.
+    pkg_root = os.path.dirname(os.path.dirname(__file__))
+    target_path = os.path.join(pkg_root, "bin", hydrust_exe)
+    if os.path.isfile(target_path):
+        return target_path
+
+    # An isolated build environment created by pip, e.g. when `hydrust` is a
+    # build requirement. pip puts `<tmp>/pip-build-env-<rand>/overlay/bin` and
+    # `<tmp>/pip-build-env-<rand>/normal/bin` at the front of PATH, and the
+    # binary lives in the first. See:
+    # https://github.com/pypa/pip/blob/102d8187a1f5a4cd5de7a549fd8a9af34e89a54f/src/pip/_internal/build_env.py#L87
+    paths = os.environ.get("PATH", "").split(os.pathsep)
+    if len(paths) >= 2:
+
+        def get_last_three_path_parts(path: str) -> list[str]:
+            """Return a list of up to the last three parts of a path."""
+            parts = []
+            while len(parts) < 3:
+                head, tail = os.path.split(path)
+                if tail or head != path:
+                    parts.append(tail)
+                    path = head
+                else:
+                    parts.append(path)
+                    break
+            return parts
+
+        maybe_overlay = get_last_three_path_parts(paths[0])
+        maybe_normal = get_last_three_path_parts(paths[1])
+        if (
+            len(maybe_normal) >= 3
+            and maybe_normal[-1].startswith("pip-build-env-")
+            and maybe_normal[-2] == "normal"
+            and len(maybe_overlay) >= 3
+            and maybe_overlay[-1].startswith("pip-build-env-")
+            and maybe_overlay[-2] == "overlay"
+        ):
+            # The overlay must contain the hydrust binary.
+            candidate = os.path.join(paths[0], hydrust_exe)
+            if os.path.isfile(candidate):
+                return candidate
+
+    raise FileNotFoundError(scripts_path)

hydrust/__main__.py

@@ -0,0 +1,18 @@
+"""Run `hydrust` as `python -m hydrust`."""
+
+import os
+import sys
+
+from hydrust import find_hydrust_bin
+
+if __name__ == "__main__":
+    hydrust = os.fsdecode(find_hydrust_bin())
+    if sys.platform == "win32":
+        import subprocess
+
+        # `execvp` on Windows spawns a child and exits immediately, which
+        # breaks the exit code and interleaves output with the shell prompt.
+        completed_process = subprocess.run([hydrust, *sys.argv[1:]])
+        sys.exit(completed_process.returncode)
+    else:
+        os.execvp(hydrust, [hydrust, *sys.argv[1:]])

hydrust-0.5.0.dist-info/METADATA

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: hydrust
+Version: 0.5.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Software Development :: Quality Assurance
+License-File: LICENSE
+Summary: Language server and CLI checker for Hydra configuration files
+Keywords: hydra,yaml,lsp,language-server,linter
+Author: Matthew Lyon
+License-Expression: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Changelog, https://github.com/m-lyon/hydra-lsp/blob/main/CHANGELOG.md
+Project-URL: Repository, https://github.com/m-lyon/hydra-lsp
+
+# Hydrust
+
+A Language Server for [Hydra](https://hydra.cc/) configuration files, written in Rust.
+
+## Features
+
+### Currently Implemented
+
+- ✅ **YAML Parsing**: Extracts `_target_` references and their parameters
+- ✅ **Hover Support**: Shows rich information when hovering over `_target_` values:
+  - Function signatures with parameter details
+  - Class information and docstrings
+  - Type annotations
+- ✅ **Go to Definition**: Jump from YAML `_target_` to Python source file
+- ✅ **Diagnostics**: Parameter validation including:
+  - Unknown parameters (unless `**kwargs` present)
+  - Missing required parameters
+  - Basic `_target_` format validation
+- ✅ **Semantic Tokens**: Rich syntax highlighting for Hydra configurations:
+  - Module path components (namespace tokens)
+  - Class and function names
+  - Parameter keys (parameter tokens)
+  - Values (string, number, and property tokens)
+- ✅ **Signature Help**: Shows parameter information while typing function arguments
+
+### Planned Features
+
+For a list of planned features and enhancements, see the [issues](https://github.com/m-lyon/hydra-lsp/issues) page.
+
+## Installation
+
+You can install `hydrust` through PyPI:
+
+```bash
+uv tool install hydrust   # or: pixi global install hydrust, pip install hydrust
+uvx hydrust check conf/   # run once without installing
+```
+
+## Usage
+
+`hydrust` provides the `check` subcommand for one-time CLI and CI invocations, as well as an LSP for hydra diagnostics over stdin/stdout:
+
+```bash
+hydrust check conf/   # diagnose configs on the command line
+hydrust server        # LSP
+```
+
+### `hydrust check`
+
+```bash
+# Check a single file
+hydrust check config.yaml
+
+# Check several files, or a whole directory tree
+hydrust check config.yaml overrides.yaml
+hydrust check conf/
+
+# Specify workspace root for local module resolution
+hydrust check config.yaml -w /path/to/project
+
+# Specify Python interpreter for site-packages resolution
+hydrust check config.yaml -p /path/to/venv/bin/python
+
+# Enable detailed resolution tracing for debugging
+hydrust check config.yaml --trace-resolution
+
+# Change verbosity level (error, warn, info, debug, trace)
+hydrust check config.yaml -v debug
+
+# Output in different formats (pretty, json, compact, github)
+hydrust check config.yaml -f json
+```
+
+Directories are searched recursively for `.yaml` and `.yml` files. The walk honours `.gitignore` and `.ignore` files within the directory being walked, and skips hidden files and directories such as `.github/`. Symlinks are followed.
+
+#### Options
+
+| Option | Description |
+|--------|-------------|
+| `-w, --workspace <PATH>` | Working directory for resolving Python modules |
+| `-p, --python <PATH>` | Path to Python interpreter for module resolution |
+| `-v, --verbosity <LEVEL>` | Logging verbosity: error, warn, info, debug, trace |
+| `-f, --output-format <FORMAT>` | Output format: pretty (default), json, compact, github |
+| `--trace-resolution` | Show detailed resolution steps for each target (written to stderr) |
+| `--disable-rule <RULE>` | Disable a diagnostic rule; may be repeated |
+
+When `--workspace` is omitted, `hydrust` resolves Python modules against the current directory.
+
+#### Continuous integration
+
+`--output-format github` emits GitHub Actions workflow commands, so
+diagnostics appear as inline annotations on the pull request. A complete
+workflow, run with `uvx` so nothing needs installing beyond uv itself:
+
+```yaml
+name: Hydra configs
+
+on: [push, pull_request]
+
+jobs:
+  hydrust:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v10.2.0
+      - run: uvx hydrust@0.5.0 check --output-format github .
+```
+
+`_target_` resolution needs the Python packages your configs point at. If they
+are not in the checked-out tree, install the project first and point `hydrust`
+at that interpreter with `--python`:
+
+```yaml
+      - run: uv sync
+      - run: uvx hydrust@0.5.0 check --output-format github --python .venv/bin/python conf/
+```
+
+#### Exit Codes
+
+- `0`: No errors found
+- `1`: One or more errors found
+- `2`: Fatal error (path not found, invalid arguments, etc.)
+
+Finding nothing to check is not an error: whether no YAML files matched at all
+or none of the ones found are Hydra configs, `hydrust check` warns on stderr and
+exits `0`.
+
+## `hydrust server`
+
+### Client Compatibility
+
+A client can be pointed at any released server binary, and an old server quietly
+ignores settings it was never taught to read. So the server describes itself in
+`capabilities.experimental.hydrust` at `initialize` (`HydrustCapabilities::new`
+in [src/backend.rs](src/backend.rs)):
+
+- `protocolVersion` — the version of this block's shape.
+- `supportedSettings` — keys read from `initializationOptions.settings`.
+- `supportedRules` — codes accepted in `disabledRules`.
+- `features` — optional behaviours switched on *for this session*, after matching
+  what the server can do against what the client asked for.
+
+A client that sees the block uses it instead of any built-in table; servers
+before v0.4.0 send no block, so clients fall back to a version table keyed on
+`serverInfo.version` or `--version`. The reference client is the VS Code
+extension ([hydra-lsp-vscode](https://github.com/m-lyon/hydra-lsp-vscode)), in
+`src/common/compatTable.ts`.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Built with [tower-lsp](https://github.com/ebkalderon/tower-lsp) framework
+- Python analysis design based on [ruff](https://github.com/astral-sh/ruff) and [ty](https://github.com/astral-sh/ty)
+
+## References
+
+- [Language Server Protocol Specification](https://microsoft.github.io/language-server-protocol/)
+- [Hydra Documentation](https://hydra.cc/docs/intro/)
+- [Tower-LSP Documentation](https://docs.rs/tower-lsp/)
+

hydrust-0.5.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+hydrust/__init__.py,sha256=8Xu_M6_VjOSZHOoYTQraetcTMxTLJPSNc5cSa88JCwk,3075
+hydrust/__main__.py,sha256=5eEUoWryFQw5eBLdz54FVk5sDQ8LFib-43tjjhf3QgM,585
+hydrust/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hydrust-0.5.0.data/scripts/hydrust.exe,sha256=BGU_OTfgEmbC7unUG23ViQca3nT7ZJ_MUQDqBqKLPEA,19102720
+hydrust-0.5.0.dist-info/METADATA,sha256=ZZy-RiaRRt48pwOwRVJxoF1pHRvB5zVdKTCozz0Srug,6848
+hydrust-0.5.0.dist-info/WHEEL,sha256=8Aej0W0a6Cz6apA3IzJrTnxLRVLAt-w0Oh8SA3Con_c,94
+hydrust-0.5.0.dist-info/licenses/LICENSE,sha256=VAkE3wmVj-ViM_5N4pBBtmZjpw7vYTaNCDYq2fezuNk,1090
+hydrust-0.5.0.dist-info/sboms/hydrust.cyclonedx.json,sha256=CnnS0FE84odLARb20P_K3xqBmFWRiq2HsG547fWqc1A,313733
+hydrust-0.5.0.dist-info/RECORD,,

hydrust-0.5.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.15.0)
+Root-Is-Purelib: false
+Tag: py3-none-win_amd64

hydrust-0.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Matthew Lyon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.