The @directive decorator

Having built-in directives from Lilya is great as it gives you a lot of niceties for your project but having custom directives is what really powers up your application and takes it to another level.

But what if you want to use a modern client to declare directives?

Lilya uses Sayer under the hood and now this allows to bring the @directive decorator to make your life easier.

Important

Before reading this section, you should get familiar with the ways Lilya handles the discovery of the applications.

The following examples and explanations will be using the --app and environment variables approach but the auto discovery is equally valid and works in the same way.

Tip

As for Lilya 0.15.3+, both custom directives and @directive are supported.

The @directive

This is still a custom directive but using Sayer under the hood to run your directives.

On the contrary of class based directives, the syntax when using the @directive is simpler when calling.

lilya run <custom-directive> <ARGS>

Quite simple, right?

Importing the decorator

This is even simpler:

from lilya.cli.decorator import directive

Where should directives be placed at?

All the custom directives created must be inside a directives/operations package in order to be discovered.

The place for the directives/operations can be anywhere in your application and you can have more than one as well.

Example:

.
├── Taskfile.yaml
└── myproject
    ├── __init__.py
    ├── apps
    │   ├── accounts
    │   │   ├── directives
    │   │   │   ├── __init__.py
    │   │   │   └── operations
    │   │   │       ├── createsuperuser.py
    │   │   │       └── __init__.py
    │   ├── payroll
    │   │   ├── directives
    │   │   │   ├── __init__.py
    │   │   │   └── operations
    │   │   │       ├── run_payroll.py
    │   │   │       └── __init__.py
    │   ├── products
    │   │   ├── directives
    │   │   │   ├── __init__.py
    │   │   │   └── operations
    │   │   │       ├── createproduct.py
    │   │   │       └── __init__.py
    ├── configs
    │   ├── __init__.py
    │   ├── development
    │   │   ├── __init__.py
    │   │   └── settings.py
    │   ├── settings.py
    │   └── testing
    │       ├── __init__.py
    │       └── settings.py
    ├── directives
    │   ├── __init__.py
    │   └── operations
    │       ├── db_shell.py
    │       └── __init__.py
    ├── main.py
    ├── serve.py
    ├── tests
    │   ├── __init__.py
    │   └── test_app.py
    └── urls.py

As you can see from the previous example, we have four directives:

• createsuperuser - Inside accounts/directives/operations.
• run_payroll - Inside payroll/directives/operations.
• createproduct - Inside products/directives/operations.
• db_shell - Inside ./directives/operations.

All of them, no matter where you put the directive, are inside a directives/operations where lilya always looks at.

This is the same as usual in Lilya, nothing has changed.

Help

There are two helps in place for the directives. The one you run the lilya executor (run) and the one for the directive.

--help

This command is only used for the executor help, for example:

$ lilya run --help

-h/--h

This flag is used to access the directive help and not the run.

$ lilya run mydirective -h

Or

$ lilya run mydirective --h

Notes

The only way to see the help of a directive is via -h/--h.

If --help is used, it will only show the help of the run and not the directive itself.

Order of priority

This is very important to understand.

What happens if we have two custom directives with the same name?

Let us use the following structure as example:

.
├── Taskfile.yaml
└── myproject
    ├── __init__.py
    ├── apps
    │   ├── accounts
    │   │   ├── directives
    │   │   │   ├── __init__.py
    │   │   │   └── operations
    │   │   │       ├── createsuperuser.py
    │   │   │       └── __init__.py
    │   │   ├── __init__.py
    │   │   ├── models.py
    │   │   ├── tests.py
    │   │   └── v1
    │   │       ├── __init__.py
    │   │       ├── schemas.py
    │   │       ├── urls.py
    │   │       └── controllers.py
    ├── configs
    │   ├── __init__.py
    │   ├── development
    │   │   ├── __init__.py
    │   │   └── settings.py
    │   ├── settings.py
    │   └── testing
    │       ├── __init__.py
    │       └── settings.py
    ├── directives
    │   ├── __init__.py
    │   └── operations
    │       ├── createsuperuser.py
    │       └── __init__.py
    ├── main.py
    ├── serve.py
    ├── tests
    │   ├── __init__.py
    │   └── test_app.py
    └── urls.py

This example is simulating a structure of a lilya project with two custom directives with the same name.

The first directive is inside ./directives/operations/ and the second inside ./apps/accounts/directives/operations.

Lilya directives work on a First Found First Executed principle and that means if you have two custom directives with the same name, lilya will execute the first found directive with that given name.

In other words, if you want to execute the createsuperuser from the accounts, the first found directive inside ./directives/operations/ shall have a different name or else it will execute it instead of the intended from accounts.

Execution

Lilya directives use the same events as the one passed in the application.

For example, if you want to execute database operations and the database connections should be established before hand, you can do in two ways:

• Use Lifespan events and the directives will use them.
• Establish the connections (open and close) inside the Directive directly.

The pratical example uses the lifespan events to execute the operations. This way you only need one place to manage the needed application events.

Example

Lets transform the example from createsuperuser into a @directive form.

As you could see from the explanation, its the same as the normal class based directives.

The createsuperuser custom directive

Let's do the createsuperuser now using the @directive.

myproject/directives/operations/createsuperuser.py

import sys
from typing import Annotated

from asyncpg.exceptions import UniqueViolationError
from lilya.cli.decorator import directive
from sayer import command, success, error, Option

from ..main import User


@directive
@command
def create(
    first_name: Annotated[str, Option(required=True)],
    last_name: Annotated[str, Option(required=True)],
    username: Annotated[str, Option(required=True)],
    email: Annotated[str, Option(required=True)],
    password: Annotated[str, Option(required=True)],
):
    """
    Creates a superuser with the given first name and last name.
    """
    try:
        user = await User.query.create_superuser(
            first_name=first_name,
            last_name=last_name,
            username=username,
            email=email,
            password=password,
        )
    except UniqueViolationError:
        error(f"User with email {email} already exists.")
        sys.exit(0)

    success(f"Superuser {user.email} created successfully.")

And this should be it. We now have a createsuperuser and an application and now we can run in the command line:

Using the --app or LILYA_DEFAULT_APP

$ lilya --app myproject.main:app run createsuperuser --first-name Lilya --last-name Framework --email example@lilya.dev --username lilya --password lilya

Or

$ export LILYA_DEFAULT_APP=myproject.main:app
$ lilya run createsuperuser --first-name Lilya --last-name Framework --email example@lilya.dev --username lilya --password lilya

As you can see, the @directive acts as the class based directives but in a different syntax.