Skip to content

Commit e262867

Browse files
nejchnejch
committed
docs: only use type annotations for documentation
1 parent f7cbcc3 commit e262867

26 files changed

+282
-287
lines changed

‎gitlab/base.py

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -298,8 +298,7 @@ def __init__(self, gl: Gitlab, parent: Optional[RESTObject] = None) -> None:
298298
"""REST manager constructor.
299299
300300
Args:
301-
gl (Gitlab): :class:`~gitlab.Gitlab` connection to use to make
302-
requests.
301+
gl: :class:`~gitlab.Gitlab` connection to use to make requests.
303302
parent: REST object to which the manager is attached.
304303
"""
305304
self.gitlab = gl

‎gitlab/client.py

Lines changed: 50 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -39,21 +39,21 @@ class Gitlab(object):
3939
"""Represents a GitLab server connection.
4040
4141
Args:
42-
url (str): The URL of the GitLab server (defaults to https://gitlab.com).
43-
private_token (str): The user private token
44-
oauth_token (str): An oauth token
45-
job_token (str): A CI job token
46-
ssl_verify (bool|str): Whether SSL certificates should be validated. If
42+
url: The URL of the GitLab server (defaults to https://gitlab.com).
43+
private_token: The user private token
44+
oauth_token: An oauth token
45+
job_token: A CI job token
46+
ssl_verify: Whether SSL certificates should be validated. If
4747
the value is a string, it is the path to a CA file used for
4848
certificate validation.
49-
timeout (float): Timeout to use for requests to the GitLab server.
50-
http_username (str): Username for HTTP authentication
51-
http_password (str): Password for HTTP authentication
52-
api_version (str): Gitlab API version to use (support for 4 only)
53-
pagination (str): Can be set to 'keyset' to use keyset pagination
54-
order_by (str): Set order_by globally
55-
user_agent (str): A custom user agent to use for making HTTP requests.
56-
retry_transient_errors (bool): Whether to retry after 500, 502, 503, or
49+
timeout: Timeout to use for requests to the GitLab server.
50+
http_username: Username for HTTP authentication
51+
http_password: Password for HTTP authentication
52+
api_version: Gitlab API version to use (support for 4 only)
53+
pagination: Can be set to 'keyset' to use keyset pagination
54+
order_by: Set order_by globally
55+
user_agent: A custom user agent to use for making HTTP requests.
56+
retry_transient_errors: Whether to retry after 500, 502, 503, or
5757
504 responses. Defaults to False.
5858
"""
5959

