jProperties for Python |pypi-badge|
===================================
jProperties is a Java Property file parser and writer for Python. It aims to provide the same functionality
as `Java's Properties class <http://docs.oracle.com/javase/7/docs/api/java/util/Properties.html>`_, although
currently the XML property format is not supported.
.. sectnum::
.. contents:: **Table of Contents**
Installation
------------
You can install jProperties using `pip <https://pip.pypa.io/>`_::
pip install jproperties
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``.
Parsing a property file
+++++++++++++++++++++++
.. code:: python
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``.
Writing a property file
+++++++++++++++++++++++
.. code:: python
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")
Reading from and writing to the same file-like object
+++++++++++++++++++++++++++++++++++++++++++++++++++++
.. code:: python
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")
Special features
----------------
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.
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.
.. code:: python
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.
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()``).
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:
.. code:: python
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)
Development
++++++++++++++++
If you want to help development, there is
`overview documentation <./DEVELOPMENT.rst>`_
Version history
---------------
Version 2.1.1
+++++++++++++
- Compatibility 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`_)
Version 2.1.0
+++++++++++++
- Add support for optional documentation comments (see `Documenting
Properties`_). Thanks to @mkrohan! (`#5`_)
Version 2.0.0
+++++++++++++
- **Python 3 support!** Thanks to @tboz203, who did a lot of the work. (`#1`_)
- Drop support for Python 2.6.
Version 1.0.1
+++++++++++++
- This is the first "proper" PyPI release, with proper PyPI metadata and proper PyPI distributions.
Nothing else has changed.
Version 1.0
+++++++++++
- Initial release
.. _#5: https://github.com/Tblue/python-jproperties/pull/5
.. _#1: https://github.com/Tblue/python-jproperties/pull/1
.. _#10: https://github.com/Tblue/python-jproperties/pull/10
.. _#13: https://github.com/Tblue/python-jproperties/pull/13
.. _#14: https://github.com/Tblue/python-jproperties/pull/14
..
NB: Without a trailing question mark in the following image URL, the
generated HTML will contain an <object> element instead of an <img>
element, which apparently cannot be made into a link (i. e. a
"clickable" image).
.. |pypi-badge| image:: https://img.shields.io/pypi/v/jproperties.svg?
:align: middle
:target: https://pypi.python.org/pypi/jproperties
Raw data
{
"_id": null,
"home_page": "https://github.com/Tblue/python-jproperties",
"name": "jproperties",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "java property properties file parser reader writer",
"author": "Tilman Blumenbach",
"author_email": "tilman+pypi@ax86.net",
"download_url": "https://files.pythonhosted.org/packages/3a/ae/5b445c77b36b5b8ec75d2bf35dc9fd54cc93b391219ab43fdb0b523c2c41/jproperties-2.1.1.tar.gz",
"platform": "",
"description": "jProperties for Python |pypi-badge|\n===================================\n\njProperties is a Java Property file parser and writer for Python. It aims to provide the same functionality\nas `Java's Properties class <http://docs.oracle.com/javase/7/docs/api/java/util/Properties.html>`_, although\ncurrently the XML property format is not supported.\n\n.. sectnum::\n.. contents:: **Table of Contents**\n\nInstallation\n------------\n\nYou can install jProperties using `pip <https://pip.pypa.io/>`_::\n\n pip install jproperties\n\nOverview\n--------\n\nObjects of the type ``Properties`` can be used like a Python dictionary (but see Caveats_ below).\nThe ``load()`` method populates the object by parsing input in the Java Property file format; the ``store()``\nmethod writes the key-value pairs stored in the object to a stream in the same format.\n\nThe ``load()`` and ``store()`` methods both take an ``encoding`` parameter. By default this is set to\n``iso-8859-1``, but it can be set to any encoding supported by Python, including e. g. the widely used\n``utf-8``.\n\nParsing a property file\n+++++++++++++++++++++++\n\n.. code:: python\n\n from jproperties import Properties\n\n p = Properties()\n with open(\"foobar.properties\", \"rb\") as f:\n p.load(f, \"utf-8\")\n\nThat's it, ``p`` now can be used like a dictionary containing properties from ``foobar.properties``.\n\nWriting a property file\n+++++++++++++++++++++++\n\n.. code:: python\n\n from jproperties import Properties\n\n p = Properties()\n p[\"foobar\"] = \"A very important message from our sponsors: Python is great!\"\n\n with open(\"foobar.properties\", \"wb\") as f:\n p.store(f, encoding=\"utf-8\")\n\nReading from and writing to the same file-like object\n+++++++++++++++++++++++++++++++++++++++++++++++++++++\n\n.. code:: python\n\n from jproperties import Properties\n\n with open(\"foobar.properties\", \"r+b\") as f:\n p = Properties()\n p.load(f, \"utf-8\")\n\n # Do stuff with the p object...\n\n f.seek(0)\n f.truncate(0)\n p.store(f, encoding=\"utf-8\")\n\nSpecial features\n----------------\n\nMetadata\n++++++++\n\nThe property file parser supports including programmatically readable and settable metadata in property files.\nMetadata for a key is represented as a Python dictionary; the keys and values of this dictionary should be strings,\nalthough when the property file is written, all non-string objects will be converted to strings. **This is a\none-way conversion**; when the metadata is read back again during a ``load()``, all keys and values will be treated\nas simple strings.\n\nBy default, the ``store()`` method does not write out the metadata. To enable that feature, set the keyword argument\n``strip_meta=False`` when calling the method.\n\nNote that metadata support is always enabled. The only thing that is optional is actually writing out the metadata.\n\nMetadata keys beginning with two underscores (``__``) are not written to the output stream by the ``store()`` method.\nThus, they can be used to attach \"runtime-only\" metadata to properties. Currently, however, metadata with such keys is\nstill read from the input stream by ``load()``; this should probably be considered erroneous behaviour.\n\nDocumenting Properties\n^^^^^^^^^^^^^^^^^^^^^^\n\nThe comments after a property definition can be added to the metadata\nwith the key ``_doc`` if the ``metadoc=True`` optional argument is given\nto the ``load`` method. This allows properties to be documented in the\nproperties file. For example, the properties file::\n\n #: _severity=fatal\n 10001=Fatal internal error: %s\n # A fatal internal error occurred. Please re-run the command\n # with the -D option to generate additional debug information.\n\nThe following example code shows how this documentation can be accessed.\n\n.. code:: python\n\n from jproperties import Properties\n\n p = Properties()\n with open(\"foobar.properties\", \"rb\") as f:\n p.load(f, \"utf-8\", metadoc=True)\n # Print the explicitly defined '_severity' metadata\n print(\"Severity: \", p.getmeta(\"10001\")['_severity'])\n # Print the implicitly defined '_doc' metadata\n print(\"Explanation: \", p.getmeta(\"10001\")['_doc'])\n\nThe documentation can be extracted from properties files and used to generate\npages in the overall system documentation or can be accessed via options\nfor command line utilities.\n\nCaveats\n^^^^^^^\n\nMetadata support influences how ``Properties`` objects are used as dictionary objects:\n\n- To set a value for a key, do ``prop_object[key] = value`` or ``prop_object[key] = value, metadata``. The first form\n will leave the key's metadata unchanged. You can also use the ``setmeta()`` method to set a key's metadata.\n- To get the value of a key, do ``value, metadata = prop_object[key]``. If there is no metadata for a key,\n ``metadata`` will be an empty dictionary. To retrieve only the metadata for a key, the ``getmeta()`` method can\n be used.\n- When used as an iterator, ``Properties`` objects will simply return all keys in an unspecified order. No metadata is\n returned (but can be retrieved using ``getmeta()``).\n\nSetting defaults\n++++++++++++++++\n\nThe internal dictionary holding the key-value pairs can be accessed using the ``properties`` property. Deleting that\nproperty deletes all key-value pairs from the object.\n\nHowever, modifying properties using this special property will **not** modify metadata in any way. That means that\ndeleting properties by doing ``del prop_obj.properties[key]`` will not remove the associated metadata from the object.\nInstead, do ``del prop_obj[key]``.\n\nThe ``properties`` property is nevertheless useful to set many default values before parsing a property file:\n\n.. code:: python\n\n from jproperties import Properties\n\n prop_obj = Properties()\n prop_obj.properties = a_big_dictionary_with_defaults\n file_obj = codecs.open(\"foobar.properties\", \"rb\", \"iso-8859-1\")\n prop_obj.load(file_obj, encoding=None)\n\n\nDevelopment\n++++++++++++++++\n\nIf you want to help development, there is\n`overview documentation <./DEVELOPMENT.rst>`_\n\nVersion history\n---------------\n\nVersion 2.1.1\n+++++++++++++\n\n- Compatibility with Python 3.10. (`#10`_)\n- Documentation improvements. (`#13`_)\n- Support decoding surrogate pairs on narrow Python builds (such as\n Python 2.7 on Mac OS X). (`#14`_)\n\nVersion 2.1.0\n+++++++++++++\n\n- Add support for optional documentation comments (see `Documenting\n Properties`_). Thanks to @mkrohan! (`#5`_)\n\nVersion 2.0.0\n+++++++++++++\n\n- **Python 3 support!** Thanks to @tboz203, who did a lot of the work. (`#1`_)\n- Drop support for Python 2.6.\n\nVersion 1.0.1\n+++++++++++++\n\n- This is the first \"proper\" PyPI release, with proper PyPI metadata and proper PyPI distributions.\n Nothing else has changed.\n\nVersion 1.0\n+++++++++++\n\n- Initial release\n\n\n.. _#5: https://github.com/Tblue/python-jproperties/pull/5\n.. _#1: https://github.com/Tblue/python-jproperties/pull/1\n.. _#10: https://github.com/Tblue/python-jproperties/pull/10\n.. _#13: https://github.com/Tblue/python-jproperties/pull/13\n.. _#14: https://github.com/Tblue/python-jproperties/pull/14\n\n..\n NB: Without a trailing question mark in the following image URL, the\n generated HTML will contain an <object> element instead of an <img>\n element, which apparently cannot be made into a link (i. e. a\n \"clickable\" image).\n.. |pypi-badge| image:: https://img.shields.io/pypi/v/jproperties.svg?\n :align: middle\n :target: https://pypi.python.org/pypi/jproperties\n\n\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License; partially licensed under the Python Software Foundation License",
"summary": "Java Property file parser and writer for Python",
"version": "2.1.1",
"split_keywords": [
"java",
"property",
"properties",
"file",
"parser",
"reader",
"writer"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1eb5822b214d287ca45f7fbe5de3daa31a96c83e46b9511158d63709d057f66e",
"md5": "91cd70fb65612bcf7042b31e49d78485",
"sha256": "4dfcd7cab56d9c79bce4453f7ca9ffbe0ff0574ddcf1c2a99a8646df60634664"
},
"downloads": -1,
"filename": "jproperties-2.1.1-py2.py3-none-any.whl",
"has_sig": true,
"md5_digest": "91cd70fb65612bcf7042b31e49d78485",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 17923,
"upload_time": "2021-08-01T18:14:36",
"upload_time_iso_8601": "2021-08-01T18:14:36.643963Z",
"url": "https://files.pythonhosted.org/packages/1e/b5/822b214d287ca45f7fbe5de3daa31a96c83e46b9511158d63709d057f66e/jproperties-2.1.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3aae5b445c77b36b5b8ec75d2bf35dc9fd54cc93b391219ab43fdb0b523c2c41",
"md5": "51f243803239546412a3afef322aacd7",
"sha256": "40b71124e8d257e8954899a91cd2d5c0f72e0f67f1b72048a5ba264567604f29"
},
"downloads": -1,
"filename": "jproperties-2.1.1.tar.gz",
"has_sig": true,
"md5_digest": "51f243803239546412a3afef322aacd7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 24154,
"upload_time": "2021-08-01T18:14:38",
"upload_time_iso_8601": "2021-08-01T18:14:38.622419Z",
"url": "https://files.pythonhosted.org/packages/3a/ae/5b445c77b36b5b8ec75d2bf35dc9fd54cc93b391219ab43fdb0b523c2c41/jproperties-2.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-08-01 18:14:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "Tblue",
"github_project": "python-jproperties",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "jproperties"
}
JSON
