Add experimental gradual typing for development

.gitignore

@@ -133,3 +133,6 @@ benchmark/data/*.json
 .swp
 
 uv.lock
+
+# While typing is experimental, don't mark the entire package as typed
+pointblank/py.typed

CONTRIBUTING.md

@@ -25,11 +25,12 @@ Once there is consensus that a PR based on the issue would be helpful, adhering
 
 ### Setting Up Your Development Environment
 
-To set up your development environment, you can follow these steps:
+To set up your development environment, first clone the posit-dev/pointblank repository.
 
-- Clone the posit-dev/pointblank repository
-- Create a virtual environment for the folder
-- Install the package in editable mode with `pip install -e .` from the root of the project folder
+If you're using UV, you may run `uv sync` and your environment is setup! If using pip or another package manager, keep following these steps:
+
+- Create a virtual environment for the folder.
+- Install the package in editable mode with `pip install -e .` from the root of the project folder.
 - Install the development dependencies with `pip install '.[dev]'` (have a look at the `pyproject.toml` file for the list of development dependencies)
 
 Our documentation uses `quartodoc` which in turn requires a local install of the Quarto CLI. To install Quarto, go to <https://quarto.org/docs/get-started/> to get the latest build for your platform.
@@ -43,3 +44,7 @@ Building the documentation can be done with `make docs-build` from the root of t
 The tests are located in the `tests` folder and we use `pytest` for running them. To run all of the tests, use `make test`. If you want to run a specific test file, you can use `pytest tests/test_file.py`.
 
 If you create new tests involving snapshots, please ensure that the resulting snapshots are relatively small. After adding snapshots, use `make test-update` (this runs `pytest --snapshot-update`). A subsequent use of `make test` should pass without any issues.
+
+### Linting and Type Checking
+
+We use `ruff` for linting, the settings used are fairly loose and objective. Linting is run in pre-commit in CI. You can run it locally with `make lint`. Type checking is currently not enforced, but we intend on gradually typing the codebase. You can run `make type` to run Astral's new experimental type checker `ty`. Feel free to leverage type hints and occasionally type checking but it's not obligatory at this time.

Makefile

@@ -18,6 +18,11 @@ lint: ## Run ruff formatter and linter
 	@uv run ruff format
 	@uv run ruff check --fix
 
+
+type: ## Run experimental(!) type checking
+	@uvx ty check pointblank
+
+
 check:
 	pyright --pythonversion 3.8 pointblank
 	pyright --pythonversion 3.9 pointblank

pointblank/_interrogation.py

@@ -1911,7 +1911,7 @@ class ColSchemaMatch:
     """
 
     data_tbl: FrameT | Any
-    schema: any
+    schema: Any
     complete: bool
     in_order: bool
     case_sensitive_colnames: bool
@@ -2425,7 +2425,7 @@ def _check_nulls_across_columns_nw(table, columns_subset):
     return result
 
 
-def _modify_datetime_compare_val(tgt_column: any, compare_val: any) -> any:
+def _modify_datetime_compare_val(tgt_column: Any, compare_val: Any) -> Any:
     tgt_col_dtype_str = str(tgt_column.dtype).lower()
 
     if compare_val is isinstance(compare_val, Column):  # pragma: no cover

pointblank/_typing.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
+import datetime
 import sys
+from collections.abc import Container
 from typing import List, Tuple, Union
 
 # Check Python version for TypeAlias support
@@ -15,6 +17,12 @@
     SegmentTuple: TypeAlias = Tuple[str, SegmentValue]
     SegmentItem: TypeAlias = Union[str, SegmentTuple]
     SegmentSpec: TypeAlias = Union[str, SegmentTuple, List[SegmentItem]]
+
+    _CompliantValue: TypeAlias = Union[str, int, float, datetime.datetime, datetime.date]
+    """A compliant value that pointblank can use in a validation step"""
+    _CompliantValues: TypeAlias = Container[_CompliantValue]
+    """A collection of compliant values that pointblank can use in a validation step"""
+
 else:
     # Python 3.8 and 3.9 compatible type aliases
     AbsoluteBounds = Tuple[int, int]
@@ -24,6 +32,10 @@
     SegmentTuple = Tuple[str, SegmentValue]
     SegmentItem = Union[str, SegmentTuple]
     SegmentSpec = Union[str, SegmentTuple, List[SegmentItem]]
+    _CompliantValue = Union[str, int, float, datetime.datetime, datetime.date]
+    """A compliant value that pointblank can use in a validation step"""
+    _CompliantValues = Container[_CompliantValue]
+    """A collection of compliant values that pointblank can use in a validation step"""
 
 # Add docstrings for better IDE support
 AbsoluteBounds.__doc__ = "Absolute bounds (i.e., plus or minus)"

pointblank/schema.py

@@ -2,10 +2,14 @@
 
 import copy
 from dataclasses import dataclass
+from typing import TYPE_CHECKING
 
 from pointblank._constants import IBIS_BACKENDS
 from pointblank._utils import _get_tbl_type, _is_lazy_frame, _is_lib_present, _is_narwhals_table
 
+if TYPE_CHECKING:
+    from typing import Any
+
 __all__ = ["Schema"]
 
 
@@ -265,14 +269,14 @@ class Schema:
     columns: str | list[str] | list[tuple[str, str]] | list[tuple[str]] | dict[str, str] | None = (
         None
     )
-    tbl: any | None = None
+    tbl: Any | None = None
 
     def __init__(
         self,
         columns: (
             str | list[str] | list[tuple[str, str]] | list[tuple[str]] | dict[str, str] | None
         ) = None,
-        tbl: any | None = None,
+        tbl: Any | None = None,
         **kwargs,
     ):
         if tbl is None and columns is None and not kwargs:
@@ -872,7 +876,7 @@ def _schema_info_generate_params_dict(
 
 
 def _get_schema_validation_info(
-    data_tbl: any,
+    data_tbl: Any,
     schema: Schema,
     passed: bool,
     complete: bool,