kernels 0.1.7__py3-none-any.whl

kernels/__init__.py

@@ -0,0 +1,3 @@
+from kernels.utils import get_kernel, install_kernel, load_kernel, get_locked_kernel
+
+__all__ = ["get_kernel", "get_locked_kernel", "load_kernel", "install_kernel"]

kernels/build.py

@@ -0,0 +1,144 @@
+"""
+Python shims for the PEP 517 and PEP 660 build backend.
+
+Major imports in this module are required to be lazy:
+```
+$ hyperfine \
+     "/usr/bin/python3 -c \"print('hi')\"" \
+     "/usr/bin/python3 -c \"from subprocess import check_call; print('hi')\""
+Base: Time (mean ± σ):      11.0 ms ±   1.7 ms    [User: 8.5 ms, System: 2.5 ms]
+With import: Time (mean ± σ):      15.2 ms ±   2.0 ms    [User: 12.3 ms, System: 2.9 ms]
+Base 1.38 ± 0.28 times faster than with import
+```
+
+The same thing goes for the typing module, so we use Python 3.10 type annotations that
+don't require importing typing but then quote them so earlier Python version ignore
+them while IDEs and type checker can see through the quotes.
+"""
+
+from kernels.compat import tomllib
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence  # noqa:I001
+    from typing import Any  # noqa:I001
+
+
+def warn_config_settings(config_settings: "Mapping[Any, Any] | None" = None) -> None:
+    import sys
+
+    if config_settings:
+        print("Warning: Config settings are not supported", file=sys.stderr)
+
+
+def call(
+    args: "Sequence[str]", config_settings: "Mapping[Any, Any] | None" = None
+) -> str:
+    """Invoke a uv subprocess and return the filename from stdout."""
+    import shutil
+    import subprocess
+    import sys
+
+    warn_config_settings(config_settings)
+    # Unlike `find_uv_bin`, this mechanism must work according to PEP 517
+    import os
+
+    cwd = os.getcwd()
+    filename = os.path.join(cwd, "pyproject.toml")
+    with open(filename, "rb") as f:
+        data = tomllib.load(f)
+
+    for kernel, _ in (
+        data.get("tool", {}).get("kernels", {}).get("dependencies", {}).items()
+    ):
+        from kernels.utils import install_kernel
+
+        install_kernel(kernel, revision="main")
+    uv_bin = shutil.which("uv")
+    if uv_bin is None:
+        raise RuntimeError("uv was not properly installed")
+    # Forward stderr, capture stdout for the filename
+    result = subprocess.run([uv_bin, *args], stdout=subprocess.PIPE)
+    if result.returncode != 0:
+        sys.exit(result.returncode)
+    # If there was extra stdout, forward it (there should not be extra stdout)
+    stdout = result.stdout.decode("utf-8").strip().splitlines(keepends=True)
+    sys.stdout.writelines(stdout[:-1])
+    # Fail explicitly instead of an irrelevant stacktrace
+    if not stdout:
+        print("uv subprocess did not return a filename on stdout", file=sys.stderr)
+        sys.exit(1)
+    return stdout[-1].strip()
+
+
+def build_sdist(
+    sdist_directory: str, config_settings: "Mapping[Any, Any] | None" = None
+) -> str:
+    """PEP 517 hook `build_sdist`."""
+    args = ["build-backend", "build-sdist", sdist_directory]
+    return call(args, config_settings)
+
+
+def build_wheel(
+    wheel_directory: str,
+    config_settings: "Mapping[Any, Any] | None" = None,
+    metadata_directory: "str | None" = None,
+) -> str:
+    """PEP 517 hook `build_wheel`."""
+    args = ["build-backend", "build-wheel", wheel_directory]
+    if metadata_directory:
+        args.extend(["--metadata-directory", metadata_directory])
+    return call(args, config_settings)
+
+
+def get_requires_for_build_sdist(
+    config_settings: "Mapping[Any, Any] | None" = None,
+) -> "Sequence[str]":
+    """PEP 517 hook `get_requires_for_build_sdist`."""
+    warn_config_settings(config_settings)
+    return []
+
+
+def get_requires_for_build_wheel(
+    config_settings: "Mapping[Any, Any] | None" = None,
+) -> "Sequence[str]":
+    """PEP 517 hook `get_requires_for_build_wheel`."""
+    warn_config_settings(config_settings)
+    return []
+
+
+def prepare_metadata_for_build_wheel(
+    metadata_directory: str, config_settings: "Mapping[Any, Any] | None" = None
+) -> str:
+    """PEP 517 hook `prepare_metadata_for_build_wheel`."""
+    args = ["build-backend", "prepare-metadata-for-build-wheel", metadata_directory]
+    return call(args, config_settings)
+
+
+def build_editable(
+    wheel_directory: str,
+    config_settings: "Mapping[Any, Any] | None" = None,
+    metadata_directory: "str | None" = None,
+) -> str:
+    """PEP 660 hook `build_editable`."""
+    args = ["build-backend", "build-editable", wheel_directory]
+
+    if metadata_directory:
+        args.extend(["--metadata-directory", metadata_directory])
+    return call(args, config_settings)
+
+
+def get_requires_for_build_editable(
+    config_settings: "Mapping[Any, Any] | None" = None,
+) -> "Sequence[str]":
+    """PEP 660 hook `get_requires_for_build_editable`."""
+    warn_config_settings(config_settings)
+    return []
+
+
+def prepare_metadata_for_build_editable(
+    metadata_directory: str, config_settings: "Mapping[Any, Any] | None" = None
+) -> str:
+    """PEP 660 hook `prepare_metadata_for_build_editable`."""
+    args = ["build-backend", "prepare-metadata-for-build-editable", metadata_directory]
+    return call(args, config_settings)

