← 返回首页
feat(api): Narrow down return type of download methods using typing.o… · python-gitlab/python-gitlab@44fd9dc · GitHub
Skip to content

Navigation Menu

Toggle navigation
Sign in
Appearance settings
Search or jump to...

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Include my email address so I can be contacted
Cancel Submit feedback

Saved searches

Use saved searches to filter your results more quickly

Cancel Create saved search
Appearance settings
Resetting focus

Commit 44fd9dc

Browse files
igorp-collabora
authored and
JohnVillalovos
committed
feat(api): Narrow down return type of download methods using typing.overload
Currently the download methods such as `ProjectJob.artifacts` have return type set to `Optional[Union[bytes, Iterator[Any]]]` which means they return either `None` or `bytes` or `Iterator[Any]`. However, the actual return type is determined by the passed `streamed` and `iterator` arguments. Using `@typing.overload` decorator it is possible to return a single type based on the passed arguments. Add overloads in the following order to all download methods: 1. If `streamed=False` and `iterator=False` return `bytes`. This is the default argument values therefore it should be first as it will be used to lookup default arguments. 2. If `iterator=True` return `Iterator[Any]`. This can be combined with both `streamed=True` and `streamed=False`. 3. If `streamed=True` and `iterator=False` return `None`. In this case `action` argument can be set to a callable that accepts `bytes`. Signed-off-by: Igor Ponomarev <igor.ponomarev@collabora.com>
1 parent e4c5c74 commit 44fd9dc

9 files changed

Lines changed: 529 additions & 6 deletions

File tree

‎gitlab/mixins.py‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,9 @@
66
Dict,
77
Iterator,
88
List,
9+
Literal,
910
Optional,
11+
overload,
1012
Tuple,
1113
Type,
1214
TYPE_CHECKING,
@@ -612,6 +614,39 @@ class DownloadMixin(_RestObjectBase):
612614
_updated_attrs: Dict[str, Any]
613615
manager: base.RESTManager
614616

