usos-api 0.2.0__tar.gz → 0.3.1__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 (32) hide show
  1. {usos_api-0.2.0 → usos_api-0.3.1}/PKG-INFO +9 -6
  2. {usos_api-0.2.0 → usos_api-0.3.1}/pyproject.toml +6 -6
  3. {usos_api-0.2.0 → usos_api-0.3.1}/usos_api/client.py +16 -7
  4. {usos_api-0.2.0 → usos_api-0.3.1}/usos_api/helper.py +2 -11
  5. {usos_api-0.2.0 → usos_api-0.3.1}/usos_api/models/__init__.py +14 -0
  6. {usos_api-0.2.0 → usos_api-0.3.1}/usos_api/models/course.py +14 -4
  7. usos_api-0.3.1/usos_api/models/registration.py +73 -0
  8. {usos_api-0.2.0 → usos_api-0.3.1}/usos_api/models/term.py +1 -1
  9. {usos_api-0.2.0 → usos_api-0.3.1}/usos_api/services/__init__.py +2 -0
  10. usos_api-0.3.1/usos_api/services/courses.py +84 -0
  11. {usos_api-0.2.0 → usos_api-0.3.1}/usos_api/services/grades.py +5 -1
  12. {usos_api-0.2.0 → usos_api-0.3.1}/usos_api/services/groups.py +1 -1
  13. usos_api-0.3.1/usos_api/services/registrations.py +112 -0
  14. usos_api-0.2.0/usos_api/services/courses.py +0 -52
  15. {usos_api-0.2.0 → usos_api-0.3.1}/README.md +0 -0
  16. {usos_api-0.2.0 → usos_api-0.3.1}/usos_api/__init__.py +0 -0
  17. {usos_api-0.2.0 → usos_api-0.3.1}/usos_api/auth.py +0 -0
  18. {usos_api-0.2.0 → usos_api-0.3.1}/usos_api/connection.py +0 -0
  19. {usos_api-0.2.0 → usos_api-0.3.1}/usos_api/exceptions.py +0 -0
  20. {usos_api-0.2.0 → usos_api-0.3.1}/usos_api/logger.py +0 -0
  21. {usos_api-0.2.0 → usos_api-0.3.1}/usos_api/models/api_documentation.py +0 -0
  22. {usos_api-0.2.0 → usos_api-0.3.1}/usos_api/models/consumer.py +0 -0
  23. {usos_api-0.2.0 → usos_api-0.3.1}/usos_api/models/grade.py +0 -0
  24. {usos_api-0.2.0 → usos_api-0.3.1}/usos_api/models/group.py +0 -0
  25. {usos_api-0.2.0 → usos_api-0.3.1}/usos_api/models/lang_dict.py +0 -0
  26. {usos_api-0.2.0 → usos_api-0.3.1}/usos_api/models/programme.py +0 -0
  27. {usos_api-0.2.0 → usos_api-0.3.1}/usos_api/models/user.py +0 -0
  28. {usos_api-0.2.0 → usos_api-0.3.1}/usos_api/services/api_documentation.py +0 -0
  29. {usos_api-0.2.0 → usos_api-0.3.1}/usos_api/services/api_server.py +0 -0
  30. {usos_api-0.2.0 → usos_api-0.3.1}/usos_api/services/terms.py +0 -0
  31. {usos_api-0.2.0 → usos_api-0.3.1}/usos_api/services/users.py +0 -0
  32. {usos_api-0.2.0 → usos_api-0.3.1}/usos_api/utils/__init__.py +0 -0
@@ -1,17 +1,20 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: usos-api
3
- Version: 0.2.0
3
+ Version: 0.3.1
4
4
  Summary: Asynchronous USOS API for Python
5
5
  Home-page: https://github.com/Antoni-Czaplicki/usos-api
6
6
  Author: Antoni-Czaplicki
7
7
  Author-email: 56671347+Antoni-Czaplicki@users.noreply.github.com
8
- Requires-Python: >=3.12,<4.0
8
+ Requires-Python: >=3.10,<4.0
9
9
  Classifier: Programming Language :: Python :: 3
