feat(query): add partial query solver engine

setup.py

@@ -20,6 +20,7 @@
         "pytest-timeout>=2.2.0,<3",  # For avoiding timing out during tests
         "hypothesis>=6.2.0,<7.0",  # Strategy-based fuzzer
         "hypothesis-jsonschema==0.19.0",  # JSON Schema fuzzer extension
+        "pandas",  # Needed to test w/ narwhals
     ],
     "lint": [
         "ruff>=0.10.0",  # Unified linter and formatter
@@ -92,10 +93,9 @@
         "lazyasd>=0.1.4",
         "asttokens>=2.4.1,<3",  # Peer dependency; w/o pin container build fails.
         "cchecksum>=0.0.3,<1",
-        # Pandas peer-dep: Numpy 2.0 causes issues for some users.
-        "numpy<2",
+        "more-itertools; python_version<'3.10'",  # backport for `itertools.pairwise`
+        "narwhals>=1.29,<2",
         "packaging>=23.0,<24",
-        "pandas>=2.2.2,<3",
         "pluggy>=1.3,<2",
         "pydantic>=2.10.0,<3",
         "pydantic-settings>=2.5.2,<3",

src/ape/api/config.py

@@ -7,7 +7,8 @@
 
 import yaml
 from ethpm_types import PackageManifest, PackageMeta, Source
-from pydantic import ConfigDict, Field, ValidationError, model_validator
+from narwhals.stable.v1 import Implementation as DataframeImplementation
+from pydantic import ConfigDict, Field, ValidationError, field_validator, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 from ape.exceptions import ConfigError
@@ -202,6 +203,17 @@ class DeploymentConfig(PluginConfig):
     """
 
 
+class QueryConfig(PluginConfig):
+    """Add 'query:' key to your config."""
+
+    backend: DataframeImplementation = DataframeImplementation.PANDAS
+    """Which Narwhals backend implementation to use."""
+
+    @field_validator("backend", mode="before")
+    def convert_backend_str(cls, value: Any) -> DataframeImplementation:
+        return DataframeImplementation.from_backend(value)
+
+
 def _get_problem_with_config(errors: list, path: Path) -> Optional[str]:
     # Attempt to find line numbers in the config matching.
     cfg_content = Source(content=path.read_text(encoding="utf8")).content
@@ -368,6 +380,8 @@ def __init__(self, *args, **kwargs):
     The version of the project.
     """
 
+    query: QueryConfig = QueryConfig()
+
     # NOTE: Plugin configs are technically "extras".
     model_config = SettingsConfigDict(extra="allow", env_prefix="APE_")
 

src/ape/api/providers.py

@@ -19,9 +19,6 @@
 from eth_utils import to_hex
 from pydantic import Field, computed_field, field_serializer, model_validator
 
-from ape.api.networks import NetworkAPI
-from ape.api.query import BlockTransactionQuery
-from ape.api.transactions import ReceiptAPI, TransactionAPI
 from ape.exceptions import (
     APINotImplementedError,
     ProviderError,
@@ -44,6 +41,9 @@
 from ape.utils.process import JoinableQueue, spawn
 from ape.utils.rpc import RPCHeaders
 
+from .networks import NetworkAPI
+from .transactions import ReceiptAPI, TransactionAPI
+
 if TYPE_CHECKING:
     from eth_pydantic_types import HexBytes
     from ethpm_types.abi import EventABI
@@ -151,12 +151,21 @@ def transactions(self) -> list[TransactionAPI]:
         """
         All transactions in a block.
         """
+        from ape.api.query import BlockTransactionQuery
+
         if self.hash is None:
-            # Unable to query transactions.
+            # NOTE: Only "unsealed" blocks do not have a hash
+            raise ProviderError("Unable to find block transactions: not sealed yet")
+
+        elif self.num_transactions == 0:
             return []
 
         try:
-            query = BlockTransactionQuery(columns=["*"], block_id=self.hash)
+            query = BlockTransactionQuery(
+                columns=["*"],
+                num_transactions=self.num_transactions,
+                block_id=self.hash,
+            )
             return cast(list[TransactionAPI], list(self.query_manager.query(query)))
         except QueryEngineError as err:
             # NOTE: Re-raising a better error here because was confusing