Нужны ли вам кавычки, зависит от парсера. Составление Docker AFAIK по-прежнему полагается на модуль PyYAML, который реализует большую часть YAML 1.1 и имеет несколько собственных особенностей.
В общем, вам нужно всего лишь процитировать то, что в противном случае может быть неверно истолковано, или конфликтовать с какой-то конструкцией YAML, которая не является скалярной строкой. Вам также нужны (двойные) кавычки для вещей, которые не могут быть представлены в простых скалярах, скалярах в одинарных кавычках или литеральных или свернутых скалярах блочного стиля.
Неверная
Вам нужно заключить в кавычки строки, похожие на некоторые другие структуры данных:
- booleans: «True», «False», но PyYAML также предполагает использование альтернативных слов, таких как «Yes», «No», «On», «Off», представляющих логические значения (и все строчные буквы, все заглавные версии должны рассматриваться также). Обратите внимание, что в стандарте YAML 1.2 удалены ссылки на эти альтернативы.
- целые числа: включает строку, состоящую только из цифр. Но также шестнадцатеричное (
0x123) и восьмеричное число (0123). Восьмеричные числа в YAML 1.2 записаны как 0o123, но PyYAML не поддерживает это, однако лучше всего указывать оба.
Специальное целое число, которое PyYAML по-прежнему поддерживает, но опять же не в спецификации YAML 1.2, представляет собой шестнадцатеричные числа: число 60, разделенное двоеточием (:), указание времени, а также MAC-адреса можно интерпретировать как таковые, если значения между / после двоеточий находятся в диапазоне 00-59
- float: строки типа
1E3 (с необязательным знаком ans mantissa) должны быть заключены в кавычки. Конечно, 3.14 также нужно заключать в кавычки, если это строка. И также следует указывать шестнадцатеричные числа (с мантиссой после числа после последнего двоеточия).
- отметки времени:
2001-12-15T02:59:43.1Z, но также необходимо указывать строки, подобные iso-8601, чтобы их нельзя было интерпретировать как отметки времени
- Значение
null записывается в виде пустой строки, как ~ или Null (для всех типов корпусов), поэтому любые строки, соответствующие этим, должны быть заключены в кавычки.
Цитирование в вышеупомянутом может быть сделано с одинарными или двойными кавычками, или могут использоваться литералы блочного стиля или сложенные скаляры. Обратите внимание, что для блочного стиля вы должны использовать |- соотв. >- чтобы не вводить завершающий символ новой строки, которого нет в исходной строке.
Столкновения
YAML назначает особое значение определенным символам или комбинациям символов. Некоторые из них имеют особое значение только в начале строки, другие только внутри строки.
- символов из набора
!&*?{[ обычно указывают на специальные конструкции YAML. Некоторые из них могут быть неоднозначными в зависимости от следующего символа, но я бы не стал на это полагаться.
- пробел, за которым следует
# указывает на комментарий конца строки
- везде, где возможна клавиша (и во многих режимах блокировки) комбинация двоеточие + пробел (
:) указывает на то, что значение будет следующим. Если эта комбинация является частью вашей скалярной строки, вы должны заключить в кавычки.
Как и в случае неверной интерпретации, вы можете использовать одинарные или двойные кавычки, литеральные или складывающиеся скаляры в стиле блоков. После первой строки скаляра блочного стиля не может быть комментариев в конце строки.
PyYAML может дополнительно запутаться любым двоеточием + пробелом в простом скаляре (даже если это значение), поэтому всегда указывайте их в кавычках.
Представление специальных символов
Вы можете вставлять специальные символы или кодовые точки Юникода в файл YAML, но если вы хотите, чтобы они были четко видны во всех случаях, вы можете использовать escape-последовательности. В этом случае вы должны использовать двойные кавычки, это единственный режим, который
позволяет избежать обратной косой черты. И, например, \u2029. Полный список таких выходов можно взять из стандарта , но обратите внимание, что PyYAML не реализует, например, \/ (или, по крайней мере, не реализовал, когда я разветвил эту библиотеку).
Один из способов выяснить, что заключать в кавычки или нет, - это использовать библиотеку, используемую для сброса имеющихся у вас строк. My ruamel.yaml и PyYAML, используемые docker-compose, при потенциальном сбросе простого скаляра, оба пытаются прочитать (да, путем анализа результата) простое скалярное представление строки, и если это приводит к чему-то отличному от строки, это ясно, кавычки должны быть применены. Вы также можете сделать это: если сомневаетесь, напишите небольшую программу, выводящую список строк, которые у вас есть, используя safe_dump() PyYAML, и применяйте кавычки везде, где делает PyYAML.