617+
@overload
618+
def download(
619+
self,
620+
streamed: Literal[False] = False,
621+
action: None = None,
622+
chunk_size: int = 1024,
623+
*,
624+
iterator: Literal[False] = False,
625+
**kwargs: Any,
626+
) -> bytes: ...
627+
628+
@overload
629+
def download(
630+
self,
631+
streamed: bool = False,
632+
action: None = None,
633+
chunk_size: int = 1024,
634+
*,
635+
iterator: Literal[True] = True,
636+
**kwargs: Any,
637+
) -> Iterator[Any]: ...
638+
639+
@overload
640+
def download(
641+
self,
642+
streamed: Literal[True] = True,
643+
action: Optional[Callable[[bytes], None]] = None,
644+
chunk_size: int = 1024,
645+
*,
646+
iterator: Literal[False] = False,
647+
**kwargs: Any,
648+
) -> None: ...
649+
615650
@cli.register_custom_action(cls_names=("GroupExport", "ProjectExport"))
616651
@exc.on_http_error(exc.GitlabGetError)
617652
def download(

‎gitlab/v4/objects/artifacts.py‎

Lines changed: 91 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,16 @@
33
https://docs.gitlab.com/ee/api/job_artifacts.html
44
"""
55

6-
from typing import Any, Callable, Iterator, Optional, TYPE_CHECKING, Union
6+
from typing import (
7+
Any,
8+
Callable,
9+
Iterator,
10+
Literal,
11+
Optional,
12+
overload,
13+
TYPE_CHECKING,
14+
Union,
15+
)
716

817
import requests
918

@@ -43,6 +52,45 @@ def delete(self, **kwargs: Any) -> None:
4352
assert path is not None
4453
self.gitlab.http_delete(path, **kwargs)
4554

55+
@overload
56+
def download(
57+
self,
58+
ref_name: str,
59+
job: str,
60+
streamed: Literal[False] = False,
61+
action: None = None,
62+
chunk_size: int = 1024,
63+
*,
64+
iterator: Literal[False] = False,
65+
**kwargs: Any,
66+
) -> bytes: ...
67+
68+
@overload
69+
def download(
70+
self,
71+
ref_name: str,
72+
job: str,
73+
streamed: bool = False,
74+
action: None = None,
75+
chunk_size: int = 1024,
76+
*,
77+
iterator: Literal[True] = True,
78+
**kwargs: Any,
79+
) -> Iterator[Any]: ...
80+
81+
@overload
82+
def download(
83+
self,
84+
ref_name: str,
85+
job: str,
86+
streamed: Literal[True] = True,
87+
action: Optional[Callable[[bytes], None]] = None,
88+
chunk_size: int = 1024,
89+
*,
90+
iterator: Literal[False] = False,
91+
**kwargs: Any,
92+
) -> None: ...
93+
4694
@cli.register_custom_action(
4795
cls_names="ProjectArtifactManager",
4896
required=("ref_name", "job"),
@@ -94,6 +142,48 @@ def download(
94142
result, streamed, action, chunk_size, iterator=iterator
95143
)
96144

145+
@overload
146+
def raw(
147+
self,
148+
ref_name: str,
149+
artifact_path: str,
150+
job: str,
151+
streamed: Literal[False] = False,
152+
action: None = None,
153+
chunk_size: int = 1024,
154+
*,
155+
iterator: Literal[False] = False,
156+
**kwargs: Any,
157+
) -> bytes: ...
158+
159+
@overload
160+
def raw(
161+
self,
162+
ref_name: str,
163+
artifact_path: str,
164+
job: str,
165+
streamed: bool = False,
166+
action: None = None,
167+
chunk_size: int = 1024,
168+
*,
169+
iterator: Literal[True] = True,
170+
**kwargs: Any,
171+
) -> Iterator[Any]: ...
172+
173+
@overload
174+
def raw(
175+
self,
176+
ref_name: str,
177+
artifact_path: str,
178+
job: str,
179+
streamed: Literal[True] = True,
180+
action: Optional[Callable[[bytes], None]] = None,
181+
chunk_size: int = 1024,
182+
*,
183+
iterator: Literal[False] = False,
184+
**kwargs: Any,
185+
) -> None: ...
186+
97187
@cli.register_custom_action(
98188
cls_names="ProjectArtifactManager",
99189
required=("ref_name", "artifact_path", "job"),

‎gitlab/v4/objects/jobs.py‎

Lines changed: 114 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,15 @@
1-
from typing import Any, Callable, cast, Dict, Iterator, Optional, TYPE_CHECKING, Union
1+
from typing import (
2+
Any,
3+
Callable,
4+
cast,
5+
Dict,
6+
Iterator,
7+
Literal,
8+
Optional,
9+
overload,
10+
TYPE_CHECKING,
11+
Union,
12+
)
213

314
import requests
415

@@ -115,6 +126,39 @@ def delete_artifacts(self, **kwargs: Any) -> None:
115126
path = f"{self.manager.path}/{self.encoded_id}/artifacts"
116127
self.manager.gitlab.http_delete(path, **kwargs)
117128

129+
@overload
130+
def artifacts(
131+
self,
132+
streamed: Literal[False] = False,
133+
action: None = None,
134+
chunk_size: int = 1024,
135+
*,
136+
iterator: Literal[False] = False,
137+
**kwargs: Any,
138+
) -> bytes: ...
139+
140+
@overload
141+
def artifacts(
142+
self,
143+
streamed: bool = False,
144+
action: None = None,
145+
chunk_size: int = 1024,
146+
*,
147+
iterator: Literal[True] = True,
148+
**kwargs: Any,
149+
) -> Iterator[Any]: ...
150+
151+
@overload
152+
def artifacts(
153+
self,
154+
streamed: Literal[True] = True,
155+
action: Optional[Callable[[bytes], None]] = None,
156+
chunk_size: int = 1024,
157+
*,
158+
iterator: Literal[False] = False,
159+
**kwargs: Any,
160+
) -> None: ...
161+
118162
@cli.register_custom_action(cls_names="ProjectJob")
119163
@exc.on_http_error(exc.GitlabGetError)
120164
def artifacts(
@@ -156,6 +200,42 @@ def artifacts(
156200
result, streamed, action, chunk_size, iterator=iterator
157201
)
158202

203+
@overload
204+
def artifact(
205+
self,
206+
path: str,
207+
streamed: Literal[False] = False,
208+
action: None = None,
209+
chunk_size: int = 1024,
210+
*,
211+
iterator: Literal[False] = False,
212+
**kwargs: Any,
213+
) -> bytes: ...
214+
215+
@overload
216+
def artifact(
217+
self,
218+
path: str,
219+
streamed: bool = False,
220+
action: None = None,
221+
chunk_size: int = 1024,
222+
*,
223+
iterator: Literal[True] = True,
224+
**kwargs: Any,
225+
) -> Iterator[Any]: ...
226+
227+
@overload
228+
def artifact(
229+
self,
230+
path: str,
231+
streamed: Literal[True] = True,
232+
action: Optional[Callable[[bytes], None]] = None,
233+
chunk_size: int = 1024,
234+
*,
235+
iterator: Literal[False] = False,
236+
**kwargs: Any,
237+
) -> None: ...
238+
159239
@cli.register_custom_action(cls_names="ProjectJob")
160240
@exc.on_http_error(exc.GitlabGetError)
161241
def artifact(
@@ -199,6 +279,39 @@ def artifact(
199279
result, streamed, action, chunk_size, iterator=iterator
200280
)
201281

282+
@overload
283+
def trace(
284+
self,
285+
streamed: Literal[False] = False,
286+
action: None = None,
287+
chunk_size: int = 1024,
288+
*,
289+
iterator: Literal[False] = False,
290+
**kwargs: Any,
291+
) -> bytes: ...
292+
293+
@overload
294+
def trace(
295+
self,
296+
streamed: bool = False,
297+
action: None = None,
298+
chunk_size: int = 1024,
299+
*,
300+
iterator: Literal[True] = True,
301+
**kwargs: Any,
302+
) -> Iterator[Any]: ...
303+
304+
@overload
305+
def trace(
306+
self,
307+
streamed: Literal[True] = True,
308+
action: Optional[Callable[[bytes], None]] = None,
309+
chunk_size: int = 1024,
310+
*,
311+
iterator: Literal[False] = False,
312+
**kwargs: Any,
313+
) -> None: ...
314+
202315
@cli.register_custom_action(cls_names="ProjectJob")
203316
@exc.on_http_error(exc.GitlabGetError)
204317
def trace(

‎gitlab/v4/objects/packages.py‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,9 @@
1111
Callable,
1212
cast,
1313
Iterator,
14+
Literal,
1415
Optional,
16+
overload,
1517
TYPE_CHECKING,
1618
Union,
1719
)
@@ -122,6 +124,48 @@ def upload(
122124
attrs.update(server_data)
123125
return self._obj_cls(self, attrs=attrs)
124126

127+
@overload
128+
def download(
129+
self,
130+
package_name: str,
131+
package_version: str,
132+
file_name: str,
133+
streamed: Literal[False] = False,
134+
action: None = None,
135+
chunk_size: int = 1024,
136+
*,
137+
iterator: Literal[False] = False,
138+
**kwargs: Any,
139+
) -> bytes: ...
140+
141+
@overload
142+
def download(
143+
self,
144+
package_name: str,
145+
package_version: str,
146+
file_name: str,
147+
streamed: bool = False,
148+
action: None = None,
149+
chunk_size: int = 1024,
150+
*,
151+
iterator: Literal[True] = True,
152+
**kwargs: Any,
153+
) -> Iterator[Any]: ...
154+
155+
@overload
156+
def download(
157+
self,
158+
package_name: str,
159+
package_version: str,
160+
file_name: str,
161+
streamed: Literal[True] = True,
162+
action: Optional[Callable[[bytes], None]] = None,
163+
chunk_size: int = 1024,
164+
*,
165+
iterator: Literal[False] = False,
166+
**kwargs: Any,
167+
) -> None: ...
168+
125169
@cli.register_custom_action(
126170
cls_names="GenericPackageManager",
127171
required=("package_name", "package_version", "file_name"),

0 commit comments

Comments
 (0)

Footer

© 2026 GitHub, Inc.