Skip to main content

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

Project description


GitHub tag Python Package Documentation Status Quality Gate Status PyPI PyPI - License PyPI - Format PyPI - Status PyPI - Python Version PyPI - Implementation

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


pip install pyyaml-include


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)



If 0.yml was:

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

We'll get:

  name: "1"
  name: "2"


If 0.yml was:

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

We'll get:

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


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


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

That is to say, a list will be returned when including file name contains wildcards. Length of the returned list equals number of matched files:

  • when only 1 file matched, length of list will be 1
  • when there are no files matched, an empty list will be returned

If 0.yml was:

files: !include include.d/*.yml

We'll get:

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


  • 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}

Non YAML files

This extending constructor can now load data from non YAML files, supported file types are:

  • json
  • toml (only available when toml installed)
  • ini

The constructor read non YAML files by different readers according to a pattern table defined in src/yamlinclude/

Default reader table can be replaced by a custom reader_map when call add_to_loader_class.




Date: 2022-04-24

  • New:

    • PyYAML 6.0 supported
  • Misc:

    • Better CI processes


Date: 2019-02-03

  • New:

    • non YAML file including
  • Misc:

    • adjust docs
    • add pip and conda configure file of development environment
  • Fix:

    • add PlainTextReader into __all__ list of reders module


Date: 2019-03-18

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


Date: 2019-01-07

  • Change:

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

    • A wrong logging text format
  • Misc:

    • add: .pylintrc


Date: 2018-12-04

  • New Feature:

    • Add base_dir argument
  • Misc:

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


Date: 2018-07-11

  • Add:

    • encoding argument
  • Bug fix:

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


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 to

    • Rename class data member DEFAULT_TAG to TAG


Date: 2018-06-08

Project details

Download files

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

Source Distribution

pyyaml-include-1.3.tar.gz (42.7 kB view hashes)

Uploaded source

Built Distribution

pyyaml_include-1.3-py3-none-any.whl (20.2 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page