Синтаксис документа YAML для Python

Содержание:

Разметка документа YAML;
Разметка списков в документе YAML;
Разметка словарей в документе YAML;
Якоря и псевдонимы в документе YAML;
Теги YAML и типы Python;
- Функции и модули Python;
- Пользовательские объекты Python.

Разметка документа YAML.

Разметка документа YAML начинается с тройного тире '---'. Значения могут быть любого типа: например, номер телефона является числовым, а имя пользователя - строковым. Отступ используется для обозначения вложенности элементов внутри последовательности. Дефис предшествует каждому вложенному внутри элементу. Комментарии в YAML начинаются с символа # (как в Python). Документ YAML заканчивается необязательным тремя точками '...', также он может иметь несколько документов внутри одного файла YAML.

Пример явного документа YAML:

# Документ YAML начинается с ---
# Комментарии начинаются с #
---
  UserName: Alicia
  Password: pinga123* 
  phone: (495) 555-32-56
  room: 10
  TablesList:
        - EmployeeTable
        - SoftwaresList
        - HardwareList 
...

Пример неявного документа YAML:

UserName: Alicia
Password: pinga123* 
phone: (495) 555-32-56
room: 10
TablesList:
      - EmployeeTable
      - SoftwaresList
      - HardwareList

Пример нескольких документов в одном файле .yaml:

---
- Ada
- APL
- ASP

- Assembly
- Awk
---
- Basic
---
- C
- C#    # Note that comments are denoted with ' #' (space then #).
- C++
- Cold Fusion
...

Разметка списков в документе YAML.

В контексте блока, элементы списков обозначаются через тире '-', а затем пробел:

# YAML
- The Dagger 'Narthanc'
- The Dagger 'Nimthanc'
- The Dagger 'Dethanc'

# Python
["The Dagger 'Narthanc'", "The Dagger 'Nimthanc'", "The Dagger 'Dethanc'"]

Последовательности блоков могут быть вложенными:

# YAML
-
  - HTML
  - LaTeX
  - SGML
  - VRML
  - XML
  - YAML
-
  - BSD
  - GNU Hurd
  - Linux

# Python
[
   ['HTML', 'LaTeX', 'SGML', 'VRML', 'XML', 'YAML'], 
   ['BSD', 'GNU Hurd', 'Linux']
]

Нет необходимости начинать вложенную последовательность с новой строки:

# YAML
- 1.1
- - 2.1
  - 2.2
- - - 3.1
    - 3.2
    - 3.3

# Python
[1.1, [2.1, 2.2], [[3.1, 3.2, 3.3]]]

Последовательность блоков может быть вложена в словарь блоков. Обратите внимание, что в этом случае нет необходимости делать отступы для блока с последовательностью.

# YAML
left hand:
- Ring of Teleportation
- Ring of Speed

right hand:
- Ring of Resist Fire
- Ring of Resist Cold
- Ring of Resist Poison

# Python
{
    'right hand': ['Ring of Resist Fire', 'Ring of Resist Cold', 'Ring of Resist Poison'],
    'left hand': ['Ring of Teleportation', 'Ring of Speed']
}

Разметка словарей в документе YAML.

В контексте блока ключи и значения словарей разделяются двоеточием ':', а затем пробел:

# YAML
base armor class: 0
base damage: [4,4]
plus to-hit: 12
plus to-dam: 16
plus to-ac: 0

# Python
{
    'plus to-hit': 12, 
    'base damage': [4, 4], 
    'base armor class': 0, 
    'plus to-ac': 0, 
    'plus to-dam': 16
}

Сложные ключи обозначаются знаком вопроса '?', а затем пробел:

# YAML
? !!python/tuple [0,0]
: The Hero
? !!python/tuple [0,1]
: Treasure
? !!python/tuple [1,0]
: Treasure
? !!python/tuple [1,1]
: The Dragon

# Python
{
    (0, 0): 'The Hero', 
    (0, 1): 'Treasure', 
    (1, 0): 'Treasure', 
    (1, 1): 'The Dragon'
}

Словари из блоков могут быть вложенными:

# YAML
hero:
  hp: 34
  sp: 8
  level: 4
