javaproperties

0.8.2 · active · verified Thu Apr 09

javaproperties is a Python library that provides comprehensive support for reading and writing Java `.properties` files, encompassing both the simple line-oriented format and XML. It offers a straightforward API inspired by Python's `json` module, alongside a `Properties` class designed to emulate the behavior of Java 8's `java.util.Properties` as closely as possible in Python. The library is actively maintained, with the latest version 0.8.2 released in December 2024, and its release cadence is irregular, with significant gaps between major versions.

Warnings

breaking Version 0.8.0 dropped support for Python 2.7, 3.4, and 3.5. Users on these Python versions must upgrade to Python 3.8+ (or 3.10+ for 0.8.2).
Fix: Upgrade your Python environment to 3.10 or newer. Check the PyPI page for the exact `Requires-Python` metadata if using older `javaproperties` versions.
breaking In version 0.7.0, the `javaproperties.parse()` function's return type changed from triples of strings to a generator of custom `PropertiesElement` objects. Code relying on the old return structure will break.
Fix: Update code to iterate over the `PropertiesElement` objects returned by `parse()` and access their attributes (e.g., `element.key`, `element.value`, `element.source`).
breaking As of version 0.5.0, parsing invalid `\uXXXX` escape sequences will now raise an `InvalidUEscapeError` instead of potentially silently failing or producing incorrect output.
Fix: Ensure that any input `.properties` files are correctly formatted, especially concerning Unicode escape sequences. Implement error handling for `InvalidUEscapeError` if processing untrusted input.
gotcha The command-line interface (CLI) tools (e.g., `javaproperties`, `json2properties`, `properties2json`) were split into a separate `javaproperties-cli` package as of version 0.4.0.
Fix: If you relied on the CLI tools, you need to install the `javaproperties-cli` package separately: `pip install javaproperties-cli`.
gotcha Starting with version 0.8.0, the `Properties` and `PropertiesFile` classes no longer explicitly raise `TypeError` when given non-string keys or values. The library now relies on static type checking to enforce type correctness.
Fix: Ensure all keys and values passed to `Properties` or `PropertiesFile` instances are strings. Utilize static type checkers (like MyPy) in your development workflow to catch type mismatches proactively.

Install

pip install javaproperties Install stable version

Imports

dumps
```
from javaproperties import dumps
```
Function to serialize a Python dict to a .properties string.
loads
```
from javaproperties import loads
```
Function to deserialize a .properties string to a Python dict.
dump
```
from javaproperties import dump
```
Function to serialize a Python dict to a file-like object.
load
```
from javaproperties import load
```
Function to deserialize a file-like object to a Python dict.
Properties
```
from javaproperties import Properties
```
Class mimicking Java's java.util.Properties, providing dictionary-like interface with additional methods.

Quickstart

This quickstart demonstrates how to use `javaproperties` to serialize Python dictionaries to Java `.properties` strings and files, and deserialize them back. It also shows the usage of the `Properties` class, which offers an API similar to Java's `java.util.Properties`.

import javaproperties
import io

# Example data to work with
data = {
    "key": "value",
    "host:port": "127.0.0.1:80",
    "snowman": "☃",
    "goat": "🐐",
    "multiline_value": "line1\\nline2"
}

# 1. Serialize a Python dictionary to a .properties string
print("--- DUMPING TO STRING ---")
properties_string = javaproperties.dumps(data, sort_keys=True, timestamp=None)
print(properties_string)

# 2. Deserialize a .properties string back to a Python dictionary
print("\n--- LOADING FROM STRING ---")
loaded_data_string = javaproperties.loads(properties_string)
print(loaded_data_string)

# 3. Serialize to a file-like object (using StringIO for demonstration)
print("\n--- DUMPING TO/LOADING FROM FILE ---")
with io.StringIO() as fp:
    javaproperties.dump(data, fp, sort_keys=True, timestamp=None, encoding='latin-1')
    fp.seek(0) # Rewind to beginning to read
    file_content = fp.read()
    print("File content:\n", file_content)

    fp.seek(0) # Rewind again for loading
    loaded_data_file = javaproperties.load(fp, encoding='latin-1')
    print("Loaded from file:", loaded_data_file)

# 4. Using the Properties class (Java-like interface)
print("\n--- USING PROPERTIES CLASS ---")
props = javaproperties.Properties()
props.update(data)
print(f"Properties object (dict-like): {props}")
print(f"Value for 'snowman': {props.get('snowman')}")

# Storing to a file with Properties class
with io.StringIO() as fp_props:
    props.store(fp_props, timestamp=None, encoding='latin-1')
    fp_props.seek(0)
    print("Properties class output:\n", fp_props.read())

view raw JSON →