rbtools.clients.sos¶

A client for Cliosoft SOS.

Cliosoft SOS is an Enterprise SCM focused on hardware design and configuration management.

Classes

class rbtools.clients.sos.SOSRevisionSpecExtra[source]¶

Bases: TypedDict

Extra revision information for a SOS revision specification.

This contains information on the SOS changelist or selection, computed based on the revision information provided to SOS.

This goes into the extra key in SCMClientRevisionSpec.

New in version 4.0: In prior versions, these keys lived directly in the base of the revision spec.

has_explicit_selection: bool¶

Whether an explicit selection was provided.

If False, a default selection will be used instead.

This is only present if sos_selection is present.

Type:

bool

sos_changelist: str¶

The changelist ID being posted for review.

Type:

str

sos_selection: List[str]¶

A list of SOS selection flags representing files to post for review.

Type:

list of str

__optional_keys__ = frozenset({'has_explicit_selection', 'sos_changelist', 'sos_selection'})¶

__orig_bases__ = (<function TypedDict>,)¶

__required_keys__ = frozenset({})¶

__total__ = True¶

class rbtools.clients.sos.SOSObjectType[source]¶

Bases: object

Constants for SOS object types.

New in version 3.1.

DIR = b'd'[source]¶

Directory.

FILE = b'f'[source]¶

Normal file.

PACKAGE = b'p'[source]¶

Package.

SYMLINK = b's'[source]¶

Symbolic link.

REFERENCE_DIR = b'D'[source]¶

Directory imported from another SOS project.

REFERENCE_FILE = b'F'[source]¶

Normal file imported from another SOS project.

REFERENCE_PACKAGE = b'P'[source]¶

Package imported from another SOS project.

REFERENCE_SYMLINK = b'S'[source]¶

Symbolic link imported from another SOS project.

class rbtools.clients.sos.SOSObjectState[source]¶

Bases: object

Constants for SOS object states.

New in version 3.1.

CHECKED_IN = b'-'[source]¶

An object that’s checked into the central server.

CHECKED_OUT = b'O'[source]¶

An object checked out for modification.

CHECKED_OUT_WITHOUT_LOCK = b'W'[source]¶

An object checked out for modification without server-side lock.

DIR_POULATED_NON_RECURSIVE = b'C'[source]¶

A directory populated non-recursively.

READ_ACCESS_DENIED = b'X'[source]¶

An object disallowing read access.

UNMANAGED = b'?'[source]¶

An object not managed by SOS.

UNPOPULATED = b'N'[source]¶

An object not populated in the local project directory.

class rbtools.clients.sos.SOSObjectChangeStatus[source]¶

Bases: object

Constants for SOS object change statuses.

New in version 3.1.

DELETED = b'!'[source]¶

An object is being deleted from the project.

MODIFIED = b'M'[source]¶

An object is being modified.

NOT_APPLICABLE = b'?'[source]¶

Change statuses are not applicable to the type of object.

UNCHANGED = b'-'[source]¶

An object is unchanged.

class rbtools.clients.sos.SOSObjectRevision[source]¶

Bases: object

Constants for SOS revisions.

New in version 3.1.

UNMANAGED = b'?'[source]¶

An object is not managed by SOS, and has no revision.

class rbtools.clients.sos.SOSChangeList(adds=None, deletes=None, modifications=None)[source]¶

Bases: object

A representation of a SOS changelist.

A changelist records the added, modified, and deleted files scheduled to be posted for review or checked into a project. These are managed via the soscmd add, soscmd commit, and soscmd describe commands in SOS 7.20+.

New in version 3.1.

adds¶

File paths scheduled to be added. Each is relative to the workarea root.

Type:

set, optional

deletes¶

File paths scheduled to be added. Each is relative to the workarea root.

Type:

set, optional

modifications¶

File paths scheduled to be modified. Each is relative to the workarea root.

Type:

set, optional

__init__(adds=None, deletes=None, modifications=None)[source]¶

Initialize the changelist.

Parameters:

• adds (set, optional) – File paths scheduled to be added. Each is relative to the workarea root.

• deletes (set, optional) – File paths scheduled to be added. Each is relative to the workarea root.

• modifications (set, optional) – File paths scheduled to be modified. Each is relative to the workarea root.

class rbtools.clients.sos.SOSClient(*args, **kwargs)[source]¶

Bases: BaseSCMClient

A client for Cliosoft SOS.

