Enhance client arguments and description (#160)

* Enhance client arguments and description

* remove unused import

Author: ludeeus

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", {}),
             },

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],

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
+            `<owner>/<repository>`, 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]

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"