importsinjson 0.1.1

Adding import functionality to JSON files

ImportsInJSON

Python JSON Import Library

---

ImportsInJSON is an easy way to allow Python to load JSON files that import data from other JSON files. This is very helpful for splitting up large JSON files into smaller chunks that can still be combined.

Installation

ImportsInJSON requires Python 3.7+.

pip install importsinjson

If you'd like to support loading JSON files with comments, either add the commentjson or pyjson5 extra when installing.

pip install importsinjson[commentjson]
# or
pip install importsinjson[pyjson5]

Usage

In your Python code, import importsinjson is a drop-in replacement for the json module.

In your JSON document, there are 2 ways to import data from other JSON files.

The first way is to simply have a key called $import with a string value that points to another file. Let's say you have a JSON file a.json:

{
  "name": "John Doe",
  "age": 30,
  "$import": "b.json"
}

and

{
  "profession": "Engineer"
}

Running importsinjson.load('a.json') will return the following:

{
  "name": "John Doe",
  "age": 30,
  "profession": "Engineer"
}

This does observe Python's dictionary merging rules, so any keys in the imported JSON file that are also in the original document will replace the values in the original document.

The second way to import data is to have a string value that starts with $import: and has the path to the file to import. Modifying the example from before, a.json would become

{
  "name": "John Doe",
  "age": 30,
  "profession": "$import:b.json"
}

However this would load the following:

{
  "name": "John Doe",
  "age": 30,
  "profession": {
    "profession": "Engineer"
  }
}

To prevent duplicate keys like this, you can add another : after the file path, and provide a path to the key in the imported file to use.

{
  "name": "John Doe",
  "age": 30,
  "profession": "$import:b.json:/profession/"
}

This value can be anywhere in the JSON document, including in a list:

{
  "name": "John Doe",
  "age": 30,
  "professions": ["$import:b.json", "$import:c.json"]
}

Options

Depending on the JSON parsing backend selected, options do vary. However, for all backends, the following options are available:

• strict: Defaults to False. If True, will raise a FileNotFoundError if the imported filepath cannot be found. Additionally, if the specified key/index could not be found, the KeyError, IndexError, etc will be raised. If False, the original value will be kept instead.

Default

The default JSON parsing backend is the Python standard library json module. All normal options for this can be used.

CommentJSON

Homepage

pip install importsinjson[commentjson]

If installed, commentjson will be used as the JSON parsing backend. This is a pure-Python implementation that strips comments from JSON data before handing them to the json module. This also supports all options of the json module. However, it does not support multi-line comments.

PyJSON5

Homepage

pip install importsinjson[pyjson5]

Lastly, if installed, pyjson5 will be used as the JSON parsing backend. This is a Cython implementation that loads JSON data with comments. This is the most restrictive backend, with very basic options. See here When using this, you may need to explictly add encoding="utf-8" to the load and loads functions.

If for some reason you want to change the prefix used to import data, you can set that like so:

import importsinjson
importsinjson.PREFIX = "$newimportsymbol"

Gotchas

Using the load function is much preferred over the loads function. This is because with a file handle, the path of the file can be used as an additional search directory when looking for imported files.

With load imported file paths can be either:

• absolute
• relative to the parent file
• relative to the current working directory

With loads imported file paths can only be:

• absolute
• relative to the current working directory

Additionally, this module also works recursively, so make sure not to create an infinite loop.