10
+ Classifier: Programming Language :: Python :: 3.10
11
+ Classifier: Programming Language :: Python :: 3.11
10
12
  Classifier: Programming Language :: Python :: 3.12
11
- Requires-Dist: aiohttp (>=3.9.5,<4.0.0)
12
- Requires-Dist: oauthlib (>=3.2.2,<4.0.0)
13
- Requires-Dist: pydantic (>=2.8.2,<3.0.0)
14
- Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
13
+ Classifier: Programming Language :: Python :: 3.13
14
+ Requires-Dist: aiohttp (>=3.11,<4.0)
15
+ Requires-Dist: oauthlib (>=3.2,<4.0)
16
+ Requires-Dist: pydantic (>=2.10,<3.0)
17
+ Requires-Dist: python-dotenv (>=1.0,<2.0)
15
18
  Project-URL: Documentation, https://usos-api.readthedocs.io
16
19
  Project-URL: Repository, https://github.com/Antoni-Czaplicki/usos-api
17
20
  Description-Content-Type: text/markdown
@@ -1,6 +1,6 @@
1
1
  [tool.poetry]
2
2
  name = "usos-api"
3
- version = "0.2.0"
3
+ version = "0.3.1"
4
4
  description = "Asynchronous USOS API for Python"
5
5
  authors = ["Antoni-Czaplicki <56671347+Antoni-Czaplicki@users.noreply.github.com>"]
6
6
  readme = "README.md"
@@ -9,11 +9,11 @@ repository = "https://github.com/Antoni-Czaplicki/usos-api"
9
9
  documentation = "https://usos-api.readthedocs.io"
10
10
 
11
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"
12
+ python = "^3.10"
13
+ aiohttp = "^3.11"
14
+ pydantic = "^2.10"
15
+ oauthlib = "^3.2"
16
+ python-dotenv = "^1.0"
17
17
 
18
18
  [tool.poetry.group.dev.dependencies]
19
19
  black = "*"
@@ -3,13 +3,16 @@ import json
3
3
  from .connection import USOSAPIConnection
4
4
  from .helper import APIHelper
5
5
  from .logger import get_logger
6
- from .services import UserService
7
- from .services.api_documentation import APIDocumentationService
8
- from .services.api_server import APIServerService
9
- from .services.courses import CourseService
10
- from .services.grades import GradeService
11
- from .services.groups import GroupService
12
- from .services.terms import TermService
6
+ from .services import (
7
+ APIDocumentationService,
8
+ APIServerService,
9
+ CourseService,
10
+ GradeService,
11
+ GroupService,
12
+ RegistrationService,
13
+ TermService,
14
+ UserService,
15
+ )
13
16
 
14
17
  _LOGGER = get_logger("USOSClient")
15
18
 
@@ -21,6 +24,11 @@ class USOSClient:
21
24
  :var UserService user_service: The user service.
22
25
  :var GroupService group_service: The group service.
23
26
  :var APIServerService api_server_service: The API server service.
27
+ :var APIDocumentationService api_documentation_service: The API documentation service.
28
+ :var CourseService course_service: The course service.
29
+ :var TermService term_service: The term service.
30
+ :var GradeService grade_service: The grade service.
31
+ :var RegistrationService registration_service: The registration service.
24
32
 
25
33
  :ivar USOSAPIConnection connection: The connection to the USOS API, used for making requests.
