v1.4.0 - Add Python 3.14 Support & Add Enhanced Checks

Summary

This release represents a significant evolution of the Docstring Format Checker package, delivering comprehensive improvements across multiple dimensions of code quality, compatibility, and maintainability. The release introduces official Python 3.14 support, achieving complete cross-version compatibility from Python 3.11 through 3.14. Major enhancements include a complete code refactoring achieving 100% test coverage (783 statements), standardisation of type annotations throughout the codebase, and integration of advanced code quality tools including pylint and complexipy for static analysis and complexity monitoring. The release also delivers seamless pre-commit hook integration, enabling automated docstring validation in development workflows. Critical Windows encoding issues have been resolved, ensuring consistent behaviour across all operating systems. These improvements establish a robust foundation for future development whilst maintaining backward compatibility with existing implementations.

Release Statistics

Attribute	Note
Version:	v1.4.0
Python Support:	3.9, 3.10, 3.11, 3.12, 3.13, 3.14
Test Coverage:	100% (783 statements)
Files Changed:	14
Lines Added:	2,918
Lines Removed:	403
Commits:	17

🐍 Python 3.14 Support

Overview

This release adds official support for Python 3.14, the latest Python version released in October 2024. The package now provides full compatibility across Python 3.11, 3.12, 3.13, and 3.14, ensuring users can leverage the latest Python features whilst maintaining support for earlier versions.

Implementation Details

The Python 3.14 support implementation includes:

• Updated GitHub Actions CI/CD workflows with Python 3.14 test matrix
• Verified compatibility with Python 3.14 standard library changes
• Validated all existing functionality against Python 3.14 runtime
• Updated package metadata in pyproject.toml to declare Python 3.14 support
• Comprehensive test execution across all supported Python versions

Technical Benefits

• Cross-Version Compatibility: The package maintains consistent behaviour across Python 3.11-3.14, allowing teams to upgrade Python versions without modifying their docstring validation configuration.
• Future-Proof Development: Early adoption of Python 3.14 ensures the package remains compatible with the latest language features and standard library improvements.
• Continuous Integration: Automated testing against all supported Python versions guarantees compatibility and prevents regression issues during development.

Usage Example

# Install with Python 3.14
python3.14 -m pip install docstring-format-checker

# Run with Python 3.14
python3.14 -m docstring_format_checker --check path/to/code

🔧 Code Refactoring and Architecture Improvements

Overview

The codebase has undergone comprehensive refactoring to improve maintainability, readability, and extensibility. This refactoring effort focused on modularising functionality, eliminating code duplication, standardising coding patterns, and enhancing error handling throughout the package.

Refactoring Achievements

• Modularisation: Core functionality has been reorganised into logical modules with clear separation of concerns. The cli.py, config.py, and core.py modules now follow single-responsibility principles, making the codebase easier to navigate and maintain.
• Code Deduplication: Identified and eliminated duplicate code patterns, consolidating common logic into reusable functions. This reduces maintenance burden and ensures consistent behaviour across the package.
• Enhanced Error Handling: Improved exception handling with custom exception classes in the utils/exceptions.py module. This provides more informative error messages and enables precise error recovery strategies.
• Documentation Improvements: Enhanced inline documentation and docstrings throughout the codebase, improving code comprehension for contributors and maintainers.

Technical Impact

The refactoring delivers:

• Reduced cyclomatic complexity in core functions
• Improved code navigation and IDE support
• Enhanced debugging capabilities through clearer stack traces
• Better alignment with Python best practices and PEP standards

🧪 100% Test Coverage Achievement

Overview

This release achieves complete test coverage with 100% code coverage across 783 statements in the core package. This milestone represents a comprehensive test suite that validates all code paths, edge cases, and error conditions throughout the package.

Testing Infrastructure

Coverage Statistics:

• Total Statements: 783
• Statements Covered: 783
• Coverage Percentage: 100%
• Test Framework: pytest
• Coverage Tool: coverage.py v7.11.0

Test Suite Expansion

The test suite has been significantly expanded with new test modules:

• test_config.py Enhancements: Added 133 lines of comprehensive configuration testing, validating:
  • Configuration file parsing and validation
  • Default configuration handling
  • Configuration override mechanisms
  • Invalid configuration error handling
  • Configuration merge strategies
