Поделиться через

Использование расширения Cookiecutter

  • Статья

cookiecutter предоставляет графический пользовательский интерфейс для обнаружения шаблонов, введения их опций и создания проектов и файлов. Visual Studio 2017 и более поздних версий включает расширение Cookiecutter. Его можно установить отдельно в более ранних версиях Visual Studio.

В Visual Studio расширение Cookiecutter доступно в разделе View>Cookiecutter Explorer:

Снимок экрана, показывающий главное окно обозревателя Cookiecutter в Visual Studio.

Необходимые условия

  • Visual Studio. Чтобы установить продукт, выполните действия, описанные в установке Visual Studio.

  • Python 3.3 или более поздней версии (32-разрядная или 64-разрядная версия) или Anaconda 3 4.2 или более поздней версии (32-разрядная или 64-разрядная версия).

    • Если подходящий интерпретатор Python недоступен, Visual Studio отображает предупреждение.

    • Если вы устанавливаете интерпретатор Python во время работы Visual Studio, выберите параметр Home на панели инструментов обозревателя Cookiecutter , чтобы определить только что установленный интерпретатор. Дополнительные сведения см. в статье Создание сред Python и управление ими в Visual Studio.

Работа с обозревателем Cookiecutter

В Проводник Cookiecutterможно просматривать и выбирать шаблоны, клонировать шаблоны на локальный компьютер, задавать параметры шаблона и создавать код из шаблонов.

Обзор шаблонов

Вы можете просматривать шаблоны в Cookiecutter Explorer , чтобы узнать, что уже установлено и что доступно.

  1. В обозревателе Cookiecutter Explorer выберите параметр Home на панели инструментов, чтобы просмотреть доступные шаблоны.

    снимок экрана, на котором показана домашняя страница обозревателя Cookiecutter в Visual Studio с шаблонами, перечисленными для категорий Рекомендуемых и GitHub.

    На домашней странице отображается список шаблонов для выбора из четырех возможных групп:

    Группа Описание Примечания
    Установлено Шаблоны, установленные на локальном компьютере. При использовании веб-шаблона его репозиторий автоматически клонируется в вложенную папку ~/.cookiecutters. Вы можете удалить установленный шаблон из системы, выбрав Удалить на панели инструментов обозревателя Cookiecutter.
    рекомендуемые Шаблоны загружены из рекомендуемого фида. Корпорация Майкрософт курирует веб-канал по умолчанию. Вы можете настроить ленту, выполнив действия, описанные в разделе Настройка параметров Cookiecutter.
    GitHub Результаты поиска GitHub для ключевого слова cookiecutter. Список репозиториев Git возвращается в форме с разбивкой на страницы. Если список результатов превышает текущее представление, можно выбрать опцию Загрузить ещё, чтобы отобразить следующий набор результатов в списке с постраничной разбивкой.
    настраиваемых Все пользовательские шаблоны, определенные с помощью Cookiecutter Explorer. При вводе пользовательского расположения шаблона в поле поиска Проводник cookiecutter расположение отображается в этой группе. Вы можете определить пользовательский шаблон, введя полный путь к репозиторию Git или полный путь к папке на локальном диске.

  2. Чтобы отобразить или скрыть список доступных шаблонов для определенной категории, щелкните стрелку рядом с категорией.

Клонирование шаблонов

Вы можете работать с доступными шаблонами в Cookiecutter Explorer, чтобы делать локальные копии для работы.

  1. В Cookiecutter Explorerвыберите шаблон. Сведения о выбранном шаблоне отображаются в нижней части проводника cookiecutter домашней странице.

    Скриншот, показывающий, как выбрать шаблон для клонирования в Проводнике Cookiecutter в Visual Studio.

    Сводка шаблона содержит ссылки для получения дополнительных сведений о шаблоне. Вы можете перейти на страницу репозитория GitHub для шаблона, просмотреть шаблон вики-или найти проблемы.

  2. Чтобы клонировать выбранный шаблон, выберите Далее. Cookiecutter создает локальную копию шаблона.

