PyInstaller Compatibility Issue: Missing dateparser_tz_cache.pkl in Frozen Applications

Summary

#1250 introduced a new data file dateparser/data/dateparser_tz_cache.pkl that is not automatically included when freezing applications with PyInstaller, causing runtime failures in previously working deployments.

Problem Description

The introduction of the timezone cache file dateparser/data/dateparser_tz_cache.pkl in #1250 has created a breaking change for users who package their applications using PyInstaller. This file is not automatically detected and included by PyInstaller's dependency analysis, resulting in FileNotFoundError exceptions when the frozen application attempts to access the cache file.

• https://github.com/aws/aws-sam-cli/issues/8139
• https://github.com/aws/aws-sam-cli/issues/8140
• https://github.com/aws/aws-sam-cli/issues/8141
• https://github.com/aws/aws-sam-cli/issues/8143

Steps to Reproduce

1. Create a Python application that uses dateparser
2. Package the application using PyInstaller:

   pyinstaller --onefile your_app.py
   

3. Run the frozen executable
4. Observe the runtime error when dateparser attempts to access the cache file

Expected Behavior

The frozen application should work without additional configuration, maintaining backward compatibility with existing PyInstaller workflows.

Actual Behavior

The application fails at runtime with a FileNotFoundError when trying to access dateparser/data/dateparser_tz_cache.pkl.

Current Workaround

Users must manually configure PyInstaller to include the data file by:

1. Creating a PyInstaller hook file or
2. Using the --add-data flag:

   pyinstaller --add-data "path/to/dateparser/data/dateparser_tz_cache.pkl:dateparser/data/" your_app.py
   

3. Or adding the file to a custom hook in their build process
4. Or revert back to 1.2.1

Impact Assessment

This change breaks existing production deployments and CI/CD pipelines that use PyInstaller without warning. Users upgrading dateparser may experience unexpected deployment failures.

Suggested Solutions

Short-term

1. Documentation Update: Add clear instructions in the README and documentation about PyInstaller compatibility requirements
2. PyInstaller Hook: Include a proper PyInstaller hook file (hook-dateparser.py) in the package to automatically handle data file inclusion
3. Runtime Fallback: Implement graceful fallback behavior when the cache file is missing

Long-term

1. Version Bump Consideration: This type of breaking change typically warrants a major version increment to signal potential compatibility issues to users

Proposed PyInstaller Hook

# hook-dateparser.py
from PyInstaller.utils.hooks import collect_data_files

datas = collect_data_files('dateparser')

Environment

• dateparser version: 1.2.2
• PyInstaller version: [various versions affected]
• Python version: [various versions]
• Operating System: Linux

Reproduce the failure with the PyInstaller command from the issue and inspect dateparser/data/dateparser_tz_cache.pkl plus the proposed hook-dateparser.py approach. Done means a frozen application can access the cache file without manual --add-data configuration, with the README or documentation explaining any remaining packaging requirements.