Skip to main content
Join the official Python Developers Survey 2018 and win valuable prizes: Start the survey!

JSON config file parser with extended syntax (e.g.: comments), line/column numbers and other extras.

Project description

build code quality code health pypi github license: MIT

The goal of this library is providing a json config file loader that has the following extras compared to the standard json.load():

  • A larger subset of javascript (and not some weird/exotic extension to json that would turn json into something that has nothing to do with json/javascript):

    • backward compatible with json so you can still load standard json files too
    • single and multi-line comments - this is more useful then you would think: it is good not only for documentation but also for temporarily disabling a block in your config without actually deleting entries
    • object (dictionary) keys without quotes
    • trailing commas (allowing commas after the last item of objects and arrays)
  • Providing line number information for each element of the loaded config file and using this to display useful error messages that help locating errors not only while parsing the file but also when processing/interpreting it.

  • A nice config query syntax that handles default values, required elements and automatically raises an exception in case of error (with useful info including the location of the error in the config file).

Config file examples

A traditional json config file:

    "servers": [
            "ip_address": "",
            "port": 8080
            "ip_address": "",
            "port": 8081
    "superusername": "tron"

Something similar with json-cfg:

    // Note that we can get rid of most quotation marks.
    servers: [
            ip_address: "",
            port: 8080
        // We have commented out the block of the second server below.
        // Trailing commas are allowed so the comma after the
        // first block (above) doesn't cause any problems.
            ip_address: "",
            port: 8081
        },  // <-- optional trailing comma
    superusername: "tron",  // <-- optional trailing comma

Hint: use javascript syntax highlight in your text editor for json config files whenever possible - this makes reading config files much easier especially when you have a lot of comments or large commented config blocks.


pip install json-cfg

Alternatively you can download the zipped library from


The json-cfg library provides two modes when it comes to loading config files: One that is very similar to the standard json.loads() and another one that returns the json wrapped into special config nodes that make handling the config file much easier:

  • jsoncfg.load() and jsoncfg.loads() are very similar to the standard json.loads(). These functions allow you to load config files with extended syntax into bare python representation of the json data (dictionaries, lists, numbers, etc…).
  • jsoncfg.load_config() and jsoncfg.loads_config() load the json data into special wrapper objects that help you to query the config with much nicer syntax. At the same time if you are looking for a value that doesn’t exist in the config then these problems are handled with exceptions that contain line/column number info about the location of the error.

One of the biggest problems with loading the config into bare python objects with a json library is that you can detect the location of config problems only while the config file is being parsed so you can detect only json syntax errors. By loading the json into special objects we can retain the location of json nodes/elements and use them in our error messages if we find a semantic error when we are processing the config data.

I assume that you have already installed json-cfg and you have the previously shown server config example in a server.cfg file in the current directory.

This is how to load and use the above server configuration with json-cfg:

import jsoncfg

config = jsoncfg.load_config('server.cfg')
for server in config.servers:
    listen_on_interface(server.ip_address(), server.port(8000))
user_name = config.superusername()

The same with a simple json library:

import json

with open('server.cfg') as f:
    config = json.load(f)
for server in config['servers']:
    listen_on_interface(server['ip_address'], server.get('port', 8000))
user_name = config['superusername']

The difference isn’t big. With json-cfg you can use extended syntax in the config file and the code that loads the config is also somewhat nicer but real difference is what happens when we encounter an error. With json-cfg you get an exception with a message that points to the problematic part of the json config file while the pure-json example throws a KeyError exception saying that your code tried to lookup a non-existing ‘ip_address’ key in a dictionary without any location info within the json config file. In case of a larger config file this can cause headaches when it comes to locating the error.

Open your server.cfg file and remove the required ip_address attribute from one of the server config blocks. This will cause an error when we try to load the config file with the above code examples. The above code snippets report the following error messages in this scenario:


jsoncfg.config_classes.JSONConfigValueNotFoundError: Required config node not found. Missing query path: .ip_address (relative to error location) [line=3;col=9]


KeyError: 'ip_address'

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date (30.7 kB) Copy SHA256 hash SHA256 Source None May 3, 2015

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page