{"id":2741,"library":"pyyaml-include","title":"PyYAML Include","description":"PyYAML Include extends PyYAML with a powerful mechanism to include other YAML files into a current YAML document. It supports local files, as well as remote files via HTTP, S3, SFTP, and more through its integration with `fsspec`. The current stable version is 2.2, with active development and somewhat irregular but consistent releases addressing new features and breaking changes.","status":"active","version":"2.2","language":"en","source_language":"en","source_url":"https://github.com/tanbro/pyyaml-include.git","tags":["yaml","pyyaml","include","configuration","fsspec"],"install":[{"cmd":"pip install \"pyyaml-include\"","lang":"bash","label":"Basic Installation"},{"cmd":"pip install \"pyyaml-include\" fsspec[http,s3]","lang":"bash","label":"With Remote File Support (e.g., HTTP, S3)"}],"dependencies":[{"reason":"Core dependency, this library extends its functionality.","package":"PyYAML"},{"reason":"Required for file system abstraction, enabling local and remote file inclusion (since v2.0). Specific backends like `fsspec[http]` are optional.","package":"fsspec","optional":true}],"imports":[{"note":"The top-level package and main constructor class were renamed in version 2.0. The old import `yamlinclude` is no longer valid.","wrong":"from yamlinclude import YamlIncludeConstructor","symbol":"Constructor","correct":"from yaml_include import Constructor"},{"note":"The package namespace changed from `yamlinclude` to `yaml_include` in version 2.0. Importing the old name will result in an `ImportError`.","wrong":"import yamlinclude","symbol":"yaml_include","correct":"import yaml_include"}],"quickstart":{"code":"import yaml\nimport yaml_include\nimport os\n\n# Create dummy YAML files for the example\nwith open(\"database.yml\", \"w\") as f:\n    f.write(\"host: localhost\\nport: 5432\\nname: mydb\\n\")\n\nwith open(\"config.yml\", \"w\") as f:\n    f.write(\"database: !inc database.yml\\napp:\\n  name: MyApp\\n\")\n\n# Register the include tag with a YAML Loader\n# It is recommended to use FullLoader for most use cases with unknown sources\nyaml.add_constructor(\"!inc\", yaml_include.Constructor(), yaml.FullLoader)\n\n# Load the main YAML file\nwith open('config.yml', 'r') as f:\n    data = yaml.full_load(f)\n\nprint(data)\n# Expected output: {'database': {'host': 'localhost', 'port': 5432, 'name': 'mydb'}, 'app': {'name': 'MyApp'}}\n\n# Clean up dummy files\nos.remove(\"database.yml\")\nos.remove(\"config.yml\")","lang":"python","description":"This quickstart demonstrates how to use `pyyaml-include` to include one YAML file (`database.yml`) into another (`config.yml`). It involves creating an instance of `yaml_include.Constructor` and registering it with a `PyYAML` loader (e.g., `yaml.FullLoader`) for a custom `!inc` tag. The example then loads the main configuration, which resolves the included file content."},"warnings":[{"fix":"Update all `import` statements and class references from `yamlinclude` to `yaml_include` and `YamlIncludeConstructor` to `Constructor`.","message":"Version 2.0 introduced significant breaking changes, including a change in the package's import namespace from `yamlinclude` to `yaml_include` and the core `YamlIncludeConstructor` class being renamed to `Constructor`. Code written for `v1.x` is not directly compatible with `v2.x`.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your project runs on Python 3.9 or newer to maintain compatibility with future `pyyaml-include` releases.","message":"Future versions (e.g., v2.3 and beyond) are expected to drop support for Python 3.8 and below. While v2.2 still supports Python >=3.8, plan to upgrade your Python environment if using older versions.","severity":"breaking","affected_versions":">=2.3.0 (planned)"},{"fix":"Avoid overly broad wildcard patterns in performance-critical applications or when dealing with large numbers of files. Consider a more explicit file inclusion strategy for such scenarios.","message":"Using shell-style wildcards (`**`, `*`, `?`) in include paths, especially with large directory trees or remote filesystems, can lead to performance issues and high memory consumption. All matched files are fully loaded into memory, not lazily.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use `yaml.safe_load()` for untrusted input or `yaml.full_load()` if you specifically need the features of the `FullLoader` for trusted sources. Register `yaml_include.Constructor` with the appropriate safe loader.","message":"By default, `PyYAML`'s `yaml.load()` function can be insecure when dealing with untrusted input due to arbitrary code execution possibilities. Although `pyyaml-include` examples often use `yaml.full_load()`, it's a good practice to be aware.","severity":"gotcha","affected_versions":"All versions (PyYAML related)"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}