GitPython/git/types.py at kill-all-proper · gitpython-developers/GitPython · GitHub

Repository navigation

History

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

# This module is part of GitPython and is released under the

# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/

import os

from typing import (

Any,

Callable,

Dict,

List,

NoReturn,

Optional,

Sequence as Sequence,

Tuple,

TYPE_CHECKING,

TypeVar,

Union,

)

import warnings

from typing import (

Literal,

Protocol,

SupportsIndex as SupportsIndex,

TypedDict,

runtime_checkable,

)

if TYPE_CHECKING:

from git.objects import Commit, Tree, TagObject, Blob

from git.repo import Repo

PathLike = Union[str, "os.PathLike[str]"]

"""A :class:`str` (Unicode) based file or directory path."""

TBD = Any

"""Alias of :class:`~typing.Any`, when a type hint is meant to become more specific."""

_T = TypeVar("_T")

"""Type variable used internally in GitPython."""

_T_Stream_co = TypeVar("_T_Stream_co", str, bytes, covariant=True)

_T_Stream_contra = TypeVar("_T_Stream_contra", str, bytes, contravariant=True)

class SupportsRead(Protocol[_T_Stream_co]):

"""A stream supporting reads, without requiring the full IO interface."""

def read(self, __size: int = -1) -> _T_Stream_co: ...

class SupportsWrite(Protocol[_T_Stream_contra]):

"""A stream supporting writes, including writers that return None."""

def write(self, __data: _T_Stream_contra) -> object: ...

AnyGitObject = Union["Commit", "Tree", "TagObject", "Blob"]

"""Union of the :class:`~git.objects.base.Object`-based types that represent actual git

object types.

As noted in :class:`~git.objects.base.Object`, which has further details, these are:

* :class:`Blob <git.objects.blob.Blob>`

* :class:`Tree <git.objects.tree.Tree>`

* :class:`Commit <git.objects.commit.Commit>`

* :class:`TagObject <git.objects.tag.TagObject>`

Those GitPython classes represent the four git object types, per

:manpage:`gitglossary(7)`:

* "blob": https://git-scm.com/docs/gitglossary#def_blob_object

* "tree object": https://git-scm.com/docs/gitglossary#def_tree_object

* "commit object": https://git-scm.com/docs/gitglossary#def_commit_object

* "tag object": https://git-scm.com/docs/gitglossary#def_tag_object

For more general information on git objects and their types as git understands them:

* "object": https://git-scm.com/docs/gitglossary#def_object

* "object type": https://git-scm.com/docs/gitglossary#def_object_type

:note:

See also the :class:`Tree_ish` and :class:`Commit_ish` unions.

"""

Tree_ish = Union["Commit", "Tree", "TagObject"]

"""Union of :class:`~git.objects.base.Object`-based types that are typically tree-ish.

See :manpage:`gitglossary(7)` on "tree-ish":

https://git-scm.com/docs/gitglossary#def_tree-ish

:note:

:class:`~git.objects.tree.Tree` and :class:`~git.objects.commit.Commit` are the

classes whose instances are all tree-ish. This union includes them, but also

:class:`~git.objects.tag.TagObject`, only **most** of whose instances are tree-ish.

Whether a particular :class:`~git.objects.tag.TagObject` peels (recursively

dereferences) to a tree or commit, rather than a blob, can in general only be known

at runtime. In practice, git tag objects are nearly always used for tagging commits,

and such tags are tree-ish because commits are tree-ish.

:note:

See also the :class:`AnyGitObject` union of all four classes corresponding to git

object types.

"""

Commit_ish = Union["Commit", "TagObject"]

"""Union of :class:`~git.objects.base.Object`-based types that are typically commit-ish.

See :manpage:`gitglossary(7)` on "commit-ish":

https://git-scm.com/docs/gitglossary#def_commit-ish

:note:

:class:`~git.objects.commit.Commit` is the only class whose instances are all

commit-ish. This union type includes :class:`~git.objects.commit.Commit`, but also

:class:`~git.objects.tag.TagObject`, only **most** of whose instances are

commit-ish. Whether a particular :class:`~git.objects.tag.TagObject` peels

(recursively dereferences) to a commit, rather than a tree or blob, can in general

only be known at runtime. In practice, git tag objects are nearly always used for

tagging commits, and such tags are of course commit-ish.

:note:

See also the :class:`AnyGitObject` union of all four classes corresponding to git

object types.

"""

GitObjectTypeString = Literal["commit", "tag", "blob", "tree"]

"""Literal strings identifying git object types and the

:class:`~git.objects.base.Object`-based types that represent them.

See the :attr:`Object.type <git.objects.base.Object.type>` attribute. These are its

values in :class:`~git.objects.base.Object` subclasses that represent git objects. These

literals therefore correspond to the types in the :class:`AnyGitObject` union.

These are the same strings git itself uses to identify its four object types.

See :manpage:`gitglossary(7)` on "object type":

https://git-scm.com/docs/gitglossary#def_object_type

"""

if TYPE_CHECKING:

Lit_commit_ish = Literal["commit", "tag"]