Поведение клонирования зависит от типа выбранного шаблона:

Тип шаблона Поведение
установлено Если выбранный шаблон был установлен в предыдущем сеансе Visual Studio, он автоматически удаляется, а последняя версия устанавливается и клонируется на локальном компьютере.
рекомендуемые Выбранный шаблон клонируется и устанавливается на локальном компьютере.
GitHub Выбранный шаблон клонируется и устанавливается на локальном компьютере.
Индивидуальный поиск - URL-адрес: если вы введете настраиваемый URL-адрес Git-репозитория в поле поиска Cookiecutter Explorer, а затем выберете шаблон, выбранный шаблон клонируется и устанавливается на локальный компьютер.
- путь к папке: если в поле поиска ввести путь к пользовательской папке и выбрать шаблон, Visual Studio загружает этот шаблон без клонирования.

Важно

Шаблоны cookiecutter клонируются в одну папку ~/.cookiecutters. Каждая вложенная папка называется именем репозитория Git, который не включает имя пользователя GitHub. Конфликты могут возникать, если клонировать разные шаблоны с одинаковым именем, поступающим от разных авторов. В этом случае Cookiecutter предотвращает перезапись существующего шаблона другим шаблоном с тем же именем. Чтобы установить другой шаблон, необходимо сначала удалить существующий.

Настройка параметров шаблона

После установки и локального клонирования шаблона Cookiecutter отображает страницу параметров. На этой странице можно указать параметры, например расположение пути к папке для созданных файлов:

снимок экрана, на котором показаны параметры только что установленного и клонированного шаблона в проводнике cookiecutter в Visual Studio.

Каждый шаблон Cookiecutter определяет собственный набор параметров. Если для параметра доступно значение по умолчанию, страница "Параметры " отображает предлагаемый текст в соответствующем поле. Значение по умолчанию может быть фрагментом кода, часто когда это динамическое значение, использующее другие параметры.

В данном примере шаблон называется cookiecutter-flask/cookiecutter-flask. При изменении значения параметра текст поля доступен для редактирования.

  1. В поле Create to укажите путь к папке для любых файлов, созданных Cookiecutter.

  2. Затем задайте другие нужные параметры для шаблона, например:

    • full_name: полное имя, применяемое к шаблону.
    • адрес электронной почты: адрес электронной почты автора шаблона.
    • github_username: псевдоним GitHub автора шаблона.
    • python_version: целевая версия Python для веб-приложений, созданных на основе шаблона.

Установка значений по умолчанию с помощью файла конфигурации

Значения по умолчанию можно настроить для определенных параметров с помощью файла конфигурации пользователя. Когда расширение Cookiecutter обнаруживает файл конфигурации пользователя, он перезаписывает значения по умолчанию шаблона со значениями файла конфигурации. Дополнительные сведения об этом поведении см. в разделе User Config документации по Cookiecutter.

Отказ от указанных задач

Некоторые шаблоны определяют определенные задачи Visual Studio, выполняемые после создания кода. К общим задачам относятся открытие веб-браузера, открытие файлов в редакторе и установка зависимостей. Если шаблон определяет конкретные задачи, в список параметров добавляется настройка выполнение дополнительных задач по завершении. Этот параметр можно настроить, чтобы отказаться от указанных задач Visual Studio.

Создание кода из шаблонов

После настройки параметров шаблона вы будете готовы использовать Cookiecutter для создания файлов проекта и генерации кода.

