https://github.com/markdouthwaite/lnkd
A simple utility for creating linked YAML documents.
https://github.com/markdouthwaite/lnkd
custom-tag pyyaml yaml
Last synced: 7 months ago
JSON representation
A simple utility for creating linked YAML documents.
- Host: GitHub
- URL: https://github.com/markdouthwaite/lnkd
- Owner: markdouthwaite
- License: mit
- Created: 2020-04-13T12:13:47.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2022-12-26T21:30:55.000Z (almost 3 years ago)
- Last Synced: 2025-03-19T22:05:08.184Z (7 months ago)
- Topics: custom-tag, pyyaml, yaml
- Language: Python
- Size: 20.5 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
LNKD
Simple linked YAML documents.
A simple utility for linking YAML documents. For Python >=3.6.
## Getting started
You can install `lnkd` with:
```bash
pip install lnkd
```
## Why does it exist?
If you work with cloud technologies, YAML is part of your day job. It's often great for
managing complex service configurations, but it's also not uncommon to get YAML files
many hundreds of lines long. Some of the more advanced features of YAML -- such as
[merge tags](https://yaml.org/type/merge.html) make this process a little easier,but
not always ideal.
Long story short, this little package is the offshoot of an afternoon roaming the
interwebs trying to figure out how best to link YAML files across multiple local and
remote locations and stitch them together nicely. It is not the only way of doing this,
and it's also almost certainly not the best way of doing it. In fact, it will make it
very easy to create a lot of anti-patterns, and by default your YAML parser is unlikely
to get on well with the new tag. Adding new syntax is dangerous. You've been warned.
Anyway, it's here on the off-chance someone wants to avoid an afternoon of trawling
Stack Overflow.
Right, so how does it look?
You now get the `!@` tag to add to your YAML. Here's how it works:
Say we've a big ol' config file. Here we'll pretend it's a `docker-compose` file:
```yaml
# service.yaml
version: '3'
services:
client:
!@ client.yaml
```
And we store our `client` service config in a file `client.yaml`:
```yaml
# client.yaml
build:
image: python:3.6-alpine
environment:
POSTGRES_USER: admin
POSTGRES_PASSWORD: 1234
POSTGRES_DB: accounts
```
If we then run:
```bash
lnkd service.yaml --output docker-compose.yaml
```
We'd get:
```yaml
# docker-compose.yaml
version: '3'
services:
client:
build:
image: python:3.6-alpine
environment:
POSTGRES_USER: admin
POSTGRES_PASSWORD: 1234
POSTGRES_DB: accounts
```
And that's pretty much it. You can use these components programmatically to load and
build your YAML structures too.
## Programmatic usage
Want to use these capabilities directly in your Python code? No problem, you can use them like:
```python
import yaml
import lnkd
with open("service.yaml", "r") as file:
data = yaml.load(file, Loader=lnkd.LinkedLoader)
```
You'll get the linked data as a dictionary.
# Notes
- If you can, use `anchors` and `aliases` instead. If you haven't heard of these before, Atlassian have written a [short example](https://confluence.atlassian.com/bitbucket/yaml-anchors-960154027.html).
- This package implements only custom tags. It _does not_ enable shared anchors and aliases across files.