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.
59
IVLE exclusively uses the `Storm`_ API for database access. Do not write any
60
SQL code yourself, or make use of low-level database libraries. The only
61
exception is in preparing the database schema, which is stored as an SQL file.
63
.. _Storm: https://storm.canonical.com/
65
... update the database schema?
66
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
68
Modify :file:`userdb/users.sql`. Any changes also need to be made in to a
69
migrations file, in :file:`userdb/migrations/`.
71
TODO: More detail on migrations.
73
.. _ref-dev-faq-read-data:
75
... read data from the database?
76
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
81
# Typically, you import all database classes you want here
82
from ivle.database import User
84
You need a `store` object to perform any interactions with the database. If
85
you are inside the web app, get a hold of the `req` (request) object, and use
86
``req.store``. In other code, create a new store as follows (where `config` is
87
a :ref:`config <ref-dev-faq-config>` object)::
89
store = ivle.database.get_store(config)
91
You can read objects out of the database through the store. For example, to
94
user = store.find(User, User.login==username).one()
96
(Note that ``store.find(User)`` just returns a sequence of all users.)
98
You can then treat `user` as a normal object, and read from its attributes.
99
All of the classes are defined in ``ivle/database.py``.
102
The code must be executed outside of the jail. Jail code runs under user
103
privileges and cannot access the database.
106
For help with the database API, see the `Storm`_ documentation.
108
... write data to the database?
109
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
111
Get an object out of the database, as :ref:`above <ref-dev-faq-read-data>`,
112
and simply write to the object's attributes. This updates the *in-memory* copy
115
To write the changes back to the database, simply use::
119
using the same store object as used to retrieve the object in the first place.
121
... insert a new object into the database?
122
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
124
Create the new object using its constructor, as with any Python object. e.g.::
127
user = ivle.database.User()
129
You can then set the attributes of the object as desired. As with writing,
130
this only creates an *in-memory* object.
132
To add the object to the database, get a :ref:`store <ref-dev-faq-read-data>`,
141
.. This is for finding obscure things in the code.
143
... the class definitions for database objects?
144
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
146
All of the classes are defined in ``ivle/database.py``.
148
What does "TypeError: Expected unicode, found <type 'str'>" mean?
149
-----------------------------------------------------------------
151
All string data going into and out of Storm (i.e., the IVLE database classes)
152
must be a Unicode string (type :class:`unicode`), not a regular byte string
153
(type :class:`str`). If you have a regular string, convert it to Unicode by
154
wrapping it in the :func:`unicode` function. For example::
156
username = unicode(username)
164
... get the local file path to a user's Subversion repo?
165
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
167
Get a :ref:`config <ref-dev-faq-config>` object, and use ::
169
repopath = os.path.join(config['paths']['svn']['repo_path'],
172
(This should probably be abstracted.)
174
... get the http:// URL for a user's Subversion repo?
175
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
177
Get a :ref:`config <ref-dev-faq-config>` object, and use ::
179
repourl = config['urls']['svn_addr'] + '/users/' + username
181
(This should probably be abstracted.)
183
... get a Subversion client from Python?
184
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
189
svnclient = ivle.svn.create_auth_svn_client(username, password)
191
If you don't have any auth credentials and you just want to do SVN things
192
which don't require auth (though I don't see why this situation would arise),
193
you can get an auth-less SVN client, which will raise exceptions if you try to
194
do authy things (e.g., commit, update or checkout)::
197
svnclient = pysvn.Client()
199
In either case, the client object will raise `pysvn.ClientError` objects, so
200
you should be handling those.
202
You may wish to make error messages simpler using this line::
204
svnclient.exception_style = 0
206
A good example of Subversion client code is in
207
``ivle/fileservice_lib/action.py``.
209
.. _ref-dev-faq-where:
added
removed
doc/dev/faq.rst
