plasticscm

In this section plasticscm module has been described with its classes.

plasticscm.Plastic

class plasticscm.Plastic(url: str = 'http://localhost:9090', *, http_username: Optional[str] = None, http_password: Optional[str] = None, ssl_verify: bool = True, timeout: Union[int, float] = None, api_version: Union[str, int, float] = '1')

Instantiates a new PlasticSCM API wrapper.

Parameters

  • url – The endpoint of API, in format http://host:port (default: “http://localhost:9090”).

  • timeout – Timeout to use for requests to the PlasticSCM server.

  • api_version – PlasticSCM API version to use (support for 1 only).

classmethod from_config(plastic_id: Optional[str] = None, config_files: Optional[List[str]] = None) → plasticscm._plastic.Plastic

Create a new PlasticSCM API wrapper from configuration files.

Parameters

  • plastic_id – ID of the configuration section.

  • config_files – List of paths to configuration files.

Returns

A PlasticSCM API wrapper.

Raises

plasticscm.config.PlasticDataError – If the configuration is not correct.

property api_version

The API version used (1 only).

property model

Classes of objects provided by the API.

get_cm_location() → pathlib.Path

Get the path of cm.

Raises

FileNotFoundError – If cm executable was not found.

get_repositories() → Tuple[plasticscm.model.Repository]

Gets all available repositories of a server, along with their information.

Returns

A list of the available repositories.

create_repository(repo_name: str, *, server: Optional[str] = None) → plasticscm.model.Repository

Create a repository in a server.

Parameters

  • repo_name – The name of the new repository.

  • server – The target server where the repository is to be created. If it is omitted or if it is None, the repository will be created in configured API server.

Returns

The newly created repository will be returned once the operation is completed.

get_repository(repo_name: str) → plasticscm.model.Repository

Gets the information concerning a single repository.

Parameters

repo_name – The name of the repository.

Returns

The desired repository will be returned once the operation is completed.

rename_repository(repo_name: str, repo_new_name: str) → plasticscm.model.Repository

Rename a repository.

Parameters

  • repo_name – The name of the repository to be renamed.

  • repo_new_name – The new name of the repository.

Returns

The updated repository will be returned once the operation is completed.

delete_repository(repo_name: str) → None

Remove a repository from a server.

Parameters

repo_name – The name of the repository to be removed.

get_workspaces() → Tuple[plasticscm.model.Workspace]

Gets all registered workspaces, along with their information.

Returns

A list of the all registered workspaces.

create_workspace(wkspace_name: str, wkspace_path: pathlib.Path, *, repo_name: Optional[str] = None) → plasticscm.model.Workspace

Create a new workspace.

Parameters

  • wkspace_name – The name of the new workspace.

  • wkspace_path – The absolute path of the new workspace.

  • repo_name – The repository of the new workspace.

Returns

The newly created workspace will be returned once the operation is completed.

get_workspace(wkspace_name: str) → plasticscm.model.Workspace

Gets the information concerning a single workspace.

Parameters

wkspace_name – The name of the workspace.

Returns

The desired workspace will be returned once the operation is completed.

rename_workspace(wkspace_name: str, wkspace_new_name: str) → plasticscm.model.Workspace

Rename a workspace.

Parameters

  • wkspace_name – The name of the workspace to be renamed.

  • wkspace_new_name – The new name of the workspace.

Returns

The updated workspace will be returned once the operation is completed.

delete_workspace(wkspace_name: str) → None

Remove a workspace.

Parameters

wkspace_name – The name of the workspace to be removed.

get_branches(repo_name: str, *, query: Optional[str] = None) → Tuple[plasticscm.model.Branch]

Gets branches in a repository, along with their information.

Parameters

  • repo_name – The name of the branches’s host repository.

  • query – An optional constraints string using the ‘cm find’ command syntax.

Returns

A list of all branches in a repository.

create_branch(repo_name: str, branch_name: str, origin_type: plasticscm.model.ObjectType, origin: Union[str, int], *, top_level: bool = False) → plasticscm.model.Branch

Create a new branch.

