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
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
|
.. IVLE - Informatics Virtual Learning Environment
Copyright (C) 2007-2009 The University of Melbourne
.. This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
.. This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
.. You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
.. _ref-dev-faq:
**************************
Frequently Asked Questions
**************************
This is a list of Frequently Asked Questions for IVLE developers. It answers
questions about common issues encountered when bludgeoning the system into
behaving.
.. _ref-dev-faq-how:
How can I...
============
.. _ref-dev-faq-config:
... get data out of the IVLE configuration?
-------------------------------------------
::
from ivle.config import Config
config = Config()
This makes `config`, a dictionary-tree containing the whole config hierarchy.
For example, to get the Subversion repository path, use
``config['paths']['svn']['repo_path']``.
.. note::
For code running inside the jail, you will see different configuration
variables than code running outside. It will be missing a lot of data, and
will contain some user-specific data.
... restrict permission to different views?
-------------------------------------------
In all views derived from ``BaseView`` the ``authorize`` function is called to
check if a user has access to a particular file. Often this is simply a check
to ensure that the user is logged in (the value of 'user' is not None), but
may be more complex such as checking if a user has a password hash set (to
prevent clobbering of external auth) or checking if a user has permission to
edit an ``Offering`` object.
Database
========
How can I...
------------
IVLE exclusively uses the `Storm`_ API for database access. Do not write any
SQL code yourself, or make use of low-level database libraries. The only
exception is in preparing the database schema, which is stored as an SQL file.
.. _Storm: https://storm.canonical.com/
... update the database schema?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Modify :file:`userdb/users.sql`. Any changes also need to be made in to a
migrations file, in :file:`userdb/migrations/`.
TODO: More detail on migrations.
.. _ref-dev-faq-read-data:
... read data from the database?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
import ivle.database
# Typically, you import all database classes you want here
from ivle.database import User
You need a `store` object to perform any interactions with the database. If
you are inside the web app, get a hold of the `req` (request) object, and use
``req.store``. In other code, create a new store as follows (where `config` is
a :ref:`config <ref-dev-faq-config>` object)::
store = ivle.database.get_store(config)
You can read objects out of the database through the store. For example, to
get a User object::
user = store.find(User, User.login==username).one()
(Note that ``store.find(User)`` just returns a sequence of all users.)
You can then treat `user` as a normal object, and read from its attributes.
All of the classes are defined in ``ivle/database.py``.
.. note::
The code must be executed outside of the jail. Jail code runs under user
privileges and cannot access the database.
.. note::
For help with the database API, see the `Storm`_ documentation.
... write data to the database?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Get an object out of the database, as :ref:`above <ref-dev-faq-read-data>`,
and simply write to the object's attributes. This updates the *in-memory* copy
of the data only.
To write the changes back to the database, simply use::
store.commit()
using the same store object as used to retrieve the object in the first place.
... insert a new object into the database?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Create the new object using its constructor, as with any Python object. e.g.::
import ivle.database
user = ivle.database.User()
You can then set the attributes of the object as desired. As with writing,
this only creates an *in-memory* object.
To add the object to the database, get a :ref:`store <ref-dev-faq-read-data>`,
and use::
store.add(user)
store.commit()
... modify user capabilities or privileges?
-------------------------------------------
User privileges are set by the ``get_permissions`` functions in
``ivle/database.py``. Permissions are highly granular and can be set on almost
every object in the database.
Most permissions are set on the ``Offering`` level with ``ProjectSet``,
``Project`` and ``Worksheet`` simply delegating the check to ``Offering``.
Since ``Exercise`` may be shared between multiple ``Offerings``, the
permissions are calculated from the users active enrollments. Other objects
such as ``User`` may only be modified by the user or an admin. If a user is
not logged in (user is None) then they will typically receive no privileges at
all.
Where do I find...
------------------
.. This is for finding obscure things in the code.
... the class definitions for database objects?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
All of the classes are defined in ``ivle/database.py``.
What does "TypeError: Expected unicode, found <type 'str'>" mean?
-----------------------------------------------------------------
All string data going into and out of Storm (i.e., the IVLE database classes)
must be a Unicode string (type :class:`unicode`), not a regular byte string
(type :class:`str`). If you have a regular string, convert it to Unicode by
wrapping it in the :func:`unicode` function. For example::
username = unicode(username)
Subversion
==========
How can I...
------------
... get the local file path to a user's Subversion repo?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Get a :ref:`config <ref-dev-faq-config>` object, and use ::
repopath = os.path.join(config['paths']['svn']['repo_path'],
'users', username)
(This should probably be abstracted.)
... get the http:// URL for a user's Subversion repo?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Get a :ref:`config <ref-dev-faq-config>` object, and use ::
repourl = config['urls']['svn_addr'] + '/users/' + username
(This should probably be abstracted.)
... get a Subversion client from Python?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
import ivle.svn
svnclient = ivle.svn.create_auth_svn_client(username, password)
If you don't have any auth credentials and you just want to do SVN things
which don't require auth (though I don't see why this situation would arise),
you can get an auth-less SVN client, which will raise exceptions if you try to
do authy things (e.g., commit, update or checkout)::
import pysvn
svnclient = pysvn.Client()
In either case, the client object will raise `pysvn.ClientError` objects, so
you should be handling those.
You may wish to make error messages simpler using this line::
svnclient.exception_style = 0
A good example of Subversion client code is in
``ivle/fileservice_lib/action.py``.
.. _ref-dev-faq-where:
|