From dc3c69898abe75d574de06174b79c019b657ffc3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Joakim=20S=C3=B8rensen?= Date: Sun, 4 Dec 2022 16:44:56 +0100 Subject: [PATCH] Enhance client arguments and description (#160) * Enhance client arguments and description * remove unused import --- aiogithubapi/client.py | 45 ++++++++++++++++++++++----- aiogithubapi/github.py | 1 + aiogithubapi/namespaces/repos.py | 53 +++++++++++++++++++++++++++----- tests/namespaces/test_repos.py | 2 +- 4 files changed, 85 insertions(+), 16 deletions(-) diff --git a/aiogithubapi/client.py b/aiogithubapi/client.py index 87fd190..58d9c58 100644 --- a/aiogithubapi/client.py +++ b/aiogithubapi/client.py @@ -2,7 +2,6 @@ from __future__ import annotations import asyncio -import json from typing import Any, Dict import aiohttp @@ -65,7 +64,15 @@ def __init__( api_version: str | None = None, **kwargs: Dict[GitHubClientKwarg, Any], ) -> None: - """Initialise the GitHub API client.""" + """ + Initialise the GitHub API client. + + **Arguments:** + `session`: The aiohttp client session to use for making requests. + `token`: The GitHub access token to use for authenticating requests. Can be a string or None. + `api_version`: The version of the GitHub API to use. Can be a string or None. + + """ self._base_request_data = GitHubBaseRequestDataModel( token=token, api_version=api_version, @@ -79,16 +86,40 @@ async def async_call_api( endpoint: str, *, data: Dict[str, Any] | str | None = None, + headers: Dict[str, Any] | None = None, + method: HttpMethod = HttpMethod.GET, + params: Dict[str, Any] | None = None, + timeout: int | None = None, **kwargs: Dict[GitHubRequestKwarg, Any], ) -> GitHubResponseModel: - """Execute the API call.""" + """ + Makes an HTTP request to the specified endpoint using the specified parameters. + + This method is asynchronous, meaning that it will not block the execution of the program while the request is being made and processed. + + **Arguments**: + + - `endpoint` (Required): The API endpoint to call. + + **Optional arguments**: + - `endpoint`: The API endpoint to call. + - `data`: The data to include in the request body. Can be a dictionary, a string, or None. + - `headers`: The headers to include in the request. Can be a dictionary or None. + - `method`: The HTTP method to use for the request. Defaults to GET. + - `params`: The query parameters to include in the request. Can be a dictionary or None. + - `timeout`: The maximum amount of time to wait for the request to complete, in seconds. Can be an integer or None. + + Returns: + A GitHubResponseModel object representing the API response. + """ request_arguments: Dict[str, Any] = { "url": self._base_request_data.request_url(endpoint), - "method": kwargs.get(GitHubRequestKwarg.METHOD, HttpMethod.GET).lower(), - "params": kwargs.get(GitHubRequestKwarg.PARAMS) - or kwargs.get(GitHubRequestKwarg.QUERY, {}), - "timeout": self._base_request_data.timeout, + "method": kwargs.get(GitHubRequestKwarg.METHOD, method).lower(), + "params": params + or kwargs.get(GitHubRequestKwarg.PARAMS, kwargs.get(GitHubRequestKwarg.QUERY, {})), + "timeout": timeout or self._base_request_data.timeout, "headers": { + **(headers or {}), **self._base_request_data.headers, **kwargs.get("headers", {}), }, diff --git a/aiogithubapi/github.py b/aiogithubapi/github.py index 14c18e3..002ede7 100644 --- a/aiogithubapi/github.py +++ b/aiogithubapi/github.py @@ -167,6 +167,7 @@ async def versions( async def markdown( self, text: str, + *, mode: str | None = None, context: RepositoryType | None = None, **kwargs: Dict[GitHubRequestKwarg, Any], diff --git a/aiogithubapi/namespaces/repos.py b/aiogithubapi/namespaces/repos.py index 0ad26b9..ac5d3c1 100644 --- a/aiogithubapi/namespaces/repos.py +++ b/aiogithubapi/namespaces/repos.py @@ -103,21 +103,58 @@ async def get( async def list_commits( self, repository: RepositoryType, + *, + sha: str | None = None, + path: str | None = None, + author: str | None = None, + since: str | None = None, + until: str | None = None, + per_page: int = 30, + page: int = 0, **kwargs: Dict[GitHubRequestKwarg, Any], ) -> GitHubResponseModel[List[GitHubCommitModel]]: """ - List commits - - **Arguments**: - - `repository` - - The repository to return commits from, example "octocat/hello-world" - + List commits from a repository. + + **Arguments**: + + - `repository`: The repository to return commits from, specified as + `/`, e.g. "octocat/hello-world". + - `sha`: Filter the commits to only those with the given SHA. + - `path`: Filter the commits to only those with changes to the given path. + - `author`: Filter the commits to only those with the given author. + - `since`: Filter the commits to only those that were made after the given + date and time. The `since` parameter should be formatted as an ISO 8601 + date and time, e.g. "2022-12-03T12:34:56Z". + - `until`: Filter the commits to only those that were made before the given + date and time. The `until` parameter should be formatted as an ISO 8601 + date and time, e.g. "2022-12-03T12:34:56Z". + - `per_page`: The number of commits to return per page. The default value is + 30 and the maximum allowed value is 100. + - `page`: The page number to return. The default value is 0 (the first page). + + For more details, see the API documentation at: https://docs.github.com/en/rest/reference/repos#list-commits """ + params = { + "per_page": per_page, + "page": page, + } + + if sha is not None: + params["sha"] = sha + if path is not None: + params["path"] = path + if author is not None: + params["author"] = author + if since is not None: + params["since"] = since + if until is not None: + params["until"] = until + response = await self._client.async_call_api( endpoint=f"/repos/{repository_full_name(repository)}/commits", + params=params, **kwargs, ) response.data = [GitHubCommitModel(data) for data in response.data] diff --git a/tests/namespaces/test_repos.py b/tests/namespaces/test_repos.py index 4eedb8e..31e2a2c 100644 --- a/tests/namespaces/test_repos.py +++ b/tests/namespaces/test_repos.py @@ -26,7 +26,7 @@ async def test_get_repository(github_api: GitHubAPI, mock_requests: MockedReques @pytest.mark.asyncio async def test_list_commits(github_api: GitHubAPI, mock_requests: MockedRequests): - response = await github_api.repos.list_commits(TEST_REPOSITORY_NAME) + response = await github_api.repos.list_commits(TEST_REPOSITORY_NAME, sha="main", path="README.md", author="awesome_author", since="2021-01-01", until="2021-01-02") assert response.status == 200 assert isinstance(response.data, list) assert response.data[0].commit.message == "Merge pull request #6"