usos-api 0.1.0__tar.gz → 0.1.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (24) hide show
  1. {usos_api-0.1.0 → usos_api-0.1.2}/PKG-INFO +8 -1
  2. usos_api-0.1.2/README.md +5 -0
  3. {usos_api-0.1.0 → usos_api-0.1.2}/pyproject.toml +34 -31
  4. {usos_api-0.1.0 → usos_api-0.1.2}/usos_api/__init__.py +5 -5
  5. {usos_api-0.1.0 → usos_api-0.1.2}/usos_api/auth.py +216 -197
  6. {usos_api-0.1.0 → usos_api-0.1.2}/usos_api/client.py +181 -176
  7. {usos_api-0.1.0 → usos_api-0.1.2}/usos_api/connection.py +137 -137
  8. {usos_api-0.1.0 → usos_api-0.1.2}/usos_api/exceptions.py +2 -2
  9. {usos_api-0.1.0 → usos_api-0.1.2}/usos_api/logger.py +20 -20
  10. {usos_api-0.1.0 → usos_api-0.1.2}/usos_api/models/__init__.py +53 -53
  11. {usos_api-0.1.0 → usos_api-0.1.2}/usos_api/models/consumer.py +17 -17
  12. {usos_api-0.1.0 → usos_api-0.1.2}/usos_api/models/course.py +77 -77
  13. {usos_api-0.1.0 → usos_api-0.1.2}/usos_api/models/grade.py +27 -27
  14. {usos_api-0.1.0 → usos_api-0.1.2}/usos_api/models/group.py +33 -33
  15. {usos_api-0.1.0 → usos_api-0.1.2}/usos_api/models/lang_dict.py +10 -10
  16. {usos_api-0.1.0 → usos_api-0.1.2}/usos_api/models/programme.py +34 -34
  17. {usos_api-0.1.0 → usos_api-0.1.2}/usos_api/models/term.py +14 -14
  18. {usos_api-0.1.0 → usos_api-0.1.2}/usos_api/models/user.py +159 -159
  19. {usos_api-0.1.0 → usos_api-0.1.2}/usos_api/services/__init__.py +5 -5
  20. {usos_api-0.1.0 → usos_api-0.1.2}/usos_api/services/api_server.py +40 -40
  21. {usos_api-0.1.0 → usos_api-0.1.2}/usos_api/services/groups.py +204 -204
  22. {usos_api-0.1.0 → usos_api-0.1.2}/usos_api/services/users.py +49 -49
  23. usos_api-0.1.0/README.md +0 -1
  24. {usos_api-0.1.0 → usos_api-0.1.2}/usos_api/utils/__init__.py +0 -0
@@ -1,7 +1,8 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: usos-api
3
- Version: 0.1.0
3
+ Version: 0.1.2
4
4
  Summary: Asynchronous USOS API for Python
5
+ Home-page: https://github.com/Antoni-Czaplicki/usos-api
5
6
  Author: Antoni-Czaplicki
6
7
  Author-email: 56671347+Antoni-Czaplicki@users.noreply.github.com
7
8
  Requires-Python: >=3.12,<4.0
@@ -11,6 +12,12 @@ Requires-Dist: aiohttp (>=3.9.5,<4.0.0)
11
12
  Requires-Dist: oauthlib (>=3.2.2,<4.0.0)
12
13
  Requires-Dist: pydantic (>=2.8.2,<3.0.0)
13
14
  Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
15
+ Project-URL: Documentation, https://usos-api.readthedocs.io
16
+ Project-URL: Repository, https://github.com/Antoni-Czaplicki/usos-api
14
17
  Description-Content-Type: text/markdown
15
18
 
16
19
  # USOS API for python, in development
