jProperties for Python

jProperties is a Java Property file parser and writer for Python. It aims to provide the same functionality as Java's Properties class, although currently the XML property format is not supported.

Table of Contents

• 1   Installation
  • 1.1   GPG-signed Git release tags
• 2   Overview
  • 2.1   Parsing a property file
  • 2.2   Writing a property file
  • 2.3   Reading from and writing to the same file-like object
• 3   Special features
  • 3.1   Metadata
    • 3.1.1   Documenting Properties
    • 3.1.2   Caveats
  • 3.2   Setting defaults
  • 3.3   Development
• 4   Version history

1   Installation

You can install jProperties using pip:

pip install jproperties

1.1   GPG-signed Git release tags

From version 2.1.2 and newer, all Git release tags such as v2.1.2 are signed with the following GPG key:

• User ID: Tilman Blumenbach <tilman+git@ax86.net>
• Fingerprint: B67BD719C23DC2A403E15EB102DE477F6DDE8B17
• Download: Use any major PGP keyserver or https://www.ax86.net/attachments/pgp-key.asc

2   Overview

Objects of the type Properties can be used like a Python dictionary (but see Caveats below). The load() method populates the object by parsing input in the Java Property file format; the store() method writes the key-value pairs stored in the object to a stream in the same format.

The load() and store() methods both take an encoding parameter. By default this is set to iso-8859-1, but it can be set to any encoding supported by Python, including e. g. the widely used utf-8.

2.1   Parsing a property file

from jproperties import Properties

p = Properties()
with open("foobar.properties", "rb") as f:
    p.load(f, "utf-8")

That's it, p now can be used like a dictionary containing properties from foobar.properties.

2.2   Writing a property file

from jproperties import Properties

p = Properties()
p["foobar"] = "A very important message from our sponsors: Python is great!"

with open("foobar.properties", "wb") as f:
    p.store(f, encoding="utf-8")

2.3   Reading from and writing to the same file-like object

from jproperties import Properties

with open("foobar.properties", "r+b") as f:
    p = Properties()
    p.load(f, "utf-8")

    # Do stuff with the p object...

    f.seek(0)
    f.truncate(0)
    p.store(f, encoding="utf-8")

3   Special features

3.1   Metadata

The property file parser supports including programmatically readable and settable metadata in property files. Metadata for a key is represented as a Python dictionary; the keys and values of this dictionary should be strings, although when the property file is written, all non-string objects will be converted to strings. This is a one-way conversion; when the metadata is read back again during a load(), all keys and values will be treated as simple strings.

By default, the store() method does not write out the metadata. To enable that feature, set the keyword argument strip_meta=False when calling the method.

Note that metadata support is always enabled. The only thing that is optional is actually writing out the metadata.

Metadata keys beginning with two underscores (__) are not written to the output stream by the store() method. Thus, they can be used to attach "runtime-only" metadata to properties. Currently, however, metadata with such keys is still read from the input stream by load(); this should probably be considered erroneous behaviour.

3.1.1   Documenting Properties

The comments after a property definition can be added to the metadata with the key _doc if the metadoc=True optional argument is given to the load method. This allows properties to be documented in the properties file. For example, the properties file:

#: _severity=fatal
10001=Fatal internal error: %s
# A fatal internal error occurred.  Please re-run the command
# with the -D option to generate additional debug information.

The following example code shows how this documentation can be accessed.

from jproperties import Properties

p = Properties()
with open("foobar.properties", "rb") as f:
    p.load(f, "utf-8", metadoc=True)
# Print the explicitly defined '_severity' metadata
print("Severity: ", p.getmeta("10001")['_severity'])
# Print the implicitly defined '_doc' metadata
print("Explanation: ", p.getmeta("10001")['_doc'])

The documentation can be extracted from properties files and used to generate pages in the overall system documentation or can be accessed via options for command line utilities.

3.1.2   Caveats

Metadata support influences how Properties objects are used as dictionary objects:

• To set a value for a key, do prop_object[key] = value or prop_object[key] = value, metadata. The first form will leave the key's metadata unchanged. You can also use the setmeta() method to set a key's metadata.
• To get the value of a key, do value, metadata = prop_object[key]. If there is no metadata for a key, metadata will be an empty dictionary. To retrieve only the metadata for a key, the getmeta() method can be used.
• When used as an iterator, Properties objects will simply return all keys in an unspecified order. No metadata is returned (but can be retrieved using getmeta()).

3.2   Setting defaults

The internal dictionary holding the key-value pairs can be accessed using the properties property. Deleting that property deletes all key-value pairs from the object.

However, modifying properties using this special property will not modify metadata in any way. That means that deleting properties by doing del prop_obj.properties[key] will not remove the associated metadata from the object. Instead, do del prop_obj[key].

The properties property is nevertheless useful to set many default values before parsing a property file:

from jproperties import Properties

prop_obj = Properties()
prop_obj.properties = a_big_dictionary_with_defaults
file_obj = codecs.open("foobar.properties", "rb", "iso-8859-1")
prop_obj.load(file_obj, encoding=None)

3.3   Development

If you want to help development, there is overview documentation

4   Version history

See file CHANGELOG.rst.