wimsapi 0.5.11

Description:

wimsapi 0.5.11

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
Here the documentation of wimsapi.
Installation
The latest stable version is available on PyPI :
pip install wimsapi

or from the sources:
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
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 = "[email protected]" # Modify user's email
u.save()

new = User("quser", "lastname", "firstname", "password", "[email protected]")
c.additem(new) # Add the new user to the class.

For more informations about usage or example : Here the complete documentation of wimsapi.
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, 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:
WIMS_URL=http://mywims.com/wims/wims.cgi pytest


Changelog
0.5.11

api.WimsAPI.authuser now accept an ip argument, allowing a persistent session for the
same IP. (Contributed by Gianluca Amato)

0.5.10

WIMS accept request saving user with invalid quser, removing or changing
invalid character. But wimsapi was taking this change into account, the quser
attribute of the user was thus invalid, causing problem when further communicating with
the WIMS server.
To solve this problem User.save() now has a adapt=True keyword argument. When True,
the quser attribute will be modified to match the one used by WIMS. If False, the
user created on the WIMS server with the modifier quser will be deleted and the new
exception InvalidIdentifier will be raised.

0.5.9

Keyword argument that will be passed to every call of request.post() can now
be given to WimsApi constructor.
Every method of Class creating a WimsAPI can also receive such argument
(check(), save(), get(), list())
Now use sdist instead of bdist to create new distribution.

0.5.8

Now use Github action for testing and publishing

0.5.7

Added __str__ method to InvalidResponseError.

0.5.6

Added response field to InvalidResponseError.

0.5.5

Added InvalidResponseError exception in api.py when WIMS send a badly formatted response.

O.5.4


Append / at the end of the WIMS server's url if it is not present when using
WimsAPI.


Added adm/raw API to the documentation.


0.5.3

Default timeout for low level API is now 10 seconds (instead of 120).

0.5.2


Parameters of api.py requests are now encoding in ISO-8859-1, mathching WIMS'
default encoding


Adding __repr__ and __str__ method to Class and Item subtypes.


Getting Exams from the WIMS server now retrieve the correct status.


0.5.1

Fix sheet's score computation

0.5.0


Added classes Exam and ExamScore, ExerciseScore and SheetScore
to store scores


Sheet / Exam:

Title and description are now optionnal in constructor.
Added method scores(user=None) to retrieve the score of one or every user.



Added class method check() to Class to check wheter a class exists or not.


Better __eq__ and __hash__ for every class.


0.4.1

Listing functions now return an empty list when needed

0.4.0

Added new item : Sheet
Added the possibility to list items and classes through Class.list() and
class.listitem().
Added __eq__() for items and classes.
Fixed some documentation

0.3.9

Renamed Class member date to expiration to match the ADM/RAW argument.
Class.limit is now an int when retrieving the class from a WIMS server.
Now propagate exception if expiration in Class __init__ is not yyyymmdd.

0.3.7 & 0.3.8

check_exists is now used properly

0.3.6

Added check_exists=True parameter to item's save method.
If check_exists is True, the api will check if an item with the same ID
exists on the WIMS' server. If it exists, save will instead modify this
item instead of trying to create new one.
wclass.additem() will now use check_exists=False.
Fix response check in wclass.save()

0.3.5

Fix missing self.lang = lang in Class' __init__

0.3.4

Fix long_description in setup.py

0.3.3

qclass argument is now optionnal in Class constructor,
allowing WIMS to choose a free qclass when saving for
the fist time.

0.3.2

Fixed WimsAPI.putexo().
Updated tests and unskipped some according to latest WIMS version.

0.3.1

Fixed buggy import in setup.py

0.3.0

Adding Classe higher level API, allowing to manipulate a WIMS' Class.
Adding User higher level API, allowing to manipulate a WIMS' User.
Adding documentation.

0.2.2

More tests.

0.2.1

Fixed travis CI.

0.2.0

Add User and Class higher level classes.
Add some tests fomr WimsApi.
Add Travis CI.

0.1.0

Initial public release.