Dev/gfql datetimes by lmeyerov · Pull Request #671 · graphistry/pygraphistry

lmeyerov · 2025-06-22T02:00:49Z

Summary

Add temporal (datetime/date/time) support to GFQL comparison predicates and is_in operator, enabling filtering by temporal values with proper timezone handling.

Changes

Features

Temporal predicate support: gt, lt, ge, le, eq, ne, between, and is_in now accept datetime, date, and time values
Timezone awareness: Full support for timezone-aware datetime comparisons
Wire protocol: JSON serialization format for temporal values with type, value, and optional timezone fields
AST classes: New DateTimeValue, DateValue, TimeValue classes in graphistry.compute.ast_temporal

Type System Improvements

Replace Any types with proper type annotations:
- ComparisonInput for comparison predicates
- IsInElementInput for is_in predicate
- BetweenBoundInput for between predicate
Add type guards with TypeGuard annotations for better type narrowing
Fix Python 3.10 compatibility issues

Code Organization

Move temporal value classes from predicates/temporal_values.py to compute/ast_temporal.py
Rename numeric.py to comparison.py (more accurate module name)
Extract temporal coercion functions to models/gfql/coercions/temporal.py
Add missing __init__.py files for proper package structure

Testing

Comprehensive temporal predicate tests including timezone handling
Fix import errors in test files
All tests, lint, and type checks passing

Examples

from graphistry import n, chain
from graphistry.compute.predicates import gt, between
import pandas as pd
from datetime import date, time

# Filter by datetime
g.chain([n({"timestamp": gt(pd.Timestamp("2023-01-01"))})])

# Filter by date range
g.chain([n({"date": between(date(2023, 6, 1), date(2023, 6, 30))})])

# Filter by time of day
g.chain([n({"time": between(time(9, 0), time(17, 0))})])

Related PRs

Documentation updates: docs: add temporal predicates documentation #672 (stacked on this PR)

Fixes #660

Dev/readme redux

@overload

- Remove predicates/__init__.py (not needed, compute/__init__ imports directly) - Replace Any types with proper type annotations using @overload - Add TypedDict classes for wire protocol (DateTimeDict, DateDict, TimeDict) - Rename numeric.py → comparison.py (more accurate since it handles both numeric and temporal) - Update all imports to use new comparison module name All tests pass, no breaking changes to public API. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

lmeyerov · 2025-06-22T17:50:25Z

Changes Made to Address PR Feedback

I've addressed the critical code quality issues:

✅ Completed

Removed __init__.py - Deleted the unnecessary predicates module init file
Fixed Any types - Replaced with proper type annotations using @overload and specific Union types
Renamed numeric.py → comparison.py - More accurate name since it handles both numeric and temporal comparisons
Improved dict typing - Created TypedDict classes (DateTimeDict, DateDict, TimeDict) instead of generic dict

🔄 Still TODO

Documentation updates (notebook and docs improvements)
Consider factoring out normalization logic further
CHANGELOG.md issue (appears to be from earlier commits)

All tests pass locally and in Docker. CI is running now.

The changes maintain full backward compatibility - no breaking changes to the public API.

The merge brought in a truncated CHANGELOG. This restores the full history from master and adds our temporal predicate changes to the Dev section. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

…rmalize_comparison_value - Remove class_name parameter that was only used in error messages - Update all call sites in comparison.py - Fix mypy errors by properly handling timezone types and reordering overloads - Fix test import after numeric.py was renamed to comparison.py 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

- Fixed notebook cell type (markdown vs code) issue - Added mini TOC and What's Next section to temporal_predicates.ipynb - Enhanced datetime_filtering.md with imports, standards info, and duration notes - Reorganized wire_protocol_examples.md with clearer structure - Fixed cross-reference links in documentation Co-Authored-By: Claude <noreply@anthropic.com>

- Replace Any types with specific ComparisonInput, IsInElementInput types - Remove Dict[str, Any] from IsInElementInput (too permissive) - Import and use proper types in predicates - Add Union imports to type guard module - Tests still pass, mypy has some remaining issues with type narrowing Co-Authored-By: Claude <noreply@anthropic.com>

- Remove temporal_predicates.ipynb demo - Remove datetime_filtering.md documentation - Remove wire_protocol_examples.md documentation - These will be added in a separate stacked PR Co-Authored-By: Claude <noreply@anthropic.com>

