gitws.datamodel module

Central GitWS Datamodel.

class gitws.datamodel.AppConfigData(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = None, *, manifest_path: Optional[str] = None, color_ui: Optional[bool] = None, group_filters: Optional[GroupFilters] = None, clone_cache: Optional[Path] = None, depth: Optional[int] = None, **values: Any)[source]

Bases: BaseSettings

Configuration data of the application.

This class holds the concrete configuration values of the application. The following values are defined:

clone_cache: Optional[Path]

Clone Cache.

Initial cloning all dependencies takes a while. This sums up if done often (i.e. in CI/CD). This local filesystem cache directory will be used, to re-use already cloned data.

This option can be overridden by specifying the GIT_WS_CLONE_CACHE environment variable.

color_ui: Optional[bool]

Defines if outputs by the tool shall be colored.

If this is not defined, output will be colored by default.

This option can be overridden by specifying the GIT_WS_COLOR_UI environment variable.

static defaults() → Dict[str, Any][source]

As all configuration options must be optional, this option provides the default values.

>>> for item in AppConfigData.defaults().items(): print(item)
('color_ui', True)
('manifest_path', 'git-ws.toml')
depth: Optional[int]

Default Clone Depth.

New clones are created with the given depth. 0 deactivates shallow cloning.

group_filters: Optional[GroupFilters]

The groups to operate on.

This is a filter for groups to operate on during workspace actions.

This option can be overridden by specifying the GIT_WS_GROUP_FILTERS environment variable.

manifest_path: Optional[str]

The path of the manifest file within a repository.

If this is not defined, the default is git-ws.toml.

This option can be overridden by specifying the GIT_WS_MANIFEST_PATH environment variable.

class gitws.datamodel.Defaults(*, remote: Optional[str] = None, revision: Optional[str] = None, groups: Optional[Groups] = (), with_groups: Optional[Groups] = (), submodules: bool = True)[source]

Bases: BaseModel

Default Values.

These default values are used, if a ProjectSpec does not specify them.

Keyword Arguments:

  • remote – Remote Name.

  • revision – Revision. Tag or Branch. SHA does not make sense here.

  • groups – Dependency Groups.

  • with_groups – Group Selection for refered projects.

groups: Optional[Groups]

The groups attribute if not specified by the dependency.

remote: Optional[str]

Remote name if not specified by the dependency. The remote must have been defined previously.

revision: Optional[str]

The revision if not specified by the dependency. Tag or Branch. SHA does not make sense here.

submodules: bool

Initialize and Update git submodules. True by default.

with_groups: Optional[Groups]

The with_groups attribute if not specified by the dependency.

class gitws.datamodel.FileRef(*, src: str, dest: str)[source]

Bases: BaseModel

File Reference Specification.

The main project and first level dependencies might specify symbolic-links or files-to-copy.

Parameters:

  • src – Source - path relative to the project directory.

  • dest – Destination - relative path to the workspace directory.

dest: str

Destination - relative path to the workspace directory.

src: str

Source - path relative to the project directory.

class gitws.datamodel.FileRefType(value)[source]

Bases: Enum

File Reference Type.

COPY = 'copy'
gitws.datamodel.Group

Dependency Group.

A group is a name consisting of lower- and uppercase letters, numbers and underscore. Dashes are allowed. Except the first sign.

Groups structure dependencies.

gitws.datamodel.GroupFilter

Group Filter.

A group filter is a group name prefixed by ‘+’ or ‘-’, to select or deselect the group. A group filter can have an optional path at the end.

Any GroupFilter is later-on converted to a GroupSelect.

class gitws.datamodel.GroupFilters(iterable=(), /)[source]

Bases: tuple

Groups Filter Specification from User.

Used by Config and Command Line Interface.

static validate(group_filters)[source]

Check Groups Filter.

Group Filters are just a tuple of str for performance reasons. This function does the validation.

class gitws.datamodel.GroupSelect(*, group: Optional[str] = None, select: bool, path: Optional[str] = None)[source]

Bases: BaseModel

Group Selection.

A group selection selects/deselects a specific group for a specific path.

