PyAVD Utilities (Internal)

Common errors

• ERROR: Could not build wheels for pyavd-utils, which is required to install pyproject.toml-based projects

  cause The Rust toolchain (rustup, cargo) is not installed or not in your system's PATH, preventing the Rust source code from compiling into a Python wheel.
  fix Install Rust and Cargo first. On Linux/macOS, use: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh` and then `source "$HOME/.cargo/env"`.

• AttributeError: module 'pyavd_utils' has no attribute 'some_function'

  cause You are attempting to call a function that either does not exist in the current `pyavd-utils` version, has been renamed, or was removed. The API is unstable and changes frequently.
  fix Consult the `pyavd-utils` source code (or the `pyavd` project that consumes it) for the exact function names and signatures for your installed version, or upgrade `pyavd` which may require a specific compatible `pyavd-utils` version.

• TypeError: argument 'data': 'str' object cannot be converted to 'bytes'

  cause A Rust-bound function expects a byte string (e.g., `bytes`) but received a Python string (`str`). This is a common FFI (Foreign Function Interface) type mismatch.
  fix Encode the Python string to bytes before passing it to the function, for example: `my_string.encode('utf-8')`.

Warnings

• breaking This library is NOT intended for direct user consumption. It does not follow semantic versioning, and its API is highly unstable, subject to breaking changes without notice or deprecation cycles. It is compiled against specific `pyavd` versions.
  Fix: Avoid direct usage. If you must use it, pin the exact version and be prepared for frequent breaking changes with `pyavd` updates. Consider using the `pyavd` library directly, which orchestrates these utilities internally.
• gotcha Installation requires a Rust toolchain (rustup, cargo) to be present on your system. If Rust is not installed, `pip install` will fail with compilation errors.
  Fix: Install Rust and Cargo via `rustup` before attempting to install `pyavd-utils`. Refer to rustup.rs for platform-specific instructions or use the provided install command.
• gotcha Functions exposed from Rust often expect byte strings for input (e.g., `bytes` or `&[u8]`) and may return byte strings or Rust-specific types, requiring careful handling for Python compatibility.
  Fix: Ensure inputs are correctly typed (e.g., `my_string.encode('utf-8')` instead of `my_string`) and handle outputs appropriately (e.g., `.decode('utf-8')` if expecting a human-readable string).

Install

• pip install pyavd-utils Install pyavd-utils (Python >=3.10)
• curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh source "$HOME/.cargo/env" pip install pyavd-utils Install Rust Toolchain (if needed) and pyavd-utils

Imports

• str_to_md5

  from pyavd_utils import str_to_md5

  While this import is technically correct, direct usage of pyavd-utils is strongly discouraged due to lack of API stability and semantic versioning. This function (and others) are internal helpers for `pyavd`.

Quickstart

Demonstrates a basic import and usage of an internal utility function. Users are strongly advised against using this library directly due to its unstable API and lack of semantic versioning. The `str_to_md5` function typically expects bytes, hence the `.encode('utf-8')`.

from pyavd_utils import str_to_md5

# WARNING: This library is NOT intended for direct user consumption.
# Its API is unstable and may change without notice, and it does not
# follow semantic versioning. Use at your own risk.

data_string = "Hello, pyavd-utils!"
# Rust-bound functions often expect bytes, not str
md5_hash = str_to_md5(data_string.encode('utf-8'))

print(f"MD5 of '{data_string}': {md5_hash}")