- Reset all docs/ to master state - These API doc changes will be in the stacked docs PR - Keeps main PR focused on code changes only Co-Authored-By: Claude <noreply@anthropic.com>

- Remove all .rst file changes from main PR - These belong in the stacked docs PR

- Remove documentation-related items - Add details about temporal value classes and wire protocol - Add details about type annotation improvements - Add fixed section for type checking and import fixes

lmeyerov · 2025-06-22T23:17:05Z

+
+
+# For backward compatibility - keep but deprecated
+class NumericASTPredicate(ComparisonPredicate):


shouldn't there be an annotation or something in that case?

lmeyerov · 2025-06-22T23:17:53Z

+            return val
+        elif is_any_temporal(val):
+            return to_ast(val)
+        elif is_string(val):


don't we need strings for something like string between calls? are there any calls that need strings here?

lmeyerov · 2025-06-22T23:18:52Z

+        else:
+            raise TypeError(f"Unsupported type for {self.__class__.__name__}: {type(val)}")
+
+    def _temporal_comparison(self, s: SeriesT, temporal_val: TemporalValue, op: str) -> SeriesT:


'op' should be a literal type..

also, instead of a big dispatch here, does it make more sense to inline these alongside their numeric counterparts below?

lmeyerov · 2025-06-22T23:21:31Z

+from ..ast_temporal import TemporalValue, DateTimeValue, DateValue, TimeValue
+from ...models.gfql.coercions.temporal import to_native
+from ...models.gfql.types.guards import is_basic_scalar, is_any_temporal
+from ...models.gfql.types.predicates import IsInElementInput


these imports are hard to maintain, do as graphistry.models. etc instead of relative

lmeyerov · 2025-06-22T23:22:14Z

+            normalized.append(self._normalize_value(val))
+        return normalized
+
+    def _normalize_value(self, val: IsInElementInput) -> Any:


this is confusing, should normalize to some named type made out of known variants

lmeyerov · 2025-06-22T23:22:25Z

+    def __init__(self, options: List[IsInElementInput]) -> None:
+        self.options = self._normalize_options(options)
+
+    def _normalize_options(self, options: List[IsInElementInput]) -> List[Any]:


lmeyerov · 2025-06-22T23:26:06Z


    def __call__(self, s: SeriesT) -> SeriesT:
