Ubuntu logo

Developer

Getting Started

Creating your template space

You can create a new template in any $XDG_DATA_DIRS/quickly/templates directory. On most system, templates should be installed to /usr/share/quickly/templates/. You can also install them in user-space in ~/.local/share/quickly/templates/:

mkdir ~/.local/share/quickly/templates/my-template/
touch ~/.local/share/quickly/templates/my-template/__init__.py

Yes, Quickly template directories are also Python packages. They aren’t on the PYTHON_PATH, but Quickly knows how to find them and load them.

Your Template class

Quickly looks for a class called Template in the root of your template’s python namespace. This class should be a sub-class of quickly.core.templates.BaseTemplate or some class that inherits from it:

from quickly.core.templates import BaseTemplate

class Template(BaseTemplate):

    class Meta:
        name = 'my-template'
        version = '1.0'

The Meta class let’s you provide some data about your template, including it’s name and version number.

For more about writing your own Templates, see Advanced Template Development

Adding Commands

Commands are added directly to the Template class itself. The name of the variable is the name of the command on the command-line. If a command takes instantiation variables, you can pass them here. Your template ends up looking a lot like this:

from quickly.core.templates import BaseTemplate
from .commands import Create, Run

class Template(BaseTemplate):

    class Meta:
        name = 'my-template'
        version = '1.0'

    # Add commands to this template
    create = Create(project_root = 'project_root')
    run = Run()

    # Example of command aliasing
    launch = run.clone()

As you can see, the command name doesn’t have to correspond to the command class’ name. You can also add more than once instance of a command class using a different command name:

$ quickly --template my-template help --all
Usage: quickly [command]

Available Commands for my-template:
  quickly create [project_name]
  quickly run -- [program arguments]
  quickly launch -- [program arguments]

Making your own Commands

Quickly commands are Python classes that sub-class the quickly.core.commands.BaseCommand class, and implement a custom .run() method:

from quickly.core.commands import BaseCommand
class SayHello(BaseCommand):

    class Meta:
        usage = 'quickly %(cmd_name)s'
        help = 'Makes Quickly say hello'

    def run(self):
        print('Hello World')

Notice that it uses %(cmd_name)s in place of the command name. This is because your command class can be given a custom name when added to a template, so the usage string (and help string) will replace %(cmd_name)s with the actual command name. You can then add that command to your template:

from quickly.core.templates import BaseTemplate
from .commands import SayHello

class Template(BaseTemplate):

    class Meta:
        name = 'my-template'
        version = '1.0'

    # Add commands to this template
    hello = SayHello()

Which gets you:

$ quickly --template my-template help
Usage: quickly [command]

Available Commands for my-template:
  quickly hello

$ quickly --template my-template help hello
Usage: quickly hello

Makes Quickly say hello

$ quickly --template my-template hello
Hello World

For more about writing your own Commands, see Advanced Command Development