Parameters

  • repo_name – The name of the host repository of the new branch.

  • branch_name – The name of the new branch. Do NOT use a hierarchical name.

  • origin_type – The type of the origin of the branch. It should be ObjectType.CHANGESET, ObjectType.LABEL or ObjectType.BRANCH.

  • origin – The point of origin from which the branch will be created.

  • top_level – Whether or not the branch will be top-level - i.e. it will have no parent (default: False).

Returns

The newly created branch will be returned once the operation is completed.

get_branch(repo_name: str, branch_name: str) → plasticscm.model.Branch

Gets information about a single branch in a repository.

Parameters

  • repo_name – The repository hosting the desired branch.

  • branch_name – The name of the desired branch. Please note that branch names are hierarchical (e.g. “main/task001/task002”).

Returns

The desired branch will be returned once the operation is completed.

rename_branch(repo_name: str, branch_name: str, branch_new_name: str) → plasticscm.model.Branch

Rename a branch.

Parameters

  • repo_name – The name of the host repository of the branch.

  • branch_name – The hierarchical name of the branch to be renamed. Please note that branch names are hierarchical (e.g. “main/task001/task002”).

  • branch_new_name – The new name of the branch. Please have in mind that the hierarchy name can not be changed.

Returns

The updated branch will be returned once the operation is completed.

delete_branch(repo_name: str, branch_name: str) → None

Remove a branch.

Parameters

  • repo_name – The name of the host repository of the branch

  • branch_name – The name of the branch to be removed. Please note that branch names are hierarchical (e.g. “main/task001/task002”).

get_labels(repo_name: str, *, query: Optional[str] = None) → Tuple[plasticscm.model.Label]

Gets labels in a repository, along with their information.

Parameters

  • repo_name – The name of the host repository of the labels.

  • query – An optional constraints string using the ‘cm find’ command syntax.

Returns

A list of all labels in a repository.

create_label(repo_name: str, label_name: str, changeset_id: int, *, comment: Optional[str] = None, apply_to_xlinks: bool = False) → plasticscm.model.Label

Create a new label and applies it to a given changeset.

Parameters

  • repo_name – The name of the future host repository.

  • label_name – The name of the new label.

  • changeset_id – The changeset to label.

  • comment – The comment to add to the label.

  • apply_to_xlinks – If True, all xlinked changesets present in the specified changeset tree will be labelled as well (default: False).

Returns

The newly created label will be returned once the operation is completed.

get_label(repo_name: str, label_name: str) → plasticscm.model.Label

Gets information about a single label.

Parameters

  • repo_name – The name of the host repository of the label.

  • label_name – The name of the label.

Returns

The desired label will be returned once the operation is completed.

rename_label(repo_name: str, label_name: str, label_new_name: str) → plasticscm.model.Label

Rename a label.

Parameters

  • repo_name – The name of the host repository of the label.

  • label_name – The name of the label to be renamed.

  • label_new_name – The new name of the label.

Returns

The updated label will be returned once the operation is completed.

delete_label(repo_name: str, label_name: str) → None

Remove a label.

Parameters

  • repo_name – The name of the host repository of the label.

  • label_name – The name of the label to be removed.

get_changesets(repo_name: str, *, query: Optional[str] = None) → Tuple[plasticscm.model.Changeset]

Gets changesets in a repository, along with their information.

Parameters

  • repo_name – The name of the host repository of the changesets.

  • query – An optional constraints string using the ‘cm find’ command syntax.

Returns

A list of all changesets in a repository.

get_changesets_in_branch(repo_name: str, branch_name: str, *, query: Optional[str] = None) → Tuple[plasticscm.model.Changeset]

Gets changesets in a given branch, along with their information.

Parameters

  • repo_name – The name of the host repository of the branch.

  • branch_name – The hierarchical name of the host branch. Please note that branch names are hierarchical (e.g. “main/task001/task002”).

  • query – An optional constraints string using the ‘cm find’ command syntax.

Returns

A list of all changesets in a given branch.

get_changeset(repo_name: str, changeset_id: int) → plasticscm.model.Changeset

Gets information about a single changeset.

