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

  • Статья

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

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

Снимок экрана: главное окно Обозреватель cookiecutter в Visual Studio.

Необходимые компоненты

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

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

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

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

Работа с Обозреватель cookiecutter

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

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

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

  1. В Обозреватель cookiecutter выберите параметр "Главная" на панели инструментов, чтобы просмотреть доступные шаблоны.

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

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

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

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

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

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

  1. В файле cookiecutter Обозреватель выберите шаблон. Сведения о выбранном шаблоне отображаются в нижней части домашней страницы cookiecutter Обозреватель.

    Снимок экрана, на котором показано, как выбрать шаблон для клонирования в cookiecutter Обозреватель в Visual Studio.

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

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

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

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

Внимание

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    Снимок экрана: кнопка

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

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

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

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

Настройка параметров cookiecutter

Выберите Инструменты>Параметры>Cookiecutter, чтобы увидеть доступные параметры Cookiecutter.

Снимок экрана: параметры cookiecutter в Visual Studio.

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

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

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

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

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

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

Свойство Description
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

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

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

Вы можете узнать, имеет ли шаблон известные проблемы, используя ссылку "Проблемы" в сводке шаблона в файле Cookiecutter Обозреватель:

Снимок экрана: открытие списка известных проблем для шаблона в cookiecutter Обозреватель.

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

Снимок экрана: список обнаруженных проблем для шаблона в GitHub.

Связанный контент