LogoLogo
Official SiteAPI Reference
stable/3.0
stable/3.0
  • Cement Developer Guide
  • Release Information
    • What's New!
    • Upgrading
    • ChangeLog
    • Deprecations
  • Getting Started
    • Installation
    • Developer Tools
    • Framework Overview
    • Beginner Tutorial
      • Part 1: Creating Your First Project
      • Part 2: Adding Features
      • Part 3: Extending a Project
      • Part 4: Making Everything Legit
  • Core Foundation
    • Interfaces and Handlers
    • Hooks
    • Configuration Settings
    • Arguments
    • Logging
    • Controllers
    • Output Rendering
    • Caching
    • Mail Messaging
    • Framework Extensions
    • Application Plugins
    • Templating
  • Utilities
    • Filesystem
    • Shell
    • Miscellaneous
  • Extensions
    • Alarm
    • Argparse
    • Colorlog
    • ConfigParser
    • Daemon
    • Dummy
    • Generate
    • Jinja2
    • Json
    • Logging
    • Memcached
    • Mustache
    • Plugin
    • Print
    • Redis
    • Scrub
    • SMTP
    • Tabulate
    • Yaml
    • Watchdog
  • Additional Topics
    • Extending The App Object
    • Unit Testing
    • Cleanup
    • Signal Handling
    • Pipenv
    • Autocomplete
    • Profiling with cProfile
    • Debugging with VSCode
  • Environment Variables
  • Terminology
  • Contributing
  • Privacy Policy
Powered by GitBook
On this page
  • Introduction
  • Requirements
  • Configuration
  • Application Configuration Settings
  • Application Meta Options
  • Usage
  • Examples
  • Generate Templates
  1. Extensions

Generate

PreviousDummyNextJinja2

Last updated 2 years ago

Introduction

The Generate Extension includes the controller, and provides a mechanism for generating common content from template directories. An example use case would be the ability for application developers to easily generate new plugins for their application… similar in other applications such as Chef Software’s chef generate cookbook type utilities.

The use this extension to generate projects, plugins, extensions, scripts, etc for developers building their applications on the framework.

Documentation References:

API References:

Requirements

  • pyYaml

  • A valid must be defined at the application level via such as jinja2, mustache, etc.

Cement 3.0.8+:

pip install cement[generate]

Applications using Cement <3.0.8 should continue to include pyYaml in their dependencies.

Configuration

Application Configuration Settings

This extension honors the following settings under the primary namespace (ex: [myapp]) of the application configuration:

Setting

Description

template_dir

Directory path of a local template directory.

Application Meta Options

Option

Description

template_handler

A template handler to use as the backend for templating

template_dirs

A list of data directories to look for templates

template_module

A python module to look for templates

Usage

Examples

from cement import App

class MyApp(App):
    class Meta:
        label = 'myapp'
        extensions = ['generate', 'jinja2']
        template_handler = 'jinja2'


with MyApp() as app:
    app.run()
$ python myapp.py --help
usage: myapp [-h] [--debug] [--quiet] {generate} ...

optional arguments:
  -h, --help  show this help message and exit
  --debug     toggle debug output
  --quiet     suppress all output

sub-commands:
  {generate}
    generate  generate controller


$ python myapp.py generate --help
usage: myapp generate [-h] {plugin} ...

optional arguments:
  -h, --help  show this help message and exit

sub-commands:
  {plugin}
    plugin      generate plugin from template

Generate Templates

The Generate Extension looks for a generate sub-directory in all defined template directory paths defined at the application level. If it finds a generate directory it treats all items within that directory as a generate template.

A Generate Template requires a single configuration YAML file called .generate.yml that looks something like:

---
ignore:
    - "^(.*)ignore-this(.*)$"
    - "^(.*)ignore-that(.*)$"

exclude:
    - "^(.*)exclude-this(.*)$"
    - "^(.*)exclude-that(.*)$"

variables:
    - name: 'my_variable_name'
      prompt: 'The Prompt Displayed to The User'

Generate Template Configuration

The following configurations are supported in a generate template’s config:

ignore

A list of regular expressions to match files that you want to completely ignore

exclude

A list of regular expressions to match files that you want to copy only (not rendered as template)

variables

A list of variable definitions that support the following sub-keys:

This extension honors the following options:

Generate
Cement Developer Tools
Templating
Cement Generate Extension
template handler
App.Meta.template_handler
App.Meta