Migrate to pyparsing 3.x and drop Python 2.7 support #337
Conversation
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
MOTIVATION
----------
Pyparsing 3.0 was released in 2021 and introduced PEP8-compliant naming
conventions for all methods and parameters (camelCase → snake_case). While
backward-compatible aliases were initially provided, pyparsing 3.3.0+ now
emits DeprecationWarnings for old names, and they will be removed in future
versions. This migration future-proofs pyhocon against breaking changes and
aligns the codebase with modern Python conventions.
Additionally, pyparsing 3.x requires Python 3.6.8+, allowing us to drop
Python 2.7 compatibility code and simplify the codebase.
HIGH-LEVEL CHANGES
------------------
1. Updated pyparsing dependency from '>=2,<4' to '>=3.0.0'
2. Dropped Python 2.7, 3.4, 3.5, 3.6 support (now requires Python 3.7+)
3. Updated all pyparsing method calls to PEP8 snake_case names
4. Updated all pyparsing parameter names to PEP8 conventions
5. Removed Python 2.x compatibility shims (basestring, unicode, urllib2, etc.)
6. Added support for Python 3.10, 3.11, 3.12, 3.13
DETAILED CHANGES
----------------
### setup.py
- Changed: 'pyparsing~=2.0;python_version<"3.0"' and 'pyparsing>=2,<4;python_version>="3.0"'
- To: 'pyparsing>=3.0.0' (unified version constraint)
- Removed Python 2.7, 3.4, 3.5, 3.6 from classifiers
- Added Python 3.10, 3.11, 3.12 to classifiers
### tox.ini
- Changed: envlist = flake8, py{27,38,39,310,311,312}
- To: envlist = flake8, py{37,38,39,310,311,312,313}
### pyhocon/config_parser.py
**Import changes:**
- replaceWith → replace_with
**Method name changes (all occurrences):**
- .parseString() → .parse_string()
- .setParseAction() → .set_parse_action()
- .setDefaultWhitespaceChars() → .set_default_whitespace_chars()
**Parameter name changes (all occurrences):**
- caseless=True → case_insensitive=True
- escChar='\' → esc_char='\'
- unquoteResults=False → unquote_results=False
- parseAll=True → parse_all=True
**Python 2.x compatibility removal:**
- Removed try/except blocks for basestring/unicode definitions
- Removed urllib2 fallback imports (now using urllib.request directly)
- Removed Python < 3.5 glob fallback
- Removed Python < 3.4 imp module fallback (now using importlib.util)
- Changed unicode() calls to str()
- Changed isinstance(x, unicode) to isinstance(x, str)
- Updated all docstring type annotations: basestring → str
### pyhocon/period_parser.py
**Method name changes:**
- .parseString() → .parse_string()
- .setParseAction() → .set_parse_action()
**Parameter name changes:**
- parseAll=True → parse_all=True
### pyhocon/config_tree.py
**Python 2.x compatibility removal:**
- Removed try/except block for basestring/unicode
- Changed unicode() calls to str()
- Changed ConfigUnquotedString parent class: unicode → str
- Updated all docstring type annotations: basestring → str
### pyhocon/converter.py
**Python 2.x compatibility removal:**
- Removed try/except block for basestring/unicode
- Changed isinstance(config, basestring) to isinstance(config, str)
- Updated all docstring type annotations: basestring → str
TESTING
-------
All 309 existing tests pass successfully with pyparsing 3.3.1.
No deprecation warnings are emitted when running the test suite.
CLI tool (pyhocon) verified working with new pyparsing version.
BACKWARD COMPATIBILITY
----------------------
This is a BREAKING CHANGE for users:
- Python 2.7 and Python 3.4-3.6 are no longer supported
- Users must upgrade to Python 3.7+ and pyparsing 3.0+
The pyhocon API itself remains unchanged - only internal implementation
and minimum version requirements have changed.
DOCUMENTATION
-------------
Added PYPARSING_MIGRATION_PLAN.md documenting the complete migration
strategy, including all API mappings and testing procedures.
Added CLAUDE.md providing guidance for AI assistants working with this
codebase.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Summary
This PR migrates pyhocon from pyparsing 2.x to pyparsing 3.x, updating all deprecated API calls to use PEP8-compliant naming conventions. As pyparsing 3.x requires Python 3.6.8+, this also removes Python 2.7 and EOL Python 3.x versions (3.4-3.6) support.
Motivation
DeprecationWarningfor old camelCase method names (e.g.,parseString,setParseAction)Changes Made
Dependency Updates
>=2,<4to>=3.0.0API Migrations (pyparsing 3.x)
Method Names (camelCase → snake_case):
parseString()→parse_string()setParseAction()→set_parse_action()setDefaultWhitespaceChars()→set_default_whitespace_chars()replaceWith()→replace_with()Parameter Names:
caseless=→case_insensitive=escChar=→esc_char=unquoteResults=→unquote_results=parseAll=→parse_all=Code Cleanup
basestring/unicodecompatibility shimsurllib2fallback (now usesurllib.requestdirectly)globfallbackimpmodule usage (now usesimportlib.util)strinstead ofunicode)Files Modified
setup.pytox.inipyhocon/config_parser.pypyhocon/period_parser.pypyhocon/config_tree.pypyhocon/converter.pyTesting
pyhoconcommand)Test Results
Breaking Changes⚠️
This PR introduces breaking changes for end users:
What Breaks
What Doesn't Break
ConfigFactory.parse_file()still works)Migration Guide for Users
For Users on Python 3.7+
No code changes required. Simply update dependencies:
For Users on Python 2.7 or 3.4-3.6
You must upgrade Python first:
Or pin to the last compatible version:
Release Notes Suggestion
Version: 0.4.0 (suggest major/minor bump due to breaking changes)
Breaking Changes
Changes
Improvements
Checklist
Additional Context
References