Skip to content

v1.4.0 - Comprehensive Package Enhancement and Tooling Migration

Choose a tag to compare

View all tags
@chrimaho chrimaho released this 13 Jul 05:02
· 80 commits to main since this release
v1.4.0
23f296f

📋 Overview

This release introduces significant enhancements to the toolbox-python package, including a new generators module, expanded validation capabilities, comprehensive docstring standards, and modernized CI/CD workflows. The changes span 30 commits across multiple areas of the codebase to improve functionality, maintainability, and developer experience while maintaining full backward compatibility.

🆕 New Modules and Core Functionality

Generators Module

  • New module: toolbox_python.generators - Provides functions for computing data on-the-fly based on input parameters rather than storing it in databases or files
  • New function: generate_group_cutoffs() - Divides a total number of items into specified groups, returning start and end indices for each group with proper validation and error handling
  • Documentation: Added comprehensive documentation with examples and complete test coverage

Enhanced Checkers Module

  • New constant: OPERATORS dictionary - Defines comparison operations for value validation including <, <=, >, >=, ==, !=, in, and not in
  • New function: is_valid_value() - Checks if a value is valid based on a specified operator and target value
  • New function: assert_is_valid_value() - Assert version of the validation function with proper error handling
  • Enhanced aliases: Added is_valid and assert_is_valid function aliases for consistency and convenience

Enhanced Strings Module

  • New function: str_to_list() - Converts strings to single-element lists while preserving other data types unchanged
  • Type safety: Includes comprehensive overloads and type hints for better development experience
  • Input flexibility: Provides a convenient way to normalize string inputs for functions that expect list-like objects

🔧 Function Enhancements and Type Safety

Improved Type Hints and Overloads

  • Enhanced overloads: Added @overload decorators for better type hints in:
    • toolbox_python.checkers.is_value_of_type() - Now properly handles both single types and tuple of types
    • toolbox_python.output.list_columns() - Distinguishes between print and return modes
    • toolbox_python.retry.retry() - Better handling of different parameter combinations
  • Type validation: Enhanced parameter validation across multiple functions using new assertion functions

Function Robustness Improvements

  • Parameter validation: Added comprehensive input validation using assert_is_valid functions to ensure type safety and value constraints
  • Error handling: Improved exception handling for the retry() function with better logging initialization and normalized exception parameter handling
  • Code structure: Better organization with descriptive comments separating validation, preparation, processing, and output phases
  • Column width logic: Simplified logic in list_columns() by replacing conditional assignment with min() function for cleaner code

📜 Package Scripts and Automation

Comprehensive Utility Scripts

  • Script module: src/utils/scripts.py - Extensive collection of utility functions organized into categories:
    • Syncing: uv_sync() for dependency management
    • Linting: run_black(), run_isort(), run_pycln(), run_pyupgrade(), run_blacken_docs(), and combined lint()
    • Checking: check_black(), check_mypy(), check_pytest(), check_codespell(), check_pylint(), and comprehensive check()
    • Git operations: add_git_credentials(), git_refresh_current_branch(), git_switch_to_main_branch(), git_add_coverage_report()
    • Documentation: docs_build_static(), docs_serve_versioned(), build_versioned_docs(), and version management

Project Scripts Configuration

  • Package scripts: Added extensive [project.scripts] table in pyproject.toml with organized sections:
    • Syncing: sync
    • Linting: run-black, run-isort, lint, lint-check
    • Checking: check-black, check-mypy, check-pytest, check-docstrings, check
    • Git: add-git-credentials, git-switch-to-main-branch, bump-version, git-update-version
    • Docs: docs-serve-static, build-versioned-docs, docs-check-versions
  • Enhanced version management: Updated src/utils/bump_version.py for better CLI compatibility and version tracking

📚 Docstring Standards and Validation

Automated Docstring Validation System

  • Validation infrastructure: Implemented comprehensive docstring checking with strict formatting requirements:
    • FunctionAndClassDetails() - Named tuple for tracking function and class details
    • check_docstrings_file() - Validates docstrings in individual files with detailed error reporting
    • _check_single_docstring() - Validates individual function/class docstrings against standards
    • _check_section_order() - Ensures proper section ordering (Summary → Params → Returns/Yields → Examples)
    • _validate_section_formats() - Validates specific section formats and content structure
    • check_docstrings_cli(), check_docstrings_all(), check_docstrings_dir() - Various checking interfaces

Enhanced Docstring Standards

  • Mandatory sections: Summary, Params, Returns/Yields, and Examples sections now required for all functions and classes
  • Format consistency: Fixed typos across all docstrings from !!! summary "Summary" to !!! note "Summary"
  • Examples improvements: Updated all code examples to use pycon syntax for better clarity and consistency
  • Type information: Enhanced Raises statements with proper exception types (e.g., TypeError, ValueError, LookupError) and detailed descriptions
  • Documentation quality: Improved parameter descriptions, return value specifications, and comprehensive usage examples