В диалоговом окне отображается кнопка после списка параметров. Текст кнопки зависит от шаблона. Вы можете увидеть Создать и открыть папку, Добавить в решениеи т. д.

  1. На странице параметров выберите кнопку, которая располагается после списка опций, например Создать и открыть папку или Добавить в решение.

    снимок экрана, на котором показана кнопка

    Cookiecutter создает код. Если выходная папка не пуста, отобразится предупреждение.

    • Если вы знакомы с выходными данными шаблона и не возражаете против перезаписи файлов, нажмите кнопку ОК, чтобы закрыть предупреждение.

    • В противном случае выберите Отмена, укажите пустую папку, а затем скопируйте созданные файлы в непустую папку выходных данных.

  2. После успешного создания файлов cookiecutter Visual Studio открывает файлы проекта шаблона в обозревателе решений.

Настройки Cookiecutter

Параметры Cookiecutter доступны в разделе Tools>Options>Cookiecutter:

Снимок экрана, на котором показаны параметры Cookiecutter в Visual Studio.

Выбор Описание
Проверьте наличие обновленных шаблонов Определяет, автоматически ли Cookiecutter проверяет наличие обновлений установленных шаблонов в Интернете.
рекомендуемый URL-адрес канала Расположение файла ленты рекомендуемых шаблонов. Расположение может быть URL-адресом или путем к локальному файлу. Оставьте URL-адрес пустым, чтобы использовать канал по умолчанию от Microsoft. Лента предоставляет простой список расположений шаблонов, разделенных новыми строками. Чтобы запросить изменения в курируемый веб-канал, выполните запрос на вытягивание источнику наGitHub.
показать справку Управляет видимостью информационной панели справки в верхней части окна Cookiecutter.

Оптимизация шаблонов Cookiecutter для Visual Studio

Расширение Cookiecutter для Visual Studio поддерживает шаблоны, созданные для Cookiecutter версии 1.4. Дополнительные сведения о создании шаблонов Cookiecutter можно найти в документации по Cookiecutter.

Отрисовка переменных шаблона по умолчанию зависит от типа данных (строка или список):

  • String: тип данных String использует метку для имени переменной, текстовое поле для ввода значения и подложку, отображающую значение по умолчанию. Подсказка в текстовом поле отображает значение по умолчанию.
  • list: тип данных списка использует метку для имени переменной и выпадающий список для выбора значения. Подсказка в поле со списком отображает значение по умолчанию.

Вы можете улучшить визуализацию, указав другие метаданные в файле cookiecutter.json, относящиеся к Visual Studio (игнорируются интерфейсом командной строки Cookiecutter). Все свойства являются необязательными:

Недвижимость Описание
label Задает текст, отображаемый над редактором переменной, а не имя переменной.
description Задает подсказку, отображаемую в элементе управления редактирования, а не значение по умолчанию для этой переменной.
url Изменяет метку в гиперссылку с подсказкой, отображающей URL-адрес. При выборе гиперссылки откроется браузер пользователя по умолчанию для этого URL-адреса.
selector Разрешает настройку редактора для переменной. В настоящее время поддерживаются следующие селекторы:
- string: стандартное текстовое поле по умолчанию для строк.
- list: стандартное поле со списком, значение по умолчанию для списков.
- yesno: поле со списком для выбора между y и n, для строк.
- odbcConnection: текстовое поле с кнопкой многоточия (...), открывающее диалоговое окно подключения к базе данных.

В следующем примере показано, как задать свойства отрисовки:

{
    "site_name": "web-app",
    "python_version": ["3.5.2"],
    "use_azure": "y",

    "_visual_studio": {
        "site_name": {
            "label": "Site name",
            "description": "E.g. <site-name>.azurewebsites.net (can only contain alphanumeric characters and `-`)"
        },
        "python_version": {
            "label": "Python version",
            "description": "The version of Python to run the site on"
        },
        "use_azure" : {
            "label": "Use Azure",
            "description": "Include Azure deployment files",
            "selector": "yesno",
            "url": "https://azure.microsoft.com"
        }
    }
}

Выполнение задач Visual Studio

Cookiecutter имеет функцию post-Generate Hooks, которая позволяет запускать произвольный код Python после создания файлов. Хотя эта функция является гибкой, она не позволяет легко получить доступ к Visual Studio.

