Skip to content

docs(gfql): add temporal predicates documentation and notebook CI testing#674

Closed
lmeyerov wants to merge 22 commits into
fix/temporal-type-errors-cleanfrom
docs/gfql-temporal-predicates
Closed

docs(gfql): add temporal predicates documentation and notebook CI testing#674
lmeyerov wants to merge 22 commits into
fix/temporal-type-errors-cleanfrom
docs/gfql-temporal-predicates

Conversation

@lmeyerov

@lmeyerov lmeyerov commented Jun 23, 2025

Copy link
Copy Markdown
Contributor

Summary

This PR adds comprehensive documentation for GFQL temporal predicates and introduces notebook CI testing infrastructure.

Changes

Documentation

  • GFQL Temporal Predicates Documentation (from previous commits in this branch):
    • Added datetime filtering guide with comprehensive examples
    • Added wire protocol reference for temporal value serialization
    • Added temporal_predicates.ipynb demonstrating date/time filtering with pandas/numpy datetime types
    • Shows usage of gt, lt, between, is_in with temporal values
    • Demonstrates timezone-aware filtering and wire protocol dict usage

CI Infrastructure

  • Notebook Testing Framework:
    • Added automated validation for Jupyter notebooks during docs build
    • Structure validation: Ensures notebooks have required fields (e.g., execution_count)
    • Execution validation: Optionally verifies notebooks run without errors
    • Currently validates temporal_predicates.ipynb and layout_tree.ipynb
    • Integrated into GitHub Actions CI pipeline

Fixes

  • Fixed temporal_predicates.ipynb structure (added missing execution_count, removed invalid markdown cell outputs)
  • Fixed pre-existing PlotterBase.py RST docstring formatting errors that were blocking docs build

Build Improvements

  • Added ipykernel==6.29.5 to docs dependencies for notebook execution
  • Updated Dockerfile to register Python kernel during build
  • Changed docs build script from /bin/sh to /bin/bash for array support

Testing

  • Docs build passes with all temporal predicates documentation
  • Notebook structure validation runs on every CI build
  • Selected notebooks don't require .plot() or register() calls, making them suitable for CI validation

Notes

  • This completes the GFQL temporal predicates feature by adding user-facing documentation
  • The notebook CI infrastructure ensures our example notebooks remain valid and executable
  • Additional notebooks can be added to validation as needed

lmeyerov and others added 8 commits June 22, 2025 21:32
- Add temporal value classes (DateTime, Date, Time) with timezone support
- Extend comparison predicates (GT, LT, GE, LE, EQ, NE, Between) for temporal values
- Enhance IsIn predicate to support temporal values with type validation
- Add comprehensive GFQL type system with guards and coercions
- Include temporal value serialization and wire format support
- Add comprehensive test coverage for temporal operations

Enables date/time comparisons and filtering in GFQL queries.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
- Add TypeGuard import with proper Python version handling
- Add TypeGuard annotation to is_basic_scalar for type narrowing
- Include TemporalValue in ComparisonInput and IsInElementInput unions
- Enables proper type checking for temporal predicates

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
- Remove unnecessary type: ignore comment
- Add proper handling for TemporalValue in _normalize_value
- Type narrowing now works correctly with TypeGuard

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
- Remove monolithic _temporal_comparison method with operator dispatch
- Add focused helper methods for series preparation and value extraction
- Inline comparison logic directly in each operator (GT, LT, GE, LE, EQ, NE)
- Eliminate all type: ignore and cast statements
- Each operator now clearly shows both numeric and temporal comparison logic

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
- Use version check for TypeGuard import only during TYPE_CHECKING
- Remove pd.Series[T] generic syntax not supported in Python 3.8
- Ensures mypy passes on all supported Python versions

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
lmeyerov and others added 6 commits June 23, 2025 03:16
- Move Any import from method-level to module-level
- Move DateTimeWire, DateWire, TimeWire imports to module-level
- Fixes dynamic import issue flagged during code review

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
- Add temporal_predicates.ipynb demo notebook with TOC and examples
- Add datetime_filtering.md with imports, standards, and duration notes
- Update wire_protocol_examples.md with clearer structure
- Documentation for GFQL temporal predicate features

Co-Authored-By: Claude <noreply@anthropic.com>
- Add comprehensive datetime filtering guide
- Add temporal predicates notebook with examples
- Add wire protocol examples for temporal values
- Update GFQL overview with temporal examples
- Update predicates quick reference with temporal operators
- Add temporal modules to API documentation

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
- Add temporal value classes to changelog
- Add wire protocol support mention
- Add documentation references (datetime guide, wire protocol, notebook)

📤 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
…links

- Add datetime_filtering and wire_protocol_examples to GFQL toctree
- Use relative HTML links that work across all hosting environments
- Links go up two levels from demos/gfql/ to reach gfql/ documentation

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
- Change from non-existent temporal_values module to ast_temporal
- Fixes autodoc import error during documentation build

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov lmeyerov force-pushed the docs/gfql-temporal-predicates branch from 05e93dd to 5c44d99 Compare June 23, 2025 18:30
lmeyerov and others added 4 commits June 23, 2025 14:42
- Streamline datetime filtering guide with concise examples
- Add clear links to Python/Pandas datetime documentation
- Improve notebook imports with explanatory comments
- Fix broken chain.rst link to use correct path
- Make documentation more actionable with direct type links

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
- Remove "recommended" verbiage in favor of direct documentation
- Keep examples factual without good/bad judgments
- Let ordering and examples guide usage naturally

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
- Document that wire protocol dicts are a supported input type
- Show how to use ISO strings via wire protocol dicts
- Clarify that only raw strings raise ValueError

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
- Replace bad_filter/good_filter with factual variable names
- Keep error handling examples factual without judgments
- Align with direct documentation style

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov lmeyerov changed the title docs(gfql): add temporal predicates documentation docs(gfql): add temporal predicates documentation and notebook CI testing Jun 23, 2025
lmeyerov added 4 commits June 23, 2025 22:36
- Add missing execution_count field to all code cells
- Remove invalid outputs field from markdown cell
- Add structure validation for notebooks during docs build
- Validate temporal_predicates.ipynb and layout_tree.ipynb
- Enable validation in CI with VALIDATE_NOTEBOOK_EXECUTION env var
- Update build script to use bash for array support
- Add ipykernel==6.29.5 to docs dependencies
- Register Python kernel in Dockerfile build step
@lmeyerov lmeyerov force-pushed the docs/gfql-temporal-predicates branch from e0f0884 to 02e3fd7 Compare June 24, 2025 02:37
@lmeyerov lmeyerov force-pushed the fix/temporal-type-errors-clean branch from bfa3ca4 to edf8508 Compare June 24, 2025 04:03
@lmeyerov lmeyerov closed this Jun 24, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant