Python utilities for automating Slicer development tasks.
This package provides a suite of tools to help automate certain tasks that are often performed when developing code and extensions for Slicer.
Note
This documentation is intended for developers working on such tools. Users of the same should refer to the Extension Wizard documentation on the Slicer wiki.
Symbolic manipulation of CMake scripts.
This module provides a set of classes to support symbolic parsing of CMake script. The use of symbolic parsing, as opposed to regular expressions, frees the user from needing to worry about syntactic context (is that really a function, or is it inside of a string or comment?) and provides a representation that is more suitable to direct manipulation.
In addition to the several token classes provided, CMakeScript provides an interface for bidirectional translation between raw text and tokenized representations.
Unlike other parsers, this module is not a “pretty formatter”, but rather is specifically designed to preserve the original formatting of a script in order to be able to perform convert losslessly from raw to parsed form and back, while still providing a parsed form that is easy to use and manipulate. Care should be used, however, when creating or manipulating scripts, as there are effectively no safeguards against producing a script that is syntactically invalid.
Bases: object
Tokenized representation of a CMake script.
The list of tokens which comprise the script. Manipulations of this list should be used to change the content of the script.
| Parameters: | content (basestring) – Textual content of a CMake script. |
|---|---|
| Raises : | SyntaxError or EOFError if a parsing error occurs (i.e. if the input text is not syntactically valid). |
with fi = open('CMakeLists.txt'):
script = CMakeParser.CMakeScript(f.read())
with fo = open('CMakeLists.txt.new', 'w'):
fo.write(str(script))
Bases: SlicerWizard.CMakeParser.Token
Command token.
The name of the command.
The delimiter which starts the command’s argument list. This shall end with '(' and may begin with whitespace if there is whitespace separating the command name from the ‘(‘.
The delimiter which ends the command’s argument list. This shall end with ')' and may begin with whitespace if there is whitespace separating the last argument (or the opening ‘(‘ if there are no arguments) from the ‘)’.
Bases: SlicerWizard.CMakeParser.Token
Comment token.
The textual content of the comment.
The delimiter which starts this comment: '#', optionally followed by a lua-style long bracket (e.g. '[[', '[===[', etc.).
Bases: SlicerWizard.CMakeParser.Token
String token.
The textual content of the string. Note that escapes are not evaluated and will appear in their raw (escaped) form.
The delimiter which starts this string. The delimiter may be empty, '"', or a lua-style long bracket (e.g. '[[', '[===[', etc.).
String tokens appear as arguments to Command, as they are not valid outside of a command context.
Bases: object
Base class for CMake script tokens.
This is the base class for CMake script tokens. An occurrence of a token whose type is exactly Token (i.e. not a subclass thereof) is a syntactic error unless the token text is empty.
The textual content of the token.
The whitespace (including newlines) which preceded the token. As the parser is strictly preserving of whitespace, note that this must be non-empty in many cases in order to produce a syntactically correct script.
Bases: object
Representation of an extension description.
This class provides a Python object representation of an extension description. The extension information is made available as attributes on the object. The “well known” attributes are described here. Custom attributes may be added with setattr(). Attributes may be removed with delattr() or the clear() method.
| Parameters: |
|
|---|---|
| Raises : |
The description may be created from a repository instance (in which case the description repository information will be populated), a path to the extension source directory, or a path to an existing .s4ext file. No more than one of repo, filepath or sourcedir may be given. If none are provided, the description will be incomplete.
Remove attributes from the extension description.
| Parameters: | attr (str or None) – Name of attribute to remove. |
|---|
If attr is not None, this removes the specified attribute from the description object, equivalent to calling delattr(instance, attr). If attr is None, all attributes are removed.
Read extension description from directory.
| Parameters: | path (basestring) – Directory containing extension description. |
|---|---|
| Raises : | IOError if path does not contain exactly one extension description file. |
This attempts to read an extension description from the specified path which contains a single extension description (.s4ext) file (usually an extension build directory).
Write extension description to a file or stream.
| Parameters: | out (IOBase or basestring) – Stream or path to which to write the description. |
|---|
This writes the extension description to the specified file path or stream object. This is suitable for producing a .s4ext file from a description object.
Bases: object
Convenience class for manipulating an extension project.
This class provides an additional layer of convenience for users that wish to manipulate the CMakeLists.txt of an extension project. The term “build script” is used throughout to refer to the CMakeLists.txt so encapsulated.
Modifications to the script are made to the in-memory, parsed representation. Use save() to write changes back to disk.
This class may be used as a context manager. When used in this manner, any changes made are automatically written back to the project’s CMakeLists.txt when the context goes out of scope.
| Parameters: | path (basestring) – Top level directory of the extension project. |
|---|
Add a module to the build rules of the project.
| Parameters: | name (basestring) – Name of the module to be added. |
|---|---|
| Raises : | EOFError if no insertion point can be found. |
This adds an add_subdirectory() call for name to the build script. If possible, the new call is inserted immediately before a placeholder comment which is designated for this purpose. Otherwise, the new call is inserted after the last existing call to add_subdirectory().
Get value of CMake variable set in project.
| Parameters: |
|
|---|---|
| Returns: | Value of the variable, or default if not set. |
| Return type: | str or type(default) |
| Raises : | KeyError if no such name is set and default is None. |
This returns the raw value of the variable name which is set in the build script. No substitution is performed (the result may contain substitution placeholders like ‘${var}‘). If more than one set() command sets the same name, the result is the raw argument to the last such command. If the value consists of more than one argument, only the first is returned.
If no set() command sets name, and default is not None, default is returned. Otherwise a KeyError is raised.
Save the project.
| Parameters: | destination (basestring or None) – Location to which to write the build script. |
|---|
This saves the extension project CMake script to the specified file:
# Open a project
p = ExtensionProject('.')
# Set a value in the project
p.setValue('EXTENSION_DESCRIPTION', 'This is an awesome extension!')
# Save the changes
p.save()
If destination is None, the CMakeLists.txt file from which the project instance was created is overwritten.
Change value of CMake variable set in project.
| Parameters: |
|
|---|---|
| Raises : | KeyError if no such name is set. |
This modifies the build script to set the variable name to value. If more than one set() command sets the same name, only the first is modified. If the value of the modified set() command has more than one argument, only the first is modified.
The build script must already contain a set() command which sets name. If it does not, a KeyError is raised.
Name of extension project.
| Type : | str |
|---|
This provides the name of the extension project, i.e. the identifier passed to project() in the extension’s build script.
Bases: object
Implementation class for the Extension Wizard.
This class provides the entry point and implementation of the Extension wizard. One normally uses it by writing a small bootstrap script to load the module, which then calls code like:
wizard = ExtensionWizard()
wizard.execute()
Interaction with GitHub uses GithubHelper.logIn() to authenticate.
Note
Most methods will signal the application to exit if something goes wrong. This behavior is hidden by the execute() method when passing exit=False; callers that need to continue execution after calling one of the other methods directly should catch SystemExit.
Add a module to an existing extension.
| Parameters: |
|
|---|
This creates a new module from the specified module template and adds it to the CMakeLists.txt of the extension. The name is used both as the name of the new module subdirectory (created in args.destination) and as the replacement value when substituting the template key.
If an error occurs, the extension is not modified, and the application displays an error message and then exits.
Add or update an extension to/in the index repository.
| Parameters: |
|
|---|
This writes the description of the specified extension — which may be an addition, or an update to a previously contributed extension — to a user fork of the extension index repository, pushes the changes, and creates a pull request to merge the contribution. In case of an update to an extension with a github public repository, a “compare URL” (a github link to view the changes between the previously contributed version of the extension and the version being newly contributed) is included in the pull request message.
This attempts to find the user’s already existing fork of the index repository, and to create one if it does not already exist. The fork is then either cloned (adding remotes for both upstream and the user’s fork) or updated, and the current upstream target branch pushed to the user’s fork, ensuring that the target branch in the user’s fork is up to date. The changes to the index repository are made in a separate branch.
If a pull request for the extension already exists, its message is updated and the corresponding branch is force-pushed (which automatically updates the code portion of the request).
If anything goes wrong, no pull request is created, and the application displays a suitable error message and then exits. Additionally, a branch push for the index changes only occurs if the failed operation is the creation or update of the pull request; other errors cause the application to exit before pushing the branch. (Updates of the user’s fork to current upstream may still occur.)
Create a new extension from specified extension template.
| Parameters: |
|
|---|
Note that the extension is written to a new subdirectory which is created in args.destination. The name is used both as the name of this directory, and as the replacement value when substituting the template key.
If an error occurs, the application displays an error message and exits.
See also
Generate extension description and write it to sys.stdout.
| Parameters: | args.destination (basestring) – Location (directory) of the extension to describe. |
|---|
If something goes wrong, the application displays a suitable error message.
Execute the wizard in CLI mode.
| Parameters: |
|---|
This sets up CLI argument parsing and executes the wizard, using the provided CLI arguments if any, or sys.argv otherwise. See buildProcessArgs() for an explanation of how args and kwargs are processed.
If multiple commands are given, an error in one may cause others to be skipped.
See also
Publish extension to github repository.
| Parameters: | args.destination (basestring) – Location (directory) of the extension to publish. |
|---|
This creates a public github repository for an extension (whose name is the extension name), adds it as a remote of the extension’s local repository, and pushes the extension to the new github repository. The extension information (homepage, icon url) is also updated to refer to the new public repository.
If the extension is not already tracked in a local git repository, a new local git repository is also created and populated by the files currently in the extension source directory.
If the local repository is dirty or already has a remote, or a github repository with the name of the extension already exists, the application displays a suitable error message and then exits.
Helpers for interacting with github.
Create github session.
| Parameters: | repo (git.Repo or None.) – If not None, use the git client (i.e. configuration) from the specified git repository; otherwise use a default client. |
|---|---|
| Returns: | A logged in github session. |
| Return type: | github.Github. |
| Raises : | github.GithubException.BadCredentialsException if authentication fails. |
This obtains and returns a logged in github session using the user’s credentials, as managed by git-credentials; login information is obtained as necessary via the same. On success, the credentials are also saved to any store that the user has configured.
Get a github repository by name or URL.
| Parameters: |
|
|---|---|
| Returns: | Matching repository, or None if no such repository was found. |
| Return type: | github.Repository.Repository or None. |
This function attempts to look up a github repository by either its qualified github name (i.e. ‘<owner>/<repository>‘) or a clone URL:
# Create session
session = GithubHelper.logIn()
# Look up repository by name
repoA = GithubHelper.getRepo(session, 'octocat/Hello-World')
# Look up repository by clone URL
cloneUrl = 'https://github.com/octocat/Hello-World.git'
repoB = GithubHelper.getRepo(session, cloneUrl)
If both name and url are provided, only name is used. The url must have “github.com” as the host.
Get user’s fork of the specified repository.
| Parameters: |
|
|---|---|
| Returns: | The specified fork repository, or None if no such fork exists and create is False. |
| Return type: | github.Repository.Repository or None. |
| Raises : | github.GithubException.GithubException if user does not have permission to create a repository. |
This function attempts to look up a repository owned by the specified user or organization which is a fork of the specified upstream repository, optionally creating one if it does not exist:
# Create session
session = GithubHelper.logIn()
# Get user
user = session.get_user("jdoe")
# Get upstream repository
upstream = GithubHelper.getRepo(session, 'octocat/Spoon-Knife')
# Look up fork
fork = GithubHelper.getFork(user=user, upstream=upstream)
Get pull request for the specified user’s fork and ref.
| Parameters: |
|
|---|---|
| Returns: | The specified pull request, or None if no such pull request exists. |
| Return type: | github.PullRequest.PullRequest or None. |
This function attempts to look up the pull request made by user for upstream to integrate the user’s ref into upstream’s target:
# Create session
session = GithubHelper.logIn()
# Get user and upstream repository
user = session.get_user("jdoe")
repo = GithubHelper.getRepo(session, 'octocat/Hello-World')
# Look up request to merge 'my-branch' of any fork into 'master'
pr = GithubHelper.getPullRequest(upstream=repo, user=user,
ref='my-branch', target='master')
If any of user, fork or target are None, those criteria are not considered when searching for a matching pull request. If multiple matching requests exist, the first matching request is returned.
Python API for simple interaction with Subversion.
Bases: object
Wrapper for executing the svn process.
This class provides a convenience wrapping for invoking the svn process. In addition to the execute() method, names of subversion commands are implicitly available as methods:
c = Subversion.Client()
c.log('.', limit=5)
Execute command and return line-split output.
| Parameters: | |
|---|---|
| Returns: | Standard output from running the command, as a list (split by line). |
| Return type: | list of str |
| Raises : | CommandError if the command exits with non-zero status. |
This executes the specified svn command and returns the standard output from the execution. See buildProcessArgs() for an explanation of how args and kwargs are processed.
See also
Return information about the specified item.
| Parameters: | |
|---|---|
| Returns: | Mapping of information fields returned by svn info. |
| Return type: | dict of str → str |
| Raises : | CommandError if the command exits with non-zero status. |
This wraps the svn info command, returning the resulting information as a dict. The dictionary keys are the value names as printed by svn info.
Bases: object
Abstract representation of a subversion repository.
The remote URL of the base of the working copy checkout.
The root URL of the remote repository.
The universally unique identifier of the repository.
The absolute path to the top level directory of the repository working copy.
The revision at which the working copy is checked out.
The last revision which contains a change to content contained in the working copy.
The absolute path to the working copy .svn directory.
A Client object which may be used to interact with the repository. The client interprets non-absolute paths as relative to the working copy root.
| Parameters: | path (basestring) – Location of the repository checkout. |
|---|---|
| Raises : |
|
Bases: object
Template collection manager.
This class provides a template collection and operations for managing and using that collection.
Add template manager CLI arguments to parser.
| Parameters: | parser (argparse.ArgumentParser) – Argument parser instance to which to add arguments. |
|---|
This adds CLI arguments to the specified parser that may be used to interact with the template collection.
Note
The arguments use '<' and '>' to annotate optional values. It is recommended to use WizardHelpFormatter with the parser so that these will be displayed using the conventional '[' and ']'.
See also
Add templates for a particular category to the collection.
| Parameters: |
|
|---|---|
| Raises : | KeyError if category is not a known template category. |
This adds all templates found in path to category to the collection, where each subdirectory of path is a template. If path contains any templates whose names already exist in the category of the collection (case insensitive), the existing entries are replaced.
Add a template path to the collection.
| Parameters: | basePath (basestring) – Path to a directory containing categorized templates. |
|---|
This adds categorized templates to the collection. basePath should be a directory which contains one or more directories whose names match a known template category (case insensitive). Each such subdirectory is added to the collection via addCategoryPath().
Copy (instantiate) a template.
| Parameters: |
|
|---|---|
| Returns: | Path to the new instance (os.path.join(destination, name)). |
| Return type: | unicode if either destination and/or name is also unicode, otherwise str. |
| Raises : |
This creates a copy of the specified template in destination, with occurrences of the template’s key replaced with name. The new copy is in a subdirectory name, which must not exist.
Note
The replacement of the template key is case sensitive, however the upper-case key is also replaced with the upper-case name.
See also
List available templates.
This displays a list of all available templates, using logging.info(), organized by category.
Automatically add paths and keys from CLI arguments.
| Parameters: |
|
|---|
This parses template-related command line arguments and updates the collection accordingly:
If a usage error is found, the application is terminated by calling die() with an appropriate error message.
See also
Set template key for specified template.
| Parameters: |
|
|---|
This sets the template key for name to key.
Note
Template keys depend only on the template name, and not the template category. As a result, two templates with the same name in different categories will use the same key.
See also
Helpers for interacting with CLI users and VCS tools.
Output a warning message (or messages), with exception if present.
| Parameters: | msg (basestring or sequence of basestring) – Message(s) to be output. |
|---|
This function outputs the specified message(s) using logging.warning(). If msg is a sequence, each message in the sequence is output, with a call to logging.warning() made for each message.
If there is a current exception, and debugging is enabled, the exception is reported prior to the other message(s) using logging.exception().
See also
Output an error message (or messages), with exception if present.
| Parameters: |
|
|---|
The output behavior (including possible report of an exception) of this function is the same as warn(), except that logging.error() is used instead of logging.warning(). After output, the program is terminated by calling sys.exit() with the specified exit code.
Get multiple-choice input from the user.
| Parameters: |
|
|---|---|
| Returns: | Value of the selected choice. |
This function presents a question (msg) to the user and asks them to select an option from a list of choices, which are presented in the manner of ‘git add –patch’ (i.e. the possible choices are shown between the prompt text and the final ‘?’). The prompt is repeated indefinitely until a valid selection is made.
The choices are a dict, with each key being a possible choice (using a single letter is recommended). The value for the selected key is returned to the caller.
The default choices provides a yes/no prompt with a bool return value.
Initialize logging.
| Parameters: | args.debug (bool) – If True, enable debug logging. |
|---|
This sets up the default logging object, with the following characteristics:
Build CLI arguments from Python-like arguments.
| Parameters: | |
|---|---|
| Returns: | Converted argument list. |
| Return type: | list of basestring |
This function converts Python-style arguments, including named arguments, to a CLI-style argument list:
>>> buildProcessArgs('p1', u'p2', None, 12, a=5, b=True, long_name=u'hello')
['-a', '5', '--long-name', u'hello', '-b', 'p1', u'p2', '12']
Named arguments are converted to named options by adding '-' (if the name is one letter) or '--' (otherwise), and converting any underscores ('_') to hyphens ('-'). If the value is True, the option is considered a flag that does not take a value. If the value is False or None, the option is skipped. Otherwise the stringified value is added following the option argument. Positional arguments — except for None, which is skipped — are similarly stringified and added to the argument list following named options.
Create a repository in an empty or non-existing location.
| Parameters: |
|
|---|---|
| Raises : | Exception if location exists and is not empty, or if the specified VCS tool is not supported. |
This creates a new repository using the specified tool at location, first creating location (and any parents) as necessary.
This function is meant to be passed as the create argument to getRepo().
Note
Only 'git' repositories are supported at this time.
Obtain a git repository for the specified path.
| Parameters: |
|
|---|---|
| Returns: | The repository instance, or None if no such repository exists. |
| Return type: | git.Repo, Subversion.Repository, or None. |
This attempts to obtain a repository for the specified path. If tool is not None, this will only look for a repository that is managed by the specified tool; otherwise, all supported repository types will be considered.
If create is callable, the specified function will be called to create the repository if one does not exist. Otherwise if bool(create) is True, and tool is either None or 'git', a repository is created using git.Repo.init. (Creation of other repository types is only supported at this time via a callable create.)
See also
Get the remote matching a URL.
| Parameters: |
|
|---|---|
| Returns: | A matching or newly created git.Remote, or None if no such remote exists. |
| Raises : | Exception if, when trying to create a remote, a remote with the specified name already exists. |
This attempts to find a git remote of the specified repository whose upstream URL matches (one of) urls. If no such remote exists and create is not None, a new remote named create will be created using the first URL of urls.
Get top level local directory of a repository.
| Parameters: | repo (git.Repo or Subversion.Repository.) – Repository instance. |
|---|---|
| Returns: | Absolute path to the repository local root. |
| Return type: | basestring |
| Raises : | Exception if the local root cannot be determined. |
This returns the local file system path to the top level of a repository working tree / working copy.
Get VCS private directory of a repository.
| Parameters: | repo (git.Repo or Subversion.Repository.) – Repository instance. |
|---|---|
| Returns: | Absolute path to the VCS private directory. |
| Return type: | basestring |
| Raises : | Exception if the private directory cannot be determined. |
This returns the VCS private directory for a repository, e.g. the .git or .svn directory.
Bases: argparse.HelpFormatter
Custom formatter for CLI arguments.
This formatter overrides argparse.HelpFormatter in order to replace occurrences of the ‘<’ and ‘>’ characters with ‘[‘ and ‘]’, respectively. This is done to work around the formatter’s wrapping, which tries to break metavars if they contain these characters and then becomes confused (read: raises an assertion).