Эту функцию можно использовать для открытия файла в редакторе Visual Studio или в веб-браузере. Вы также можете активировать пользовательский интерфейс Visual Studio, который предложит пользователю создать виртуальную среду и установить требования к пакету.

Чтобы разрешить эти сценарии, Visual Studio ищет расширенные метаданные в файле cookiecutter.json. Он ищет команды, выполняемые после того, как пользователь открывает созданные файлы в обозревателе решений или после добавления файлов в существующий проект. (Опять же, пользователь может отказаться от выполнения задач, очистив параметр Выполнить дополнительные задачи при завершении шаблона.)

В следующем примере показано, как задать расширенные метаданные в файле cookiecutter.json:

"_visual_studio_post_cmds": [
    {
        "name": "File.OpenFile",
        "args": "{{cookiecutter._output_folder_path}}\\readme.txt"
    },
    {
        "name": "Cookiecutter.ExternalWebBrowser",
        "args": "https://learn.microsoft.com"
    },
    {
        "name": "Python.InstallProjectRequirements",
        "args": "{{cookiecutter._output_folder_path}}\\dev-requirements.txt"
    }
]

Укажите команды по имени и используйте нелокализованное (английский) имя для работы с локализованными установками Visual Studio. Вы можете протестировать и найти имена команд в окне Visual Studio.

Если вы хотите передать один аргумент, укажите аргумент в виде строки, как показано для метаданных name в предыдущем примере.

Если не нужно передавать аргумент, оставьте значение пустой строкой или опустите его из JSON-файла:

"_visual_studio_post_cmds": [
    {
        "name": "View.WebBrowser"
    }
]

Для нескольких аргументов используйте массив. Для переключателей разделите их и их значения на отдельные аргументы и используйте правильные кавычки, как показано в этом примере:

"_visual_studio_post_cmds": [
    {
        "name": "File.OpenFile",
        "args": [
            "{{cookiecutter._output_folder_path}}\\read me.txt",
            "/e:",
            "Source Code (text) Editor"
        ]
    }
]

Аргументы могут ссылаться на другие переменные Cookiecutter. В предыдущем примере внутренняя переменная _output_folder_path используется для формирования абсолютного пути к созданию файлов.

Команда Python.InstallProjectRequirements работает только при добавлении файлов в существующий проект. Это ограничение существует, так как команда обрабатывается проектом Python в обозревателе решений, и нет проекта для получения сообщения в обозревателе решений - представлении папок.

Устранение неполадок с шаблоном

В следующих разделах приведены советы по устранению неполадок в среде Python и коде при работе с Cookiecutter.

Ошибка загрузки шаблона

Некоторые шаблоны могут использовать недопустимые типы данных в файле cookiecutter.json, например, булевский тип. Вы можете сообщить о случаях автору шаблона, выбрав ссылку Проблемы в панели сведений о шаблоне.

Сбой скрипта перехватчика

Некоторые шаблоны могут использовать скрипты после создания, несовместимые с пользовательским интерфейсом Cookiecutter. Например, скрипты, запрашивающие у пользователя ввод, могут завершиться ошибкой из-за отсутствия терминальной консоли.

Хук-скрипт не поддерживается в Windows

Если post-script-файл .sh, возможно, не связан с приложением в вашей операционной системе Windows. Может появиться диалоговое окно Windows, чтобы найти совместимое приложение в магазине Windows.

Шаблоны с известными проблемами

Вы можете узнать, есть ли у шаблона известные проблемы, с помощью ссылки Проблемы в сводке шаблона в Cookiecutter Explorer.

снимок экрана, показывающий, как открыть список известных проблем для шаблона в проводнике Cookiecutter.

Ссылка открывает страницу проблем GitHub для шаблона:

снимок экрана, показывающий список обнаруженных проблем для шаблона в GitHub.

Связанное содержимое