"""Deprecated. Type of literal strings identifying typically-commitish git object types.

Prior to a bugfix, this type had been defined more broadly. Any usage is in practice

ambiguous and likely to be incorrect. This type has therefore been made a static type

error to appear in annotations. It is preserved, with a deprecated status, to avoid

introducing runtime errors in code that refers to it, but it should not be used.

Instead of this type:

* For the type of the string literals associated with :class:`Commit_ish`, use

``Literal["commit", "tag"]`` or create a new type alias for it. That is equivalent to

this type as currently defined (but usable in statically checked type annotations).

* For the type of all four string literals associated with :class:`AnyGitObject`, use

:class:`GitObjectTypeString`. That is equivalent to the old definition of this type

prior to the bugfix (and is also usable in statically checked type annotations).

"""

def _getattr(name: str) -> Any:

if name != "Lit_commit_ish":

raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

warnings.warn(

"Lit_commit_ish is deprecated. It is currently defined as "

'`Literal["commit", "tag"]`, which should be used in its place if desired. It '

'had previously been defined as `Literal["commit", "tag", "blob", "tree"]`, '

"covering all four git object type strings including those that are never "

"commit-ish. For that, use the GitObjectTypeString type instead.",

DeprecationWarning,

stacklevel=2,

)

return Literal["commit", "tag"]

if not TYPE_CHECKING: # Preserve static checking for undefined/misspelled attributes.

__getattr__ = _getattr

def __dir__() -> List[str]:

return [*globals(), "Lit_commit_ish"]

# Config_levels ---------------------------------------------------------

Lit_config_levels = Literal["system", "global", "user", "repository"]

"""Type of literal strings naming git configuration levels.

These strings relate to which file a git configuration variable is in.

"""

ConfigLevels_Tup = Tuple[Literal["system"], Literal["user"], Literal["global"], Literal["repository"]]

"""Static type of a tuple of the four strings representing configuration levels."""

# Progress parameter type alias -----------------------------------------

CallableProgress = Optional[Callable[[int, Union[str, float], Union[str, float, None], str], None]]

"""General type of a function or other callable used as a progress reporter for cloning.

This is the type of a function or other callable that reports the progress of a clone,

when passed as a ``progress`` argument to :meth:`Repo.clone <git.repo.base.Repo.clone>`

or :meth:`Repo.clone_from <git.repo.base.Repo.clone_from>`.

:note:

Those :meth:`~git.repo.base.Repo.clone` and :meth:`~git.repo.base.Repo.clone_from`

methods also accept :meth:`~git.util.RemoteProgress` instances, including instances

of its :meth:`~git.util.CallableRemoteProgress` subclass.

:note:

Unlike objects that match this type, :meth:`~git.util.RemoteProgress` instances are

not directly callable, not even when they are instances of

:meth:`~git.util.CallableRemoteProgress`, which wraps a callable and forwards

information to it but is not itself callable.

:note:

This type also allows ``None``, for cloning without reporting progress.

"""

# -----------------------------------------------------------------------------------

def assert_never(inp: NoReturn, raise_error: bool = True, exc: Union[Exception, None] = None) -> None:

"""For use in exhaustive checking of a literal or enum in if/else chains.

A call to this function should only be reached if not all members are handled, or if

an attempt is made to pass non-members through the chain.

:param inp:

If all members are handled, the argument for `inp` will have the

:class:`~typing.Never`/:class:`~typing.NoReturn` type.

Otherwise, the type will mismatch and cause a mypy error.

:param raise_error:

If ``True``, will also raise :exc:`ValueError` with a general

"unhandled literal" message, or the exception object passed as `exc`.

:param exc:

It not ``None``, this should be an already-constructed exception object, to be

raised if `raise_error` is ``True``.

"""

if raise_error:

if exc is None:

raise ValueError(f"An unhandled literal ({inp!r}) in an if/else chain was found")

else:

raise exc

class Files_TD(TypedDict):

"""Dictionary with stat counts for the diff of a particular file.

For the :class:`~git.util.Stats.files` attribute of :class:`~git.util.Stats`

objects.

"""

insertions: int

deletions: int

lines: int

change_type: str

class Total_TD(TypedDict):

"""Dictionary with total stats from any number of files.

For the :class:`~git.util.Stats.total` attribute of :class:`~git.util.Stats`

objects.

"""

insertions: int

deletions: int

lines: int

files: int

class HSH_TD(TypedDict):

"""Dictionary carrying the same information as a :class:`~git.util.Stats` object."""

total: Total_TD

files: Dict[PathLike, Files_TD]

@runtime_checkable

class Has_Repo(Protocol):

"""Protocol for having a :attr:`repo` attribute, the repository to operate on."""

repo: "Repo"

@runtime_checkable

class Has_id_attribute(Protocol):

"""Protocol for having :attr:`_id_attribute_` used in iteration and traversal."""

_id_attribute_: str

GitPython/git/types.py at kill-all-proper · gitpython-developers/GitPython · GitHub

Repository navigation

Expand file tree

Breadcrumbs

types.py

Latest commit

History

Breadcrumbs

types.py

File metadata and controls