shotgunsoftware/tk-core — pull request #46 by manneohrstrom (2014-01-29 14:54:15+00:00)
Title: 20834 tank commands api

This adds API support to a majority of the Tank commands.

You can either execute global commands which do not need a project, or project level commands, which require a tk handle.

Here's the basic sequence of interaction:

```python

# global commands
>>> import tank

>>> tank.list_commands()
['setup_project', 'core']

# create a command object
>>> tank.get_command("setup_project")

>>> cmd = _

>>> cmd.name
'setup_project'
>>> cmd.category
'Configuration'
>>> cmd.description
'Sets up a new project with the Shotgun Pipeline Toolkit.'

# required parameters
>>> import pprint
>>> pprint.pprint(cmd.parameters)
{'check_storage_path_exists': {'default': True,
'description': 'Check that the path to the storage exists. this is enabled by default but can be turned off in order to deal with certain expert level use cases relating to UNC paths.',
'type': 'bool'},
'config_path_linux': {'default': '',
'description': 'The path on disk where the configuration should be installed on Linux.',
'type': 'str'},
'config_path_mac': {'default': None,
'description': 'The path on disk where the configuration should be installed on Macosx.',
'type': 'str'},
'config_path_win': {'default': '',
'description': 'The path on disk where the configuration should be installed on Windows.',
'type': 'str'},
'config_uri': {'default': 'tk-config-default',
'description': "The configuration to use when setting up this project. This can be a path on disk to a directory containing a config, a path to a git bare repo or 'tk-config-default' to fetch the default config from the toolkit app store.",
'type': 'str'},
'force': {'default': False,
'description': 'Enabling this flag allows you to run the set up project on projects which have already been previously set up. ',
'type': 'bool'},
'project_folder_name': {'default': None,
'description': 'Name of the folder which you want to be the root point of the created project. If a project already exists, this parameter must reflect the name of the top level folder of the project.',
'type': 'str'},
'project_id': {'default': None,
'description': 'Shotgun id for the project you want to set up.',
'type': 'int'}}

# run the execute method to run it. pass necessary params
>>> cmd.execute({"project_folder_name": "foo", "project_id": 156})
```

For the project level commands, there are more stuff to choose from:

```python
>>> tk.list_commands()
['setup_project', 'core', 'localize', 'validate', 'cache_apps', 'clear_cache', 'app_info', 'install_app', 'install_engine', 'updates', 'configurations']
>>> cmd = tk.get_command("updates")
>>> cmd.parameters
{'app_filter': {'default': 'ALL', 'type': 'str', 'description': 'Name of app to check.'}, 'engine_filter': {'default': 'ALL', 'type': 'str', 'description': 'Name of engine to check.'}, 'environment_filter': {'default': 'ALL', 'type': 'str', 'description': 'Name of environment to check.'}}
>>> cmd.execute({})
```

Misc notes:

- A default logger is used for output, you can set your own via a method on the command object.
- Default values can be set up in the param schema. The code helps validates params etc.
- You can define return values, see the `core` command