26
34
  """
@@ -45,6 +53,7 @@ class USOSClient:
45
53
  self.grade_service = GradeService(self.connection)
46
54
  self.api_server_service = APIServerService(self.connection)
47
55
  self.api_documentation_service = APIDocumentationService(self.connection)
56
+ self.registration_service = RegistrationService(self.connection)
48
57
 
49
58
  self.helper = APIHelper(self)
50
59
 
@@ -22,18 +22,9 @@ class APIHelper:
22
22
  ects_by_term = await self.client.course_service.get_user_courses_ects()
23
23
  terms = await self.client.term_service.get_terms(list(ects_by_term.keys()))
24
24
  term_ids = [
25
- term.id for term in terms if not current_term_only or term.is_current
26
- ]
27
- course_ids = [
28
- course_id
29
- for term_id in term_ids
30
- for course_id in ects_by_term[term_id].keys()
25
+ term.id for term in terms if not current_term_only or term.is_ongoing
31
26
  ]
32
27
 
33
- courses = {
34
- course.id: course
35
- for course in await self.client.course_service.get_courses(course_ids)
36
- }
37
28
  grades_by_term = await self.client.grade_service.get_grades_by_terms(term_ids)
38
29
 
39
30
  user_grades = []
@@ -47,7 +38,7 @@ class APIHelper:
47
38
  for grade in grades:
48
39
  grade.weight = ects
49
40
  grade.course_edition = CourseEdition(
50
- course=courses[course_id], term=term
41
+ course_id=course_id, term_id=term.id
51
42
  )
52
43
  user_grades.append(grade)
53
44
 
@@ -20,6 +20,14 @@ from .grade import Grade
20
20
  from .group import Group
21
21
  from .lang_dict import LangDict
22
22
  from .programme import Programme, StudentProgramme
23
+ from .registration import (
24
+ CoursesCart,
25
+ Link,
26
+ Registration,
27
+ RegistrationCourse,
28
+ RegistrationRound,
29
+ Stage,
30
+ )
23
31
  from .term import Term
24
32
  from .user import (
25
33
  EmailAccess,
@@ -75,4 +83,10 @@ __all__ = [
75
83
  "APIMethodIndexItem",
76
84
  "APIModuleInfo",
77
85
  "ScopeInfo",
86
+ "Registration",
87
+ "RegistrationRound",
88
+ "RegistrationCourse",
89
+ "Stage",
90
+ "Link",
91
+ "CoursesCart",
78
92
  ]
@@ -1,4 +1,4 @@
1
- from typing import TYPE_CHECKING, Optional
1
+ from typing import TYPE_CHECKING, Any, Optional
2
2
 
3
3
  from pydantic import BaseModel
4
4
 
@@ -65,13 +65,23 @@ class CourseEdition(BaseModel):
65
65
  Class representing a course edition.
66
66
  """
67
67
 
68
- course: Course | None = None
69
- term: Term | None = None
68
+ course_id: str | None = None
69
+ course_name: LangDict | None = None
70
+ term_id: str | None = None
70
71
  homepage_url: str | None = None
72
+ profile_url: str | None = None
73
+ coordinators: list[dict[str, Any]] | None = None
74
+ lecturers: list[dict[str, Any]] | None = None
75
+ passing_status: str | None = None # passed, failed, not_yet_passed
76
+ user_groups: list[Group] | None = None
77
+
71
78
  description: LangDict | None = None
72
79
  bibliography: LangDict | None = None
73
80
  notes: LangDict | None = None
74
- course_units: list[CourseUnit] | None = None
81
+ course_units_ids: list[str] | None = None
82
+ participants: list[dict[str, Any]] | None = None
83
+ grades: list[dict[str, Any]] | None = None
84
+ attributes: list[dict[str, list[LangDict]]] | None = None
75
85
 
76
86
 
77
87
  class CourseEditionConducted(BaseModel):
