1
.. IVLE - Informatics Virtual Learning Environment
2
Copyright (C) 2007-2009 The University of Melbourne
4
.. This program is free software; you can redistribute it and/or modify
5
it under the terms of the GNU General Public License as published by
6
the Free Software Foundation; either version 2 of the License, or
7
(at your option) any later version.
9
.. This program is distributed in the hope that it will be useful,
10
but WITHOUT ANY WARRANTY; without even the implied warranty of
11
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12
GNU General Public License for more details.
14
.. You should have received a copy of the GNU General Public License
15
along with this program; if not, write to the Free Software
16
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
20
**************************
21
Frequently Asked Questions
22
**************************
24
This is a list of Frequently Asked Questions for IVLE developers. It answers
25
questions about common issues encountered when bludgeoning the system into
33
.. _ref-dev-faq-config:
35
... get data out of the IVLE configuration?
36
-------------------------------------------
40
from ivle.config import Config
43
This makes `config`, a dictionary-tree containing the whole config hierarchy.
45
For example, to get the Subversion repository path, use
46
``config['paths']['svn']['repo_path']``.
49
For code running inside the jail, you will see different configuration
50
variables than code running outside. It will be missing a lot of data, and
51
will contain some user-specific data.
53
... restrict permission to different views?
54
-------------------------------------------
56
In all views derived from ``BaseView`` the ``authorize`` function is called to
57
check if a user has access to a particular file. Often this is simply a check
58
to ensure that the user is logged in (the value of 'user' is not None), but
59
may be more complex such as checking if a user has a password hash set (to
60
prevent clobbering of external auth) or checking if a user has permission to
61
edit an ``Offering`` object.
69
IVLE exclusively uses the `Storm`_ API for database access. Do not write any
70
SQL code yourself, or make use of low-level database libraries. The only
71
exception is in preparing the database schema, which is stored as an SQL file.
73
.. _Storm: https://storm.canonical.com/
75
... update the database schema?
76
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
78
Modify :file:`userdb/users.sql`. Any changes also need to be made in to a
79
migrations file, in :file:`userdb/migrations/`.
81
TODO: More detail on migrations.
83
.. _ref-dev-faq-read-data:
85
... read data from the database?
86
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
91
# Typically, you import all database classes you want here
92
from ivle.database import User
94
You need a `store` object to perform any interactions with the database. If
95
you are inside the web app, get a hold of the `req` (request) object, and use
96
``req.store``. In other code, create a new store as follows (where `config` is
97
a :ref:`config <ref-dev-faq-config>` object)::
99
store = ivle.database.get_store(config)
101
You can read objects out of the database through the store. For example, to
104
user = store.find(User, User.login==username).one()
106
(Note that ``store.find(User)`` just returns a sequence of all users.)
108
You can then treat `user` as a normal object, and read from its attributes.
109
All of the classes are defined in ``ivle/database.py``.
112
The code must be executed outside of the jail. Jail code runs under user
113
privileges and cannot access the database.
116
For help with the database API, see the `Storm`_ documentation.
118
... write data to the database?
119
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
121
Get an object out of the database, as :ref:`above <ref-dev-faq-read-data>`,
122
and simply write to the object's attributes. This updates the *in-memory* copy
125
To write the changes back to the database, simply use::
129
using the same store object as used to retrieve the object in the first place.
131
... insert a new object into the database?
132
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
134
Create the new object using its constructor, as with any Python object. e.g.::
137
user = ivle.database.User()
139
You can then set the attributes of the object as desired. As with writing,
140
this only creates an *in-memory* object.
142
To add the object to the database, get a :ref:`store <ref-dev-faq-read-data>`,
148
... modify user capabilities or privileges?
149
-------------------------------------------
151
User privileges are set by the ``get_permissions`` functions in
152
``ivle/database.py``. Permissions are highly granular and can be set on almost
153
every object in the database.
155
Most permissions are set on the ``Offering`` level with ``ProjectSet``,
156
``Project`` and ``Worksheet`` simply delegating the check to ``Offering``.
157
Since ``Exercise`` may be shared between multiple ``Offerings``, the
158
permissions are calculated from the users active enrollments. Other objects
159
such as ``User`` may only be modified by the user or an admin. If a user is
160
not logged in (user is None) then they will typically receive no privileges at
166
.. This is for finding obscure things in the code.
168
... the class definitions for database objects?
169
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
171
All of the classes are defined in ``ivle/database.py``.
173
What does "TypeError: Expected unicode, found <type 'str'>" mean?
174
-----------------------------------------------------------------
176
All string data going into and out of Storm (i.e., the IVLE database classes)
177
must be a Unicode string (type :class:`unicode`), not a regular byte string
178
(type :class:`str`). If you have a regular string, convert it to Unicode by
179
wrapping it in the :func:`unicode` function. For example::
181
username = unicode(username)
189
... get the local file path to a user's Subversion repo?
190
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
192
Get a :ref:`config <ref-dev-faq-config>` object, and use ::
194
repopath = os.path.join(config['paths']['svn']['repo_path'],
197
(This should probably be abstracted.)
199
... get the http:// URL for a user's Subversion repo?
200
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
202
Get a :ref:`config <ref-dev-faq-config>` object, and use ::
204
repourl = config['urls']['svn_addr'] + '/users/' + username
206
(This should probably be abstracted.)
208
... get a Subversion client from Python?
209
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
214
svnclient = ivle.svn.create_auth_svn_client(username, password)
216
If you don't have any auth credentials and you just want to do SVN things
217
which don't require auth (though I don't see why this situation would arise),
218
you can get an auth-less SVN client, which will raise exceptions if you try to
219
do authy things (e.g., commit, update or checkout)::
222
svnclient = pysvn.Client()
224
In either case, the client object will raise `pysvn.ClientError` objects, so
225
you should be handling those.
227
You may wish to make error messages simpler using this line::
229
svnclient.exception_style = 0
231
A good example of Subversion client code is in
232
``ivle/fileservice_lib/action.py``.
234
.. _ref-dev-faq-where:
added
removed
doc/dev/faq.rst