Keyword Arguments:

  • select – Select (True) or Deselect (False)

  • group – Group Name.

  • path – Path.

static from_group_filter(group_filter) → GroupSelect[source]

Create Group Selection from group_filter.

>>> GroupSelect.from_group_filter("+test")
GroupSelect(group='test', select=True)
>>> GroupSelect.from_group_filter("-test")
GroupSelect(group='test', select=False)
>>> GroupSelect.from_group_filter("-test@path")
GroupSelect(group='test', select=False, path='path')
>>> GroupSelect.from_group_filter("-@path")
GroupSelect(select=False, path='path')
>>> GroupSelect.from_group_filter("te-st")
Traceback (most recent call last):
    ...
ValueError: Invalid group selection 'te-st'
group: Optional[str]

Group.

path: Optional[str]

Path.

select: bool

Selected (‘+’) or not (‘-‘).

class gitws.datamodel.GroupSelects(iterable=(), /)[source]

Bases: tuple

Collection of GroupSelect.

static from_group_filters(group_filters: Optional[GroupFilters] = None) → GroupSelects[source]

Create GroupSelects from group_filters.

>>> GroupSelects.from_group_filters()
()
>>> GroupSelects.from_group_filters(('', ))
()
>>> GroupSelects.from_group_filters(('+test', ))
(GroupSelect(group='test', select=True),)
>>> GroupSelects.from_group_filters(('+test', '-doc'))
(GroupSelect(group='test', select=True), GroupSelect(group='doc', select=False))
static from_groups(groups: Optional[Groups] = None) → GroupSelects[source]

Create GroupSelects from group_filters.

>>> GroupSelects.from_groups()
()
>>> GroupSelects.from_groups(('', ))
()
>>> GroupSelects.from_groups(('test', ))
(GroupSelect(group='test', select=True),)
>>> GroupSelects.from_groups(('test', 'doc'))
(GroupSelect(group='test', select=True), GroupSelect(group='doc', select=True))
class gitws.datamodel.Groups(iterable=(), /)[source]

Bases: tuple

Groups.

static validate(groups)[source]

Validate Groups.

Groups are just a tuple of str for performance reasons. This function does the validation.

class gitws.datamodel.MainFileRef(*, src: str, dest: str, groups: Groups = ())[source]

Bases: FileRef

Main Project File Reference.

Parameters:

  • src – Source - path relative to the project directory.

  • dest – Destination - relative path to the workspace directory.

Keyword Arguments:

groups – Groups

groups: Groups

groups specification.

class gitws.datamodel.Manifest(*, group_filters: GroupFilters = (), linkfiles: Tuple[MainFileRef, ...] = (), copyfiles: Tuple[MainFileRef, ...] = (), dependencies: Tuple[Project, ...] = (), path: Optional[str] = None, **extra_data: Any)[source]

Bases: BaseModel

The Manifest.

A manifest describes the actual project and its dependencies.

Keyword Arguments:

  • group_filters – Group Filtering.

  • linkfiles – symbolic links to be created in the workspace

  • copyfiles – files to be created in the workspace

  • dependencies – Dependency Projects.

  • path – Filesystem Path. Relative to Workspace Root Directory.

The ManifestSpec represents the User Interface. The options which can be specified in the manifest file. The Manifest is the resolved version of ManifestSpec with all calculated information needed by GitWS to operate.

Manifest.from_spec() resolves a ManifestSpec into a Manifest.

copyfiles: Tuple[MainFileRef, ...]

Files To Be Created In The Workspace.

dependencies: Tuple[Project, ...]

Dependencies - Other Projects To Be Cloned In The Workspace.

static from_spec(spec: ManifestSpec, path: Optional[str] = None, refurl: Optional[str] = None, resolve_url: bool = False) → Manifest[source]

Create Manifest from ManifestSpec.

Parameters:

spec – The source ManifestSpec.

Keyword Arguments:

  • path – File path of the spec.

  • refurl – URL of the repository containing spec.

  • resolve_url – Convert relative to absolute URLs. Requires refurl.

Raises:

NoAbsUrlError – On resolve_url=True if refurl is None and project uses a relative URL.

group_filters: GroupFilters

Default Group Selection and Deselection.

linkfiles: Tuple[MainFileRef, ...]

Symbolic Links To Be Created In The Workspace.

path: Optional[str]

Path to the manifest file, relative to project path.

class gitws.datamodel.ManifestSpec(*, version: str = '1.0', group_filters: GroupFilters = (), linkfiles: Tuple[MainFileRef, ...] = (), copyfiles: Tuple[MainFileRef, ...] = (), remotes: Tuple[Remote, ...] = (), defaults: Defaults = Defaults(), dependencies: Tuple[ProjectSpec, ...] = ())[source]

Bases: BaseModel

ManifestSpec.

A manifest describes the actual project and its dependencies.

The ManifestSpec represents the User Interface. The options which can be specified in the manifest file. The Manifest is the resolved version of ManifestSpec with all calculated information needed by GitWS to operate.

Keyword Arguments:

  • version – Version String. Actually 1.0.

  • remotes – Remote Aliases.

  • group_filters – Group Filtering.

  • linkfiles – symbolic links to be created in the workspace

  • copyfiles – files to be created in the workspace

  • defaults – Default settings.

  • dependencies – Dependency Projects.

copyfiles: Tuple[MainFileRef, ...]

Files To Be Created In The Workspace.

defaults: Defaults

Default Values.

dependencies: Tuple[ProjectSpec, ...]

Dependencies - Other Projects To Be Cloned In The Workspace.

dump(doc: Optional[TOMLDocument] = None, path: Optional[Path] = None, minimal: bool = False) → str[source]

Return ManifestSpec as string.

The output will include an inline documentation of all available options. If doc or path are specified, any additional attributes and comments are kept.

Keyword Arguments:

  • doc – Existing document to be updated.

  • path – Path to possibly existing document.

  • minimal – Skip unset

>>> print(ManifestSpec(defaults=Defaults(revision='main'), dependencies=(ProjectSpec(name='mylib'),)).dump())
version = "1.0"
##
## Git Workspace's Manifest. Please see the documentation at:
##
## https://git-ws.readthedocs.io/en/latest/manual/manifest.html
##


# group-filters = ["-doc", "-feature@path"]
group-filters = []


# [[remotes]]
# name = "myremote"
# url-base = "https://github.com/myuser"


[defaults]
revision = "main"

# remote = "myserver"
# revision = "main"
# groups = ["test"]
# with-groups = ["doc"]


## A minimal dependency:
# [[dependencies]]
# name = "my"

## A full flavored dependency using a 'remote':
# [[dependencies]]
# name = "myname"
# remote = "remote"
# sub-url = "my.git"
# revision = "main"
# path = "mydir"
# groups = ["group"]
#
# [[dependencies.linkfiles]]
# src = "file0-in-mydir.txt"
# dest = "link0-in-workspace.txt"
#
# [[dependencies.linkfiles]]
# src = "file1-in-mydir.txt"
# dest = "link1-in-workspace.txt"
#
# [[dependencies.copyfiles]]
# src = "file0-in-mydir.txt"
# dest = "file0-in-workspace.txt"
#
# [[dependencies.copyfiles]]
# src = "file1-in-mydir.txt"
# dest = "file1-in-workspace.txt"

## A full flavored dependency using a 'url':
# [[dependencies]]
# name = "myname"
# url = "https://github.com/myuser/my.git"
# revision = "main"
# path = "mydir"
# groups = ["group"]
#
# [[dependencies.linkfiles]]
# src = "file0-in-mydir.txt"
# dest = "link0-in-workspace.txt"
#
# [[dependencies.linkfiles]]
# src = "file1-in-mydir.txt"
# dest = "link1-in-workspace.txt"
#
# [[dependencies.copyfiles]]
# src = "file0-in-mydir.txt"
# dest = "file0-in-workspace.txt"
#
# [[dependencies.copyfiles]]
# src = "file1-in-mydir.txt"
# dest = "file1-in-workspace.txt"

[[dependencies]]
name = "mylib"