@@ -0,0 +1,73 @@
1
+ from datetime import datetime
2
+
3
+ from pydantic import BaseModel
4
+
5
+ from usos_api.models import LangDict
6
+ from usos_api.models.course import Course
7
+ from usos_api.models.programme import Programme
8
+ from usos_api.models.term import Term
9
+
10
+
11
+ class Registration(BaseModel):
12
+ id: str | None = None
13
+ description: LangDict | None = None
14
+ message: LangDict | None = None
15
+ type: str | None = None
16
+ status: str | None = None
17
+ faculty: str | None = None
18
+ is_linkage_required: bool | None = None
19
+ www_instance: str | None = None
20
+
21
+ rounds: list["RegistrationRound"] | None = None
22
+ related_courses: list["RegistrationCourse"] | None = None
23
+
24
+
25
+ class RegistrationRound(BaseModel):
26
+ id: str | None = None
27
+ name: LangDict | None = None
28
+ status: str | None = None
29
+ registration_mode: str | None = None
30
+ start_date: datetime | None = None
31
+ end_date: datetime | None = None
32
+ selection_limit: int | None = None
33
+ is_dedicated: bool | None = None
34
+ is_overflow_allowed: bool | None = None
35
+ is_exchange: bool | None = None
36
+ is_only_entitled: bool | None = None
37
+ rank_code: str | None = None
38
+ ranking: dict | None = None
39
+ is_processed: bool | None = None
40
+ registration: Registration | None = None
41
+
42
+
43
+ class RegistrationCourse(BaseModel):
44
+ registration_id: str | None = None
45
+ course_id: str | None = None
46
+ term_id: str | None = None
47
+ status: str | None = None
48
+ limits: dict | None = None
49
+ www_instance: str | None = None
50
+
51
+
52
+ class Stage(BaseModel):
53
+ id: str | None = None
54
+ name: LangDict | None = None
55
+
56
+
57
+ class Link(BaseModel):
58
+ programme: Programme | None = None
59
+ stage: Stage | None = None
60
+
61
+
62
+ class CoursesCart(BaseModel):
63
+ links: list[Link] | None = None
64
+ course: Course | None = None
65
+ term: Term | None = None
66
+ user_registration_status: str | None = None
67
+ is_registration_valid: bool | None = None
68
+ choice_number: int | None = None
69
+ limits: int | None = None
70
+ is_linkage_required: bool | None = None
71
+ registrations_count: int | None = None
72
+ registration_status: str | None = None
73
+ active_registration_round_id: str | None = None
@@ -14,7 +14,7 @@ class Term(BaseModel):
14
14
  is_active: bool | None = None
15
15
 
16
16
  @property
17
- def is_current(self) -> bool:
17
+ def is_ongoing(self) -> bool:
18
18
  """
19
19
  Check if the term is currently active.
20
20
  """
@@ -3,6 +3,7 @@ from .api_server import APIServerService
3
3
  from .courses import CourseService
4
4
  from .grades import GradeService
5
5
  from .groups import GroupService
6
+ from .registrations import RegistrationService
6
7
  from .terms import TermService
7
8
  from .users import UserService
8
9
 
@@ -14,4 +15,5 @@ __all__ = [
14
15
  "GroupService",
15
16
  "TermService",
16
17
  "UserService",
18
+ "RegistrationService",
17
19
  ]
