README.md 2.97 KB
Newer Older
Alex Constantin-Gómez's avatar
Alex Constantin-Gómez committed
1
2
# imperial_doc_materials

Alex's avatar
Alex committed
3
4
5
6
7
8
9
10
11
12
13
14
15
Python client for the [Materials API](https://api-materials.doc.ic.ac.uk/) in DoC.

## Setup

Add this code to your Flask's ```app.py``` if not done already (it should already be present in the Flask template):

```python
# Add integration to the Materials API
import imperial_doc_materials
imperial_doc_materials.init_app(app)
imperial_doc_materials.set_redirect_url('auth.login')
```

Alex's avatar
Alex committed
16
17
The ```set_redirect_url()``` method should take the route name of your login page.

Alex's avatar
Alex committed
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
## Using the Materials API in a Flask route

Again, there are examples of this in the template. You must use the ```@using_materials``` decorator before the route function definition. This will give you access to a ```Materials``` client object which you can use to make requests.

```python
@home_blueprint.route('')
@login_required     # Indicate that the user must be logged in (via LDAP)
@using_materials    # Indicate that we want to access the Materials API
def dashboard(materials_client, user):    
    my_courses = materials_client.get_courses_for_year("2122")
    return render_template('dashboard.html', user=user, my_courses=my_courses)
```

**Important:** if using other decorators such as ```@login_required``` provided by the [imperial_ldap package](https://gitlab.doc.ic.ac.uk/paas-packages/imperial_ldap), the parameters to the function appear in inverse order. For example, in the code above, the login decorator appears first, so the ```user``` parameter provided by it goes last.

Alex's avatar
Alex committed
33
34
35
36
37
38
39
40
41
42
## Creating a client at login

In you login route, you should create a client for the logged in user by passing in the username and password. This will create a Materials client in the session:

```python
from imperial_doc_materials import materials_login

materials_login(username, password)
```

Alex's avatar
Alex committed
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
## The API

### ```Materials``` class:

- Creating a new client given a username and password:

    ```client = Materials.create_client(username, password)```

- Getting the list of enrolled ```Course```s given an academic year (of the form "2122"):

    ```courses = client.get_courses_for_year(academic_year)```

- Getting the list of all the ```Resource```s that are available for a given academic year:

    ```resources = client.get_resources_for_year(academic_year)```

### ```Course``` class:

The available fields of a ```Course``` instance are:

- ```title``` (string): the full name of the course
- ```code``` (string): the code of the course
- ```has_materials``` (bool): whether the course has any materials uploaded
- ```resources``` (List[Resource]): a list of all the ```Resource```s for that course

### ```Resource``` class:

The available fields of a ```Resource``` instance are:

- ```id``` (int): the internal DoC ID of the uploaded resource
- ```title``` (string): the name of the resource
- ```type``` (string): if the course is a "file" or a "link"
- ```category``` (string): the category of the resource
- ```url``` (string): the URL to the resource
- ```course_code``` (string): the code of the corresponding course