# [[linkfiles]]
# src = "file-in-main-clone.txt"
# dest = "link-in-workspace.txt"


# [[copyfiles]]
# src = "file-in-main-clone.txt"
# dest = "file-in-workspace.txt"
group_filters: GroupFilters

Default Group Selection and Deselection.

linkfiles: Tuple[MainFileRef, ...]

Symbolic Links To Be Created In The Workspace.

classmethod load(path: Path) → ManifestSpec[source]

Load ManifestSpec from path.

The file referenced by path must be a TOML file according to the manifest scheme.

Raises:
remotes: Tuple[Remote, ...]

Remotes - Helpers to Simplify URL Handling.

save(path: Path, update=True)[source]

Save ManifestSpec at path.

The file will include an inline documentation of all available options.

Keyword Arguments:

update – Additional attributes and comments added by the user are kept. Otherwise the file is just overwritten.

classmethod upgrade(path: Path)[source]

Upgrade ManifestSpec at path to latest version including documentation.

version: str

Manifest Version Identifier.

Actual Version: 1.0.

class gitws.datamodel.Project(*, name: str, path: str, level: Optional[int] = None, url: Optional[str] = None, revision: Optional[str] = None, manifest_path: str = 'git-ws.toml', groups: Groups = (), with_groups: Groups = (), submodules: bool = True, linkfiles: Tuple[FileRef, ...] = (), copyfiles: Tuple[FileRef, ...] = (), is_main: bool = False)[source]

Bases: BaseModel

Project.

A project describes a dependency.

Parameters:

  • name – Name.

  • path – Project Filesystem Path. Relative to Workspace Root Directory.

Keyword Arguments:

  • level – Dependency Tree Level.

  • url – URL. Assembled from remote s url_base, sub_url and/or name.

  • revision – Revision to be checked out. Tag, branch or SHA.

  • manifest_path – Path to the manifest file. Relative to path of project. git-ws.toml by default.

  • groups – Dependency Groups.

  • with_groups – Group Selection for refered project.

  • submodules – initialize and update git submodules

  • linkfiles – symbolic links to be created in the workspace

  • copyfiles – files to be created in the workspace

  • is_main – Project is Main Project.

The ProjectSpec represents the User Interface. The options which can be specified in the manifest file. The Project is the resolved version of ProjectSpec with all calculated information needed by GitWS to operate.

Project.from_spec() resolves a ProjectSpec into a Project. ProjectSpec.from_project() does the reverse.

Note

Project.from_spec() resolves some attributes irreversible. So Project.from_spec(ProjectSpec.from_project()) will not return the original project.

copyfiles: Tuple[FileRef, ...]

Files To Be Created In The Workspace.

static from_spec(manifest_spec: ManifestSpec, spec: ProjectSpec, level: int, refurl: Optional[str] = None, resolve_url: bool = False) → Project[source]

Create Project from manifest_spec and spec.

Parameters:

  • manifest_spec – Manifest Specification.

  • spec – Base project to be resolved.

  • level – Dependency tree level.

Keyword Arguments:

  • refurl – Remote URL of the manifest_spec.

  • resolve_url – Resolve URLs to absolute ones.

Raises:

NoAbsUrlError – On resolve_url=True if refurl is None and project uses a relative URL.

Project.from_spec() resolves a ProjectSpec into a Project. ProjectSpec.from_project() does the reverse.

groups: Groups

Dependency Groups.

property info

repr-like info string but more condensed.

>>> Project(name='name', path='name').info
'name'
>>> Project(name='name', path='path').info
"name (path='path')"
>>> Project(name='name', path='name', revision='main').info
"name (revision='main')"
>>> Project(name='name', path='name', groups=('test', 'doc')).info
"name (groups='test,doc')"
is_main: bool

Project is the main project.

level: Optional[int]

Dependency Tree Level.

linkfiles: Tuple[FileRef, ...]

Symbolic Links To Be Created In The workspace.

manifest_path: str

Path to the manifest file. Relative to path of project. git-ws.toml by default.

name: str

Dependency Name.

path: str