@@ -0,0 +1,84 @@
1
+ from typing import Optional
2
+
3
+ from ..connection import USOSAPIConnection
4
+ from ..models import Course, CourseEdition, Term
5
+
6
+
7
+ class CourseService:
8
+ """
9
+ A service for course-related operations.
10
+ """
11
+
12
+ def __init__(self, connection: USOSAPIConnection):
13
+ """
14
+ Initialize the course service.
15
+
16
+ :param connection: The connection to use.
17
+ """
18
+ self.connection = connection
19
+
20
+ async def get_user_courses_ects(self) -> dict[str, dict[str, float]]:
21
+ """
22
+ Get user courses ECTS.
23
+
24
+ :return: The user courses ECTS.
25
+ """
26
+ response = await self.connection.post("services/courses/user_ects_points")
27
+ return {
28
+ term: {course: float(points) for course, points in courses.items()}
29
+ for term, courses in response.items()
30
+ }
31
+
32
+ async def get_courses(
33
+ self, course_ids: list[str], fields: Optional[list[str]] = None
34
+ ) -> list[Course]:
35
+ """
36
+ Get courses by their IDs.
37
+
38
+ :param course_ids: The IDs of the courses to get.
39
+ :param fields: The fields to include in the response.
40
+ :return: A list of courses.
41
+ """
42
+ if not course_ids:
43
+ return []
44
+
45
+ course_ids_str = "|".join(course_ids)
46
+ fields_str = "|".join(fields) if fields else "id|name"
47
+
48
+ response = await self.connection.post(
49
+ "services/courses/courses", course_ids=course_ids_str, fields=fields_str
50
+ )
51
+
52
+ return [Course(**course_data) for course_data in response.values()]
53
+
54
+ async def get_user_course_editions(
55
+ self,
56
+ active_terms_only: bool = False,
57
+ ongoing_terms_only: bool = False,
58
+ ) -> list[CourseEdition]:
59
+ """
60
+ Get information on user's courses.
61
+
62
+ This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible!
63
+ If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.
64
+
65
+ :param active_terms_only: Return only these course editions which are related to the currently active academic terms. Apparently, this parameter does not always work as expected, so you can use `ongoing_terms_only` instead.
66
+ :param ongoing_terms_only: Return only these course editions which are related to the currently ongoing academic terms (filtered locally based on start and finish dates).
67
+ :return: A dictionary of selected fields and their values.
68
+ """
69
+ params = {
70
+ "fields": "course_editions[course_id|course_name|term_id|homepage_url|profile_url|coordinators|lecturers|passing_status|user_groups|grades|attributes]|terms",
71
+ "active_terms_only": str(active_terms_only).lower(),
72
+ }
73
+
74
+ response = await self.connection.post("services/courses/user", **params)
75
+
76
+ terms = {term["id"]: Term(**term) for term in response["terms"]}
77
+ ongoing_terms = {term_id for term_id, term in terms.items() if term.is_ongoing}
78
+
79
+ return [
80
+ CourseEdition(**course_edition)
81
+ for term_id, course_editions in response["course_editions"].items()
82
+ if not ongoing_terms_only or term_id in ongoing_terms
83
+ for course_edition in course_editions
84
+ ]
@@ -84,6 +84,7 @@ class GradeService:
84
84
  exam_session_number: Grade(**grade)
85
85
  for unit in units
86
86
  for exam_session_number, grade in unit.items()
87
+ if grade
87
88
  }
88
89
  return processed_units_grades
89
90
 
@@ -95,5 +96,8 @@ class GradeService:
95
96
  :return: The processed course grades.
96
97
  """
97
98
  return [
98
- Grade(**grade) for session in course_grades for grade in session.values()
99
+ Grade(**grade)
100
+ for session in course_grades
101
+ for grade in session.values()
102
+ if grade
99
103
  ]
@@ -10,7 +10,7 @@ def _filter_ongoing_terms(terms: list[Term]) -> list[Term]:
10
10
  :param terms: The terms to filter.
11
11
  :return: The ongoing terms.
12
12
  """
13
- return [term for term in terms if term.is_current]
13
+ return [term for term in terms if term.is_ongoing]
14
14
 
15
15
 
16
16
  def _deserialize_term(data: dict) -> Term:
