Minimal type checking changes

[lispandfound]

This PR introduces minimal type checking changes into qcore, and adds a GitHub functionality to check them. I've tried to make this PR as small as possible to make it reviewable. However, the distributions module required some changes: Most functions now take a seed and size parameter. The size parameter is introduced to make the type checking work (i.e. when size = 1, distributions return floats, else they return arrays).

[gemini-code-assist]

Summary of Changes

Hello @lispandfound, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the type safety and maintainability of the qcore library by integrating comprehensive type hints and static analysis. It involves a systematic application of type annotations across various modules, refactoring key functions to accommodate these new types, and streamlining the codebase by removing deprecated or redundant utilities. The changes aim to improve code quality, reduce potential runtime errors, and facilitate easier understanding and future development.

Highlights

• Type Checking Introduction: Introduced minimal type checking changes across the qcore library, accompanied by new GitHub functionality to enforce these checks.
• Dependency Updates: Removed the matplotlib dependency and added typing-extensions>=4.9.0 to support advanced type hinting features, particularly for deprecation decorators.
• Distributions Module Refactoring: Functions within qcore/uncertainties/distributions.py now accept seed and size parameters, enabling them to return either a single float or a NumPy array based on the size argument, with corresponding type overloads.
• Deprecation Standardization: Replaced warnings.deprecated with typing_extensions.deprecated and added explicit deprecation messages to several functions and classes, particularly in qcore/constants.py, qcore/formats.py, qcore/shared.py, and qcore/utils.py.
• Code Cleanup and Simplification: Removed redundant utility functions such as dump_yaml, setup_dir, compare_versions from qcore/utils.py, and the transf function from qcore/timeseries.py. Also removed calc_backarc and related volcanic front coordinates from qcore/src_site_dist.py.
• Type Hinting Enhancements: Extensive type hints were added or refined across numerous files, including archive_structure.py, cli.py, coordinates.py, geo.py, grid.py, nhm.py, point_in_polygon.py, simulation_structure.py, siteamp_models.py, timeseries.py, and xyts.py to improve code clarity and maintainability.
• New Typing Module: A new file, qcore/typing.py, was introduced to define custom type variables (TNFloat, TFloat) for more precise type annotations.

Ignored Files

• Ignored by pattern: .github/workflows/** (1)
  • .github/workflows/types.yml

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[lispandfound]

The warnings deprecated function was replaced with the deprecated function from typing_extensions because the type checker complained that deprecated isn't in the warnings module for the lowest version of python we support (3.11 for this repo).

[gemini-code-assist]

Code Review

This pull request introduces extensive type hinting throughout the qcore library, significantly improving code clarity and enabling static analysis. It also refactors several parts of the code for better readability and adherence to PEP 8 standards. While these are great improvements, the PR also includes several breaking changes by removing functions from the public API (e.g., get_fault_bb_dir, transf, calc_backarc, dump_yaml, setup_dir, compare_versions). It would be beneficial to document these removals in the pull request description. I've identified a few critical bugs in the new distribution functions and a logic issue in ExtendedEnum that need to be addressed.

[Copilot]

Pull request overview

This PR introduces minimal type checking infrastructure and adds type annotations throughout the qcore codebase. The changes include adding a GitHub Actions workflow for type checking, introducing function overloads for better type safety in distribution functions with size/seed parameters, refactoring deprecated functions, and removing unused code.

Key changes:

• Added type annotations to function signatures across multiple modules
• Introduced overloads for distribution functions to properly type return values based on size parameter
• Added GitHub Actions workflow for type checking using ty
• Removed deprecated/unused functions and cleaned up code
• Added typing-extensions dependency for better compatibility

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
tests/test_xyts.py	Removed trailing blank line
tests/test_geo.py	Added type annotations and updated test values to use pytest.approx for floating-point comparisons; added unused Path import
tests/test_coordinates.py	Added type annotations to test functions; added unused re import
qcore/xyts.py	Added type annotations, renamed attributes (cosR→cos_r, etc.), added overloads for corners() method, added data validation checks; contains duplicate attribute definitions
qcore/utils.py	Deprecated load_yaml function, removed dump_yaml, setup_dir, and compare_versions functions
qcore/uncertainties/distributions.py	Added size and seed parameters to distribution functions with overloads for type safety; contains bugs in truncated_log_normal implementation
qcore/typing.py	New file with type variable definitions for numpy floating types
qcore/timeseries.py	Added type annotations, added type ignore for PyFFTW config, removed transf function
qcore/src_site_dist.py	Added type annotations and overloads for calc_rrup_rjb, removed calc_backarc function
qcore/siteamp_models.py	Added pragma: no cover directives for numba-compiled functions
qcore/simulation_structure.py	Added type annotations and simplified get_fault_yaml_path implementation
qcore/shared.py	Deprecated functions, changed IOBase to FileIO in type hints, added type ignore comments
qcore/point_in_polygon.py	Added type annotations using numpy typing
qcore/nhm.py	Added return type annotations
qcore/grid.py	Added type annotations, error handling for missing resolution parameter
qcore/geo.py	Updated type hints to use union syntax, improved closest_location return type
qcore/formats.py	Changed mutable default arguments to None, added type annotations and overloads
qcore/coordinates.py	Added type annotations, refactored variable names (cosA→cos_a, etc.)
qcore/constants.py	Added type annotations, improved is_substring safety
qcore/cli.py	Improved type annotations using ParamSpec and TypeVar
qcore/archive_structure.py	Added comprehensive docstrings and type annotations
pyproject.toml	Removed matplotlib dependency, added typing-extensions>=4.9.0
.github/workflows/types.yml	New workflow file for type checking with ty on Python 3.13

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.