kernels/cli.py

@@ -0,0 +1,98 @@
+import argparse
+import dataclasses
+import json
+import sys
+from pathlib import Path
+
+from kernels.compat import tomllib
+from kernels.lockfile import KernelLock, get_kernel_locks
+from kernels.utils import build_variant, install_kernel, install_kernel_all_variants
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="kernel", description="Manage compute kernels"
+    )
+    subparsers = parser.add_subparsers(required=True)
+
+    download_parser = subparsers.add_parser("download", help="Download locked kernels")
+    download_parser.add_argument(
+        "project_dir",
+        type=Path,
+        help="The project directory",
+    )
+    download_parser.add_argument(
+        "--all-variants",
+        action="store_true",
+        help="Download all build variants of the kernel",
+    )
+    download_parser.set_defaults(func=download_kernels)
+
+    lock_parser = subparsers.add_parser("lock", help="Lock kernel revisions")
+    lock_parser.add_argument(
+        "project_dir",
+        type=Path,
+        help="The project directory",
+    )
+    lock_parser.set_defaults(func=lock_kernels)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+def download_kernels(args):
+    lock_path = args.project_dir / "kernels.lock"
+
+    if not lock_path.exists():
+        print(f"No kernels.lock file found in: {args.project_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    with open(args.project_dir / "kernels.lock", "r") as f:
+        lock_json = json.load(f)
+
+    all_successful = True
+
+    for kernel_lock_json in lock_json:
+        kernel_lock = KernelLock.from_json(kernel_lock_json)
+        print(
+            f"Downloading `{kernel_lock.repo_id}` at with SHA: {kernel_lock.sha}",
+            file=sys.stderr,
+        )
+        if args.all_variants:
+            install_kernel_all_variants(
+                kernel_lock.repo_id, kernel_lock.sha, variant_locks=kernel_lock.variants
+            )
+        else:
+            try:
+                install_kernel(
+                    kernel_lock.repo_id,
+                    kernel_lock.sha,
+                    variant_lock=kernel_lock.variants[build_variant()],
+                )
+            except FileNotFoundError as e:
+                print(e, file=sys.stderr)
+                all_successful = False
+
+    if not all_successful:
+        sys.exit(1)
+
+
+def lock_kernels(args):
+    with open(args.project_dir / "pyproject.toml", "rb") as f:
+        data = tomllib.load(f)
+
+    kernel_versions = data.get("tool", {}).get("kernels", {}).get("dependencies", None)
+
+    all_locks = []
+    for kernel, version in kernel_versions.items():
+        all_locks.append(get_kernel_locks(kernel, version))
+
+    with open(args.project_dir / "kernels.lock", "w") as f:
+        json.dump(all_locks, f, cls=_JSONEncoder, indent=2)
+
+
+class _JSONEncoder(json.JSONEncoder):
+    def default(self, o):
+        if dataclasses.is_dataclass(o):
+            return dataclasses.asdict(o)
+        return super().default(o)

kernels/compat.py

@@ -0,0 +1,8 @@
+import sys
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+__all__ = ["tomllib"]

kernels/lockfile.py

@@ -0,0 +1,134 @@
+from dataclasses import dataclass
+import hashlib
+from pathlib import Path
+from typing import Dict
+
+from huggingface_hub import HfApi
+from packaging.specifiers import SpecifierSet
+from packaging.version import InvalidVersion, Version
+
+from kernels.compat import tomllib
+
+
+@dataclass
+class VariantLock:
+    hash: str
+    hash_type: str = "git_lfs_concat"
+
+
+@dataclass
+class KernelLock:
+    repo_id: str
+    sha: str
+    variants: Dict[str, VariantLock]
+
+    @classmethod
+    def from_json(cls, o: Dict):
+        variants = {
+            variant: VariantLock(**lock) for variant, lock in o["variants"].items()
+        }
+        return cls(repo_id=o["repo_id"], sha=o["sha"], variants=variants)
+
+
+def _get_available_versions(repo_id: str):
+    """Get kernel versions that are available in the repository."""
+    versions = {}
+    for tag in HfApi().list_repo_refs(repo_id).tags:
+        if not tag.name.startswith("v"):
+            continue
+        try:
+            versions[Version(tag.name[1:])] = tag
+        except InvalidVersion:
+            continue
+
+    return versions
+
+
+def get_kernel_locks(repo_id: str, version_spec: str):
+    """
+    Get the locks for a kernel with the given version spec.
+
+    The version specifier can be any valid Python version specifier:
+    https://packaging.python.org/en/latest/specifications/version-specifiers/#version-specifiers
+    """
+    versions = _get_available_versions(repo_id)
+    requirement = SpecifierSet(version_spec)
+    accepted_versions = sorted(requirement.filter(versions.keys()))
+
+    if len(accepted_versions) == 0:
+        raise ValueError(
+            f"No version of `{repo_id}` satisfies requirement: {version_spec}"
+        )
+
+    tag_for_newest = versions[accepted_versions[-1]]
+
+    r = HfApi().repo_info(
+        repo_id=repo_id, revision=tag_for_newest.target_commit, files_metadata=True
+    )
+    if r.sha is None:
+        raise ValueError(
+            f"Cannot get commit SHA for repo {repo_id} for tag {tag_for_newest.name}"
+        )
+
+    if r.siblings is None:
+        raise ValueError(
+            f"Cannot get sibling information for {repo_id} for tag {tag_for_newest.name}"
+        )
+
+    variant_files = {}
+    for sibling in r.siblings:
+        if sibling.rfilename.startswith("build/torch"):
+            if sibling.blob_id is None:
+                raise ValueError(f"Cannot get blob ID for {sibling.rfilename}")
+
+            path = Path(sibling.rfilename)
+            variant = path.parts[1]
+            filename = Path(*path.parts[2:])
+
+            hash = sibling.lfs.sha256 if sibling.lfs is not None else sibling.blob_id
+
+            files = variant_files.setdefault(variant, [])
+
+            # Encode as posix for consistent slash handling, then encode
+            # as utf-8 for byte-wise sorting later.
+            files.append((filename.as_posix().encode("utf-8"), hash))
+
+    variant_locks = {}
+    for variant, files in variant_files.items():
+        m = hashlib.sha256()
+        for filename, hash in sorted(files):
+            # Filename as bytes.
+            m.update(filename)
+            # Git blob or LFS file hash as bytes.
+            m.update(bytes.fromhex(hash))
+
+        variant_locks[variant] = VariantLock(hash=f"sha256-{m.hexdigest()}")
+
+    return KernelLock(repo_id=repo_id, sha=r.sha, variants=variant_locks)
+
+
+def write_egg_lockfile(cmd, basename, filename):
+    import logging
+
+    cwd = Path.cwd()
+    pyproject_path = cwd / "pyproject.toml"
+    if not pyproject_path.exists():
+        # Nothing to do if the project doesn't have pyproject.toml.
+        return
+
+    with open(pyproject_path, "rb") as f:
+        data = tomllib.load(f)
+
+    kernel_versions = data.get("tool", {}).get("kernels", {}).get("dependencies", None)
+    if kernel_versions is None:
+        return
+
+    lock_path = cwd / "kernels.lock"
+    if not lock_path.exists():
+        logging.warning(f"Lock file {lock_path} does not exist")
+        # Ensure that the file gets deleted in editable installs.
+        data = None
+    else:
+        data = open(lock_path, "r").read()
+
+    cmd.write_or_delete_file(basename, filename, data)

kernels/utils.py

@@ -0,0 +1,264 @@
+import ctypes
+import hashlib
+import importlib
+import importlib.metadata
+import inspect
+import json
+import os
+from pathlib import Path
+import platform
+import sys
+from importlib.metadata import Distribution
+from types import ModuleType
+from typing import Dict, List, Optional, Tuple
+
+from huggingface_hub import hf_hub_download, snapshot_download
+from packaging.version import parse
+
+from kernels.compat import tomllib
+from kernels.lockfile import KernelLock, VariantLock
+
+CACHE_DIR: Optional[str] = os.environ.get("HF_KERNELS_CACHE", None)
+
+
+def build_variant():
+    import torch
+
+    if torch.version.cuda is None:
+        raise AssertionError(
+            "This kernel requires CUDA to be installed. Torch was not compiled with CUDA enabled."
+        )
+
+    torch_version = parse(torch.__version__)
+    cuda_version = parse(torch.version.cuda)
+    cxxabi = "cxx11" if torch.compiled_with_cxx11_abi() else "cxx98"
+    cpu = platform.machine()
+    os = platform.system().lower()
+
+    return f"torch{torch_version.major}{torch_version.minor}-{cxxabi}-cu{cuda_version.major}{cuda_version.minor}-{cpu}-{os}"
+
+
+def import_from_path(module_name: str, file_path):
+    # We cannot use the module name as-is, after adding it to `sys.modules`,
+    # it would also be used for other imports. So, we make a module name that
+    # depends on the path for it to be unique using the hex-encoded hash of
+    # the path.
+    path_hash = "{:x}".format(ctypes.c_size_t(hash(file_path)).value)
+    module_name = f"{module_name}_{path_hash}"
+    spec = importlib.util.spec_from_file_location(module_name, file_path)
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def install_kernel(
+    repo_id: str,
+    revision: str,
+    local_files_only: bool = False,
+    variant_lock: Optional[VariantLock] = None,
+) -> Tuple[str, str]:
+    """
+    Download a kernel for the current environment to the cache.
+
+    The output path is validated againt `hash` when set.
+    """
+    package_name = repo_id.split("/")[-1]
+    package_name = package_name.replace("-", "_")
+    variant = build_variant()
+    repo_path = snapshot_download(
+        repo_id,
+        allow_patterns=f"build/{variant}/*",
+        cache_dir=CACHE_DIR,
+        revision=revision,
+        local_files_only=local_files_only,
+    )
+
+    if variant_lock is not None:
+        validate_kernel(repo_path=repo_path, variant=variant, hash=variant_lock.hash)
+
+    variant_path = f"{repo_path}/build/{variant}"
+    module_init_path = f"{variant_path}/{package_name}/__init__.py"
+
+    if not os.path.exists(module_init_path):
+        raise FileNotFoundError(
+            f"Kernel `{repo_id}` at revision {revision} does not have build: {variant}"
+        )
+
+    return package_name, variant_path
+
+
+def install_kernel_all_variants(
+    repo_id: str,
+    revision: str,
+    local_files_only: bool = False,
+    variant_locks: Optional[Dict[str, VariantLock]] = None,
+) -> str:
+    repo_path = Path(
+        snapshot_download(
+            repo_id,
+            allow_patterns="build/*",
+            cache_dir=CACHE_DIR,
+            revision=revision,
+            local_files_only=local_files_only,
+        )
+    )
+
+    if variant_locks is not None:
+        for entry in (repo_path / "build").iterdir():
+            variant = entry.parts[-1]
+
+            variant_lock = variant_locks.get(variant)
+            if variant_lock is None:
+                raise ValueError(f"No lock found for build variant: {variant}")
+
+            validate_kernel(
+                repo_path=repo_path, variant=variant, hash=variant_lock.hash
+            )
+
+    return f"{repo_path}/build"
+
+
+def get_metadata(repo_id: str, revision: str, local_files_only: bool = False):
+    with open(
+        hf_hub_download(
+            repo_id,
+            "build.toml",
+            cache_dir=CACHE_DIR,
+            revision=revision,
+            local_files_only=local_files_only,
+        ),
+        "rb",
+    ) as f:
+        return tomllib.load(f)
+
+
+def get_kernel(repo_id: str, revision: str = "main"):
+    package_name, package_path = install_kernel(repo_id, revision=revision)
+    return import_from_path(package_name, f"{package_path}/{package_name}/__init__.py")
+
+
+def load_kernel(repo_id: str):
+    """Get a pre-downloaded, locked kernel."""
+    locked_sha = _get_caller_locked_kernel(repo_id)
+
+    if locked_sha is None:
+        raise ValueError(f"Kernel `{repo_id}` is not locked")
+
+    filename = hf_hub_download(
+        repo_id,
+        "build.toml",
+        cache_dir=CACHE_DIR,
+        local_files_only=True,
+        revision=locked_sha,
+    )
+    with open(filename, "rb") as f:
+        metadata = tomllib.load(f)
+    package_name = metadata["torch"]["name"]
+
+    repo_path = os.path.dirname(filename)
+    package_path = f"{repo_path}/build/{build_variant()}"
+    return import_from_path(package_name, f"{package_path}/{package_name}/__init__.py")
+
+
+def get_locked_kernel(repo_id: str, local_files_only: bool = False):
+    """Get a kernel using a lock file."""
+    locked_sha = _get_caller_locked_kernel(repo_id)
+
+    if locked_sha is None:
+        raise ValueError(f"Kernel `{repo_id}` is not locked")
+
+    package_name, package_path = install_kernel(
+        repo_id, locked_sha, local_files_only=local_files_only
+    )
+
+    return import_from_path(package_name, f"{package_path}/{package_name}/__init__.py")
+
+
+def _get_caller_locked_kernel(repo_id: str) -> Optional[str]:
+    for dist in _get_caller_distributions():
+        lock_json = dist.read_text("kernels.lock")
+        if lock_json is not None:
+            for kernel_lock_json in json.loads(lock_json):
+                kernel_lock = KernelLock.from_json(kernel_lock_json)
+                if kernel_lock.repo_id == repo_id:
+                    return kernel_lock.sha
+    return None
+
+
+def _get_caller_distributions() -> List[Distribution]:
+    module = _get_caller_module()
+    if module is None:
+        return []
+
+    # Look up all possible distributions that this module could be from.
+    package = module.__name__.split(".")[0]
+    dist_names = importlib.metadata.packages_distributions().get(package)
+    if dist_names is None:
+        return []
+
+    return [importlib.metadata.distribution(dist_name) for dist_name in dist_names]
+
+
+def _get_caller_module() -> Optional[ModuleType]:
+    stack = inspect.stack()
+    # Get first module in the stack that is not the current module.
+    first_module = inspect.getmodule(stack[0][0])
+    for frame in stack[1:]:
+        module = inspect.getmodule(frame[0])
+        if module is not None and module != first_module:
+            return module
+    return first_module
+
+
+def validate_kernel(*, repo_path: str, variant: str, hash: str):
+    """Validate the given build variant of a kernel against a hasht."""
+    variant_path = Path(repo_path) / "build" / variant
+
+    # Get the file paths. The first element is a byte-encoded relative path
+    # used for sorting. The second element is the absolute path.
+    files: List[Tuple[bytes, Path]] = []
+    # Ideally we'd use Path.walk, but it's only available in Python 3.12.
+    for dirpath, _, filenames in os.walk(variant_path):
+        for filename in filenames:
+            file_abs = Path(dirpath) / filename
+
+            # Python likes to create files when importing modules from the
+            # cache, only hash files that are symlinked blobs.
+            if file_abs.is_symlink():
+                files.append(
+                    (
+                        file_abs.relative_to(variant_path).as_posix().encode("utf-8"),
+                        file_abs,
+                    )
+                )
+
+    m = hashlib.sha256()
+
+    for filename, full_path in sorted(files):
+        m.update(filename)
+
+        blob_filename = full_path.resolve().name
+        if len(blob_filename) == 40:
+            # SHA-1 hashed, so a Git blob.
+            m.update(git_hash_object(full_path.read_bytes()))
+        elif len(blob_filename) == 64:
+            # SHA-256 hashed, so a Git LFS blob.
+            m.update(hashlib.sha256(full_path.read_bytes()).digest())
+        else:
+            raise ValueError(f"Unexpected blob filename length: {len(blob_filename)}")
+
+    computedHash = f"sha256-{m.hexdigest()}"
+    if computedHash != hash:
+        raise ValueError(
+            f"Lock file specifies kernel with hash {hash}, but downloaded kernel has hash: {computedHash}"
+        )
+
+
+def git_hash_object(data: bytes, object_type: str = "blob"):
+    """Calculate git SHA1 of data."""
+    header = f"{object_type} {len(data)}\0".encode()
+    m = hashlib.sha1()
+    m.update(header)
+    m.update(data)
+    return m.digest()

kernels-0.1.7.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.2
+Name: kernels
+Version: 0.1.7
+Summary: Download cuda kernels
+Author-email: OlivierDehaene <olivier@huggingface.co>, Daniel de Kok <daniel@huggingface.co>, David Holtz <david@huggingface.co>, Nicolas Patry <nicolas@huggingface.co>
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: huggingface-hub>=0.26.3
+Requires-Dist: packaging>=24.2
+Requires-Dist: tomli>=2.0.1; python_version < "3.11"
+Requires-Dist: torch>=2.4
+
+# kernels
+
+The Kernel Hub allows Python libraries and applications to load compute
+kernels directly from the [Hub](https://hf.co/). To support this kind
+of dynamic loading, Hub kernels differ from traditional Python kernel
+packages in that they are made to be:
+
+- Portable: a kernel can be loaded from paths outside `PYTHONPATH`.
+- Unique: multiple versions of the same kernel can be loaded in the
+  same Python process.
+- Compatible: kernels must support all recent versions of Python and
+  the different PyTorch build configurations (various CUDA versions
+  and C++ ABIs). Furthermore, older C library versions must be supported.
+
+## Usage
+
+Kernels depends on `torch>=2.5` and CUDA for now. 
+
+Here is how you would use the [activation](https://huggingface.co/kernels-community/activation) kernels from the Hugging Face Hub:
+
+```python
+import torch
+
+from kernels import get_kernel
+
+# Download optimized kernels from the Hugging Face hub
+activation = get_kernel("kernels-community/activation")
+
+# Random tensor
+x = torch.randn((10, 10), dtype=torch.float16, device="cuda")
+
+# Run the kernel
+y = torch.empty_like(x)
+activation.gelu_fast(y, x)
+
+print(y)
+```
+
+These kernels can be built from the [kernel-builder library](https://github.com/huggingface/kernel-builder). 
+
+If you're looking to better understand how these kernels are structured, or looking to build your own kernels, 
+please take a look at the following guide: 
+[writing kernels](https://github.com/huggingface/kernel-builder/blob/main/docs/writing-kernels.md).
+
+## Installation
+
+To install `kernels`, we recommend installing from the pypi package:
+
+```bash
+pip install kernels
+```
+
+You should then be able to run the script above (also in [examples/basic.py](examples/basic.py)):
+```bash
+python examples/basic.py
+```
+
+## Docker Reference
+
+build and run the reference [examples/basic.py](examples/basic.py) in a Docker container with the following commands:
+
+```bash
+docker build --platform linux/amd64 -t kernels-reference -f docker/Dockerfile.reference .
+docker run --gpus all -it --rm -e HF_TOKEN=$HF_TOKEN kernels-reference
+```
+
+## Locking kernel versions
+
+Projects that use `setuptools` can lock the kernel versions that should be
+used. First specify the accepted versions in `pyproject.toml` and make
+sure that `kernels` is a build dependency:
+
+```toml
+[build-system]
+requires = ["kernels", "setuptools"]
+build-backend = "setuptools.build_meta"
+
+[tool.kernels.dependencies]
+"kernels-community/activation" = ">=0.0.1"
+```
+
+Then run `kernel lock .` in the project directory. This generates a `kernels.lock` file with
+the locked revisions. The locked revision will be used when loading a kernel with
+`get_locked_kernel`:
+
+```python
+from kernels import get_locked_kernel
+
+activation = get_locked_kernel("kernels-community/activation")
+```
+
+**Note:** the lock file is included in the package metadata, so it will only be visible
+to `kernels` after doing an (editable or regular) installation of your project.
+
+## Pre-downloading locked kernels
+
+Locked kernels can be pre-downloaded by running `kernel download .` in your
+project directory. This will download the kernels to your local Hugging Face
+Hub cache.
+
+The pre-downloaded kernels are used by the `get_locked_kernel` function.
+`get_locked_kernel` will download a kernel when it is not pre-downloaded. If you
+want kernel loading to error when a kernel is not pre-downloaded, you can use
+the `load_kernel` function instead:
+
+```python
+from kernels import load_kernel
+
+activation = load_kernel("kernels-community/activation")
+```

kernels-0.1.7.dist-info/RECORD

@@ -0,0 +1,11 @@
+kernels/__init__.py,sha256=P6Y2kXOCJWnSMajdiGBREmRx9T0rlSBD8Az4LXWmH_k,165
+kernels/build.py,sha256=_T89LLg1hCP2ypa2b5lB7UGVCZUdLiAv1FhI3PCGyHQ,4867
+kernels/cli.py,sha256=pm1ljPSvJjDV7ItfhjYCG3VaFwuWQaemYMyUqDI9bik,2943
+kernels/compat.py,sha256=1DTrGg6048IV5bJoGkjqerTw9y-Sti2ePbiCbOwoEJU,120
+kernels/lockfile.py,sha256=4BNyUOVFn0e6cV-7NERB0XdAjBbWoHiprIFcbyb6qEQ,4104
+kernels/utils.py,sha256=NfY5Al5yXsrkMwdwEt8g0KWo5-oUj8wOyQUYiA__pTc,8663
+kernels-0.1.7.dist-info/METADATA,sha256=KJc9KXs359NyEaDzv7mf6Km26I0Nj53zqoKGsW2_qpY,4010
+kernels-0.1.7.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+kernels-0.1.7.dist-info/entry_points.txt,sha256=Q0zGqrVqbX7YwPRYkCUF60_3spqgMBI7hOrFN6xmfNg,116
+kernels-0.1.7.dist-info/top_level.txt,sha256=uO_uHWo6VnVSrria-cIfRu733iZI5qs5mwirtAFigww,8
+kernels-0.1.7.dist-info/RECORD,,

kernels-0.1.7.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.8.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

kernels-0.1.7.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+kernels = kernels.cli:main
+
+[egg_info.writers]
+kernels.lock = kernels.lockfile:write_egg_lockfile

kernels-0.1.7.dist-info/top_level.txt

@@ -0,0 +1 @@
+kernels