pyyaml-include 1.1.1.1

Extending PyYAML with a custom constructor for including YAML files within YAML files

pyyaml-include

An extending constructor of PyYAML: include YAML files into YAML document.

Install

pip install pyyaml-include

Usage

Consider we have such YAML files:

├── 0.yml
└── include.d
    ├── 1.yml
    └── 2.yml

• 1.yml 's content:

  name: "1"
  

• 2.yml 's content:

  name: "2"
  

To include 1.yml, 2.yml in 0.yml, we shall add YamlIncludeConstructor to PyYAML's loader, then add an !include tag in 0.yaml:

import yaml
from yamlinclude import YamlIncludeConstructor

YamlIncludeConstructor.add_to_loader_class(loader_class=yaml.FullLoader, base_dir='/your/conf/dir')

with open('0.yml') as f:
    data = yaml.load(f, Loader=yaml.FullLoader)

print(data)

Mapping

If 0.yml was:

file1: !include include.d/1.yml
file2: !include include.d/2.yml

We'll get:

file1:
  name: "1"
file2:
  name: "2"

Sequence

If 0.yml was:

files:
  - !include include.d/1.yml
  - !include include.d/2.yml

We'll get:

files:
  - name: "1"
  - name: "2"

ℹ Note:

File name can be either absolute (like /usr/conf/1.5/Make.yml) or relative (like ../../cfg/img.yml).

Wildcards

File name can contain shell-style wildcards. Data loaded from the file(s) found by wildcards will be set in a sequence.

If 0.yml was:

files: !include include.d/*.yml

We'll get:

files:
  - name: "1"
  - name: "2"

ℹ Note:

• For Python>=3.5, if recursive argument of !include YAML tag is true, the pattern “**” will match any files and zero or more directories and subdirectories.
• Using the “**” pattern in large directory trees may consume an inordinate amount of time because of recursive search.

In order to enable recursive argument, we shall set it in Mapping or Sequence arguments mode:

• Arguments in Sequence mode:

  !include [tests/data/include.d/**/*.yml, true]
  

• Arguments in Mapping mode:

  !include {pathname: tests/data/include.d/**/*.yml, recursive: true}
  

Authors

liu xue yan [e-mail]

Changelog

1.1

Date: 2019-03-18

• Change:
  • Update PyYAML to 5.*
  • Rename: Argument loader_class of YamlIncludeConstructor.add_to_loader_class() (former: loader_cls)

1.0.4

Date: 2019-01-07

• Change:

  • rename: TAG ==> DEFAULT_TAG_NAME
  • add: encoding argument

• Fix:

  • A wrong logging text format

• Misc:

  • add: .pylintrc

1.0.3

Date: 2018-12-04

• New Feature:

  • Add base_dir argument

• Misc:

  • Add some new unit-test
  • Add Python3.7 in CircleCI

1.0.2

Date: 2018-07-11

• Add:

  • encoding argument

• Bug fix:

  • encoding error if non-ascii characters on non-utf8 os.

1.0.1

Date: 2018-07-03

• Add:

  • Old Python2.6 and new Python3.7 compatibilities

  • class method add_to_loader_class

    A class method to add the constructor itself into YAML loader class

  • Sphinx docs

• Change:

  • Rename module file include.py to constructor.py

  • Rename class data member DEFAULT_TAG to TAG

1.0

Date: 2018-06-08