+        # Check if we have any temporal values in options
+        has_temporal = any(


should we check all temporal vs all numeric, and erorr if mixed?

- Remove unnecessary cast() calls that were causing mypy errors - Simplify temporal value type conversions in comparison predicates - Let mypy infer types from to_ast() return annotation

lmeyerov · 2025-06-22T23:42:00Z

        import torch.nn.functional as F
        from graphistry.networks import HeteroEmbed
-        from tqdm import trange
+        from tqdm import trange  # type: ignore[import]


Major improvements: - Replace all Any types with proper type annotations - Add validation to prevent mixing temporal and numeric in is_in - Use Literal types for comparison operators - Move to absolute imports instead of relative - Factor out shared normalization logic - Add proper TypedDict usage for wire formats - Fix lint issues (line length, unused imports, trailing whitespace) Breaking changes: - is_in now raises ValueError when mixing temporal and numeric values - Comparison operators now use proper typed parameters Addresses PR comments on type safety and code organization.

- Remove empty __init__.py files that were added to PR - Fix NormalizedIsInElement type to include all temporal types - Fix Between class to pass original inputs to sub-predicates - Fix type annotation in is_in validation method Resolves 8 mypy type errors. All tests pass. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

lmeyerov added 30 commits October 12, 2024 16:44

docs(changelog)

228a01d

docs(more)

9090d35

docs(changelog)

9d97433

infra(rtd dockerfile): cache pip install

8b4bbe3

fix(readme.md): ipynb refs

d38d13e

fix(docs pdf): drop svg and external images

9576fc7

fix(docgen)

2b73869

docs(readme.md): tighter next links and to docssite

ace3244

fix(docgen)

4a6fbc1

docs(changelog): 0.34.16

45fab3d

Merge pull request #604 from graphistry/dev/readme-redux

dc4f796

Dev/readme redux

infra(isomorphic utils): more

8a13e4f

infra(gib): logging

4a13501

fix(warns)

46e9976

feat(gib): speedup via bulk mode

f8f14d1

refactor(fa2): simplify

64d12ff

feat(fa2): play=0

b2ad0fd

feat(fa2): compute partition bounds for subcalls

6e97ead

refactor(gib): minor

8ed55e6

feat(circle layout):partition mode

d386e87

wip(gib demo)

02afd8a

wip(gib debugging)

86d49a3

fix(gib): circle

160a140

fix(type): gfql

34cc5c4

fix(fa2): engine switcher

b3535b2

fix(gib): igraph defaults

c4c6505

fix(gib): igraph defaults

2a4cf0f

infra(test): py10

98e6b6d

infra(setup.py): move graphviz to heavy bc apt-get

39f995d

infra(setup.py): more keywords

8552f24

lmeyerov commented Jun 22, 2025

View reviewed changes

Comment thread graphistry/compute/predicates/is_in.py

lmeyerov commented Jun 22, 2025

View reviewed changes

Comment thread graphistry/compute/predicates/numeric.py

lmeyerov and others added 5 commits June 22, 2025 12:56

refactor: remove documentation from PR to reduce size

fe53141

- Remove temporal_predicates.ipynb demo - Remove datetime_filtering.md documentation - Remove wire_protocol_examples.md documentation - These will be added in a separate stacked PR Co-Authored-By: Claude <noreply@anthropic.com>

lmeyerov mentioned this pull request Jun 22, 2025

docs: add temporal predicates documentation #672

Closed

3 tasks

lmeyerov and others added 3 commits June 22, 2025 15:57

refactor: remove API docs changes from main PR

fc504dd

- Reset all docs/ to master state - These API doc changes will be in the stacked docs PR - Keeps main PR focused on code changes only Co-Authored-By: Claude <noreply@anthropic.com>

fix: reset all API docs to master state

a86ebba

- Remove all .rst file changes from main PR - These belong in the stacked docs PR

docs: update CHANGELOG to reflect actual code changes in PR

d33d192

- Remove documentation-related items - Add details about temporal value classes and wire protocol - Add details about type annotation improvements - Add fixed section for type checking and import fixes

lmeyerov commented Jun 22, 2025

View reviewed changes

fix(types): resolve Python 3.10 type checking issues

b49d96a

- Remove unnecessary cast() calls that were causing mypy errors - Simplify temporal value type conversions in comparison predicates - Let mypy infer types from to_ast() return annotation

lmeyerov commented Jun 22, 2025

View reviewed changes

Comment thread graphistry/models/gfql/types/predicates.py

lmeyerov commented Jun 22, 2025

View reviewed changes

Comment thread graphistry/models/gfql/types/predicates.py

lmeyerov commented Jun 22, 2025

View reviewed changes

lmeyerov force-pushed the dev/gfql-datetimes branch from e1d57c3 to 2b2fedb Compare June 23, 2025 00:28

lmeyerov force-pushed the dev/gfql-datetimes branch from 09cf8b5 to 5dbf8ce Compare June 23, 2025 01:11

lmeyerov closed this Jun 23, 2025

lmeyerov deleted the dev/gfql-datetimes branch June 23, 2025 01:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Dev/gfql datetimes#671

Dev/gfql datetimes#671
lmeyerov wants to merge 1196 commits into
masterfrom
dev/gfql-datetimes

lmeyerov commented Jun 22, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

lmeyerov commented Jun 22, 2025

Uh oh!

lmeyerov Jun 22, 2025

Uh oh!

lmeyerov Jun 22, 2025 •

edited

Loading

Uh oh!

lmeyerov Jun 22, 2025

Uh oh!

lmeyerov Jun 22, 2025

Uh oh!

lmeyerov Jun 22, 2025

Uh oh!

lmeyerov Jun 22, 2025

Uh oh!

lmeyerov Jun 22, 2025

Uh oh!

lmeyerov Jun 22, 2025

Uh oh!

Uh oh!

Uh oh!

lmeyerov Jun 22, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants



		# For backward compatibility - keep but deprecated
		class NumericASTPredicate(ComparisonPredicate):

Uh oh!

Conversation

lmeyerov commented Jun 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Features

Type System Improvements

Code Organization

Testing

Examples

Related PRs

Uh oh!

Uh oh!

Uh oh!

lmeyerov commented Jun 22, 2025

Changes Made to Address PR Feedback

✅ Completed

🔄 Still TODO

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lmeyerov Jun 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

lmeyerov commented Jun 22, 2025 •

edited

Loading

lmeyerov Jun 22, 2025 •

edited

Loading