@@ -0,0 +1,112 @@
1
+ from ..connection import USOSAPIConnection
2
+ from ..models import CoursesCart, Registration
3
+
4
+
5
+ class RegistrationService:
6
+ """
7
+ A service for registration-related operations.
8
+ """
9
+
10
+ def __init__(self, connection: USOSAPIConnection):
11
+ """
12
+ Initialize the registration service.
13
+
14
+ :param connection: The connection to use.
15
+ """
16
+ self.connection = connection
17
+
18
+ async def get_user_registrations(
19
+ self, active_only: bool = True, fields: list[str] = None
20
+ ) -> list[Registration]:
21
+ """
22
+ Get user registrations.
23
+
24
+ :param active_only: Whether to return only active registrations.
25
+ :param fields: Selector of result fields you are interested in (optional, default is specified fields).
26
+ :return: The user registrations.
27
+ """
28
+ fields = "|".join(fields) if fields else None
29
+
30
+ response = await self.connection.post(
31
+ "services/registrations/user_registrations",
32
+ fields=fields,
33
+ active_only=active_only,
34
+ )
35
+ return [Registration(**registration) for registration in response]
36
+
37
+ async def get_registration(
38
+ self, registration_id: str, fields: list[str] = None
39
+ ) -> Registration:
40
+ """
41
+ Get a registration.
42
+
43
+ :param registration_id: The ID of the registration.
44
+ :param fields: Selector of result fields you are interested in (optional, default is specified fields).
45
+ :return: The registration.
46
+ """
47
+
48
+ fields = "|".join(fields) if fields else None
49
+
50
+ response = await self.connection.post(
51
+ "services/registrations/registration", id=registration_id, fields=fields
52
+ )
53
+ return Registration(**response)
54
+
55
+ async def register_to_course(
56
+ self,
57
+ round_id: str,
58
+ course_id: str,
59
+ term_id: str,
60
+ user_programme_id: str = None,
61
+ user_stage_id: str = None,
62
+ ) -> dict:
63
+ """
64
+ Register to a course.
65
+
66
+ :param round_id: Registration round ID.
67
+ :param course_id: Course code.
68
+ :param term_id: Cycle code.
69
+ :param user_programme_id: User program ID (optional).
70
+ :param user_stage_id: User stage ID (optional).
71
+ :return: Empty dict on success.
72
+ """
73
+ data = {
74
+ "round_id": round_id,
75
+ "course_id": course_id,
76
+ "term_id": term_id,
77
+ }
78
+ if user_programme_id:
79
+ data["user_programme_id"] = user_programme_id
80
+ if user_stage_id:
81
+ data["user_stage_id"] = user_stage_id
82
+
83
+ response = await self.connection.post("services/registrations/register", **data)
84
+ return response
85
+
86
+ async def get_courses_cart(self, fields: list[str] = None) -> list[CoursesCart]:
87
+ """
88
+ Get user courses cart with registrations information.
89
+
90
+ :param fields: Selector of result fields you are interested in (optional, default is specified fields).
91
+ :return: A CoursesCartResponse object.
92
+ """
93
+ if fields is None:
94
+ fields = [
95
+ "links",
96
+ "course",
97
+ "term",
98
+ "user_registration_status",
99
+ "is_registration_valid",
100
+ "choice_number",
101
+ "limits",
102
+ "is_linkage_required",
103
+ "registrations_count",
104
+ "registration_status",
105
+ "active_registration_round_id",
106
+ ]
107
+ fields = "|".join(fields)
108
+
109
+ response = await self.connection.post(
110
+ "services/registrations/courses_cart", fields=fields
111
+ )
112
+ return [CoursesCart(**course) for course in response]
@@ -1,52 +0,0 @@
1
- from typing import Optional
2
-
3
- from ..connection import USOSAPIConnection
4
- from ..models import Course
5
-
6
-
7
- class CourseService:
8
- """
9
- A service for course-related operations.
10
- """
11
-
12
- def __init__(self, connection: USOSAPIConnection):
13
- """
14
- Initialize the course service.
15
-
16
- :param connection: The connection to use.
17
- """
18
- self.connection = connection
19
-
20
- async def get_user_courses_ects(self) -> dict[str, dict[str, float]]:
21
- """
22
- Get user courses ECTS.
23
-
24
- :return: The user courses ECTS.
25
- """
26
- response = await self.connection.post("services/courses/user_ects_points")
27
- return {
28
- term: {course: float(points) for course, points in courses.items()}
29
- for term, courses in response.items()
30
- }
31
-
32
- async def get_courses(
33
- self, course_ids: list[str], fields: Optional[list[str]] = None
34
- ) -> list[Course]:
35
- """
36
- Get courses by their IDs.
37
-
38
- :param course_ids: The IDs of the courses to get.
39
- :param fields: The fields to include in the response.
40
- :return: A list of courses.
41
- """
42
- if not course_ids:
43
- return []
44
-
45
- course_ids_str = "|".join(course_ids)
46
- fields_str = "|".join(fields) if fields else "id|name"
47
-
48
- response = await self.connection.post(
49
- "services/courses/courses", course_ids=course_ids_str, fields=fields_str
50
- )
51
-
52
- return [Course(**course_data) for course_data in response.values()]
File without changes
File without changes
File without changes
File without changes