Typing Stubs for JMESPath

Warnings

• gotcha The `types-jmespath` package aims to provide accurate annotations for `jmespath==1.1.*`. Using a `jmespath` version outside this range, or significantly older/newer than the stub version, may lead to incorrect type checking results or errors. It is recommended to keep the stub version aligned with your `jmespath` runtime version.
  Fix: Ensure your installed `jmespath` version is compatible with the `types-jmespath` version (e.g., `jmespath~=1.1.0` and `types-jmespath~=1.1.0`). You can check the stub's target version on PyPI or Typeshed's statistics page.
• gotcha `types-jmespath` is a stub-only package and does not contain any runtime code. Installing it does not provide the `jmespath` functionality; you must install the `jmespath` library separately for your application to run. Its sole purpose is to provide type hints for static analysis by type checkers.
  Fix: Always install the actual `jmespath` library (e.g., `pip install jmespath`) in addition to `types-jmespath` if you intend to use `jmespath` functionality at runtime.
• gotcha Issues or inaccuracies found within the `types-jmespath` annotations should be reported to the `typeshed` GitHub repository, not the `jmespath` project itself. The `typeshed` project is responsible for maintaining these third-party stubs.
  Fix: When contributing fixes or reporting issues, open a pull request or issue directly on the `python/typeshed` GitHub repository.

Install

• pip install types-jmespath Install types-jmespath
• pip install jmespath types-jmespath Install JMESPath and its stubs

Imports

• search

  from jmespath import search

  This stub package provides type annotations for the `jmespath` library. You do not import directly from `types_jmespath`. Instead, you import from `jmespath`, and type checkers will automatically use the installed stubs.

Quickstart

This quickstart demonstrates basic usage of the `jmespath` library. When `types-jmespath` is installed alongside `jmespath`, type checkers will use the provided stubs to validate the type correctness of your `jmespath` operations without altering runtime behavior.

import jmespath
from typing import Any, Dict, List

data: Dict[str, Any] = {
    "store": {
        "book": [
            {"category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95},
            {"category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99}
        ],
        "bicycle": {"color": "red", "price": 19.95}
    }
}

# Example 1: Simple retrieval
title: Any = jmespath.search("store.book[0].title", data)
print(f"Title: {title}")

# Example 2: Projection to get all authors
authors: List[str] = jmespath.search("store.book[*].author", data)
print(f"Authors: {authors}")

# Example 3: Filtering based on a condition
fiction_books: List[Dict[str, Any]] = jmespath.search("store.book[?category=='fiction']", data)
print(f"Fiction books: {fiction_books}")

# With types-jmespath installed, a type checker (like mypy or pyright)
# would utilize these stubs to perform static analysis,
# ensuring that `jmespath.search` calls conform to its expected signature
# and that return types are handled correctly based on the JMESPath expression.