orc:
  hp: 12
  sp: 0
  level: 2

# Python
{
    'hero': {'hp': 34, 'sp': 8, 'level': 4}, 
    'orc': {'hp': 12, 'sp': 0, 'level': 2}
}

Словари из блоков могут быть вложенными в список блоков:

# YAML
- name: PyYAML
  status: 4
  license: MIT
  language: Python
- name: PySyck
  status: 5
  license: BSD
  language: Python

# Python
[
    {'status': 4, 'language': 'Python', 'name': 'PyYAML', 'license': 'MIT'},
    {'status': 5, 'license': 'BSD', 'name': 'PySyck', 'language': 'Python'}
]

Якоря и псевдонимы в документе YAML.

Используя YAML, можно представить объекты произвольных графоподобных структур. Если необходимо ссылаться на один и тот же объект из разных частей документа YAML, то нужно использовать якоря и псевдонимы.

Якоря обозначаются знаком '&', а псевдонимы - знаком '*'. Например, следующий документ YAML выражает идею героя, держащего тяжелый меч в обеих руках.

left hand: &A
  name: The Bastard Sword of Eowyn
  weight: 30
right hand: *A

Модуль PyYAML теперь полностью поддерживает рекурсивные объекты. Например, следующий документ YAML создаст объект списка, содержащий ссылку на себя.

&A [ *A ]

Теги документа YAML и типы Python.

Теги используются для обозначения типа узла YAML. Стандартные теги YAML определены в http://yaml.org/type/index.html.

Теги могут быть неявными:

# YAML
boolean: true
integer: 3
float: 3.14

# Python
{'boolean': True, 'integer': 3, 'float': 3.14}

А могут быть явными:

# YAML
boolean: !!bool "true"
integer: !!int "3"
float: !!float "3.14"

# Python
{'boolean': True, 'integer': 3, 'float': 3.14}

В следующей таблице описывается, как узлы с разными тегами преобразуются в объекты Python.

Тэг YAML	Тип Python
Стандартный тэг YAML
`!!null`	`None`
`!!bool`	`bool`
`!!int`	`int`
`!!float`	`float`
`!!binary`	`bytes`
`!!timestamp`	`datetime.datetime`
`!!omap, !!pairs`	`список пар кортежей`
`!!set`	`set`
`!!str`	`str`
`!!seq`	`list`
`!!map`	`dict`
Специфичные для Python теги
`!!python/none`	`None`
`!!python/bool`	`bool`
`!!python/bytes`	`bytes`
`!!python/str`	`str`
`!!python/unicode`	`str`
`!!python/int`	`int`
`!!python/long`	`int`
`!!python/float`	`float`
`!!python/complex`	`complex`
`!!python/list`	`list`
`!!python/tuple`	`tuple`
`!!python/dict`	`dict`
Сложные теги Python
`!!python/name:module.name`	`module.name`
`!!python/module:package.module`	`package.module`
`!!python/object:module.cls`	`module.cls экземпляр`
`!!python/object/new:module.cls`	`module.cls экземпляр`
`!!python/object/apply:module.f`	`значение f(...)`

Функции и модули.

Чтобы представить статические объекты Python, такие как функции или классы, необходимо использовать сложный тег !!python/name.

Например, функция yaml.dump() может быть представлена следующим образом:

!!python/name:yaml.dump

Аналогично, модули представляются с помощью тега !python/module:

!!python/module:yaml

Пользовательские объекты Python.

Любой сериализуемый объект может быть сериализован с помощью тега !!python/object:

!!python/object:module.Class { attribute: value, ... }

Для поддержки протокола pickle предусмотрены две дополнительные формы тега !!python/object:

!!python/object/new:module.Class
args: [argument, ...]
kwds: {key: value, ...}
state: ...
listitems: [item, ...]
dictitems: [key: value, ...]

!!python/object/apply:module.function
args: [argument, ...]
kwds: {key: value, ...}
state: ...
listitems: [item, ...]
dictitems: [key: value, ...]

Если только поле args непустое, то вышеприведенные записи можно сократить:

!!python/object/new:module.Class [argument, ...]

!!python/object/apply:module.function [argument, ...]