Package: don
DON - Dot Object NotationDON stands for Dot Object Notation. It is a convenient way to write
simple configuration files.ContentsDON - Dot Object NotationRequirementsInstallationSupportResourcesLicenseTutorialGetting startedDON syntaxRequirementsThis module should be used with Python 3.4 or any later version of
Python interpreter.This module depends only on the Python standard library. It does not
depend on any third party libraries.InstallationYou can install this package using pip3 using the following command.pip3 install donYou can install this package from source distribution. To do so,
download the latest .tar.gz file fromhttps://pypi.python.org/pypi/don,
extract it, then open command prompt or shell, and change your current
directory to the directory where you extracted the source distribution,
and then execute the following command.python3 setup.py installNote that on a Windows system, you may have to replacepython3with
the path to your Python 3 interpreter.SupportTo report any bugs, or ask any question, please visithttps://github.com/susam/don/issues.ResourcesHere is a list of useful links about this project.Latest release on PyPISource code on GitHubIssue tracker on GitHubChangelog on GitHubLicenseThis is free software. You are permitted to redistribute and use it in
source and binary forms, with or without modification, under the terms
of the Simplified BSD License. See the LICENSE.rst file for the complete
license.This software is provided WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
LICENSE.rst file for the complete disclaimer.TutorialGetting startedHere is a very simple example of DON.title: Countries

india.capital: New Delhi
india.demonym: Indian
india.driving: Left

italy.capital: Rome
italy.demonym: Italian
italy.driving: RightThe above DON specifies three top-level DON attributes (also known as
root attributes). They aretitle,indiaanditaly. Thetitleattribute is a string attribute. The value oftitleisCountries. However,indiaanditalyare object attributes.
The value ofindiais an object which contains three attributes:capital,demonymanddriving.The root object is an object of typedon.Object. This is a
dictionary that supports accessing its keys as attributes as well.
Therefore, for the above example,title,indiaanditalyare
keys in the root object. The value of string attributes are of typestr. The value of object attributes are of typedon.Object.The following Python code demonstrates how thedonmodule may be
used to parse the above example DON into a root DON object, and then
access the attributes.importdon# An example DONs="""
title: Countries

india.capital: New Delhi
india.demonym: Indian
india.driving: Left

italy.capital: Rome
italy.demonym: Italian
italy.driving: Right
"""# Parse DONroot=don.parse(s)# Access a root attributeprint(root.title)# Access object attributes in various waysprint(root.india.capital)# As attributesprint(root['india']['demonym'])# As dictionary keysprint(root.india['driving'])# In a mixed fashion# An object attribute is actually a dictionaryprint(root.italy)Here is the output of the above program.Countries
New Delhi
Indian
Left
{'driving': 'Right', 'capital': 'Rome', 'demonym': 'Italian'}This is all there is to parsing a DON string into an object and
accessing its attributes.DON syntaxA DON string or DON file contains a list of key value pairs. Each key
value pair is separated by a colon. Here is an example.fruit: mango
drink: beer
level: debugEmpty lines, lines consisting of whitespace characters only and lines
beginning with the hash character, i.e.#, are ignored. Therefore,
lines beginning with#may be used to write comments. The following
DON example is equivalent to the previous example.# Eat and drink
fruit: mango
drink: beer

# Logging level
level: debugFurther, any leading whitespace before a key or a value, and any
trailing whitespace after a key or value are ignored. The following DON
example is equivalent to the previous example.# Eat and drink
  fruit : mango
    drink: beer

  # Logging level
level:debugA DON string represents a single object, known as the root object, that
contains attributes. For example, when the above example is parsed by
DON parser, the string is converted into a root object (which we will
call asroot). This root object in turn contains three attributes
with three values. In this case, all three values happen to be strings,
so these attributes may be called string attributes.The keys in DON may be one or more dot separated tokens. Each token must
be a valid Python identifier. Here is an example that shows dot
separated tokens as keys.process.priority: normal
process.protocol: tcp
process.log.file: log.txt
process.log.level: debug
process.log.rotate: dailyIn this example, the root object contains an object attribute calledprocesswhich in turn contains two string attributes calledpriorityandprotocol, and one object attribute calledlog.
Thelogattribute in turn contains three string attributes calledfile,levelandrotate.Here is a tree diagram that shows the relationship between the various
attributes.(root)
 `-- process
     |-- priority
     |-- protocol
     `-- log
         |-- file
         |-- level
         `-- rotateThis is a DON tree. The root node is known as the root object. The
internal nodes are always object attributes. They contain one or more
other attributes as their values. The leaf nodes are always string
attributes. They contain strings as their values.A key may contain one or more empty tokens before any non-empty token.
An empty token in a key is equivalent to the corresponding token in its
previous key, i.e. the Nth empty token in a key is a synonym for the Nth
token in its previous key. An empty token must appear before any
non-empty token. The number of empty tokens in a key must not exceed the
number of tokens in its previous key. According to these rules, the
following DON example is equivalent to the previous example.process.priority: normal
.protocol: tcp
.log.file: log.txt
..level: debug
..rotate: dailySince leading and trailing whitespace characters around keys and values
are ignored, the keys with empty tokens may be indented to improve
readability.process.priority: normal
       .protocol: tcp
       .log.file: log.txt
          ..level: debug
          ..rotate: dailyWhen a key is followed by empty value, it only declares the key. It does
not define anything. It does not cause the DON tree to be updated.
Declaring a key is useful for using empty tokens in the following keys,
so that the empty tokens in the following keys become synonyms of the
corresponding tokens in the declared key. This can improve readability
quite significantly as shown by the following DON example which is
equivalent to the previous example.process:
    .priority: normal
    .protocol: tcp
    .log:
        ..file: log.txt
        ..level: debug
        ..rotate: daily