python-jproperties

jProperties brings Java’s Properties file format to Python, letting code load and save .properties files the same way a JVM application would — including line continuation, colon/equals separators, and both ISO-8859-1 and UTF-8 encodings. The Properties class implements Python’s MutableMapping so it behaves like a dict while still round-tripping original key order and comments when a file is re-saved.

Beyond basic parsing, jProperties supports per-key metadata (arbitrary key/value pairs attached to a property via special #: comment lines) and an opt-in docstring mode that turns ordinary comments preceding a key into retrievable documentation. This makes it useful not just for reading configuration but for tooling that needs to inspect, annotate, or regenerate Java-style property files from Python, such as build scripts, localization pipelines, or config migration tools bridging Java and Python systems.

What You Get

• A Properties class implementing Python’s MutableMapping, so property files behave like a normal dict
• Full Java .properties grammar support: line continuation, :/= separators, comment lines, and escape sequences (\n, \t, \uXXXX, surrogate pairs)
• Per-key metadata via #: comment lines, readable/writable through getmeta()/setmeta() without polluting the property values themselves
• Optional metadoc=True mode that captures plain comments preceding a key as a _doc metadata field for self-documenting property files
• Configurable encoding on both load and store (defaults to iso-8859-1 to match the Java spec, but any Python codec works, e.g. utf-8)
• A bundled propconv CLI script for converting a property file between encodings from the command line

Common Use Cases

• Reading Java application config (.properties files) from a Python-based deployment or ops tool
• Writing property files that a downstream Java process will consume, preserving Java-compatible escaping
• Round-tripping property files in config-migration or localization tooling where key order and comments must survive edits
• Attaching structured metadata (severity, doc strings) to individual keys for tooling that generates documentation from property files

Under The Hood

Architecture The entire library lives in a single module, jproperties.py, built around one Properties class that subclasses MutableMapping. Parsing is a hand-rolled character-at-a-time reader (_peek/_getc/_handle_eol/_skip_whitespace) feeding _parse_key/_parse_value/_parse_comment, which are chained together by _parse_logical_line and _parse. Parser state (source stream, line number, one-character lookahead, key order, pending metadata) lives directly on the instance and is reset via reset()/clear(), so one object can parse multiple files without losing previously accumulated properties. There is no separate parser/model split — reading, writing, and the public dict-like interface are all fused into one class, so any change to escape handling touches both load() and store() simultaneously.

Tech Stack The implementation is pure standard library (codecs, functools, itertools, re, struct, time, collections.namedtuple) plus a single third-party dependency, six, kept only for Python 2/3 compatibility helpers even though the project’s classifiers now declare Python 3-only support (a TODO in pyproject.toml notes it should eventually be dropped). Packaging uses setuptools with setuptools_scm for git-tag-derived dynamic versioning, and the only build artifact beyond the library itself is a console-script entry point (propconv) for command-line encoding conversion. There is no web framework, database, or external service dependency of any kind.

Code Quality Eleven pytest modules cover escaping, line continuation, encodings, metadata, docstring extraction, missing keys/values, repeated keys, and UTF-16 surrogate pairs, run through tox across Python 3.8-3.12 on both Ubuntu and macOS with branch coverage enabled via pytest-cov — a thorough, edge-case-aware suite for a small parser. There are no PEP 484 type hints (docstrings instead use older Sphinx-style :type:/:param: tags) and no linter or formatter configuration is checked in, though GitHub’s CodeQL security scan runs on every push and pull request.

What Makes It Unique jProperties’ core value is faithfully reproducing Java’s Properties file semantics in Python rather than treating .properties as a generic key=value format — it matches Java’s exact escaping rules, including \uXXXX unicode escapes with correct UTF-16 surrogate-pair handling for characters outside the Basic Multilingual Plane. On top of that it layers a metadata mechanism (#: comment lines, plus an opt-in mode that captures ordinary comments as documentation) that has no equivalent in Java’s own implementation, letting Python tooling attach structured, queryable metadata to individual properties. It is a narrow, well-executed niche rather than a broadly novel architecture.