Dependency Path. name will be used as default.

revision: Optional[str]

Revision to be checked out. Tag, branch or SHA.

submodules: bool

Initialize and Update git submodules.

url: Optional[str]

URL. Assembled from remote s url_base, sub_url and/or name.

with_groups: Groups

Group Selection for referred project.

class gitws.datamodel.ProjectSpec(*, name: str, remote: Optional[str] = None, sub_url: Optional[str] = None, url: Optional[str] = None, revision: Optional[str] = None, path: Optional[str] = None, manifest_path: Optional[str] = 'git-ws.toml', groups: Groups = (), with_groups: Groups = (), submodules: Optional[bool] = None, linkfiles: Tuple[FileRef, ...] = (), copyfiles: Tuple[FileRef, ...] = ())[source]

Bases: BaseModel

Project Dependency Specification

A project specifies the reference to a repository.

Parameters:

name – Name.

Keyword Arguments:

  • remote – Remote Alias - Remote URL Helper

  • sub_url – URL relative to Remote.url_base.

  • url – URL

  • revision – Revision

  • path – Project Filesystem Path. Relative to Workspace Root Directory.

  • manifest_path – Path to the manifest file. Relative to path of project. git-ws.toml by default.

  • groups – Dependency Groups.

  • with_groups – Group Selection for refered project.

  • submodules – initialize and update git submodules

  • linkfiles – symbolic links to be created in the workspace

  • copyfiles – files to be created in the workspace

Some parameters are restricted:

  • remote and url are mutually exclusive.

  • url and sub-url are likewise mutually exclusive

  • sub-url requires a remote.

The ProjectSpec represents the User Interface. The options which can be specified in the manifest file. The Project is the resolved version of ProjectSpec with all calculated information needed by GitWS to operate.

copyfiles: Tuple[FileRef, ...]

Files To Be Created In The Workspace.

static from_project(project: Project) → ProjectSpec[source]

Create ProjectSpec from project.

Parameters:

project – The source Project.

Note

Project.from_spec() resolves some attributes irreversible. So Project.from_spec(ProjectSpec.from_project()) will not return the original project.

groups: Groups

Dependency Groups.

linkfiles: Tuple[FileRef, ...]

Symbolic Links To Be Created In The Workspace.

manifest_path: Optional[str]

Path to the manifest file. Relative to path of project. git-ws.toml by default.

name: str

Dependency Name.

path: Optional[str]

Path within workspace. name will be used as default.

remote: Optional[str]

Remote Alias Name. The remote must have been defined previously.

revision: Optional[str]

Revision to be checked out.

sub_url: Optional[str]

Relative URL to remote s url_base OR the URL of the manifest file.

submodules: Optional[bool]

Initialize and Update git submodules.

url: Optional[str]

Absolute URL.

with_groups: Groups

Group Selection for refered project.

class gitws.datamodel.Remote(*, name: str, url_base: str = None)[source]

Bases: BaseModel

Remote Alias - Remote URL Helper.

Parameters:

name – Remote Name

Keyword Arguments:

url_base – Base URL. Optional.

name: str

The Name of the Remote. Must be unique within Manifest.

url_base: str

URL to a directory of repositories.

class gitws.datamodel.WorkspaceFileRef(*, type_: str, project_path: str, src: str, dest: str, hash_: Optional[int] = None)[source]

Bases: BaseModel

Actual File Reference with Workspace.

Parameters:

  • Path. (project_path - Project) –

  • src – Source - path relative to the project directory.

  • dest – Destination - relative path to the workspace directory.

Keyword Arguments:

hash – Source File Hash for Copied Files.

dest: str

Destination - relative path to the workspace directory.

hash_: Optional[int]

Hash - Source File Hash for Copied Files.

project_path: str

Project Path.

src: str

Source - path relative to project_path.

type_: str

File

gitws.datamodel.validate_group(group)[source]

Validate Group.

Group is just a str for performance reasons. This function does the validation.

gitws.datamodel.validate_group_filter(group_filter)[source]

Groups Filter.

Group Filters are just a tuple of str for performance reasons. This function does the validation.