From e814c6b0163da625529e7d41aac3a7143783a35d Mon Sep 17 00:00:00 2001 From: Gil Forsyth Date: Tue, 28 Nov 2023 15:05:30 -0500 Subject: [PATCH] docs(tests): document class variables in BackendTest --- docs/contribute/BackendTest.org | 22 ---------- ibis/backends/tests/base.py | 78 ++++++++++++++++++++++++++------- 2 files changed, 61 insertions(+), 39 deletions(-) delete mode 100644 docs/contribute/BackendTest.org diff --git a/docs/contribute/BackendTest.org b/docs/contribute/BackendTest.org deleted file mode 100644 index a7b7fc182727..000000000000 --- a/docs/contribute/BackendTest.org +++ /dev/null @@ -1,22 +0,0 @@ -#+title: Backend Test - -| Variable | Default | Type | Description | Required | -|-------------------------------------+------------------------------+---------------------------+-------------------------------------------------------------------------+----------| -| ~check_dtype~ | True | Bool | check that dtypes match when comparing Pandas ~series~ | True | -| ~check_names~ | True | Bool | check that column name matches when comparing Pandas ~series~ | True | -| ~supports_arrays~ | True | Bool | backend supports arrays | | -| ~supports_arrays_outside_of_select~ | True | Bool | backend supports arrays outside of select statements | | -| ~supports_window_operations~ | True | Bool | backend supports windowing | | -| ~supports_divide_by_zero~ | False | Bool | backend supports division by zero | | -| ~returned_timestamp_unit~ | "us" | Unit abbreviation | precision of timestamp unit returned | | -| ~supported_to_timestamp_units~ | {"s", "ms", "us"} | Set of unit abbreviations | supported units of precision for timestamps | | -| ~supports_floating_modulus~ | True | Bool | backend supports floating numbers in modulus operations | | -| ~native_bool~ | True | Bool | backend has native boolean types | | -| ~supports_structs~ | True | Bool | backend supports structs | | -| ~supports_json~ | True | Bool | backend supports JSON | | -| ~supports_map~ | False | Bool | backend supports maps basically nothing does except trino and snowflake | | -| ~reduction_tolerance~ | 1e-7 | Float | | | -| ~default_identifier_case_fn~ | staticmethod(toolz.identity) | Function | | | -| ~stateful~ | True | Bool | | | -| ~service_name~ | None | | | | -| ~supports_tpch~ | False | Bool | | | diff --git a/ibis/backends/tests/base.py b/ibis/backends/tests/base.py index 4c1c52749889..1fdb96663b28 100644 --- a/ibis/backends/tests/base.py +++ b/ibis/backends/tests/base.py @@ -5,7 +5,7 @@ import inspect import subprocess from pathlib import Path -from typing import TYPE_CHECKING, Any +from typing import TYPE_CHECKING, Any, Literal import numpy as np import pandas as pd @@ -21,26 +21,48 @@ class BackendTest(abc.ABC): - check_dtype = True - check_names = True - supports_arrays = True - supports_arrays_outside_of_select = supports_arrays - supports_window_operations = True - supports_divide_by_zero = False - returned_timestamp_unit = "us" + """ + The base class for managing configuration and data loading for a backend + that does not require Docker for testing (this includes both in-process + backends and cloud backends like Snowflake and BigQuery). + """ + + check_dtype: bool = True + "Check that dtypes match when comparing Pandas Series" + check_names: bool = True + "Check that column name matches when comparing Pandas Series" + supports_arrays: bool = True + "Whether backend supports Arrays / Lists" + supports_arrays_outside_of_select: bool = supports_arrays + "Whether backend supports Arrays / Lists outside of Select Statements" + supports_window_operations: bool = True + "Whether backend supports Window Operations" + supports_divide_by_zero: bool = False + "Whether backend supports division by zero" + returned_timestamp_unit: str = "us" supported_to_timestamp_units = {"s", "ms", "us"} - supports_floating_modulus = True - native_bool = True - supports_structs = True - supports_json = True - supports_map = False # basically nothing does except trino and snowflake + supports_floating_modulus: bool = True + "Whether backend supports floating point in modulus operations" + native_bool: bool = True + "Whether backend has native boolean types" + supports_structs: bool = True + "Whether backend supports Structs" + supports_json: bool = True + "Whether backend supports operating on JSON" + supports_map: bool = False + "Whether backend supports mappings (currently DuckDB, Snowflake, and Trino)" reduction_tolerance = 1e-7 + "Used for a single test in `test_aggregation.py`. You should not need to touch this." default_identifier_case_fn = staticmethod(toolz.identity) + "Function applied to all identifier names to change case as necessary (e.g. Snowflake ALL_CAPS)" stateful = True - service_name = None - supports_tpch = False + "Whether special handling is needed for running a multi-process pytest run." + supports_tpch: bool = False + "Child class defines a `load_tpch` method that loads the required TPC-H tables into a connection." force_sort_before_comparison = False - rounding_method = "away_from_zero" + "Sort results before comparing against reference computation." + rounding_method: Literal["away_from_zero", "half_to_even"] = "away_from_zero" + "Name of round method to use for rounding test comparisons." @property @abc.abstractmethod @@ -62,6 +84,20 @@ def format_table(name: str) -> str: return name def __init__(self, *, data_dir: Path, tmpdir, worker_id, **kw) -> None: + """ + Initializes the test class -- note that none of the arguments are + required and will be provided by `pytest` or by fixtures defined in + `ibis/backends/conftest.py`. + + data_dir + Directory where test data resides (will be provided by the + `data_dir` fixture in `ibis/backends/conftest.py`) + tmpdir + Pytest fixture providing a temporary directory location + worker_id + A unique identifier for each worker used for running test + concurrently via e.g. `pytest -n auto` + """ self.connection = self.connect(tmpdir=tmpdir, worker_id=worker_id, **kw) self.data_dir = data_dir self.script_dir = data_dir.parent / "schema" @@ -112,7 +148,7 @@ def load_data( if worker_id != "master": root_tmp_dir = root_tmp_dir.parent - fn = root_tmp_dir / (getattr(cls, "service_name", None) or cls.name()) + fn = root_tmp_dir / cls.name() with FileLock(f"{fn}.lock"): cls.skip_if_missing_deps() @@ -295,7 +331,15 @@ def _tpch_table(self, name: str): class ServiceBackendTest(BackendTest): + """Parent class to use for backend test configuration if backend requires a + Docker container(s) in order to run locally. + + """ + + service_name: str | None = None + "Name of service defined in docker-compose.yml corresponding to backend." data_volume = "/data" + "Data volume defined in docker-compose.yml corresponding to backend." @property @abc.abstractmethod