Skip to content

💻 Client

Wakatime API client.

Class that contains the ways to integrate with the Wakatime API.

Attributes:

Name Type Description
base_url str

Base URL for the API.
api_key str

Encoded API key.
session aiohttp.ClientSession

HTTP session.
Source code in awakatime/awakatime.py 
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
class Awakatime:
    """Wakatime API client.

    Class that contains the ways to integrate with the Wakatime API.

    Attributes:
        base_url (str): Base URL for the API.
        api_key (str): Encoded API key.
        session (aiohttp.ClientSession): HTTP session.
    """

    base_url = "https://wakatime.com"

    def __init__(self, api_key: str):
        """Initialize a new Wakatime client.

        Transform the API key into a base64 encoded string.

        Args:
            api_key (str): API key to use.
        """
        self.api_key = encode_base64(api_key)
        self.session = ClientSession(self.base_url)

    async def __aenter__(self):
        return self

    async def __aexit__(self, *_):
        await self.close()

    async def request(self, method: str, endpoint: str, **kwargs) -> ClientResponse:
        """Make a request to the WakaTime API.

        This method is a coroutine.

        Args:
            method (str): HTTP method to use.
            endpoint (str): API endpoint to use.
            **kwargs: Additional arguments to pass to the request.

        Returns:
            The response from the API.

        Raises:
            aiohttp.ClientResponseError: If the response status code is not 2xx.
        """
        headers = {
            "Authorization": f"Basic {self.api_key}",
            "Content-Type": "application/json",
        }
        return await self.session.request(
            method,
            endpoint,
            headers=headers,
            raise_for_status=True,
            **kwargs,
        )

    async def get_all_time(self, user: str = "current", **kwargs) -> dict:
        """Get total time logged for the user.

        This method is a coroutine.

        See https://wakatime.com/developers#all_time_since_today for more information.

        Args:
            user (str, optional): Wakatime user to get the data from.

        Keyword Args:
            project (str, optional): Project name to filter by.

        Returns:
            All time logged for the user.

        Raises:
            KeyError: If the response JSON is missing the "data" key.
            aiohttp.ClientResponseError: If the response status code is not 2xx.
        """
        endpoint = f"/api/v1/users/{user}/all_time_since_today"

        response = await self.request("GET", endpoint, params=kwargs)
        response_data = await response.json()
        return response_data["data"]

    async def get_commits(self, project: str, user: str = "current", **kwargs) -> list[dict]:
        """Get commits for a WakaTime project.

        This method is a coroutine.

        See https://wakatime.com/developers#commits for more information.

        Args:
            project (str): Project name to get the data from.
            user (str, optional): Wakatime user to get the data from.

        Keyword Args:
            author (str, optional): Author name to filter by.
            branch (str, optional): Branch name to filter by.
            page (int, optional): Page number to get.

        Returns:
            List of project commits.

        Raises:
            aiohttp.ClientResponseError: If the response status code is not 2xx.
        """
        endpoint = f"/api/v1/users/{user}/projects/{project}/commits"

        response = await self.request("GET", endpoint, params=kwargs)
        return await response.json()  # a resposta é direta

    async def get_projects(self, user: str = "current", **kwargs) -> list[dict]:
        """Get all projects logged for the user.

        This method is a coroutine.

        See https://wakatime.com/developers#projects for more information.

        Args:
            user (str, optional): Wakatime user to get the data from.

        Keyword Args:
            q (str, optional): Filter projects by name.

        Returns:
            List of projects.

        Raises:
            KeyError: If the response JSON is missing the "data" key.
            aiohttp.ClientResponseError: If the response status code is not 2xx.
        """
        endpoint = f"/api/v1/users/{user}/projects"

        response = await self.request("GET", endpoint, params=kwargs)
        response_data = await response.json()
        return response_data["data"]

    async def get_machines(self, user: str = "current") -> list[dict]:
        """Get all machines data logged for the user.

        This method is a coroutine.

        See https://wakatime.com/developers#machine_names for more information.

        Args:
            user (str, optional): Wakatime user to get the data from.

        Returns:
            List of user machines data.

        Raises:
            KeyError: If the response JSON is missing the "data" key.
            aiohttp.ClientResponseError: If the response status code is not 2xx.
        """
        endpoint = f"/api/v1/users/{user}/machine_names"

        response = await self.request("GET", endpoint)
        response_data = await response.json()
        return response_data["data"]

    async def close(self):
        await self.session.close()

__init__(api_key)

Initialize a new Wakatime client.

Transform the API key into a base64 encoded string.

Parameters:

Name Type Description Default
api_key str

API key to use.

 required
Source code in awakatime/awakatime.py 
19
20
21
22
23
24
25
26
27
28
def __init__(self, api_key: str):
    """Initialize a new Wakatime client.

    Transform the API key into a base64 encoded string.

    Args:
        api_key (str): API key to use.
    """
    self.api_key = encode_base64(api_key)
    self.session = ClientSession(self.base_url)

get_all_time(user='current', **kwargs) async

Get total time logged for the user.

This method is a coroutine.

See https://wakatime.com/developers#all_time_since_today for more information.

Parameters:

Name Type Description Default
user str

Wakatime user to get the data from.

 'current'

Other Parameters:

Name Type Description
project str

Project name to filter by.

Returns:

Type Description
dict

All time logged for the user.

Raises:

Type Description
KeyError

If the response JSON is missing the "data" key.
aiohttp.ClientResponseError