Parameters

  • repo_name – The name of the host repository of the changeset.

  • changeset_id – The id of the changeset.

Returns

The desired changeset will be returned once the operation is completed.

get_pending_changes(wkspace_name: str, *, change_types: Optional[List[plasticscm.model.Change.Type]] = None) → Tuple[plasticscm.model.Change]

Gets pending changes in a workspace, along with their information.

Parameters

  • wkspace_name – The name of the workspace.

  • change_types – A list detailing the desired change types. It should be a list of Change.Type’s values (default: all change types).

Returns

A list of all penging changes of the desired change types.

undo_pending_changes(wkspace_name: str, paths: List[Union[str, pathlib.Path]]) → plasticscm.model.AffectedPaths

Deletes the pending changes in a workspace.

Paths must be a list of paths representing files with pending changes to be undone.

Parameters

  • wkspace_name – The name of the workspace.

  • paths – A list of file paths with pending changes to be undone. They can be either full paths or workspace-relative paths.

Returns

The paths that were affected by the undo operation.

get_workspace_update_status(wkspace_name: str) → plasticscm.model.OperationStatus

Gets the status of the last workspace update operation.

Parameters

wkspace_name – The name of the workspace.

Returns

The status of the last workspace update operation.

update_workspace(wkspace_name: str) → plasticscm.model.OperationStatus

Update the workspace and download latest changes.

Parameters

wkspace_name – The name of the workspace.

Returns

The status of the workspace update operation.

get_workspace_switch_status(wkspace_name: str) → plasticscm.model.OperationStatus

Gets the status of the last workspace switch operation.

Parameters

wkspace_name – The name of the workspace.

Returns

The status of the last workspace switch operation.

switch_workspace(wkspace_name: str, object_type: plasticscm.model.ObjectType, object: Union[str, int]) → plasticscm.model.OperationStatus

Switch the workspace to a branch, changeset or label.

Parameters

  • wkspace_name – The name of the workspace.

  • object_type – The type of switch destination. It should be ObjectType.CHANGESET, ObjectType.LABEL or ObjectType.BRANCH.

  • object – The target point the workspace will be set to. It should be (according to object_type) the changeset id, the label name or the branch name.

Returns

The status of the workspace switch operation.

get_workspace_checkin_status(wkspace_name: str) → plasticscm.model.CheckinStatus

Gets the status of the last workspace checkin operation.

Parameters

wkspace_name – The name of the workspace.

Returns

The status of the last workspace checkin operation.

checkin_workspace(wkspace_name: str, *, paths: Optional[List[str]] = None, comment: Optional[str] = None, recurse: bool = True) → plasticscm.model.CheckinStatus

Stores changes in the repository.

Parameters

  • wkspace_name – The name of the workspace.

  • paths – The list of target paths to be checked in. Set to the workspace root if empty or not present.

  • comment – The checkin comment.

  • recurse – If set to True, directories present in the paths parameter will have their children recursively checked in. If paths is empty or not present, its value is overridden to True (default: True).

Returns

The status of the workspace checkin operation.

get_item(repo_name: str, item_path: str) → plasticscm.model.Item

Gets information about a single item in a repository.

Parameters

  • repo_name – The name of the repository.

  • item_path – The path of selected item.

Returns

The desired item will be returned once the operation is completed.

get_item_in_branch(repo_name: str, branch_name: str, item_path: str) → plasticscm.model.Item

Gets information about a single item in the desired branch.

Parameters

  • repo_name – The name of the host repository of the branch.

  • branch_name – The name of the branch. Please note that branch names are hierarchical (e.g. “main/task001/task002”).

  • item_path – The path of selected item.

Returns

The desired item will be returned once the operation is completed.

get_item_in_changeset(repo_name: str, changeset_id: int, item_path: str) → plasticscm.model.Item

Gets information about a single item in the desired changeset.

Parameters

  • repo_name – The name of the host repository of the changeset.

  • changeset_id – The id of the changeset.

  • item_path – The path of selected item.

Returns

The desired item will be returned once the operation is completed.

get_item_in_label(repo_name: str, label_name: str, item_path: str) → plasticscm.model.Item

Gets information about a single item in the desired label.

