Package: jproperties
jProperties is a Java Property file parser and writer for Python. It aims to provide the same functionality
asJava’s Properties class, although
currently the XML property format is not supported.Table of Contents1Installation2Overview2.1Parsing a property file2.2Writing a property file2.3Reading from and writing to the same file-like object3Special features3.1Metadata3.1.1Documenting Properties3.1.2Caveats3.2Setting defaults3.3Development4Version history4.1Version 2.1.14.2Version 2.1.04.3Version 2.0.04.4Version 1.0.14.5Version 1.01InstallationYou can install jProperties usingpip:pip install jproperties2OverviewObjects of the typePropertiescan be used like a Python dictionary (but seeCaveatsbelow).
Theload()method populates the object by parsing input in the Java Property file format; thestore()method writes the key-value pairs stored in the object to a stream in the same format.Theload()andstore()methods both take anencodingparameter. By default this is set toiso-8859-1, but it can be set to any encoding supported by Python, including e. g. the widely usedutf-8.2.1Parsing a property filefromjpropertiesimportPropertiesp=Properties()withopen("foobar.properties","rb")asf:p.load(f,"utf-8")That’s it,pnow can be used like a dictionary containing properties fromfoobar.properties.2.2Writing a property filefromjpropertiesimportPropertiesp=Properties()p["foobar"]="A very important message from our sponsors: Python is great!"withopen("foobar.properties","wb")asf:p.store(f,encoding="utf-8")2.3Reading from and writing to the same file-like objectfromjpropertiesimportPropertieswithopen("foobar.properties","r+b")asf: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")3Special features3.1MetadataThe 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 aload(), all keys and values will be treated
as simple strings.By default, thestore()method does not write out the metadata. To enable that feature, set the keyword argumentstrip_meta=Falsewhen 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 thestore()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 byload(); this should probably be considered erroneous behaviour.3.1.1Documenting PropertiesThe comments after a property definition can be added to the metadata
with the key_docif themetadoc=Trueoptional argument is given
to theloadmethod.  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.fromjpropertiesimportPropertiesp=Properties()withopen("foobar.properties","rb")asf:p.load(f,"utf-8",metadoc=True)# Print the explicitly defined '_severity' metadataprint("Severity: ",p.getmeta("10001")['_severity'])# Print the implicitly defined '_doc' metadataprint("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.2CaveatsMetadata support influences howPropertiesobjects are used as dictionary objects:To set a value for a key, doprop_object[key] = valueorprop_object[key] = value, metadata. The first form
will leave the key’s metadata unchanged. You can also use thesetmeta()method to set a key’s metadata.To get the value of a key, dovalue, metadata = prop_object[key]. If there is no metadata for a key,metadatawill be an empty dictionary. To retrieve only the metadata for a key, thegetmeta()method can
be used.When used as an iterator,Propertiesobjects will simply return all keys in an unspecified order. No metadata is
returned (but can be retrieved usinggetmeta()).3.2Setting defaultsThe internal dictionary holding the key-value pairs can be accessed using thepropertiesproperty. Deleting that
property deletes all key-value pairs from the object.However, modifying properties using this special property willnotmodify metadata in any way. That means that
deleting properties by doingdel prop_obj.properties[key]will not remove the associated metadata from the object.
Instead, dodel prop_obj[key].Thepropertiesproperty is nevertheless useful to set many default values before parsing a property file:fromjpropertiesimportPropertiesprop_obj=Properties()prop_obj.properties=a_big_dictionary_with_defaultsfile_obj=codecs.open("foobar.properties","rb","iso-8859-1")prop_obj.load(file_obj,encoding=None)3.3DevelopmentIf you want to help development, there isoverview documentation4Version history4.1Version 2.1.1Compatibility with Python 3.10. (#10)Documentation improvements. (#13)Support decoding surrogate pairs on narrow Python builds (such as
Python 2.7 on Mac OS X). (#14)4.2Version 2.1.0Add support for optional documentation comments (seeDocumenting
Properties). Thanks to @mkrohan! (#5)4.3Version 2.0.0Python 3 support!Thanks to @tboz203, who did a lot of the work. (#1)Drop support for Python 2.6.4.4Version 1.0.1This is the first “proper” PyPI release, with proper PyPI metadata and proper PyPI distributions.
Nothing else has changed.4.5Version 1.0Initial release