1
2
3
4
5
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
|
[](https://github.com/qcoumes/wimsapi/actions/)
[](https://codecov.io/gh/qcoumes/wimsapi)
[](https://www.codefactor.io/repository/github/qcoumes/wimsapi)
[](https://wimsapi.readthedocs.io/?badge=master)
[](https://badge.fury.io/py/wimsapi)
[](#)
[](https://github.com/qcoumes/wimsapi/blob/master/LICENSE)
# Python API for WIMS' adm/raw module
**WimsAPI** is an API written in python3 allowing to communicate with a *WIMS*
server through its *adm/raw* extension.
For more information about *adm/raw*,
[see its documentation](https://wims.auto.u-psud.fr/wims/wims.cgi?module=adm/raw&job=help)
Here the [documentation of wimsapi](https://wimsapi.readthedocs.io/en/latest/).
## Installation
The latest stable version is available on [PyPI](https://pypi.org/project/wimsapi/) :
```bash
pip install wimsapi
```
or from the sources:
```bash
git clone https://github.com/qcoumes/wimsapi
cd wimsapi
python3 setup.py install
```
## Configuration
### Global configuration
In order for *WIMS* to accept requests from **WimsAPI**,
a file must be created in `[WIMS_HOME]/log/classes/.connections/`,
the file's name will serve as the identifier name for **WimsAPI**.
Here an exemple of such file:
`[WIMS_HOME]/log/classes/.connections/myself`
```
ident_site=172.17.0.1
ident_desc=This WIMS server
ident_agent=python-requests
# http / https.
ident_protocol=http
# password must be a word composed of alpha-numeric characters.
ident_password=toto
ident_type=json
# The address and identifier/password pair for calling back.
back_url=http://localhost/wims/wims.cgi
back_ident=myself
back_password=toto
```
Here a description of the important parameters:
* `ident_site`: a space separated list of IP allowed to send request to this
*WIMS* server.
* `ident_agent`: ***Must*** be set to `python-requests`.
* `ident_password`: Used alongside the file's name as *identifier* in the request
to authenticate yourself on *WIMS*.
* `ident_type`: ***Must*** be set to `json`.
The above example would allow a computer/server of ip `172.17.0.1` to send a request
to the *WIMS* server with identifier *myself* and password *toto*.
### Class Configuration
If you create a class thanks to this API, everything should work perfectly.
However, if you want to use it with an already existing class, some more
configuration must be done.
You must edit the file `[WIMS_HOME]/log/classes/[CLASS_ID]/.def` and add
this line at the end of the file:
```
!set class_connections=+IDENT/RCLASS+
```
Where **IDENT** is the identifier use by the API (name of the corresponding
file in `[WIMS_HOME]/log/classes/.connections/` as defined above) and
**RCLASS** is an identifier sent in the request to authenticate yourself
on the class.
Basically, to authenticate yourself on a class on your *WIMS* server, you
will need :
* `url` : URL to the *WIMS* (`https://wims.unice.fr/wims/wims.cgi` for instance)
* `ident` : Name of the file in `[WIMS_HOME]/log/classes/.connections/`
* `passwd` : Value of `ident_password` in
`[WIMS_HOME]/log/classes/.connections/[IDENT]`
* `rclass` : Value set after the **/** in `class_connections` in
`[WIMS_HOME]/log/classes/[CLASS_ID]/.def`
## Example
```python
from wimsapi import Class, User
c = Class.get("https://wims.unice.fr/wims/wims.cgi", "myself", "toto", 9999, "myclass")
c.institution = "Another institution" # Modify class' institution
c.save()
u = User.get(c, "qcoumes")
u.email = "coumes.quentin@gmail.com" # Modify user's email
u.save()
new = User("quser", "lastname", "firstname", "password", "mail@mail.com")
c.additem(new) # Add the new user to the class.
```
For more informations about usage or example : Here the complete [documentation of wimsapi](https://wimsapi.readthedocs.io/en/latest/).
## Testing
To test *wimsapi*, you will need a running WIMS' server. If needed, you can set up one quickly with docker using the DockerFile [here](https://github.com/qcoumes/docker-wims-minimal), following the *README* steps.
The default URL used for tests is `http://localhost:7777/wims/wims.cgi`, you can override it with the environment variable `WIMS_URL`. For instance:
```bash
WIMS_URL=http://mywims.com/wims/wims.cgi pytest
```
|
