Java Property file parser and writer for Python

Warnings

• breaking Version 2.1.2 is the last version to support Python 2.7. Subsequent versions (post 2.1.2) drop support for Python versions older than 3.8. Ensure your Python environment meets the required version for the specific `jproperties` release you are using.
  Fix: Upgrade to Python 3.8 or newer, or pin `jproperties<2.1.3` for Python 2.7 compatibility.
• gotcha The `store()` method, by default, does not write out metadata associated with properties. To include metadata in the output file, you must explicitly set `strip_meta=False` when calling `store()`.
  Fix: When calling `p.store(file_obj, comments, strip_meta=False)`, ensure `strip_meta=False` is passed if metadata persistence is desired.
• gotcha Directly modifying or deleting key-value pairs via the internal `prop_obj.properties` dictionary (e.g., `del prop_obj.properties[key]`) will NOT remove any associated metadata. To ensure metadata is also removed, always use the dictionary-like access on the `Properties` object itself (e.g., `del prop_obj[key]`).
  Fix: Use `del prop_obj[key]` to delete a property and its metadata, or `prop_obj[key] = value` or `prop_obj[key] = value, metadata` to set values with or without updating metadata.
• gotcha The `jproperties` library does not support the XML property file format used by Java's `Properties` class. It specifically targets the plain text `.properties` file format. If you need XML support, consider alternative libraries like `javaproperties`.
  Fix: Use the plain text `.properties` format or choose a different library (e.g., `javaproperties`) if XML format is required.
• gotcha When iterating over a `Properties` object (e.g., `for key in p:`), only the keys are returned. Associated metadata is not included. To retrieve metadata for a specific key, you must access it using `value, metadata = p[key]` or `p.getmeta(key)`.
  Fix: Use `value, metadata = p[key]` for paired access or `p.getmeta(key)` to retrieve metadata explicitly.

Install

• pip install jproperties Install jproperties

Imports

• Properties

  from jproperties import Properties

Quickstart

This quickstart demonstrates how to create a `.properties` file, load its contents into a `jproperties.Properties` object, access property values (including their associated metadata), modify and add new properties, and then store the updated properties back to a file. It highlights the use of `iso-8859-1` encoding, which is common for Java properties files.

import os
from jproperties import Properties

# 1. Define a .properties file content
props_content = '''\
# My Application Configuration
app.name=MyApp
app.version=1.0.0
app.env=development
# _some_meta=value
db.host=localhost
db.port=5432
'''

# 2. Write it to a temporary file
prop_file_path = "config.properties"
with open(prop_file_path, "wb") as f:
    # jproperties expects bytes, often iso-8859-1 for Java properties
    f.write(props_content.encode('iso-8859-1'))

# 3. Load the properties
p = Properties()
with open(prop_file_path, "rb") as f:
    p.load(f, "iso-8859-1") # Specify encoding, defaults to iso-8859-1

# 4. Access values
app_name, app_name_meta = p["app.name"]
print(f"App Name: {app_name} (Metadata: {app_name_meta})")

db_host, db_host_meta = p["db.host"]
print(f"DB Host: {db_host} (Metadata: {db_host_meta})")

# 5. Modify / Add properties (with metadata)
p["app.version"] = "1.1.0", {"last_updated": "2026-04-10"}
p["new.setting"] = "some_value"

# 6. Store properties to a new file (including metadata)
out_prop_file_path = "config_updated.properties"
with open(out_prop_file_path, "wb") as f:
    p.store(f, "Updated Configuration", timestamp=False, strip_meta=False)

print(f"\nUpdated configuration written to: {out_prop_file_path}")

# Clean up temporary files
os.remove(prop_file_path)
os.remove(out_prop_file_path)