@@ -225,11 +225,11 @@ def from_config(
225225
"""Create a Gitlab connection from configuration files.
226226
227227
Args:
228-
gitlab_id (str): ID of the configuration section.
228+
gitlab_id: ID of the configuration section.
229229
config_files list[str]: List of paths to configuration files.
230230
231231
Returns:
232-
(gitlab.Gitlab): A Gitlab connection.
232+
A Gitlab connection.
233233
234234
Raises:
235235
gitlab.config.GitlabDataError: If the configuration is not correct.
@@ -269,7 +269,7 @@ def version(self) -> Tuple[str, str]:
269269
object.
270270
271271
Returns:
272-
tuple (str, str): The server version and server revision.
272+
tuple: The server version and server revision.
273273
('unknown', 'unknwown') if the server doesn't
274274
perform as expected.
275275
"""
@@ -293,7 +293,7 @@ def lint(self, content: str, **kwargs: Any) -> Tuple[bool, List[str]]:
293293
"""Validate a gitlab CI configuration.
294294
295295
Args:
296-
content (txt): The .gitlab-ci.yml content
296+
content: The .gitlab-ci.yml content
297297
**kwargs: Extra options to send to the server (e.g. sudo)
298298
299299
Raises:
@@ -317,11 +317,9 @@ def markdown(
317317
"""Render an arbitrary Markdown document.
318318
319319
Args:
320-
text (str): The markdown text to render
321-
gfm (bool): Render text using GitLab Flavored Markdown. Default is
322-
False
323-
project (str): Full path of a project used a context when `gfm` is
324-
True
320+
text: The markdown text to render
321+
gfm: Render text using GitLab Flavored Markdown. Default is False
322+
project: Full path of a project used a context when `gfm` is True
325323
**kwargs: Extra options to send to the server (e.g. sudo)
326324
327325
Raises:
@@ -363,7 +361,7 @@ def set_license(self, license: str, **kwargs: Any) -> Dict[str, Any]:
363361
"""Add a new license.
364362
365363
Args:
366-
license (str): The license string
364+
license: The license string
367365
**kwargs: Extra options to send to the server (e.g. sudo)
368366
369367
Raises:
@@ -541,20 +539,19 @@ def http_request(
541539
"""Make an HTTP request to the Gitlab server.
542540
543541
Args:
544-
verb (str): The HTTP method to call ('get', 'post', 'put',
545-
'delete')
546-
path (str): Path or full URL to query ('/projects' or
542+
verb: The HTTP method to call ('get', 'post', 'put', 'delete')
543+
path: Path or full URL to query ('/projects' or
547544
'http://whatever/v4/api/projecs')
548-
query_data (dict): Data to send as query parameters
549-
post_data (dict|bytes): Data to send in the body (will be converted to
545+
query_data: Data to send as query parameters
546+
post_data: Data to send in the body (will be converted to
550547
json by default)
551-
raw (bool): If True, do not convert post_data to json
552-
streamed (bool): Whether the data should be streamed
553-
files (dict): The files to send to the server
554-
timeout (float): The timeout, in seconds, for the request
555-
obey_rate_limit (bool): Whether to obey 429 Too Many Request
548+
raw: If True, do not convert post_data to json
549+
streamed: Whether the data should be streamed
550+
files: The files to send to the server
551+
timeout: The timeout, in seconds, for the request
552+
obey_rate_limit: Whether to obey 429 Too Many Request
556553
responses. Defaults to True.
557-
max_retries (int): Max retries after 429 or transient errors,
554+
max_retries: Max retries after 429 or transient errors,
558555
set to -1 to retry forever. Defaults to 10.
559556
**kwargs: Extra options to send to the server (e.g. sudo)
560557
@@ -667,11 +664,11 @@ def http_get(
667664
"""Make a GET request to the Gitlab server.
668665
669666
Args:
670-
path (str): Path or full URL to query ('/projects' or
667+
path: Path or full URL to query ('/projects' or
671668
'http://whatever/v4/api/projecs')
672-
query_data (dict): Data to send as query parameters
673-
streamed (bool): Whether the data should be streamed
674-
raw (bool): If True do not try to parse the output as json
669+
query_data: Data to send as query parameters
670+
streamed: Whether the data should be streamed
671+
raw: If True do not try to parse the output as json
675672
**kwargs: Extra options to send to the server (e.g. sudo)
676673
677674
Returns:
@@ -712,9 +709,9 @@ def http_list(
712709
"""Make a GET request to the Gitlab server for list-oriented queries.
713710
714711
Args:
715-
path (str): Path or full URL to query ('/projects' or
712+
path: Path or full URL to query ('/projects' or
716713
'http://whatever/v4/api/projects')
717-
query_data (dict): Data to send as query parameters
714+
query_data: Data to send as query parameters
718715
**kwargs: Extra options to send to the server (e.g. sudo, page,
719716
per_page)
720717
@@ -761,13 +758,13 @@ def http_post(
761758
"""Make a POST request to the Gitlab server.
762759
763760
Args:
764-
path (str): Path or full URL to query ('/projects' or
761+
path: Path or full URL to query ('/projects' or
765762
'http://whatever/v4/api/projecs')
766-
query_data (dict): Data to send as query parameters
767-
post_data (dict): Data to send in the body (will be converted to
763+
query_data: Data to send as query parameters
764+
post_data: Data to send in the body (will be converted to
768765
json by default)
769-
raw (bool): If True, do not convert post_data to json
770-
files (dict): The files to send to the server
766+
raw: If True, do not convert post_data to json
767+
files: The files to send to the server
771768
**kwargs: Extra options to send to the server (e.g. sudo)
772769
773770
Returns:
@@ -810,13 +807,13 @@ def http_put(
810807
"""Make a PUT request to the Gitlab server.
811808
812809
Args:
813-
path (str): Path or full URL to query ('/projects' or
810+
path: Path or full URL to query ('/projects' or
814811
'http://whatever/v4/api/projecs')
815-
query_data (dict): Data to send as query parameters
816-
post_data (dict|bytes): Data to send in the body (will be converted to
812+
query_data: Data to send as query parameters
813+
post_data: Data to send in the body (will be converted to
817814
json by default)
818-
raw (bool): If True, do not convert post_data to json
819-
files (dict): The files to send to the server
815+
raw: If True, do not convert post_data to json
816+
files: The files to send to the server
820817
**kwargs: Extra options to send to the server (e.g. sudo)
821818
822819
Returns:
@@ -849,7 +846,7 @@ def http_delete(self, path: str, **kwargs: Any) -> requests.Response:
849846
"""Make a DELETE request to the Gitlab server.
850847
851848
Args:
852-
path (str): Path or full URL to query ('/projects' or
849+
path: Path or full URL to query ('/projects' or
853850
'http://whatever/v4/api/projecs')
854851
**kwargs: Extra options to send to the server (e.g. sudo)
855852
@@ -868,8 +865,8 @@ def search(
868865
"""Search GitLab resources matching the provided string.'
869866
870867
Args:
871-
scope (str): Scope of the search
872-
search (str): Search string
868+
scope: Scope of the search
869+
search: Search string
873870
**kwargs: Extra options to send to the server (e.g. sudo)
874871
875872
Raises:

‎gitlab/exceptions.py

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -297,8 +297,7 @@ def on_http_error(error: Type[Exception]) -> Callable[[__F], __F]:
297297
raise specialized exceptions instead.
298298
299299
Args:
300-
error(Exception): The exception type to raise -- must inherit from
301-
GitlabError
300+
The exception type to raise -- must inherit from GitlabError
302301
"""
303302

304303
def wrap(f: __F) -> __F:

‎gitlab/mixins.py

Lines changed: 21 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -86,8 +86,8 @@ def get(
8686
"""Retrieve a single object.
8787
8888
Args:
89-
id (int or str): ID of the object to retrieve
90-
lazy (bool): If True, don't request the server, but create a
89+
id: ID of the object to retrieve
90+
lazy: If True, don't request the server, but create a
9191
shallow object giving access to the managers. This is
9292
useful if you want to avoid useless calls to the API.
9393
**kwargs: Extra options to send to the server (e.g. sudo)
@@ -199,10 +199,10 @@ def list(self, **kwargs: Any) -> Union[base.RESTObjectList, List[base.RESTObject
199199
"""Retrieve a list of objects.
200200
201201
Args:
202-
all (bool): If True, return all the items, without pagination
203-
per_page (int): Number of items to retrieve per request
204-
page (int): ID of the page to return (starts with page 1)
205-
as_list (bool): If set to False and no pagination option is
202+
all: If True, return all the items, without pagination
203+
per_page: Number of items to retrieve per request
204+
page: ID of the page to return (starts with page 1)
205+
as_list: If set to False and no pagination option is
206206
defined, return a generator instead of a list
207207
**kwargs: Extra options to send to the server (e.g. sudo)
208208
@@ -282,7 +282,7 @@ def create(
282282
"""Create a new object.
283283
284284
Args:
285-
data (dict): parameters to send to the server to create the
285+
data: parameters to send to the server to create the
286286
resource
287287
**kwargs: Extra options to send to the server (e.g. sudo)
288288
@@ -433,8 +433,8 @@ def set(self, key: str, value: str, **kwargs: Any) -> base.RESTObject:
433433
"""Create or update the object.
434434
435435
Args:
436-
key (str): The key of the object to create/update
437-
value (str): The value to set for the object
436+
key: The key of the object to create/update
437+
value: The value to set for the object
438438
**kwargs: Extra options to send to the server (e.g. sudo)
439439
440440
Raises:
@@ -623,7 +623,7 @@ def approve(
623623
"""Approve an access request.
624624
625625
Args:
626-
access_level (int): The access level for the user
626+
access_level: The access level for the user
627627
**kwargs: Extra options to send to the server (e.g. sudo)
628628
629629
Raises:
@@ -659,12 +659,12 @@ def download(
659659
"""Download the archive of a resource export.
660660
661661
Args:
662-
streamed (bool): If True the data will be processed by chunks of
662+
streamed: If True the data will be processed by chunks of
663663
`chunk_size` and each chunk is passed to `action` for
664664
treatment
665-
action (callable): Callable responsible of dealing with chunk of
665+
action: Callable responsible of dealing with chunk of
666666
data
667-
chunk_size (int): Size of each chunk
667+
chunk_size: Size of each chunk
668668
**kwargs: Extra options to send to the server (e.g. sudo)
669669
670670
Raises:
@@ -793,7 +793,7 @@ def time_estimate(self, duration: str, **kwargs: Any) -> Dict[str, Any]:
793793
"""Set an estimated time of work for the object.
794794
795795
Args:
796-
duration (str): Duration in human format (e.g. 3h30)
796+
duration: Duration in human format (e.g. 3h30)
797797
**kwargs: Extra options to send to the server (e.g. sudo)
798798
799799
Raises:
@@ -831,7 +831,7 @@ def add_spent_time(self, duration: str, **kwargs: Any) -> Dict[str, Any]:
831831
"""Add time spent working on the object.
832832
833833
Args:
834-
duration (str): Duration in human format (e.g. 3h30)
834+
duration: Duration in human format (e.g. 3h30)
835835
**kwargs: Extra options to send to the server (e.g. sudo)
836836
837837
Raises:
@@ -878,10 +878,10 @@ def participants(self, **kwargs: Any) -> Dict[str, Any]:
878878
"""List the participants.
879879
880880
Args:
881-
all (bool): If True, return all the items, without pagination
882-
per_page (int): Number of items to retrieve per request
883-
page (int): ID of the page to return (starts with page 1)
884-
as_list (bool): If set to False and no pagination option is
881+
all: If True, return all the items, without pagination
882+
per_page: Number of items to retrieve per request
883+
page: ID of the page to return (starts with page 1)
884+
as_list: If set to False and no pagination option is
885885
defined, return a generator instead of a list
886886
**kwargs: Extra options to send to the server (e.g. sudo)
887887
@@ -909,8 +909,8 @@ def render(self, link_url: str, image_url: str, **kwargs: Any) -> Dict[str, Any]
909909
"""Preview link_url and image_url after interpolation.
910910
911911
Args:
912-
link_url (str): URL of the badge link
913-
image_url (str): URL of the badge image
912+
link_url: URL of the badge link
913+
image_url: URL of the badge image
914914
**kwargs: Extra options to send to the server (e.g. sudo)
915915
916916
Raises:

‎gitlab/v4/objects/clusters.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ def create(
4141
"""Create a new object.
4242
4343
Args:
44-
data (dict): Parameters to send to the server to create the
44+
data: Parameters to send to the server to create the
4545
resource
4646
**kwargs: Extra options to send to the server (e.g. sudo or
4747
'ref_name', 'stage', 'name', 'all')
@@ -92,7 +92,7 @@ def create(
9292
"""Create a new object.
9393
9494
Args:
95-
data (dict): Parameters to send to the server to create the
95+
data: Parameters to send to the server to create the
9696
resource
9797
**kwargs: Extra options to send to the server (e.g. sudo or
9898
'ref_name', 'stage', 'name', 'all')

‎gitlab/v4/objects/commits.py

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ def cherry_pick(self, branch: str, **kwargs: Any) -> None:
5050
"""Cherry-pick a commit into a branch.
5151
5252
Args:
53-
branch (str): Name of target branch
53+
branch: Name of target branch
5454
**kwargs: Extra options to send to the server (e.g. sudo)
5555
5656
Raises:
@@ -69,7 +69,7 @@ def refs(
6969
"""List the references the commit is pushed to.
7070
7171
Args:
72-
type (str): The scope of references ('branch', 'tag' or 'all')
72+
type: The scope of references ('branch', 'tag' or 'all')
7373
**kwargs: Extra options to send to the server (e.g. sudo)
7474
7575
Raises:
@@ -109,7 +109,7 @@ def revert(
109109
"""Revert a commit on a given branch.
110110
111111
Args:
112-
branch (str): Name of target branch
112+
branch: Name of target branch
113113
**kwargs: Extra options to send to the server (e.g. sudo)
114114
115115
Raises:
@@ -191,7 +191,7 @@ def create(
191191
"""Create a new object.
192192
193193
Args:
194-
data (dict): Parameters to send to the server to create the
194+
data: Parameters to send to the server to create the
195195
resource
196196
**kwargs: Extra options to send to the server (e.g. sudo or
197197
'ref_name', 'stage', 'name', 'all')

0 commit comments

Comments
 (0)