SDK

Starting with version 0.3.0 of Fantastico framework all dispersed shell scripts are unified under Fantastico Software Development Kit. In addition, the sdk is complemented by autogenerated documentation.

Intro

Fantastico sdk was developed with the following requirements in my mind:

• Allow developers to manage Fantastico projects easily (using a single uniform command line). This is similar to many other frameworks (e.g android sdk).
• Allow easily extension of sdk through plugins (e.g: activate off the shelf components into my project).
• Create a uniform way to provide feedback to developers (prompt user for data, show help messages, support parameters).
• Make the sdk compliant with linux way of developing command lines.

Usage

In this section you can find samples of how to use the sdk and how to make it available in older projects.

# For versions prior to **0.3.0**
pip install fantastico -U

fsdk --help

When you invoke fantastico sdk with –help argument it will list all available commands. Similar to other linux command lines you can obtain help hierarchical:

# Show help screen for fantastico <command>
fsdk <command> --help

In order for Fantastico SDK to work correctly make sure your project is on the PYTHONPATH. If PYTHONPATH is not set correctly you will not be able to use some sdk extensions.

Supported commands

• Activate extension command
• Fantastico command
• Syncdb command
• Version command

Technical summary

class fantastico.sdk.fantastico.SdkCore(argv, cmd_factory=<class 'fantastico.sdk.sdk_core.SdkCommandsRegistry'>, supported_prefixes=None, settings_facade_cls=<class 'fantastico.settings.SettingsFacade'>)

This class provides the core functionality of Fantastico Software Development Kit. It wires all available commands together and handles requests accordingly. To better understand how sdk is designed see the following class diagram:

As you can see in above diagram, sdk core is just the main entry point of Fantastico Software Development Kit. It wires all available sdk commands together and it adds support for uniformly executes them and pass them arguments..

exec()

This method does nothing because fantastico is designed to accept only registered subcommands.

get_arguments()

This property retrieves support fantastico arguments.

get_help()

This method returns the friendly help message describing the method.

class fantastico.sdk.sdk_core.SdkCommandsRegistry

This class holds all registered commands available to use in the sdk. It is important to understand that commands and subcommands are registered by name and must be unique. This is because, by design, each command can easily become a subcommand for another command. It facilitates very flexible extension of sdk and reusage of existing commands.

static add_command(cmd_name, cmd_cls)

This method registers a new command using the given name.

Parameters:

• cmd_name (str) – Command name used to uniquely identify the command.
• cmd_class (fantastico.sdk.sdk_core.SdkCommand) – A subclass of sdk command.

Raises fantastico.sdk.sdk_exceptions.FantasticoSdkError:  

If the given name is not unique or cmd class is wrong.

static get_command(cmd_name, cmd_args)

This method retrieve a concrete sdk command by name with the give args passed.

Parameters:

• cmd_name (str) – The registered command name we want to instantiate.
• cmd_args (list) – a list of arguments received from command line.

Returns:

Command instance.

Return type:

fantastico.sdk.sdk_core.SdkCommand

Raises fantastico.sdk.sdk_exceptions.FantasticoSdkCommandNotFoundError:  

if command is not registered.

class fantastico.sdk.sdk_core.SdkCommandArgument(arg_short_name, arg_name, arg_type, arg_help)

This class describe the attributes supported by a command argument. For a simple example of how arguments are used read fantastico.sdk.sdk_core.SdkCommand

help

This read only property holds the argument help message.

name

This read only property holds the argument name. Name property will represent the long name argument available for sdk commands. E.g: –name.

short_name

This read only property holds the argument short name. Short name property will represent the short name argument available for sdk commands. E.g: -n.

type

This read only property holds the argument type.

class fantastico.sdk.sdk_core.SdkCommand(argv, cmd_factory)

This class provides the contract which must be provided by each concrete command. A command of sdk is just and extension which can provide custom actions being executed by Fantastico in a uniform manner.

Below you can find a simple example of how to implement a concrete command:

In the previous example, we have shown that all received arguments from command line are magically provided into self._arguments attribute of the command.

When a sdk command is instantiated with a list of command line arguments the first element from the list must be the command name. This happens because all arguments passed after a command name belongs only to that command.

exec()

This method must be overriden by each concrete command and must provide the command execution logic.

Raises fantastico.sdk.sdk_exceptions.FantasticoSdkCommandError:  if an exception occurs while executing the command.

exec_command(*args, **kwargs)

This method provides a template for executing the current command if subcommands are present. Internally it invokes overriden exec method.

Raises:

• fantastico.sdk.sdk_exceptions.FantasticoSdkCommandError – if an exception occurs while executing the command.
• fantastico.sdk.sdk_exceptions.FantasticoSdkCommandNotFoundError – if a subcommand does not exist.

get_arguments()

This method must be overriden by each concrete command and must return the command supported arguments.

class fantastico.sdk.sdk_decorators.SdkCommand(name, help, target=None, settings_facade_cls=<class 'fantastico.settings.SettingsFacade'>)

This decorator describe the sdk commands metadata:

1. name
2. target (which is the main purpose of the command. E.g: fantastico - this mean command is designed to work as a subcommand for fantastico cmd).
3. help (which describes what this method does). It will automatically contain a link to official fantastico documentation of the command.

It is used in conjunction with fantastico.sdk.sdk_core.SdkCommand. Each sdk command decorated with this decorator automatically receives get_name and get_target methods.

class fantastico.sdk.sdk_exceptions.FantasticoSdkError(msg=None, http_code=400)

This is the base exception used to describe unexpected situations occuring into fantastico sdk. Below you can see the sdk hierarchy of concrete exceptions.

class fantastico.sdk.sdk_exceptions.FantasticoSdkCommandError(msg=None, http_code=400)

This class describe an exception which occured into one of fantastico sdk commands.

class fantastico.sdk.sdk_exceptions.FantasticoSdkCommandNotFoundError(msg=None, http_code=400)

This class describe an exception which occurs when we try to execute an inexistent command.