Metadata-Version: 2.1
Name: wimsapi
Version: 0.5.11
Summary: A Python 3 implementation of WIMS adm/raw module.
Home-page: https://github.com/qcoumes/wimsapi
Author: Coumes Quentin
Author-email: coumes.quentin@gmail.com
License: UNKNOWN
Description: [![Python package](https://github.com/qcoumes/wimsapi/workflows/Python%20package/badge.svg)](https://github.com/qcoumes/wimsapi/actions/)
        [![codecov](https://codecov.io/gh/qcoumes/wimsapi/branch/master/graph/badge.svg)](https://codecov.io/gh/qcoumes/wimsapi)
        [![CodeFactor](https://www.codefactor.io/repository/github/qcoumes/wimsapi/badge)](https://www.codefactor.io/repository/github/qcoumes/wimsapi)
        [![Documentation Status](https://readthedocs.org/projects/wimsapi/badge/?version=master)](https://wimsapi.readthedocs.io/?badge=master)
        [![PyPI Version](https://badge.fury.io/py/wimsapi.svg)](https://badge.fury.io/py/wimsapi)
        [![Python 3.5+](https://img.shields.io/badge/python-3.5+-brightgreen.svg)](#)
        [![License MIT](https://img.shields.io/badge/license-MIT-brightgreen.svg)](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
        ```
        
        
        ______
        
        # 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.
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Description-Content-Type: text/markdown