Parameters

  • repo_name – The name of the host repository of the label.

  • label_name – The name of the label.

  • item_path – The path of selected item.

Returns

The desired item will be returned once the operation is completed.

get_item_revision(repo_name: str, revision_spec: str) → plasticscm.model.Item

Load a single item’s revision in the workspace and gets information about it.

Parameters

  • repo_name – The name of the repository.

  • revision_spec – Specification of the selected revision.

Returns

The desired item’s revision will be returned once the operation is completed.

get_item_revision_history_in_branch(repo_name: str, branch_name: str, item_path: str) → Tuple[plasticscm.model.RevisionHistoryItem]

Gets the item’s revision history for a given branch.

Parameters

  • repo_name – The name of the host repository of the branch.

  • branch_name – The name of the branch. Please note that branch names are hierarchical (e.g. “main/task001/task002”).

  • item_path – The path of selected item.

Returns

A list of all item’s revision history items for a given branch.

get_item_revision_history_in_changeset(repo_name: str, changeset_id: int, item_path: str) → Tuple[plasticscm.model.RevisionHistoryItem]

Gets the item’s revision history for a given changeset.

Parameters

  • repo_name – The name of the host repository of the changeset.

  • changeset_id – The id of the changeset.

  • item_path – The path of selected item.

Returns

A list of all item’s revision history items for a given changeset.

get_item_revision_history_in_label(repo_name: str, label_name: str, item_path: str) → Tuple[plasticscm.model.RevisionHistoryItem]

Gets the item’s revision history for a given label.

Parameters

  • repo_name – The name of the host repository of the label.

  • label_name – The name of the label.

  • item_path – The path of selected item.

Returns

A list of all item’s revision history items for a given label.

diff_changesets(repo_name: str, changeset_id: int, source_changeset_id: int) → Tuple[plasticscm.model.Diff]

Gets the differences between the source changeset and the desired changeset.

Parameters

  • repo_name – The name of the host repository of the changesets.

  • changeset_id – The id of the changeset.

  • source_changeset_id – The id of the source changeset.

Returns

A list of all differences between the source changeset and the desired changeset.

diff_changeset(repo_name: str, changeset_id: int) → Tuple[plasticscm.model.Diff]

Gets the differences between the parent changeset and the desired changeset.

Parameters

  • repo_name – The name of the host repository of the changeset.

  • changeset_id – The id of the changeset.

Returns

A list of all differences between the parent changeset and the desired changeset.

diff_branch(repo_name: str, branch_name: str) → Tuple[plasticscm.model.Diff]

Gets the differences between the current branch and the desired branch.

Parameters

  • repo_name – The name of the host repository of the branch.

  • branch_name – The name of the branch. Please note that branch names are hierarchical (e.g. “main/task001/task002”).

Returns

A list of all differences between the current branch and the desired branch.

add_workspace_item(wkspace_name: str, item_path: str, *, add_parents: bool = True, checkout_parent: bool = True, recurse: bool = True) → plasticscm.model.AffectedPaths

Add an item to version control.

Parameters

  • wkspace_name – The name of the workspace.

  • item_path – The path of the item to be added.

  • add_parents – If True, the command will add any parent directories which are not under version control yet (default: True).

  • checkout_parent – If True, the parent node of the selected item will be checked out as a result (default: True).

  • recurse – If True, causes all the children items to be recursively added (default: True).

Returns

The paths that were affected by the addition operation.

checkout_workspace_item(wkspace_name: str, item_path: str) → plasticscm.model.AffectedPaths

Mark workspace item as ready to modify.

Parameters

  • wkspace_name – The name of the workspace.

  • item_path – The path of selected item.

Returns

The paths that were affected by the checkout operation.

move_workspace_item(wkspace_name: str, item_path: str, dest_item_path: str) → plasticscm.model.AffectedPaths

Move or rename a file or directory in the workspace.

Parameters

  • wkspace_name – The name of the workspace.

  • item_path – Source path of selected item.

  • dest_item_path – Destination path to move the selected item (e.g. “src/bar.c”).

Returns

The paths that were affected by the movement operation.