• test_core.py Enhancements: Added 337 lines of core functionality testing, covering:
  • Docstring extraction and parsing
  • Format validation logic
  • Multi-style docstring support (Google, NumPy, Sphinx)
  • Error detection and reporting
  • Edge cases and boundary conditions
• test_cli.py Updates: Enhanced CLI testing to validate:
  • Command-line argument parsing
  • Exit code handling
  • Output formatting
  • Error message presentation

Quality Assurance Benefits

• Regression Prevention: Complete test coverage ensures that code changes cannot inadvertently break existing functionality without detection.
• Confidence in Refactoring: Developers can confidently refactor code knowing that the comprehensive test suite will catch any behavioural changes.
• Documentation Through Tests: The test suite serves as executable documentation, demonstrating expected behaviour for all package features.
• Continuous Quality Monitoring: Automated test execution in CI/CD pipelines maintains quality standards across all contributions.

Running the Test Suite

# Run full test suite with coverage
uv run pytest --config-file=pyproject.toml --cov-report=term-missing

# Run tests for specific module
uv run pytest src/tests/test_core.py

# Generate HTML coverage report
uv run pytest --config-file=pyproject.toml --cov-report=html

📋 Pylint Integration and Code Quality Standards

Overview

This release integrates pylint as a static analysis tool, establishing comprehensive code quality standards and automated linting checks. The pylint configuration enforces consistent coding style, detects potential bugs, and identifies code smells throughout the codebase.

Pylint Configuration

A comprehensive pylint configuration has been added to pyproject.toml, including:

• Enabled Checks:

  • Code style consistency (PEP 8 compliance)
  • Unused import detection
  • Variable naming conventions
  • Function complexity limits
  • Documentation completeness
  • Potential bug patterns

• Disabled Checks:

  • Selectively disabled checks that conflict with project-specific requirements or generate false positives in the codebase.

• Custom Settings:

  • Tailored scoring thresholds and error severity levels to match project quality standards.

Code Quality Improvements

The pylint integration has driven improvements in:

• Naming Conventions: Standardised variable, function, and class naming according to Python conventions.
• Import Organisation: Cleaned up import statements, removing unused imports and organising imports logically.
• Code Complexity: Refactored complex functions to reduce cyclomatic complexity and improve maintainability.
• Documentation Standards: Ensured all public functions, classes, and modules have appropriate docstrings.

Usage in Development Workflow

# Run pylint on entire codebase
pylint src/docstring_format_checker

# Run pylint with custom configuration
pylint --rcfile=pyproject.toml src/docstring_format_checker

# Check specific file
pylint src/docstring_format_checker/core.py

# Generate detailed report
pylint --output-format=text src/docstring_format_checker > pylint-report.txt

Integration with CI/CD

The pylint checks are integrated into the CI/CD pipeline, automatically validating code quality on every pull request and commit. This ensures that code quality standards are maintained consistently across all contributions.

🔗 Pre-Commit Hook Integration

Overview

This release introduces seamless integration with pre-commit hooks through a new .pre-commit-hooks.yaml configuration file. This enables automatic docstring validation before commits, preventing invalid docstrings from entering the codebase.

Pre-Commit Configuration

The .pre-commit-hooks.yaml file defines a hook for the Docstring Format Checker:

- id: docstring-format-checker
  name: Docstring Format Checker
  description: Validate Python docstring formats
  entry: docstring-format-checker
  language: python
  types: [python]

Integration Steps

Add the Docstring Format Checker to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/data-science-extensions/docstring-format-checker
    rev: v1.4.0
    hooks:
      - id: docstring-format-checker
        args: ['--config-file=.dfc.yaml']

Workflow Integration

• Automated Validation: Pre-commit hooks automatically run before each commit, validating docstrings in changed files.
• Early Error Detection: Catches docstring format issues before code review, reducing feedback cycles and maintaining code quality standards.
• Customisable Configuration: Supports passing configuration arguments to the hook, enabling project-specific docstring validation rules.
• Fast Execution: Only checks files staged for commit, ensuring quick feedback without slowing down development workflow.

Development Workflow Example

# Install pre-commit hooks
pre-commit install

# Manually run hooks on all files
pre-commit run --all-files