20
+
21
+ This is a python library for USOS API. It is in development, so it is not recommended to use it in production.
22
+
23
+ Visit [documentation](https://usos-api.readthedocs.io) for more information.
@@ -0,0 +1,5 @@
1
+ # USOS API for python, in development
2
+
3
+ This is a python library for USOS API. It is in development, so it is not recommended to use it in production.
4
+
5
+ Visit [documentation](https://usos-api.readthedocs.io) for more information.
@@ -1,31 +1,34 @@
1
- [tool.poetry]
2
- name = "usos-api"
3
- version = "0.1.0"
4
- description = "Asynchronous USOS API for Python"
5
- authors = ["Antoni-Czaplicki <56671347+Antoni-Czaplicki@users.noreply.github.com>"]
6
- readme = "README.md"
7
-
8
- [tool.poetry.dependencies]
9
- python = "^3.12"
10
- aiohttp = "^3.9.5"
11
- pydantic = "^2.8.2"
12
- oauthlib = "^3.2.2"
13
- python-dotenv = "^1.0.1"
14
-
15
- [tool.poetry.group.dev.dependencies]
16
- black = "*"
17
- isort = "*"
18
- ruff = "*"
19
-
20
- [tool.poetry.group.docs]
21
- optional = true
22
-
23
- [tool.poetry.group.docs.dependencies]
24
- sphinx = "*"
25
- sphinx_rtd_theme = "*"
26
- readthedocs-sphinx-search = "*"
27
- sphinx-autodoc-typehints = "*"
28
-
29
- [build-system]
30
- requires = ["poetry-core"]
31
- build-backend = "poetry.core.masonry.api"
1
+ [tool.poetry]
2
+ name = "usos-api"
3
+ version = "0.1.2"
4
+ description = "Asynchronous USOS API for Python"
5
+ authors = ["Antoni-Czaplicki <56671347+Antoni-Czaplicki@users.noreply.github.com>"]
6
+ readme = "README.md"
7
+ homepage = "https://github.com/Antoni-Czaplicki/usos-api"
8
+ repository = "https://github.com/Antoni-Czaplicki/usos-api"
9
+ documentation = "https://usos-api.readthedocs.io"
10
+
11
+ [tool.poetry.dependencies]
12
+ python = "^3.12"
13
+ aiohttp = "^3.9.5"
14
+ pydantic = "^2.8.2"
15
+ oauthlib = "^3.2.2"
16
+ python-dotenv = "^1.0.1"
17
+
18
+ [tool.poetry.group.dev.dependencies]
19
+ black = "*"
20
+ isort = "*"
21
+ ruff = "*"
22
+
23
+ [tool.poetry.group.docs]
24
+ optional = true
25
+
26
+ [tool.poetry.group.docs.dependencies]
27
+ sphinx = "*"
28
+ sphinx_rtd_theme = "*"
29
+ readthedocs-sphinx-search = "*"
30
+ sphinx-autodoc-typehints = "*"
31
+
32
+ [build-system]
33
+ requires = ["poetry-core"]
34
+ build-backend = "poetry.core.masonry.api"
@@ -1,5 +1,5 @@
1
- from .client import USOSClient
2
- from .exceptions import USOSAPIException
3
- from .logger import get_logger
4
-
5
- __all__ = ["USOSClient", "USOSAPIException", "get_logger"]
1
+ from .client import USOSClient
2
+ from .exceptions import USOSAPIException
3
+ from .logger import get_logger
4
+
5
+ __all__ = ["USOSClient", "USOSAPIException", "get_logger"]
@@ -1,197 +1,216 @@
1
- import urllib
2
-
3
- import aiohttp
4
- from oauthlib.oauth1 import Client
5
-
6
- from .exceptions import USOSAPIException
7
- from .logger import get_logger
8
-
9
- _LOGGER = get_logger("AuthManager")
10
-
11
-
12
- class AuthManager:
13
- """
14
- A manager for the USOS API authentication.
15
- """
16
-
17
- REQUEST_TOKEN_SUFFIX = "services/oauth/request_token"
18
- AUTHORIZE_SUFFIX = "services/oauth/authorize"
19
- ACCESS_TOKEN_SUFFIX = "services/oauth/access_token"
20
- REVOKE_TOKEN_SUFFIX = "services/oauth/revoke_token"
21
- SCOPES = "|".join(["offline_access", "studies"])
22
-
23
- def __init__(self, api_base_address: str, consumer_key: str, consumer_secret: str):
24
- """
25
- Initialize the authentication manager.
26
-
27
- :param api_base_address: The base address of the USOS API.
28
- :param consumer_key: Consumer key obtained from the USOS API.
29
- :param consumer_secret: Consumer secret obtained from the USOS API.
30
- """
31
- self.base_address = api_base_address.rstrip("/") + "/"
32
- self.consumer_key = consumer_key
33
- self.consumer_secret = consumer_secret
34
- self.access_token = None
35
- self.access_token_secret = None
36
- self._session = None
37
- self._oauth_client = Client(consumer_key, consumer_secret)
38
-
39
- async def __aenter__(self) -> "AuthManager":
40
- """
41
- Enter the manager.
42
-
43
- :return: The manager.
44
- """
45
- await self.open()
46
- return self
47
-
48
- async def __aexit__(self, exc_type, exc_value, traceback):
49
- """
50
- Exit the manager.
51
-
52
- :param exc_type: The exception type.
53
- :param exc_value: The exception value.
54
- :param traceback: The traceback.
55
- """
56
- await self.close()
57
-
58
- async def open(self):
59
- """
60
- Open the manager.
61
- """
62
- self._session = aiohttp.ClientSession()
63
-
64
- async def close(self):
65
- """
66
- Close the manager.
67
- """
68
- if self._session:
69
- await self._session.close()
70
-
71
- async def _generate_request_token(self, callback_url: str) -> None:
72
- """
73
- Generate a new request token.
74
-
75
- :param callback_url:
76
- """
77
- url = f"{self.base_address}{self.REQUEST_TOKEN_SUFFIX}"
78
- params = {
79
- "oauth_callback": callback_url,
80
- "scopes": self.SCOPES,
81
- }
82
- headers = {"Content-Type": "application/x-www-form-urlencoded"}
83
- url, headers, body = Client(
84
- self.consumer_key, client_secret=self.consumer_secret
85
- ).sign(
86
- url, http_method="POST", body=params, headers=headers
87
- ) # Use a new client to avoid using the access token if it's set
88
- async with self._session.post(url, data=body, headers=headers) as response:
89
- await self._handle_response_errors(response)
90
- data = dict(urllib.parse.parse_qsl(await response.text()))
91
- self._request_token = data["oauth_token"]
92
- self._request_token_secret = data["oauth_token_secret"]
93
- self._oauth_client.resource_owner_key = self._request_token
94
- self._oauth_client.resource_owner_secret = self._request_token_secret
95
- _LOGGER.info(f"New request token generated: {self._request_token}")
96
-
97
- async def get_authorization_url(self, callback_url: str) -> str:
98
- """
99
- Get the authorization URL.
100
-
101
- :param callback_url: The callback URL.
102
- """
103
- await self._generate_request_token(callback_url)
104
- return f"{self.base_address}{self.AUTHORIZE_SUFFIX}?oauth_token={self._request_token}"
105
-
106
- async def authorize_with_token(self, token: str) -> tuple[str, str]:
107
- """
108
- Authorize the client with a token.
109
-
110
- :param token: The token to authorize the client with.
111
- :return: The access token and secret.
112
- """
113
- self._oauth_client.verifier = token
114
- url = f"{self.base_address}{self.ACCESS_TOKEN_SUFFIX}"
115
- url, headers, body = self._oauth_client.sign(url, http_method="POST")
116
- async with self._session.post(url, data=body, headers=headers) as response:
117
- await self._handle_response_errors(response)
118
- data = dict(urllib.parse.parse_qsl(await response.text()))
119
- self.load_access_token(data["oauth_token"], data["oauth_token_secret"])
120
- _LOGGER.info(
121
- f"Authorization successful, received access token: {self.access_token}"
122
- )
123
- return self.access_token, self.access_token_secret
124
-
125
- def load_access_token(self, access_token: str, access_token_secret: str):
126
- """
127
- Load the access token and secret into the manager.
128
-
129
- :param access_token: The access token.
130
- :param access_token_secret: The access token secret.
131
- """
132
- self.access_token = access_token
133
- self.access_token_secret = access_token_secret
134
- self._oauth_client = Client(
135
- self.consumer_key,
136
- client_secret=self.consumer_secret,
137
- resource_owner_key=self.access_token,
138
- resource_owner_secret=self.access_token_secret,
139
- )
140
-
141
- def sign_request(
142
- self, url: str, http_method: str = "GET", **kwargs
143
- ) -> tuple[str, dict, dict]:
144
- """
145
- Sign a request with the OAuth client.
146
-
147
- :param url: The URL to sign.
148
- :param http_method: The HTTP method to use.
149
- :param kwargs: Additional parameters to pass.
150
- :return: The signed URL, headers, and body.
151
- """
152
- if not self.access_token:
153
- raise USOSAPIException("Access token not set. Did you forget to authorize?")
154
- url, headers, body = self._oauth_client.sign(
155
- url, http_method=http_method, **kwargs
156
- )
157
- return url, headers, body
158
-
159
- async def _handle_response_errors(self, response: aiohttp.ClientResponse):
160
- """
161
- Handle errors in the response.
162
-
163
- :param response: The response to handle.
164
- :raises USOSAPIException: If an error occurred.
165
- """
166
- if response.status != 200:
167
- text = await response.text()
168
- if response.status == 401:
169
- _LOGGER.error(
170
- f"HTTP 401: Unauthorized. Your access key probably expired. Response: {text}"
171
- )
172
- raise USOSAPIException(
173
- "HTTP 401: Unauthorized. Your access key probably expired."
174
- )
175
- elif response.status == 400:
176
- raise USOSAPIException(f"HTTP 400: Bad request: {text}")
177
- else:
178
- raise USOSAPIException(f"HTTP {response.status}: {text}")
179
-
180
- async def _revoke_token(self):
181
- """
182
- Revoke the current access token.
183
- """
184
- url = f"{self.base_address}{self.REVOKE_TOKEN_SUFFIX}"
185
- url, headers, body = self._oauth_client.sign(url, http_method="POST")
186
- async with self._session.post(url, data=body, headers=headers) as response:
187
- await self._handle_response_errors(response)
188
- _LOGGER.info("Token revoked successfully.")
189
-
190
- async def logout(self):
191
- """
192
- Log out the user.
193
- """
194
- if not self.access_token:
195
- return
196
- await self._revoke_token()
197
- self.access_token = None
1
+ import urllib
2
+
3
+ import aiohttp
4
+ from oauthlib.oauth1 import Client
5
+
6
+ from .exceptions import USOSAPIException
7
+ from .logger import get_logger
8
+
9
+ _LOGGER = get_logger("AuthManager")
10
+
11
+
12
+ class AuthManager:
13
+ """
14
+ A manager for the USOS API authentication.
15
+ """
16
+
17
+ REQUEST_TOKEN_SUFFIX = "services/oauth/request_token"
18
+ AUTHORIZE_SUFFIX = "services/oauth/authorize"
19
+ ACCESS_TOKEN_SUFFIX = "services/oauth/access_token"
20
+ REVOKE_TOKEN_SUFFIX = "services/oauth/revoke_token"
21
+ SCOPES = "|".join(["offline_access", "studies"])
22
+
23
+ def __init__(self, api_base_address: str, consumer_key: str, consumer_secret: str):
24
+ """
25
+ Initialize the authentication manager.
26
+
27
+ :param api_base_address: The base address of the USOS API.
28
+ :param consumer_key: Consumer key obtained from the USOS API.
29
+ :param consumer_secret: Consumer secret obtained from the USOS API.
30
+ """
31
+ self.base_address = api_base_address.rstrip("/") + "/"
32
+ self.consumer_key = consumer_key
33
+ self.consumer_secret = consumer_secret
34
+ self.access_token = None
35
+ self.access_token_secret = None
36
+ self._session = None
37
+ self._oauth_client = Client(consumer_key, consumer_secret)
38
+
39
+ async def __aenter__(self) -> "AuthManager":
40
+ """
41
+ Enter the manager.
42
+
43
+ :return: The manager.
44
+ """
45
+ await self.open()
46
+ return self
47
+
48
+ async def __aexit__(self, exc_type, exc_value, traceback):
49
+ """
50
+ Exit the manager.
51
+
52
+ :param exc_type: The exception type.
53
+ :param exc_value: The exception value.
54
+ :param traceback: The traceback.
55
+ """
56
+ await self.close()
57
+
58
+ async def open(self):
59
+ """
60
+ Open the manager.
61
+ """
62
+ self._session = aiohttp.ClientSession()
63
+
64
+ async def close(self):
65
+ """
66
+ Close the manager.
67
+ """
68
+ if self._session:
69
+ await self._session.close()
70
+
71
+ async def _generate_request_token(self, callback_url: str) -> None:
72
+ """
73
+ Generate a new request token.
74
+
75
+ :param callback_url:
76
+ """
77
+ url = f"{self.base_address}{self.REQUEST_TOKEN_SUFFIX}"
78
+ params = {
79
+ "oauth_callback": callback_url,
80
+ "scopes": self.SCOPES,
81
+ }
82
+ headers = {"Content-Type": "application/x-www-form-urlencoded"}
83
+ url, headers, body = Client(
84
+ self.consumer_key, client_secret=self.consumer_secret
85
+ ).sign(
86
+ url, http_method="POST", body=params, headers=headers
87
+ ) # Use a new client to avoid using the access token if it's set
88
+ async with self._session.post(url, data=body, headers=headers) as response:
89
+ await self._handle_response_errors(response)
90
+ data = dict(urllib.parse.parse_qsl(await response.text()))
91
+ self._request_token = data["oauth_token"]
92
+ self._request_token_secret = data["oauth_token_secret"]
93
+ self._oauth_client.resource_owner_key = self._request_token
94
+ self._oauth_client.resource_owner_secret = self._request_token_secret
95
+ _LOGGER.info(f"New request token generated: {self._request_token}")
96
+
97
+ async def get_authorization_url(self, callback_url: str) -> str:
98
+ """
99
+ Get the authorization URL.
100
+
101
+ :param callback_url: The callback URL.
102
+ """
103
+ await self._generate_request_token(callback_url)
104
+ return f"{self.base_address}{self.AUTHORIZE_SUFFIX}?oauth_token={self._request_token}"
105
+
106
+ async def authorize(self, verifier: str, request_token, request_token_secret):
107
+ """
108
+ Authorize the client with verifier and optionally token and token secret.
109
+
110
+ :param verifier: The verifier to authorize the client with.
111
+ :param token: The OAuth token obtained from the previous step.
112
+ :param token_secret: The OAuth token secret obtained from the previous step.
113
+ :return: The access token and secret.
114
+ """
115
+ self._oauth_client.verifier = verifier
116
+ if request_token:
117
+ self._oauth_client.resource_owner_key = request_token
118
+ if request_token_secret:
119
+ self._oauth_client.resource_owner_secret = request_token_secret
120
+ url = f"{self.base_address}{self.ACCESS_TOKEN_SUFFIX}"
121
+ url, headers, body = self._oauth_client.sign(url, http_method="POST")
122
+ try:
123
+ async with self._session.post(url, data=body, headers=headers) as response:
124
+ await self._handle_response_errors(response)
125
+ data = dict(urllib.parse.parse_qsl(await response.text()))
126
+ self.load_access_token(data["oauth_token"], data["oauth_token_secret"])
127
+ _LOGGER.info(
128
+ f"Authorization successful, received access token: {self.access_token}"
129
+ )
130
+ return self.access_token, self.access_token_secret
131
+ except AttributeError as e:
132
+ if e.args[0] == "'NoneType' object has no attribute 'post'":
133
+ raise USOSAPIException(
134
+ "Authorization failed. Did you forget to open the manager?"
135
+ )
136
+ raise
137
+
138
+ def load_access_token(self, access_token: str, access_token_secret: str):
139
+ """
140
+ Load the access token and secret into the manager.
141
+
142
+ :param access_token: The access token.
143
+ :param access_token_secret: The access token secret.
144
+ """
145
+ self.access_token = access_token
146
+ self.access_token_secret = access_token_secret
147
+ self._oauth_client = Client(
148
+ self.consumer_key,
149
+ client_secret=self.consumer_secret,
150
+ resource_owner_key=self.access_token,
151
+ resource_owner_secret=self.access_token_secret,
152
+ )
153
+
154
+ def get_access_token(self):
155
+ return self.access_token, self.access_token_secret
156
+
157
+ def get_request_token(self):
158
+ return self._request_token, self._request_token_secret
159
+
160
+ def sign_request(
161
+ self, url: str, http_method: str = "GET", **kwargs
162
+ ) -> tuple[str, dict, dict]:
163
+ """
164
+ Sign a request with the OAuth client.
165
+
166
+ :param url: The URL to sign.
167
+ :param http_method: The HTTP method to use.
168
+ :param kwargs: Additional parameters to pass.
169
+ :return: The signed URL, headers, and body.
170
+ """
171
+ if not self.access_token:
172
+ raise USOSAPIException("Access token not set. Did you forget to authorize?")
173
+ url, headers, body = self._oauth_client.sign(
174
+ url, http_method=http_method, **kwargs
175
+ )
176
+ return url, headers, body
177
+
178
+ async def _handle_response_errors(self, response: aiohttp.ClientResponse):
179
+ """
180
+ Handle errors in the response.
181
+
182
+ :param response: The response to handle.
183
+ :raises USOSAPIException: If an error occurred.
184
+ """
185
+ if response.status != 200:
186
+ text = await response.text()
187
+ if response.status == 401:
188
+ _LOGGER.error(
189
+ f"HTTP 401: Unauthorized. Your access key probably expired. Response: {text}"
190
+ )
191
+ raise USOSAPIException(
192
+ "HTTP 401: Unauthorized. Your access key probably expired."
193
+ )
194
+ elif response.status == 400:
195
+ raise USOSAPIException(f"HTTP 400: Bad request: {text}")
196
+ else:
197
+ raise USOSAPIException(f"HTTP {response.status}: {text}")
198
+
199
+ async def _revoke_token(self):
200
+ """
201
+ Revoke the current access token.
202
+ """
203
+ url = f"{self.base_address}{self.REVOKE_TOKEN_SUFFIX}"
204
+ url, headers, body = self._oauth_client.sign(url, http_method="POST")
205
+ async with self._session.post(url, data=body, headers=headers) as response:
206
+ await self._handle_response_errors(response)
207
+ _LOGGER.info("Token revoked successfully.")
208
+
209
+ async def logout(self):
210
+ """
211
+ Log out the user.
212
+ """
213
+ if not self.access_token:
214
+ return
215
+ await self._revoke_token()
216
+ self.access_token = None