rbtools.utils.source_tree¶

Utilities for scanning and working with source trees.

New in version 4.0.

Functions

scan_scmclients_for_path(path, *, ...[, ...])

Scan and return information for SCMClients usable for a path.

Classes

`SCMClientScanCandidate`(scmclient[, local_path])	A candidate found when scanning a source tree for SCMs.
`SCMClientScanResult`(scmclient, local_path, ...)	The result of a scan for SCMs in a tree.

class rbtools.utils.source_tree.SCMClientScanCandidate(scmclient: BaseSCMClient, local_path: Optional[str] = None)[source]¶

Bases: object

A candidate found when scanning a source tree for SCMs.

New in version 4.0.

scmclient: BaseSCMClient¶

The SCMClient that was matched.

Type:: rbtools.clients.base.scmclient.BaseSCMClient

local_path: Optional[str] = None¶

The local path on the filesystem for the match.

This may be None.

Type:: str

__dataclass_fields__ = {'local_path': Field(name='local_path',type='Optional[str]',default=None,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD), 'scmclient': Field(name='scmclient',type='BaseSCMClient',default=<dataclasses._MISSING_TYPE object>,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD)}¶

__dataclass_params__ = _DataclassParams(init=True,repr=True,eq=True,order=False,unsafe_hash=False,frozen=False,match_args=True,kw_only=False,slots=False,weakref_slot=False)¶

__eq__(other)¶: Return self==value.

__hash__ = None¶

__init__(scmclient: BaseSCMClient, local_path: Optional[str] = None) → None¶

__match_args__ = ('scmclient', 'local_path')¶

__repr__()¶: Return repr(self).

class rbtools.utils.source_tree.SCMClientScanResult(scmclient: Optional[BaseSCMClient], local_path: Optional[str], repository_info: Optional[RepositoryInfo], candidates: List[SCMClientScanCandidate], dependency_errors: Dict[str, SCMClientDependencyError], scmclient_errors: Dict[str, Exception])[source]¶

Bases: object

The result of a scan for SCMs in a tree.

New in version 4.0.

scmclient: Optional[BaseSCMClient]¶

The matching SCMClient, if found.

This will be None if no suitable SCMClient was found for the tree.

Type:: rbtools.clients.base.scmclient.BaseSCMClient

local_path: Optional[str]¶

The matching local path on the filesystem, if found.

This will be None if no suitable SCMClient was found for the tree, or if a repository was matched as remote-only.

Type:: str

repository_info: Optional[RepositoryInfo]¶

The matching repository information, if found.

This will be None if no suitable SCMClient was found for the tree.

Type:: rbtools.clients.base.repository.RepositoryInfo

candidates: List[SCMClientScanCandidate]¶

A list of all possible candidates for the tree.

The matching candidate will be a part of this list, if one was found.

Type:: list of SCMClientScanCandidate

dependency_errors: Dict[str, SCMClientDependencyError]¶

SCMClient dependency errors encountered during the scan.

Each key will correspond to the BaseSCMClient.scmclient_id of the erroring SCMClient, and each value will be a SCMClientDependencyError containing further details.

Type:: dict

scmclient_errors: Dict[str, Exception]¶

Unexpected SCMClient errors encountered during the scan.

Each key will correspond to the BaseSCMClient.scmclient_id of the erroring SCMClient, and each value will be an Exception subclass.

Type:: dict

property found: bool[source]¶

Whether a matching SCMClient was found.

Type:: bool

__dataclass_fields__ = {'candidates': Field(name='candidates',type='SCMClientScanCandidateList',default=<dataclasses._MISSING_TYPE object>,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD), 'dependency_errors': Field(name='dependency_errors',type='SCMClientScanDependencyErrors',default=<dataclasses._MISSING_TYPE object>,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD), 'local_path': Field(name='local_path',type='Optional[str]',default=<dataclasses._MISSING_TYPE object>,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD), 'repository_info': Field(name='repository_info',type='Optional[RepositoryInfo]',default=<dataclasses._MISSING_TYPE object>,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD), 'scmclient': Field(name='scmclient',type='Optional[BaseSCMClient]',default=<dataclasses._MISSING_TYPE object>,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD), 'scmclient_errors': Field(name='scmclient_errors',type='SCMClientScanErrors',default=<dataclasses._MISSING_TYPE object>,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD)}¶

__dataclass_params__ = _DataclassParams(init=True,repr=True,eq=True,order=False,unsafe_hash=False,frozen=False,match_args=True,kw_only=False,slots=False,weakref_slot=False)¶

__eq__(other)¶: Return self==value.

__hash__ = None¶

__init__(scmclient: Optional[BaseSCMClient], local_path: Optional[str], repository_info: Optional[RepositoryInfo], candidates: List[SCMClientScanCandidate], dependency_errors: Dict[str, SCMClientDependencyError], scmclient_errors: Dict[str, Exception]) → None¶

__match_args__ = ('scmclient', 'local_path', 'repository_info', 'candidates', 'dependency_errors', 'scmclient_errors')¶

__repr__()¶: Return repr(self).

rbtools.utils.source_tree.scan_scmclients_for_path(path: str, *, scmclient_kwargs: dict[str, Any], scmclient_ids: list[str] = [], check_remote: bool = True) → SCMClientScanResult[source]¶

Scan and return information for SCMClients usable for a path.

This looks for local source trees matching any supported SCMClient, starting at the provided path and working up toward the root of the filesystem. It will also by default check remote-only repositories, if the appropriate options are passed when instantiating each SCMClient.

All candidates are recorded, which can be helpful with diagnosing a match (in the case of nested repositories). If there was at least one candidate found, the most likely match will be returned along with the candidates.

Any errors encountered during matching will be logged and returned, to help with providing useful errors to the caller.

New in version 4.0.

Parameters:

path (str) – The starting path for the search.
scmclient_kwargs (dict) – Keyword arguments to pass when instantiating each SCMClient.
scmclient_ids (list of str, optional) –
An explicit list of SCMClient IDs to try to use in the scan.

If empty, this will try all registered SCMClients.
check_remote (bool, optional) –
Whether to allow checking of remote repositories.

This is dependent on support and logic within each SCMClient.

Returns:

The results of the SCMClient scan. This will never be None.

Return type:

SCMClientScanResult