Cliosoft SOS is an Enterprise SCM focused on hardware design and configuration management.

This implementation makes use of soscmd to fetch information on repositories and generate suitable diffs.

Diff generation makes use of the proposed DiffX standard (SOS itself doesn’t have a native diff format with metadata).

This implementation is expected to be used with SOS 7.20 or higher.

New in version 3.1.

scmclient_id: str = 'sos'[source]¶

The unique ID of the client.

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

Type:

str

name: str = 'Cliosoft SOS'[source]¶

The name of the client.

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

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

DEFAULT_SELECTION = ['-scm'][source]¶

INCLUDE_FILES_SELECTION = ['-sor', '-sfo', '-sdo', '-sunm'][source]¶

RSO_SPLIT_RE = re.compile(',\\s*')[source]¶

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

Initialize the client.

Parameters:

• *args (tuple) – Positional arguments for the parent constructor.

• **kwargs (dict) – Keyword arguments for the parent constructor.

check_dependencies() → None[source]¶

Check whether all base dependencies are available.

This checks for the presence of soscmd in the system path.

New in version 4.0.

Raises:

rbtools.clients.errors.SCMClientDependencyError – A soscmd 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, or None if not inside of a workarea.

Return type:

str

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

Return repository information for the current SOS workarea.

Returns:

The workarea repository information, or None if not in a SOS workarea.

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, and it begins with select:, then anything after is expected to be SOS selection flags to match files to post.

If a single revision is passed in, and it does not begin with select:, then it’s assumed to be a changelist ID.

If zero revisions are passed in, a default selection of -scm will be used.

Anything else is unsupported.

Parameters:

revisions (list of str, optional) – A list of SOS selection patterns or changelist IDs, as specified by the user.

Returns:

The parsed revision spec.

See SCMClientRevisionSpec for the format of this dictionary.

This only makes use of the extra field, which is documented in SOSRevisionSpecExtra.

Return type:

dict

Raises:

• rbtools.clients.errors.InvalidRevisionSpecError – The given revisions could not be parsed.

• rbtools.clients.errors.TooManyRevisionsError – The specified revisions list contained too many revisions.

get_tree_matches_review_request(review_request: ReviewRequestResource, revisions: SCMClientRevisionSpec, **kwargs) → bool[source]¶

Return whether a tree matches metadata in a review request.

This will compare the stored state in a review request (set when posting a change for review) to the project, server, workarea ID, and changelist ID of the current tree.

This is used for enhanced guessing of review requests, available in RBTools 3.1+.

Parameters:

• review_request (rbtools.api.resources.ReviewRequestResource) – The review request being matched.

• revisions (dict) – The posted revision information. This is expected to be the result of parse_revision_spec().

• **kwargs (dict, unused) – Additional keyword arguments for future expansion.

Returns:

True if the review request matches the tree. False if it does not.

Return type:

bool

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

Perform a diff using the given revisions.

This goes through the work of generating a diff for SOS, generating a DiffX-compatible diff.

It will start by grabbing the changelist details or the files matched by a selection, exporting the old revision of each, and diffing that to the current version in the tree.

The DiffX metadata contains the SOS project, server, RSO, and the changelist ID if posting a change for review. This is needed server-side for looking up each file.

The current selection will be stashed before this operation and then restored afterward, in order to avoid impacting any current selections from the user.

The results will also contain additional metadata used to store in the review request’s extra_data field, for smart review request matching. This includes the SOS project, server, workarea ID, and the changelist ID if posting a changelist for review.

Parameters:

• revisions (dict) – A dictionary of revisions, as returned by parse_revision_spec().

• include_files (list of unicode, optional) – A list of files to whitelist during the diff generation.

• exclude_patterns (list of unicode, optional) – A list of shell-style glob patterns to blacklist during diff generation.

• **kwargs (dict, unused) – Unused keyword arguments.

Returns:

A dictionary containing keys documented in SCMClientDiffResult.

Return type:

dict

run_soscmd(subcommand, *args, **kwargs)[source]¶

Run soscmd with the provided arguments.

This will be run in the specified directory (if passing cwd as a keyword argument), or in the workarea root. If neither are set, it will instead run in the current directory.

Parameters:

• subcommand (unicode) – The soscmd sub-command to run.

• *args (tuple) – Additional arguments to pass to the sub-command.

• **kwargs (dict) – Keyword arguments to pass to execute().

Returns:

The result from the execution, based on the keyword arguments.

Return type:

object