22LazyMixin ,
33IterableObj ,
44)
5- from .symbolic import SymbolicReference
5+ from .symbolic import SymbolicReference ,T_References
6+
7+
8+ # typing ------------------------------------------------------------------
9+
10+ from typing import Any ,Callable ,Iterator ,List ,Match ,Optional ,Tuple ,Type ,TypeVar ,Union ,TYPE_CHECKING # NOQA
11+ from git .types import Commit_ish ,PathLike ,TBD ,Literal ,TypeGuard ,_T # NOQA
12+
13+ if TYPE_CHECKING :
14+ from git .repo import Repo
15+
16+ # ------------------------------------------------------------------------------
617
718
819__all__ = ["Reference" ]
920
1021#{ Utilities
1122
1223
13- def require_remote_ref_path (func ) :
24+ def require_remote_ref_path (func : Callable [..., _T ]) -> Callable [..., _T ] :
1425"""A decorator raising a TypeError if we are not a valid remote, based on the path"""
1526
16- def wrapper (self ,* args ) :
27+ def wrapper (self : T_References ,* args : Any ) -> _T :
1728if not self .is_remote ():
1829raise ValueError ("ref path does not point to a remote reference: %s" % self .path )
1930return func (self ,* args )
@@ -32,7 +43,7 @@ class Reference(SymbolicReference, LazyMixin, IterableObj):
3243_resolve_ref_on_create = True
3344_common_path_default = "refs"
3445
35- def __init__ (self ,repo ,path ,check_path = True ):
46+ def __init__ (self ,repo : 'Repo' ,path : PathLike ,check_path : bool = True )-> None :
3647"""Initialize this instance
3748 :param repo: Our parent repository
3849
@@ -41,16 +52,17 @@ def __init__(self, repo, path, check_path=True):
4152 refs/heads/master
4253 :param check_path: if False, you can provide any path. Otherwise the path must start with the
4354 default path prefix of this type."""
44- if check_path and not path .startswith (self ._common_path_default + '/' ):
45- raise ValueError ("Cannot instantiate %r from path %s" % (self .__class__ .__name__ ,path ))
55+ if check_path and not str (path ).startswith (self ._common_path_default + '/' ):
56+ raise ValueError (f"Cannot instantiate{ self .__class__ .__name__ !r} { path } )
57+ self .path :str # SymbolicReference converts to string atm
4658super (Reference ,self ).__init__ (repo ,path )
4759
48- def __str__ (self ):
60+ def __str__ (self )-> str :
4961return self .name
5062
5163#{ Interface
5264
53- def set_object (self ,object ,logmsg = None ):# @ReservedAssignment
65+ def set_object (self ,object : Commit_ish ,logmsg : Union [ str , None ] = None )-> 'Reference' :# @ReservedAssignment
5466"""Special version which checks if the head-log needs an update as well
5567 :return: self"""
5668oldbinsha = None
@@ -84,7 +96,7 @@ def set_object(self, object, logmsg=None): # @ReservedAssignment
8496# NOTE: Don't have to overwrite properties as the will only work without a the log
8597
8698@property
87- def name (self ):
99+ def name (self )-> str :
88100""":return: (shortest) Name of this reference - it may contain path components"""
89101# first two path tokens are can be removed as they are
90102# refs/heads or refs/tags or refs/remotes
@@ -94,7 +106,8 @@ def name(self):
94106return '/' .join (tokens [2 :])
95107
96108@classmethod
97- def iter_items (cls ,repo ,common_path = None ):
109+ def iter_items (cls :Type [T_References ],repo :'Repo' ,common_path :Union [PathLike ,None ]= None ,
110+ * args :Any ,** kwargs :Any )-> Iterator [T_References ]:
98111"""Equivalent to SymbolicReference.iter_items, but will return non-detached
99112 references as well."""
100113return cls ._iter_items (repo ,common_path )
@@ -105,7 +118,7 @@ def iter_items(cls, repo, common_path=None):
105118
106119@property # type: ignore ## mypy cannot deal with properties with an extra decorator (2021-04-21)
107120@require_remote_ref_path
108- def remote_name (self ):
121+ def remote_name (self )-> str :
109122"""
110123 :return:
111124 Name of the remote we are a reference of, such as 'origin' for a reference
@@ -116,7 +129,7 @@ def remote_name(self):
116129
117130@property # type: ignore ## mypy cannot deal with properties with an extra decorator (2021-04-21)
118131@require_remote_ref_path
119- def remote_head (self ):
132+ def remote_head (self )-> str :
120133""":return: Name of the remote head itself, i.e. master.
121134 :note: The returned name is usually not qualified enough to uniquely identify
122135 a branch"""