Abstract Class to manage the interaction between the users and the Script folder (mantid subproject).

Inside the mantid repository (https://github.com/mantidproject) there is also a subproject called scripts (https://github.com/mantidproject/scripts), created to allow users to share their scripts, as well as to allow Mantid Team to distribute to the Mantid community scripts for analysis and also to enhance the quality of the scripts used for the sake of data analysis.

The ScriptRepository interface aims to provide a simple way to interact with that repository in order to promote its usage. In order to enhance the usage, it is necessary:

List all scripts available at the repository
Download selected scripts.
Check for updates
Allow to publish users scripts/folders.

ScriptRepository may show all the files inside the script repository through ScriptRepository::listFiles. Only the names of the files may not be sufficient, to help deciding if the file would be usefull or not, so, the author, the description and when the file was last changed can be accessed through ScriptRepository::ScriptInfo.

The list of the files could become confusing if a large amount of automatically created files is installed. In order to avoid this, it is possible to edit the file patterns that should be ignored when listing files, this is done through ScriptRepository::setIgnorePatterns, and you can check this settings through the ScriptRepository::ignorePatterns.

After looking at a file, you may be interested in downloading it through ScriptRepository::download.

When working with the repository, the files may be local only, if the user created a file inside his folder, it may not be downloaded, it can be locally modified, or changed remotely and not up-to-date, or even, being modified locally and remotely. Use ScriptRepository::fileStatus in order to get these informations of any file.

The user may decide to upload one of his file or folder, to share it. This is possible through the ScriptRepository::upload. The same command may be used to publish also some updates made to an already shared file.

Finally, the ScriptRepository have to check periodically the remote repository (https://github.com/mantidproject/scripts), but it will be done indirectly through a mantid web service, it is the responsibility of external tools to ensure it is done periodically, through ScriptRepository::check4Update. For the sake of simplicity, this method is used also to create the local repository in case it does not exists.

Before using the ScriptRepository, it must be installed inside a local folder (ScriptRepository::install). If ScriptRepository is not created pointing to a valid local repository, the methog ScriptRepository::isValid will return false, and no method will be available, except, install. As a good practice, it is good to ensure that the connection between the local object and the mantid web service is available, through the ScriptRepository::connect.

Note: Exceptions will be triggered through ScriptRepoException in order user understandable information as well as techinical details.; Mantid::API::ScriptRepositoryImpl implements this class.

Author: Gesner Passos, ISIS, RAL

Date: 11/12/2012

Files

Scripts, Folders and Files Description

The description of the files and scripts will obey an agreement for the following type of files:

Python Scripts

If the script is as python file, then the description will be the module doc attribute. If this information is not availabe, them, it will try to get the first group of comments, at the header of the file. For example, the following code:

import mantid

print mantid.__doc__

Produces:

Mantid
======

http://www.mantidproject.org

The Mantid project pro (...)

Another example, consider this python file:

#!/usr/bin/env python
 
print 'Hello world'

Will show the description as follow:

This module is responsible to display a
'Hello world' greeting.

Folders

If the script is a folder, it will try to find a file init.py, so to check if this folder is a python module. If it does, it will parse the init.py as in section Python Scripts. Otherwise, it will look for a file starting with name README, and will show it. For example, if the mantid repository path would be passed, it would show the content of its README.md file:

Mantid
======

The Mantid project provides (...)

In this case, author should be any name found inside the README file that starts with the following line: 'Author:'.

README files

They will work as was expected for folders Folders.