Comprehensive Package Enhancement and Tooling Migration with new modules, improved validation, and modernized CI/CD workflows#36
Merged
Conversation
- Added `OPERATORS` constant dictionary to define comparison operations. - Introduced `is_valid_value` and `assert_is_valid_value` functions for value validation based on operators. - Updated documentation in `checkers.md` to include new functions and constants. - Enhanced test coverage in `test_checkers.py` for the new validation functions. - Improved docstrings across all functions
…clarity, and refine the `Raises` statements
… to better enhance type hints in the `output` and `retry` modules
- Introduces a new utility function that converts strings to single-element lists while preserving other data types unchanged. - This enhancement provides a convenient way to normalize string inputs for functions that expect list-like objects, improving code flexibility when handling mixed input types. - Includes comprehensive test coverage with parameterized tests for various input scenarios including strings, lists, tuples, sets, dictionaries, and numeric types.
…cture with better comments - Enhances function robustness by adding comprehensive parameter validation using assertion functions to ensure type safety and value constraints. - Improves code readability through better organization with descriptive comments that clearly separate validation, preparation, processing, and output phases. - Simplifies column width logic by replacing conditional assignment with `min()` function for cleaner code.
…ng initialization - Normalizes exceptions parameter to always be a tuple for consistent handling regardless of input type. - Moves log variable initialization outside conditional block to improve code clarity and ensure proper variable scope.
- Introduces a new generators module that provides functions for computing data on-the-fly based on input parameters rather than storing it in databases or files. - Includes new `generate_group_cutoffs()` function that divides a total number of items into specified groups, returning start and end indices for each group with proper validation and error handling. - Updates documentation to include the new module in the main index with comprehensive description and examples.
- Implements automated docstring checking with strict formatting requirements including mandatory Summary, Params, Returns/Yields, and Examples sections. - Add custom `pre-commit` hook integration for continuous validation during development workflow. - Update existing docstrings to comply with new validation standards and fixes inconsistent section formatting across multiple modules.
-> From `!!! summary "Summary"` -> To `!!! note "Summary"`
…mands for installations and checks
…andle `git` and `docs` processes
- Change from `cli.scripts:...` to `utils:scripts:...` - Reorder in to sections: `Syncing`, `Linting`, `Checking` - Add new sections: `Git`, `Docs`
…mands for improved consistency and performance
…import ...` for improved consistency
Contributor
There was a problem hiding this comment.
Pull Request Overview
This PR expands the toolbox-python package with new generation utilities, enhanced validation and type safety, and modernizes development workflows.
- Introduces a new
generatorsmodule withgenerate_group_cutoffsand input assertions - Enhances core modules (
checkers,retry,output) with overloads, assertion-based validation, and improved docstring formatting - Migrates CLI scripts, pre-commit hooks, and GitHub CI/CD from Make and Hatch to the UV toolchain
Reviewed Changes
Copilot reviewed 30 out of 31 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| src/utils/scripts.py | Added UV-based CLI utility scripts for syncing, linting, checking, docs, and Git operations |
| src/utils/bump_version.py | Extracted configuration and update logic into get_config/update_files, exposed main |
| src/toolbox_python/generators.py | New generate_group_cutoffs function with type-checked input validation |
| src/toolbox_python/retry.py | Refactored retry decorator with overloads, assertions for parameters, and precise returns |
| src/toolbox_python/output.py | Added overloads for list_columns, input assertions, and streamlined spacing calculations |
| src/toolbox_python/checkers.py | Introduced OPERATORS, is_valid_value/assert_is_valid_value, and consolidated checks |
| pyproject.toml | Migrated project scripts to uv run commands, updated build backend to uv_build |
| .github/workflows/ci.yml & cd.yml | Replaced all make commands with uv run commands and added UV environment variables |
Comments suppressed due to low confidence (1)
src/utils/scripts.py:1
- [nitpick] The new utility scripts in
src/utils/scripts.pycurrently have no dedicated tests. Consider adding tests to verify key commands and improve maintainability.
## --------------------------------------------------------------------------- #
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
📋 Overview
This comprehensive pull request introduces significant enhancements to the
toolbox-pythonpackage, including a newgeneratorsmodule, expanded validation capabilities, improved docstring standards, and modernized CI/CD workflows. The changes span 24 commits and touch multiple areas of the codebase to improve functionality, maintainability, and developer experience.🆕 New Modules and Functions
Generators Module
toolbox_python.generators- Provides functions for computing data on-the-fly based on input parameters rather than storing it in databases or filesgenerate_group_cutoffs()- Divides a total number of items into specified groups, returning start and end indices for each group with proper validation and error handlingEnhanced Checkers Module
OPERATORSdictionary - Defines comparison operations for value validationis_valid_value()- Checks if a value is valid based on a specified operator and target valueassert_is_valid_value()- Assert version of the validation function with proper error handlingis_validandassert_is_validfunction aliases for consistencyEnhanced Strings Module
str_to_list()- Converts strings to single-element lists while preserving other data types unchanged🔧 Function Enhancements and Type Safety
Improved Type Hints
@overloaddecorators for better type hints in:toolbox_python.checkers.is_value_of_type()- Now properly handles both single types and tuple of typestoolbox_python.output.list_columns()- Distinguishes between print and return modestoolbox_python.retry.retry()- Better handling of different parameter combinationsImproved Function Robustness
assert_is_validfunctionsretry()function with better logging initialization📜 Package Scripts and Automation
New Utility Scripts
src/utils/scripts.py- Comprehensive collection of utility functions for:uv_sync()for dependency managementrun_black(),run_isort(),run_pycln(),run_pyupgrade(), etc.check_black(),check_mypy(),check_pytest(), etc.add_git_credentials(),git_refresh_current_branch(), etc.docs_build_static(),docs_serve_versioned(), etc.Project Scripts Configuration
[project.scripts]table inpyproject.tomlwith organized sections:syncrun-black,run-isort,lint, etc.check-black,check-mypy,check, etc.add-git-credentials,git-switch-to-main-branch, etc.docs-serve-static,build-versioned-docs, etc.📚 Docstring Standards and Validation
Comprehensive Docstring Validation System
FunctionAndClassDetails()- Named tuple for tracking function and class detailscheck_docstrings_file()- Validates docstrings in individual files_check_single_docstring()- Validates individual function/class docstrings_check_section_order()- Ensures proper section ordering_validate_section_formats()- Validates specific section formatscheck_docstrings_cli(),check_docstrings_all(),check_docstrings_dir()- Various checking interfacesEnhanced Docstring Standards
!!! summary "Summary"to!!! note "Summary"pyconsyntax for better clarityRaisesstatements with proper exception types and descriptions🚀 CI/CD Workflow Modernization
Migration to UV Commands
makecommands withuv runcommands in.github/workflows/ci.ymlfor improved consistency and performance.github/workflows/cd.yml:makecommands withuv runcommands throughoutPre-commit Integration
mypyfrom v1.15.0 to v1.16.1pyupgradefrom v3.19.1 to v3.20.0uv-pre-commitfrom 0.6.12 to 0.7.20check-docstringshook for continuous validation--allow-redefinitionflag to mypy configuration⚙️ Configuration and Build System Updates
Project Configuration
pyproject.tomlto includeno-redefindisable_error_codelisthatchlingtouv_buildfor better integration with UV toolchainuvto the development dependency group for better toolchain integrationDocumentation Configuration
generatorsmodule to navigation structurematerial/gitlabtomaterial/githubGit Management
🧪 Testing and Quality Assurance
Enhanced Test Coverage
src/tests/test_generators.py- Tests for the generators modulesrc/tests/test_strings.py- Tests for new string functionssrc/tests/test_checkers.py- Tests for new validation functionsQuality Improvements
🎯 Impact and Benefits
This release significantly enhances the
toolbox-pythonpackage by:The changes maintain backward compatibility while providing substantial improvements to functionality, developer experience, and project maintenance workflows.