rbtools.clients.tfs¶

A client for Team Foundation Server.

Classes

`BaseTFWrapper`(*[, config, options])	Base class for TF wrappers.
`TEEWrapper`(**kwargs)	Implementation wrapper for using Team Explorer Everywhere.
`TFExeWrapper`(*[, config, options])	Implementation wrapper for using VS2017's tf.exe.
`TFHelperWrapper`(**kwargs)	Implementation wrapper using our own helper.
`TFSClient`(args, *kwargs)	A client for Team Foundation Server.

class rbtools.clients.tfs.BaseTFWrapper(*, config: Optional[Dict[str, Any]] = None, options: Optional[Namespace] = None)[source]¶

Bases: object

Base class for TF wrappers.

New in version 4.0.

__init__(*, config: Optional[Dict[str, Any]] = None, options: Optional[Namespace] = None) → None[source]¶

Initialize the wrapper.

Parameters:

config (dict, optional) – The loaded configuration.
options (argparse.Namespace, optional) – The command line options.

check_dependencies() → None[source]¶

Check whether all dependencies for the client are available.

By default, no dependencies are checked.

get_local_path() → Optional[str][source]¶

Return the local path to the working tree.

Returns:: The filesystem path of the repository on the client system.
Return type:: str

get_repository_info() → Optional[RepositoryInfo][source]¶

Return repository information for the current working tree.

Returns:: The repository info structure.
Return type:: rbtools.clients.base.repository.RepositoryInfo

parse_revision_spec(revisions: List[str]) → SCMClientRevisionSpec[source]¶

Parse the given revision spec.

These will be used to generate the diffs to upload to Review Board (or print). The diff for review will include the changes in (base, tip], and the parent diff (if necessary) will include (parent, base].

If a single revision is passed in, this will return the parent of that revision for “base” and the passed-in revision for “tip”.

If zero revisions are passed in, this will return revisions relevant for the “current change” (changes in the work folder which have not yet been checked in).

Parameters:

revisions (list of str) –

A list of revisions as specified by the user.

Items in the list do not necessarily represent a single revision, since the user can use the TFS-native syntax of r1~r2. Versions passed in can be any versionspec, such as a changeset number, L-prefixed label name, W (latest workspace version), or T (latest upstream version).

Returns:

The parsed revision spec.

See SCMClientRevisionSpec for the format of this dictionary.

This always populates base and tip.

Return type:

dict

Raises:

rbtools.clients.errors.TooManyRevisionsError – Too many revisions were specified.
rbtools.clients.errors.InvalidRevisionSpecError – The given revision spec could not be parsed.

diff(*, client: TFSClient, revisions: SCMClientRevisionSpec, include_files: List[str], exclude_patterns: List[str]) → SCMClientDiffResult[source]¶

Return the generated diff.

Parameters:

client (TFSClient) – The client performing the diff.
revisions (dict) – A dictionary containing base and tip keys.
include_files (list) – A list of file paths to include in the diff.
exclude_patterns (list) – A list of file paths to exclude from the diff.
**kwargs (dict, unused) – Unused keyword arguments.

Returns:

A dictionary of diff results.

See SCMClientDiffResult for the format of this dictionary.

Return type:

dict

class rbtools.clients.tfs.TFExeWrapper(*, config: Optional[Dict[str, Any]] = None, options: Optional[Namespace] = None)[source]¶

Bases: BaseTFWrapper

Implementation wrapper for using VS2017’s tf.exe.

REVISION_WORKING_COPY = '--rbtools-working-copy'[source]¶

check_dependencies() → None[source]¶

Check whether all dependencies for the client are available.

This will check for tf.exe.

Raises:: rbtools.clients.errors.SCMClientDependencyError – A tf tool could not be found.

get_local_path() → Optional[str][source]¶

Return the local path to the working tree.

Returns:: The filesystem path of the repository on the client system.
Return type:: str

get_repository_info() → Optional[RepositoryInfo][source]¶

Return repository information for the current working tree.

Returns:: The repository info structure.
Return type:: rbtools.clients.base.repository.RepositoryInfo

parse_revision_spec(revisions: List[str]) → SCMClientRevisionSpec[source]¶

Parse the given revision spec.

If a single revision is passed in, this will return the parent of that revision for “base” and the passed-in revision for “tip”.

If zero revisions are passed in, this will return revisions relevant for the “current change” (changes in the work folder which have not yet been checked in).

Versions passed in can be any versionspec, such as a changeset number, L-prefixed label name, W (latest workspace version), or T (latest upstream version).

Parameters:

revisions (list of str) –

A list of revisions as specified by the user.

Returns:

The parsed revision spec.

See SCMClientRevisionSpec for the format of this dictionary.

This always populates base and tip.

Return type:

dict

Raises:

