Add Tutorial Walk Through

[derks]

The doc is pretty intense... need something to go in-between Quickstart and Read All This Shit To Understand All The Things.

[fxstein]

For what its worth: I am looking for some more real world examples of controllers, interfaces and handlers. When to use what.

For example I have an App class that needs to perform special tasks to init the overall configuration. Like assemble more complex variables or objects based on the app config settings.

I am also looking for how to add capabilities to have the app communicate with external interfaces. e.g. perform REST gets and posts and leverage the config settings for the interface/handler.

I assume controllers are only for tasks that are exposed to the CLI. But I am not quite sure when to use Interfaces and handlers.

Sorry if these are Noob questions. Still trying to figure everything out.

[derks]

@fxstein I appreciate your feedback here, and again apologize for the delay in development (my $dayjob has been busy). To touch on your questions a bit:

For example I have an App class that needs to perform special tasks to init the overall configuration. Like assemble more complex variables or objects based on the app config settings.

For this, I generally tie into CementApp.validate_config() which is intended to be used for this purpose more or less. The validate_config method is called after configuration files are parsed... I've used it for doing something like the following (due to ConfigParser limitations):

from cement.core.foundation import CementApp
from cement.utils.misc import is_true

class MyApp(CementApp):
    class Meta:
        label = 'myapp'

    def validate_config(self):
        # convert 1, 0, true, false, etc to boolean
        my_param = self.config.get('myapp', 'my_param')
        self.config.set('myapp', 'my_param', is_true(my_param))

I am also looking for how to add capabilities to have the app communicate with external interfaces. e.g. perform REST gets and posts and leverage the config settings for the interface/handler.

For this, I use a combination of post_argument_parsing hook, and CementApp.extend():

from cement.core import hook

def extend_my_api_client(app):
    # do something to setup an api client object
    my_api_client = SomeAPIClientClass()

    app.extend('my_api_client', my_api_client)

hook.register('post_argument_parsing', extend_my_api_client)

You can then access app.my_api_client throughout your application. Maybe app.my_api_client.get(12345) (whatever the object does).

I assume controllers are only for tasks that are exposed to the CLI. But I am not quite sure when to use Interfaces and handlers.

Yes, controllers are specifically for exposing operations to the end-user via CLI commands/arguments. Interfaces/Handlers are primarily for segmenting bits of code that might have alternative use cases (handlers). Take for example a database interface. You might want to define an IDatabase interface that specifies exactly what functions an implemenation handler must support. That might be simple CRUD operations like create, read, update, delete... where the actually operations are implemented in the handler, but the application (or developer) can have a standardized usage interface. in that case IDatabase defines the interface (i.e. that implementation must provide create(), read(), etc) but you might have unique implementations like MySQLDatabaseHandler, PostgresDatabaseHandler, etc.... the usage of the handler would be the same (app.db.read(...), app.db.update(...), etc.

Does that make sense?

[derks]

This can be closed, complete doc/api rewrites took place when Cement 3 was released. https://builtoncement.com