🚀 CI/CD Workflow Modernization

Migration to UV-Based Tooling

  • CI workflow: Complete refactoring of .github/workflows/ci.yml:
    • Replaced all make commands with uv run commands for improved consistency and performance
    • Added UV environment variables for optimal configuration
    • Streamlined dependency installation and checking processes
  • CD workflow: Comprehensive modernization of .github/workflows/cd.yml:
    • Replaced make commands with uv run commands throughout all jobs
    • Added environment variables for UV configuration (UV_LINK_MODE, UV_NATIVE_TLS, UV_NO_SYNC)
    • Improved git operations with new utility functions
    • Enhanced version management and tag handling
    • Fixed tag reference issues to ensure correct version numbers in releases
    • Streamlined package building and publishing processes

Enhanced Pre-commit Integration

  • Hook updates: Updated pre-commit hook versions for better compatibility:
    • Updated mypy from v1.15.0 to v1.16.1 with additional --allow-redefinition flag
    • Updated pyupgrade from v3.19.1 to v3.20.0
    • Updated uv-pre-commit from 0.6.12 to 0.7.20
    • Removed outdated poetry check hooks
  • New validation: Added check-docstrings hook for continuous validation during development workflow

⚙️ Configuration and Build System Updates

Project Configuration Enhancements

  • Build system: Migrated from hatchling to uv_build for better integration with UV toolchain and improved build reliability
  • MyPy configuration: Updated to include no-redef in disable_error_code list for better type checking compatibility
  • Dependencies: Added uv to the development dependency group for comprehensive toolchain integration
  • Python requirements: Updated syntax from ">3.9,<4.0" to ">=3.9,<4.0" for standard compliance

Documentation Configuration

  • MkDocs updates:
    • Added new generators module to navigation structure for complete module coverage
    • Fixed repository icon from material/gitlab to material/github for accurate branding
    • Enhanced navigation structure to reflect all available modules
  • Improved organization: Better categorization and presentation of module documentation

Enhanced Type System

  • Collection types: Expanded collection_types.py with new type aliases:
    • Added datetime collections: datetime_list, datetime_tuple, datetime_set, datetime_list_tuple
    • Added int collections: int_set, int_list_tuple
    • Enhanced dict collections: reorganized and added better documentation
    • Improved organization with clear section comments for better maintainability

🧪 Testing and Quality Assurance

Comprehensive Test Coverage

  • New test modules: Added extensive test coverage for new functionality:
    • src/tests/test_generators.py - Complete test suite for the generators module with edge cases
    • Enhanced src/tests/test_strings.py - Tests for new str_to_list() function with various input types
    • Expanded src/tests/test_checkers.py - Comprehensive tests for new validation functions including OPERATORS testing
  • Test improvements: Updated existing tests to use pytest.raises instead of pytest imports for better compatibility
  • Coverage maintenance: Maintained 100% test coverage across all modules while adding new functionality

Quality Improvements

  • Validation robustness: Enhanced function robustness through comprehensive parameter validation using new assertion functions
  • Error handling: Improved error capture and reporting in docstring checking with detailed feedback
  • Type safety: Better type hints and validation across the codebase with overloads and proper type checking
  • Code organization: Improved code structure with better separation of concerns and descriptive comments

🎯 Impact and Benefits

This release significantly enhances the toolbox-python package by:

  • Expanding core functionality with new modules and utilities that provide valuable data processing capabilities for on-demand computation
  • Improving developer experience through better type hints, comprehensive validation, standardized tooling, and automated quality checks
  • Enhancing code quality with comprehensive validation systems, consistent documentation standards, and robust error handling
  • Modernizing CI/CD with migration to UV-based tooling for better reliability, performance, and maintainability
  • Strengthening maintainability through comprehensive testing, automated docstring validation, and organized project scripts
  • Improving type safety with enhanced type hints, validation functions, and comprehensive overloads for better IDE support

💪 Pull Requests

  • Reorder classifiers and update Python requirement syntax in pyproject.toml by @chrimaho in #35
  • Comprehensive Package Enhancement and Tooling Migration with new modules, improved validation, and modernized CI/CD workflows by @chrimaho in #36

The changes maintain full backward compatibility while providing substantial improvements to functionality, developer experience, and project maintenance workflows. All existing APIs remain unchanged, ensuring seamless upgrades for existing users.

Full Changelog: v1.3.1...v1.4.0

Contributors

chrimaho
Assets 4
Loading