# Run hooks on specific files
pre-commit run --files src/docstring_format_checker/core.py

# Update hooks to latest versions
pre-commit autoupdate

⚙️ Configuration and Workflow Enhancements

Overview

This release delivers multiple configuration and workflow improvements, including enhanced DFC configuration capabilities, CHANGELOG formatting updates, changelog generation refactoring, and integration of workflow automation tools.

DFC Configuration Updates

Enhanced the Docstring Format Checker configuration system with:

• Improved Validation: More robust configuration file parsing with better error messages for invalid configurations.
• Default Value Handling: Refined default configuration values to provide sensible defaults whilst maintaining flexibility.
• Configuration Merging: Enhanced logic for merging project-specific configurations with package defaults.

CHANGELOG Formatting

Updated CHANGELOG.md formatting to improve readability and maintainability:

• Consistent Structure: Standardised changelog entry format across all versions, making it easier to track changes over time.
• Emoji Section Headers: Added emoji-prefixed H3 headers for visual scanning of changelog sections.
• Enhanced Descriptions: Improved change descriptions with more context and technical details.

Changelog Generation Refactoring

Refactored the changelog generation utility (src/utils/changelog.py) to improve:

• Automation Capabilities: Enhanced scripts to automatically generate changelog entries from commit messages and pull request descriptions.
• Template Consistency: Standardised changelog entry templates to ensure consistent formatting across releases.
• Git Integration: Improved integration with git commands to extract commit information and generate accurate changelog content.

Workflow Script Updates

Updated workflow scripts in src/utils/scripts.py to include:

• DFC Integration: Added Docstring Format Checker to automated checking scripts, ensuring docstring validation is part of the standard workflow.
• Enhanced Error Handling: Improved error reporting in workflow scripts to provide clearer feedback when checks fail.

Usage Example

# Run automated workflow checks (includes DFC)
python src/utils/scripts.py check

# Generate changelog entries for new release
python src/utils/changelog.py generate --version v1.4.0

📊 Complexity Monitoring with Complexipy

Overview

This release integrates complexipy, a modern Python complexity analysis tool, to monitor and maintain code complexity standards. This integration provides automated complexity metrics and helps prevent the introduction of overly complex code that is difficult to maintain.

Complexipy Integration

• Automated Analysis: Complexipy runs as part of the CI/CD pipeline, analysing code complexity on every commit and pull request.
• Complexity Metrics: Tracks cyclomatic complexity, cognitive complexity, and other maintainability metrics across the codebase.
• Threshold Enforcement: Configurable complexity thresholds prevent merging code that exceeds acceptable complexity limits.

Complexity Standards

The project enforces the following complexity standards:

• Function Complexity: Maximum cyclomatic complexity of 10 for individual functions, encouraging simple, focused functions.
• Class Complexity: Maximum average complexity of 8 across all methods in a class.
• Module Complexity: Overall module complexity limits to maintain manageable file sizes.

Benefits of Complexity Monitoring

• Maintainability: Lower complexity code is easier to understand, modify, and extend, reducing long-term maintenance costs.
• Bug Prevention: Complex code correlates with higher bug rates. Complexity limits reduce the likelihood of introducing bugs.
• Code Review Efficiency: Reviewers can focus on logic and design rather than untangling complex code structures.
• Refactoring Signals: Complexity metrics identify code that would benefit from refactoring before it becomes a maintenance burden.

Usage in Development

# Analyse complexity of entire codebase
complexipy src/docstring_format_checker

# Check specific file
complexipy src/docstring_format_checker/core.py

# Generate complexity report
complexipy --output=json src/docstring_format_checker > complexity-report.json

🖥️ Windows Encoding Compatibility

Overview

This release resolves critical Windows encoding issues that caused test failures on Windows operating systems. The Windows platform uses cp1252 (Western European) encoding by default, which lacks support for Unicode characters including emojis and extended ASCII art used by pyfiglet. These encoding mismatches caused both output encoding errors and input decoding errors during test execution.

Root Cause Analysis

• Windows Default Encoding: Windows uses cp1252 encoding by default for console I/O operations, limiting character support to Western European characters.
• Unicode Requirements: The package uses Unicode characters including:
  • Checkmark emoji (✅, U+2705) in success messages
  • ASCII art from pyfiglet containing extended character sets
