Merge pull request #198 from tylerriccio33/typing

Add experimental gradual typing for development

Author: rich-iannone

.gitignore

@@ -141,3 +141,6 @@ benchmark/data/*.json
 uv.lock
 memory
 .vscode/mcp.json
+
+# 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

@@ -45,6 +45,11 @@ install-pre-commit: # Install pre-commit hooks
 run-pre-commit: # Run pre-commit hooks
 	@uvx pre-commit run --all-files
 
+
+type: ## Run experimental type checking
+	@uv run ty check pointblank
+
+
 check:
 	pyright --pythonversion 3.8 pointblank
 	pyright --pythonversion 3.9 pointblank

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
 # In Python 3.14+, __doc__ attribute on typing.Union objects became read-only

pointblank/schema.py

@@ -2,12 +2,16 @@
 
 import copy
 from dataclasses import dataclass
+from typing import TYPE_CHECKING
 
 import narwhals as nw
 
 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", "_check_schema_match"]
 
 
@@ -272,14 +276,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:
@@ -889,7 +893,7 @@ def _schema_info_generate_params_dict(
 
 
 def _get_schema_validation_info(
-    data_tbl: any,
+    data_tbl: Any,
     schema: Schema,
     passed: bool,
     complete: bool,