rbtools.clients.tfs¶

A client for Azure DevOps / Team Foundation Server TFVC repositories.

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+ tf.exe.
`TFHelperWrapper`(**kwargs)	Implementation wrapper using our own helper.
`TFSClient`(args, *kwargs)	A client for Azure DevOps / Team Foundation Server TFVC repositories.

class rbtools.clients.tfs.BaseTFWrapper(*, config: RBToolsConfig | None = None, options: argparse.Namespace | None = None)[source]¶

Bases: object

Base class for TF wrappers.

Added in version 4.0.

__firstlineno__ = 42¶

__init__(*, config: RBToolsConfig | None = None, options: argparse.Namespace | None = None) → None[source]¶

Initialize the wrapper.

Parameters:

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

__static_attributes__ = ('config', 'options')¶

check_dependencies() → None[source]¶

Check whether all dependencies for the client are available.

By default, no dependencies are checked.

config: RBToolsConfig | None¶: The loaded configuration.

diff(*, client: TFSClient, revisions: SCMClientRevisionSpec, include_files: Sequence[str], exclude_patterns: Sequence[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

get_local_path() → str | None[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() → RepositoryInfo | None[source]¶

Return repository information for the current working tree.

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

options: argparse.Namespace | None¶: The command line options.

parse_revision_spec(revisions: Sequence[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.

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

Bases: BaseTFWrapper

Implementation wrapper for using Team Explorer Everywhere.

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

__firstlineno__ = 605¶

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

Initialize the wrapper.

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

__static_attributes__ = ('tf',)¶

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.

Added in version 4.0.

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

diff(*, client: TFSClient, revisions: SCMClientRevisionSpec, include_files: Sequence[str], exclude_patterns: Sequence[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

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

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

Added 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

get_local_path() → str | None[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() → RepositoryInfo | None[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: Sequence[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.

class rbtools.clients.tfs.TFExeWrapper(*, config: RBToolsConfig | None = None, options: argparse.Namespace | None = None)[source]¶

Bases: BaseTFWrapper

Implementation wrapper for using VS2017+ tf.exe.

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

__firstlineno__ = 184¶

__static_attributes__ = ()¶

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.

diff(*, client: TFSClient, revisions: SCMClientRevisionSpec, include_files: Sequence[str], exclude_patterns: Sequence[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

get_local_path() → str | None[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() → RepositoryInfo | None[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: Sequence[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.

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

Bases: BaseTFWrapper

Implementation wrapper using our own helper.

__firstlineno__ = 1104¶

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

Initialize the wrapper.

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

__static_attributes__ = ('helper_path',)¶

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.

Added in version 4.0.

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

diff(*, client: TFSClient, revisions: SCMClientRevisionSpec, include_files: Sequence[str], exclude_patterns: Sequence[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.

get_local_path() → str | None[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() → RepositoryInfo | None[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: Sequence[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.

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

Bases: BaseSCMClient

A client for Azure DevOps / Team Foundation Server TFVC repositories.

__firstlineno__ = 1346¶

__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.

__static_attributes__ = ('_tf_wrapper',)¶

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.

Added in version 4.0.

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

diff(revisions: SCMClientRevisionSpec, *, include_files: Sequence[str] | None = None, exclude_patterns: Sequence[str] | None = None, **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

get_local_path() → str | None[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() → RepositoryInfo | None[source]¶

Return repository information for the current working tree.

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

name: str = 'Azure DevOps / TFS (TFVC)'[source]¶

The name of the client.

Type:: str

parse_revision_spec(revisions: Sequence[str] | None = None) → 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.

requires_diff_tool: bool | Sequence[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.

Added in version 4.0.

Type:: bool or list

scmclient_id: str = 'tfs'[source]¶

The unique ID of the client.

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

Type:: str

server_tool_ids: ClassVar[Sequence[str] | None] = ['tfs'][source]¶

A comma-separated list of SCMClient IDs on the server.

This supersedes server_tool_names when running on a version of Review Board that supports passing tool IDs to the repositories list API.

Added in version 5.0.1.

Type:: str

server_tool_names: ClassVar[str | None] = 'Team Foundation Server'[source]¶

A comma-separated list of SCMClient names on the server.

Added in version 3.0.

Type:: str

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

property tf_wrapper: BaseTFWrapper[source]¶

The wrapper used to communicate with a TF tool.

Type:: BaseTFWrapper