• Subprocess Encoding: Python's subprocess.run() with text=True inherits the system default encoding, causing encoding/decoding failures on Windows.

Solution Implementation

The encoding issues have been resolved by adding the PYTHONIOENCODING environment variable to CI/CD workflows:

.github/workflows/ci.yml Update:

env:
  PYTHONIOENCODING: utf-8

.github/workflows/cd.yml Update:

env:
  PYTHONIOENCODING: utf-8

How PYTHONIOENCODING Resolves Both Issues

• Environment Variable Inheritance: PYTHONIOENCODING=utf-8 is inherited by all Python processes and subprocesses, ensuring consistent UTF-8 encoding throughout the execution chain.
• Output Encoding Fix: Forces Python to encode all output (including emoji characters) as UTF-8, preventing UnicodeEncodeError when writing to stdout/stderr.
• Input Decoding Fix: Forces Python to decode all input (including pyfiglet ASCII art) as UTF-8, preventing UnicodeDecodeError when reading from subprocess stdout.
• Cross-Platform Consistency: Ensures identical encoding behaviour across Windows, Linux, and macOS, eliminating platform-specific bugs.

Error Examples Resolved

Before Fix - Output Encoding Error:

UnicodeEncodeError: 'charmap' codec can't encode character '\u2705' 
in position 42: character maps to <undefined>

Before Fix - Input Decoding Error:

UnicodeDecodeError: 'charmap' codec can't decode byte 0x90 
in position 156: character maps to <undefined>

After Fix:

Both errors resolved - all tests pass on Windows with consistent UTF-8 encoding.

Technical Benefits

• Cross-Platform Compatibility: Ensures consistent behaviour across all operating systems, eliminating Windows-specific test failures.
• Unicode Support: Full Unicode character support enables use of emojis, international characters, and extended ASCII art in output.
• Developer Experience: Windows developers can run tests locally without encountering encoding-related failures.
• CI/CD Reliability: Windows CI/CD pipelines now execute reliably without encoding-related test failures.

Testing and Validation

The encoding fixes have been validated through:

• Windows CI Pipeline: All tests pass on Windows Server with Python 3.11-3.14.
• Emoji Output Testing: Success messages with checkmark emoji display correctly on Windows.
• Pyfiglet Integration: ASCII art generation and rendering work correctly on Windows.
• Subprocess Testing: Subprocess execution with text=True handles UTF-8 encoding/decoding correctly.

🔄 Additional Improvements

Merge Strategy

All 17 commits have been merged via pull request #18, maintaining a clean git history and ensuring all changes passed CI/CD validation before integration.

Coverage Tool Update

Updated coverage.py from v7.10.6 to v7.11.0, benefiting from:

• Performance improvements in coverage analysis
• Enhanced HTML report generation
• Bug fixes in coverage measurement accuracy

Documentation Updates

• CHANGELOG.md Expansion: Added 1,853 lines documenting all changes since v1.3.0 with comprehensive release notes.
• Code Documentation: Enhanced inline documentation and docstrings throughout refactored code.
• Contributing Guidelines: Updated CONTRIBUTING.md with new development workflow requirements including pre-commit hooks and quality tools.

📦 Installation and Upgrade

Installing v1.4.0

# Install from PyPI
pip install docstring-format-checker==1.4.0

# Install with uv (recommended)
uv pip install docstring-format-checker==1.4.0

# Install from source
git clone https://github.com/data-science-extensions/docstring-format-checker.git
cd docstring-format-checker
git checkout v1.4.0
uv pip install -e .

Upgrading from v1.3.0

# Upgrade with pip
pip install --upgrade docstring-format-checker

# Upgrade with uv
uv pip install --upgrade docstring-format-checker

Compatibility Notes

• Breaking Changes: None. Version 1.4.0 maintains full backward compatibility with v1.3.0 configuration files and usage patterns.
• Configuration Migration: No configuration changes required when upgrading from v1.3.0.
• Python Version Requirements: Python 3.11 or higher required (unchanged from v1.3.0).

💪 Pull Requests

• Comprehensive Code Quality Enhancement: Python 3.14 Support, Refactoring, and 100% Test Coverage by @chrimaho in #18

---

Full Changelog: v1.3.0...v1.4.0