If the response status code is not 2xx.
Source code in awakatime/awakatime.py 
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
async def get_all_time(self, user: str = "current", **kwargs) -> dict:
    """Get total time logged for the user.

    This method is a coroutine.

    See https://wakatime.com/developers#all_time_since_today for more information.

    Args:
        user (str, optional): Wakatime user to get the data from.

    Keyword Args:
        project (str, optional): Project name to filter by.

    Returns:
        All time logged for the user.

    Raises:
        KeyError: If the response JSON is missing the "data" key.
        aiohttp.ClientResponseError: If the response status code is not 2xx.
    """
    endpoint = f"/api/v1/users/{user}/all_time_since_today"

    response = await self.request("GET", endpoint, params=kwargs)
    response_data = await response.json()
    return response_data["data"]

get_commits(project, user='current', **kwargs) async

Get commits for a WakaTime project.

This method is a coroutine.

See https://wakatime.com/developers#commits for more information.

Parameters:

Name Type Description Default
project str

Project name to get the data from.

 required
user str

Wakatime user to get the data from.

 'current'

Other Parameters:

Name Type Description
author str

Author name to filter by.
branch str

Branch name to filter by.
page int

Page number to get.

Returns:

Type Description
list[dict]

List of project commits.

Raises:

Type Description
aiohttp.ClientResponseError

If the response status code is not 2xx.
Source code in awakatime/awakatime.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
async def get_commits(self, project: str, user: str = "current", **kwargs) -> list[dict]:
    """Get commits for a WakaTime project.

    This method is a coroutine.

    See https://wakatime.com/developers#commits for more information.

    Args:
        project (str): Project name to get the data from.
        user (str, optional): Wakatime user to get the data from.

    Keyword Args:
        author (str, optional): Author name to filter by.
        branch (str, optional): Branch name to filter by.
        page (int, optional): Page number to get.

    Returns:
        List of project commits.

    Raises:
        aiohttp.ClientResponseError: If the response status code is not 2xx.
    """
    endpoint = f"/api/v1/users/{user}/projects/{project}/commits"

    response = await self.request("GET", endpoint, params=kwargs)
    return await response.json()  # a resposta é direta

get_machines(user='current') async

Get all machines data logged for the user.

This method is a coroutine.

See https://wakatime.com/developers#machine_names for more information.

Parameters:

Name Type Description Default
user str

Wakatime user to get the data from.

 'current'

Returns:

Type Description
list[dict]

List of user machines data.

Raises:

Type Description
KeyError

If the response JSON is missing the "data" key.
aiohttp.ClientResponseError

If the response status code is not 2xx.
Source code in awakatime/awakatime.py 
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
async def get_machines(self, user: str = "current") -> list[dict]:
    """Get all machines data logged for the user.

    This method is a coroutine.

    See https://wakatime.com/developers#machine_names for more information.

    Args:
        user (str, optional): Wakatime user to get the data from.

    Returns:
        List of user machines data.

    Raises:
        KeyError: If the response JSON is missing the "data" key.
        aiohttp.ClientResponseError: If the response status code is not 2xx.
    """
    endpoint = f"/api/v1/users/{user}/machine_names"

    response = await self.request("GET", endpoint)
    response_data = await response.json()
    return response_data["data"]

get_projects(user='current', **kwargs) async

Get all projects logged for the user.

This method is a coroutine.

See https://wakatime.com/developers#projects for more information.

Parameters:

Name Type Description Default
user str

Wakatime user to get the data from.

 'current'

Other Parameters:

Name Type Description
q str

Filter projects by name.

Returns:

Type Description
list[dict]

List of projects.

Raises:

Type Description
KeyError

If the response JSON is missing the "data" key.
aiohttp.ClientResponseError

If the response status code is not 2xx.
Source code in awakatime/awakatime.py 
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
async def get_projects(self, user: str = "current", **kwargs) -> list[dict]:
    """Get all projects logged for the user.

    This method is a coroutine.

    See https://wakatime.com/developers#projects for more information.

    Args:
        user (str, optional): Wakatime user to get the data from.

    Keyword Args:
        q (str, optional): Filter projects by name.

    Returns:
        List of projects.

    Raises:
        KeyError: If the response JSON is missing the "data" key.
        aiohttp.ClientResponseError: If the response status code is not 2xx.
    """
    endpoint = f"/api/v1/users/{user}/projects"

    response = await self.request("GET", endpoint, params=kwargs)
    response_data = await response.json()
    return response_data["data"]

request(method, endpoint, **kwargs) async

Make a request to the WakaTime API.

This method is a coroutine.

Parameters:

Name Type Description Default
method str

HTTP method to use.

 required
endpoint str

API endpoint to use.

 required
**kwargs

Additional arguments to pass to the request.

 {}

Returns:

Type Description
ClientResponse

The response from the API.

Raises:

Type Description
aiohttp.ClientResponseError

If the response status code is not 2xx.
Source code in awakatime/awakatime.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
async def request(self, method: str, endpoint: str, **kwargs) -> ClientResponse:
    """Make a request to the WakaTime API.

    This method is a coroutine.

    Args:
        method (str): HTTP method to use.
        endpoint (str): API endpoint to use.
        **kwargs: Additional arguments to pass to the request.

    Returns:
        The response from the API.

    Raises:
        aiohttp.ClientResponseError: If the response status code is not 2xx.
    """
    headers = {
        "Authorization": f"Basic {self.api_key}",
        "Content-Type": "application/json",
    }
    return await self.session.request(
        method,
        endpoint,
        headers=headers,
        raise_for_status=True,
        **kwargs,
    )