Merge pull request #244 from realpython/python-yaml

Supplementary materials for the YAML tutorial

Author: bzaczynski

python-yaml/README.md

@@ -0,0 +1,50 @@
+# YAML: The Missing Battery in Python
+
+Python scripts and sample data for the [YAML: The Missing Battery in Python](https://realpython.com/python-yaml/) tutorial on Real Python.
+
+## Installation
+
+This code requires the following libraries:
+
+- PyYAML
+- FastAPI
+- uvicorn
+
+To install them, activate your [virtual environment](https://realpython.com/python-virtual-environments-a-primer/), and type the following command:
+
+```shell
+(venv) $ python -m pip install -r requirements.txt
+```
+
+Additionally, you can install optional dependencies that were mentioned in the tutorial:
+
+```shell
+(venv) $ python -m pip install yamllint yq shyaml
+```
+
+## Usage
+
+Print a sample YAML document with syntax highlighting:
+
+```console
+$ cat data.yaml | python colorize.py
+```
+
+Print a static HTML preview of a sample YAML document:
+
+```console
+$ cat data.yaml | python yaml2html.py
+```
+
+Print an interactive HTML preview of a sample YAML document:
+
+```console
+$ cat data.yaml | python tree.py
+```
+
+Start an interactive demo of a YAML formatter at <http://localhost:8000/>:
+
+```console
+$ cd formatter/
+$ uvicorn server:app
+```

python-yaml/colorize.py

@@ -0,0 +1,36 @@
+# colorize.py
+
+import sys
+
+import yaml
+
+
+def colorize(text):
+    colors = {
+        yaml.KeyToken: lambda x: f"\033[34;1m{x}\033[0m",
+        yaml.ValueToken: lambda x: f"\033[36m{x}\033[0m",
+        yaml.TagToken: lambda x: f"\033[31m{x}\033[0m",
+    }
+
+    for start, end, token in reversed(list(tokenize(text))):
+        color = colors.get(type(token), lambda text: text)
+        text = text[:start] + color(text[start:end]) + text[end:]
+
+    return text
+
+
+def tokenize(text, loader=yaml.SafeLoader):
+    last_token = yaml.ValueToken(None, None)
+    for token in yaml.scan(text, loader):
+        start = token.start_mark.index
+        end = token.end_mark.index
+        if isinstance(token, yaml.TagToken):
+            yield start, end, token
+        elif isinstance(token, yaml.ScalarToken):
+            yield start, end, last_token
+        elif isinstance(token, (yaml.KeyToken, yaml.ValueToken)):
+            last_token = token
+
+
+if __name__ == "__main__":
+    print(colorize("".join(sys.stdin.readlines())))

python-yaml/data.yaml

@@ -0,0 +1,17 @@
+message:
+  date: 2022-01-16 12:46:17Z
+  from: [email protected]
+  to:
+    - [email protected]
+    - [email protected]
+  cc:
+    - [email protected]
+  subject: Friendly reminder
+  content: |
+    Dear XYZ,
+
+    Lorem ipsum dolor sit amet...
+  attachments:
+    image1.gif: !!binary
+        R0lGODdhCAAIAPAAAAIGAfr4+SwAA
+        AAACAAIAAACDIyPeWCsClxDMsZ3CgA7

python-yaml/formatter/server.py

@@ -0,0 +1,62 @@
+"""
+Running the backend:
+$ uvicorn formatter:app
+
+Viewing the frontend:
+http://127.0.0.1:8000/
+"""
+
+from typing import Optional
+
+import yaml
+from fastapi import FastAPI
+from fastapi.responses import JSONResponse, HTMLResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+
+TEST_DATA = {
+    "person": {
+        "name_latin": "Ivan",
+        "name": "Иван",
+        "age": 42,
+    }
+}
+
+
+class Parameters(BaseModel):
+    # Boolean flags:
+    allow_unicode: bool = False
+    canonical: bool = False
+    default_flow_style: bool = False
+    explicit_end: bool = False
+    explicit_start: bool = False
+    sort_keys: bool = True
+
+    # Valued parameters:
+    indent: Optional[int] = None
+    width: Optional[int] = None
+    default_style: Optional[str] = None
+    encoding: Optional[str] = None
+    line_break: Optional[str] = None
+    version: Optional[list] = None
+
+
+app = FastAPI()
+app.mount("/static", StaticFiles(directory="static/"), name="static")
+
+
+@app.get("/", response_class=HTMLResponse)
+async def index():
+    with open("views/index.html", "rb") as file:
+        return file.read()
+
+
+@app.post("/")
+async def serialize(parameters: Parameters):
+    try:
+        serialized = yaml.dump(TEST_DATA, **vars(parameters))
+        if isinstance(serialized, bytes):
+            return repr(serialized)
+        return serialized
+    except Exception as ex:
+        return JSONResponse(str(ex), status_code=400)

python-yaml/formatter/static/app.js

@@ -0,0 +1,65 @@
+document.addEventListener("DOMContentLoaded", async () => {
+
+    const allowUnicode = document.querySelector("#allow_unicode")
+    const canonical = document.querySelector("#canonical")
+    const content = document.querySelector("#content")
+    const defaultFlowStyle = document.querySelector("#default_flow_style")
+    const defaultStyle = document.querySelector("#default_style")
+    const encoding = document.querySelector("#encoding")
+    const explicitEnd = document.querySelector("#explicit_end")
+    const explicitStart = document.querySelector("#explicit_start")
+    const form = document.querySelector("form")
+    const indent = document.querySelector("#indent")
+    const lineBreak = document.querySelector("#line_break")
+    const sortKeys = document.querySelector("#sort_keys")
+    const version = document.querySelector("#version")
+    const width = document.querySelector("#width")
+
+    const getPayload = () => {
+        return {
+
+            // Boolean flags:
+            allow_unicode: allowUnicode.checked,
+            canonical: canonical.checked,
+            default_flow_style: defaultFlowStyle.checked,
+            explicit_end: explicitEnd.checked,
+            explicit_start: explicitStart.checked,
+            sort_keys: sortKeys.checked,
+
+            // Valued parameters:
+            indent: parseInt(indent.value),
+            width: parseInt(width.value),
+            default_style: defaultStyle.value,
+            encoding: encoding.value || null,
+            line_break: lineBreak.value,
+            version: (version.value && version.value.split(".").map(x => parseInt(x))) || null,
+        }
+    }
+
+    const reformat = async () => {
+        try {
+            const response = await fetch("/", {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(getPayload()),
+            })
+            content.value = await response.json()
+        } catch (error) {
+            alert(`Error: ${error}`)
+        }
+    }
+
+    function showRangeValue() {
+        this.previousElementSibling.innerText = this.value
+    }
+
+    form.addEventListener("change", reformat)
+    indent.addEventListener("change", showRangeValue)
+    width.addEventListener("change", showRangeValue)
+
+    showRangeValue.call(indent)
+    showRangeValue.call(width)
+    await reformat()
+})

python-yaml/formatter/static/style.css

@@ -0,0 +1,16 @@
+* {
+  box-sizing: border-box;
+  font-family: "Roboto Condensed", sans-serif;
+  font-size: 18pt;
+}
+
+.column {
+  float: left;
+  margin: 15px;
+}
+
+.row:after {
+  content: "";
+  display: table;
+  clear: both;
+}

python-yaml/formatter/views/index.html

@@ -0,0 +1,99 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>YAML Formatter</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Roboto+Condensed&display=swap" rel="stylesheet"/>
+    <link rel="stylesheet" href="/static/style.css">
+  </head>
+  <body>
+    <form>
+      <div class="row">
+        <div class="column">
+          <textarea id="content" readonly rows="15" cols="50"></textarea>
+        </div>
+        <div class="column">
+          <h2>Boolean Flags</h2>
+          <p>
+            <input type="checkbox" id="allow_unicode" name="allow_unicode">
+            <label for="allow_unicode">allow_unicode</label>
+          </p>
+          <p>
+            <input type="checkbox" id="canonical" name="canonical">
+            <label for="canonical">canonical</label>
+          </p>
+          <p>
+            <input type="checkbox" id="default_flow_style" name="default_flow_style">
+            <label for="default_flow_style">default_flow_style</label>
+          </p>
+          <p>
+            <input type="checkbox" id="explicit_end" name="explicit_end">
+            <label for="explicit_end">explicit_end</label>
+          </p>
+          <p>
+            <input type="checkbox" id="explicit_start" name="explicit_start">
+            <label for="explicit_start">explicit_start</label>
+          </p>
+          <p>
+            <input type="checkbox" id="sort_keys" name="sort_keys" checked>
+            <label for="sort_keys">sort_keys</label>
+          </p>
+        </div>
+        <div class="column">
+          <h2>Valued Parameters</h2>
+          <p>
+            <label for="indent">indent</label>
+            <span></span>
+            <input type="range" id="indent" name="indent" min="2" max="9" value="2">
+          </p>
+          <p>
+            <label for="width">width</label>
+            <span></span>
+            <input type="range" id="width" name="width" min="2" max="50" value="50">
+          </p>
+          <p>
+            <label for="default_style">default_style</label>
+            <select id="default_style" name="default_style">
+                <option value="">None</option>
+                <option value="'">Single-quote '</option>
+                <option value="&#34;">Double-quote "</option>
+            </select>
+          </p>
+          <p>
+            <label for="encoding">encoding</label>
+            <select id="encoding" name="encoding">
+              <option value="">None</option>
+              <option value="utf-8">UTF-8</option>
+              <option value="utf-16">UTF-16</option>
+              <option value="utf-32">UTF-32</option>
+              <option value="iso-8859-1">ISO-8859-1</option>
+              <option value="iso-8859-2">ISO-8859-2</option>
+            </select>
+          </p>
+          <p>
+            <label for="line_break">line_break</label>
+            <select id="line_break" name="line_break">
+              <option value="&#13;">macOS \r</option>
+              <option value="&#10;" selected>Linux \n</option>
+              <option value="&#13;&#10;">Windows \r\n</option>
+            </select>
+          </p>
+          <p>
+            <label for="version">version</label>
+            <select id="version" name="version">
+              <option value="">None</option>
+              <option value="1.1">1.1</option>
+              <option value="1.2">1.2</option>
+              <option value="1.99">1.99</option>
+              <option value="2.0">2.0</option>
+            </select>
+          </p>
+        </div>
+      </div>
+    </form>
+    <script src="/static/app.js"></script>
+  </body>
+</html>

python-yaml/models.py

@@ -0,0 +1,20 @@
+# models.py
+
+import codecs
+from dataclasses import dataclass
+
+
+@dataclass
+class Person:
+    first_name: str
+    last_name: str
+
+
+class User:
+    __slots__ = ["name"]
+
+    def __init__(self, name):
+        self.name = name
+
+    def __setstate__(self, state):
+        self.name = codecs.decode(state["name"], "rot13")

python-yaml/requirements.txt

@@ -0,0 +1,12 @@
+anyio==3.5.0
+asgiref==3.5.0
+click==8.0.4
+fastapi==0.75.0
+h11==0.13.0
+idna==3.3
+pydantic==1.9.0
+PyYAML==6.0
+sniffio==1.2.0
+starlette==0.17.1
+typing_extensions==4.1.1
+uvicorn==0.17.6