rbtools.clients.errors.TooManyRevisionsError – Too many revisions were specified.
rbtools.clients.errors.InvalidRevisionSpecError – The given revision spec could not be parsed.

diff(*, client: TFSClient, revisions: SCMClientRevisionSpec, include_files: List[str], exclude_patterns: List[str]) → SCMClientDiffResult[source]¶

Return the generated diff.

Parameters:

client (TFSClient) – The client performing the diff.
revisions (dict) – A dictionary containing base and tip keys.
include_files (list) – A list of file paths to include in the diff.
exclude_patterns (list) – A list of file paths to exclude from the diff.

Returns:

A dictionary of diff results.

See SCMClientDiffResult for the format of this dictionary.

Return type:

dict

class rbtools.clients.tfs.TEEWrapper(**kwargs)[source]¶

Bases: BaseTFWrapper

Implementation wrapper for using Team Explorer Everywhere.

REVISION_WORKING_COPY = '--rbtools-working-copy'[source]¶

classmethod get_default_tf_locations(target_platform: str = 'darwin') → List[str][source]¶

Return default locations for tf.cmd for the given platform.

New in version 4.0.

Parameters:: target_platform (str) – The platform to return paths for.
Returns:: The list of possible platforms.
Return type:: list of str

__init__(**kwargs) → None[source]¶

Initialize the wrapper.

Parameters:: **kwargs (dict) – Keyword arguments to pass to the parent class.

check_dependencies() → None[source]¶

Check whether all dependencies for the client are available.

This checks for the presence of tf or tf.cmd in known locations and in the system path.

It will also include the --tf-cmd location, if provided.

New in version 4.0.

Raises:: rbtools.clients.errors.SCMClientDependencyError – A tf tool could not be found.

get_local_path() → Optional[str][source]¶

Return the local path to the working tree.

Returns:: The filesystem path of the repository on the client system.
Return type:: str

get_repository_info() → Optional[RepositoryInfo][source]¶

Return repository information for the current working tree.

Returns:: The repository info structure.
Return type:: rbtools.clients.base.repository.RepositoryInfo

parse_revision_spec(revisions: List[str]) → SCMClientRevisionSpec[source]¶

Parse the given revision spec.

If a single revision is passed in, this will return the parent of that revision for “base” and the passed-in revision for “tip”.

If zero revisions are passed in, this will return revisions relevant for the “current change” (changes in the work folder which have not yet been checked in).

Parameters:

revisions (list of str) –

A list of revisions as specified by the user.

Returns:

The parsed revision spec.

See SCMClientRevisionSpec for the format of this dictionary.

This always populates base and tip.

Return type:

dict

Raises:

rbtools.clients.errors.TooManyRevisionsError – Too many revisions were specified.
rbtools.clients.errors.InvalidRevisionSpecError – The given revision spec could not be parsed.

diff(*, client: TFSClient, revisions: SCMClientRevisionSpec, include_files: List[str], exclude_patterns: List[str]) → SCMClientDiffResult[source]¶

Return the generated diff.

Parameters:

client (TFSClient) – The client performing the diff.
revisions (dict) – A dictionary containing base and tip keys.
include_files (list) – A list of file paths to include in the diff.
exclude_patterns (list) – A list of file paths to exclude from the diff.

Returns:

A dictionary of diff results.

See SCMClientDiffResult for the format of this dictionary.

parent_diff will always be None.

Return type:

dict

class rbtools.clients.tfs.TFHelperWrapper(**kwargs)[source]¶

Bases: BaseTFWrapper

Implementation wrapper using our own helper.

__init__(**kwargs) → None[source]¶

Initialize the wrapper.

Parameters:: **kwargs (dict) – Keyword arguments to pass to the parent class.

check_dependencies() → None[source]¶

Check whether all dependencies for the client are available.

This will check that java is installed, so the provided JAR file can be used.

New in version 4.0.

Raises:: rbtools.clients.errors.SCMClientDependencyError – java could not be found.

get_local_path() → Optional[str][source]¶

Return the local path to the working tree.

Returns:: The filesystem path of the repository on the client system.
Return type:: str

get_repository_info() → Optional[RepositoryInfo][source]¶

Return repository information for the current working tree.

Returns:: The repository info structure.
Return type:: rbtools.clients.base.repository.RepositoryInfo

parse_revision_spec(revisions: List[str]) → SCMClientRevisionSpec[source]¶

Parse the given revision spec.

If a single revision is passed in, this will return the parent of that revision for “base” and the passed-in revision for “tip”.

If zero revisions are passed in, this will return revisions relevant for the “current change” (changes in the work folder which have not yet been checked in).

Parameters:

revisions (list of str) –

A list of revisions as specified by the user.

Returns:

The parsed revision spec.

See SCMClientRevisionSpec for the format of this dictionary.

This always populates base and tip.

Return type:

dict

Raises:

rbtools.clients.errors.TooManyRevisionsError – Too many revisions were specified.
rbtools.clients.errors.InvalidRevisionSpecError – The given revision spec could not be parsed.

diff(*, client: TFSClient, revisions: SCMClientRevisionSpec, include_files: List[str], exclude_patterns: List[str]) → SCMClientDiffResult[source]¶

Return the generated diff.

Parameters:

client (TFSClient) – The client performing the diff.
revisions (dict) – A dictionary containing base and tip keys.
include_files (list) – A list of file paths to include in the diff.
exclude_patterns (list) – A list of file paths to exclude from the diff.

Returns:

A dictionary of diff results.

See SCMClientDiffResult for the format of this dictionary.

Return type:

dict

Raises:

rbtools.clients.errors.SCMError – Something failed when creating the diff.

class rbtools.clients.tfs.TFSClient(*args, **kwargs)[source]¶

Bases: BaseSCMClient

A client for Team Foundation Server.

scmclient_id: str = 'tfs'[source]¶

The unique ID of the client.

New in version 4.0: This will be required in RBTools 5.0.

Type:: str

name: str = 'Team Foundation Server'[source]¶

The name of the client.

Type:: str

server_tool_names: Optional[str] = 'Team Foundation Server'[source]¶

A comma-separated list of SCMClient names on the server

New in version 3.0.

Type:: str

requires_diff_tool: Union[bool, List[str]] = True[source]¶

Whether this tool requires a command line diff tool.

This may be a boolean or a list.

If a boolean, then this must be False if no command line tool is required, or True if any command line tool supported by RBTools is available (in which case the SCMClient is responsible for ensuring compatibility).

If a list, then this must be a list of registered diff tool IDs that are compatible.

New in version 4.0.

Type:: bool or list

supports_diff_exclude_patterns: bool = True[source]¶

Whether the SCM client supports excluding files from the diff.

Type:: bool

supports_patch_revert: bool = True[source]¶

Whether the SCM client supports reverting patches.

Type:: bool

__init__(*args, **kwargs) → None[source]¶

Initialize the client.

Parameters:

*args (tuple) – Positional arguments to pass to the parent class.
**kwargs (dict) – Keyword arguments to pass to the parent class.

property tf_wrapper: BaseTFWrapper[source]¶

The wrapper used to communicate with a TF tool.

Type:: BaseTFWrapper

check_dependencies() → None[source]¶

Check whether all dependencies for the client are available.

There are three different backends that can be used to access the underlying TFS repository. We try them in this order:

VS2017+ tf.exe
Our custom rb-tfs wrapper, built on the TFS Java SDK
Team Explorer Everywhere’s tf command

This checks for each, setting underlying wrappers to communicate with whichever tool is found.

If no tool is found, the raised exception will present the high-level possibilities.

New in version 4.0.

Raises:: rbtools.clients.errors.SCMClientDependencyError – No suitable dependencies could be found.

get_local_path() → Optional[str][source]¶

Return the local path to the working tree.

Returns:: The filesystem path of the repository on the client system.
Return type:: str

get_repository_info() → Optional[RepositoryInfo][source]¶

Return repository information for the current working tree.

Returns:: The repository info structure.
Return type:: rbtools.clients.base.repository.RepositoryInfo

parse_revision_spec(revisions: List[str] = []) → SCMClientRevisionSpec[source]¶

Parse the given revision spec.

If a single revision is passed in, this will return the parent of that revision for “base” and the passed-in revision for “tip”.

If zero revisions are passed in, this will return revisions relevant for the “current change” (changes in the work folder which have not yet been checked in).

Parameters:

revisions (list of str, optional) – A list of revisions as specified by the user. Items in the list do not necessarily represent a single revision, since the user can use the TFS-native syntax of r1~r2. Versions passed in can be any versionspec, such as a changeset number, L-prefixed label name, W (latest workspace version), or T (latest upstream version).

Returns:

The parsed revision spec.

See SCMClientRevisionSpec for the format of this dictionary.

This always populates base and tip.

Return type:

dict

Raises:

rbtools.clients.errors.TooManyRevisionsError – Too many revisions were specified.
rbtools.clients.errors.InvalidRevisionSpecError – The given revision spec could not be parsed.

diff(revisions: SCMClientRevisionSpec, *, include_files: List[str] = [], exclude_patterns: List[str] = [], **kwargs) → SCMClientDiffResult[source]¶

Return the generated diff.

Parameters:

revisions (dict) – A dictionary containing base and tip keys.
include_files (list, optional) – A list of file paths to include in the diff.
exclude_patterns (list, optional) – A list of file paths to exclude from the diff.
**kwargs (dict, unused) – Unused keyword arguments.

Returns:

A dictionary of diff results.

See SCMClientDiffResult for the format of this dictionary.

Return type:

dict