← Back to branch summary

~azzar1/unity/add-show-desktop-key

« back to all changes in this revision

Viewing changes to doc/dev/faq.rst

  • Committer: mattgiuca
  • Date: 2008-02-18 00:32:43 UTC
  • Revision ID: svn-v3-trunk0:2b9c9e99-6f39-0410-b283-7f802c844ae2:trunk:487
setup.py: Added code to convert usrmgt_port into an int before writing to conf
    (and checking). Same as db_port.
userservice: Now uses config'd values for usrmgt settings instead of
    hard-coded.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/dev/faq.rst
1
 
.. IVLE - Informatics Virtual Learning Environment
2
 
   Copyright (C) 2007-2009 The University of Melbourne
3
 
 
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.
8
 
 
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.
13
 
 
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
17
 
 
18
 
.. _ref-dev-faq:
19
 
 
20
 
**************************
21
 
Frequently Asked Questions
22
 
**************************
23
 
 
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
26
 
behaving.
27
 
 
28
 
.. _ref-dev-faq-how:
29
 
 
30
 
How can I...
31
 
============
32
 
 
33
 
.. _ref-dev-faq-config:
34
 
 
35
 
... get data out of the IVLE configuration?
36
 
-------------------------------------------
37
 
 
38
 
::
39
 
 
40
 
    from ivle.config import Config
41
 
    config = Config()
42
 
 
43
 
This makes `config`, a dictionary-tree containing the whole config hierarchy.
44
 
 
45
 
For example, to get the Subversion repository path, use
46
 
``config['paths']['svn']['repo_path']``.
47
 
 
48
 
.. note::
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.
52
 
 
53
 
... restrict permission to different views?
54
 
-------------------------------------------
55
 
 
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.
62
 
 
63
 
Database
64
 
========
65
 
 
66
 
How can I...
67
 
------------
68
 
 
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.
72
 
 
73
 
.. _Storm: https://storm.canonical.com/
74
 
 
75
 
... update the database schema?
76
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
77
 
 
78
 
Modify :file:`userdb/users.sql`. Any changes also need to be made in to a
79
 
migrations file, in :file:`userdb/migrations/`.
80
 
 
81
 
TODO: More detail on migrations.
82
 
 
83
 
.. _ref-dev-faq-read-data:
84
 
 
85
 
... read data from the database?
86
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
87
 
 
88
 
::
89
 
 
90
 
    import ivle.database
91
 
    # Typically, you import all database classes you want here
92
 
    from ivle.database import User
93
 
 
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)::
98
 
 
99
 
    store = ivle.database.get_store(config)
100
 
 
101
 
You can read objects out of the database through the store. For example, to
102
 
get a User object::
103
 
 
104
 
    user = store.find(User, User.login==username).one()
105
 
 
106
 
(Note that ``store.find(User)`` just returns a sequence of all users.)
107
 
 
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``.
110
 
 
111
 
.. note::
112
 
   The code must be executed outside of the jail. Jail code runs under user
113
 
   privileges and cannot access the database.
114
 
 
115
 
.. note::
116
 
   For help with the database API, see the `Storm`_ documentation.
117
 
 
118
 
... write data to the database?
119
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
120
 
 
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
123
 
of the data only.
124
 
 
125
 
To write the changes back to the database, simply use::
126
 
 
127
 
    store.commit()
128
 
 
129
 
using the same store object as used to retrieve the object in the first place.
130
 
 
131
 
... insert a new object into the database?
132
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
133
 
 
134
 
Create the new object using its constructor, as with any Python object. e.g.::
135
 
 
136
 
    import ivle.database
137
 
    user = ivle.database.User()
138
 
 
139
 
You can then set the attributes of the object as desired. As with writing,
140
 
this only creates an *in-memory* object.
141
 
 
142
 
To add the object to the database, get a :ref:`store <ref-dev-faq-read-data>`,
143
 
and use::
144
 
 
145
 
    store.add(user)
146
 
    store.commit()
147
 
 
148
 
... modify user capabilities or privileges?
149
 
-------------------------------------------
150
 
 
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.
154
 
 
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 
161
 
all.
162
 
 
163
 
Where do I find...
164
 
------------------
165
 
 
166
 
.. This is for finding obscure things in the code.
167
 
 
168
 
... the class definitions for database objects?
169
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
170
 
 
171
 
All of the classes are defined in ``ivle/database.py``.
172
 
 
173
 
What does "TypeError: Expected unicode, found <type 'str'>" mean?
174
 
-----------------------------------------------------------------
175
 
 
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::
180
 
 
181
 
    username = unicode(username)
182
 
 
183
 
Subversion
184
 
==========
185
 
 
186
 
How can I...
187
 
------------
188
 
 
189
 
... get the local file path to a user's Subversion repo?
190
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
191
 
 
192
 
Get a :ref:`config <ref-dev-faq-config>` object, and use ::
193
 
 
194
 
    repopath = os.path.join(config['paths']['svn']['repo_path'],
195
 
                            'users', username)
196
 
 
197
 
(This should probably be abstracted.)
198
 
 
199
 
... get the http:// URL for a user's Subversion repo?
200
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
201
 
 
202
 
Get a :ref:`config <ref-dev-faq-config>` object, and use ::
203
 
 
204
 
    repourl = config['urls']['svn_addr'] + '/users/' + username
205
 
 
206
 
(This should probably be abstracted.)
207
 
 
208
 
... get a Subversion client from Python?
209
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
210
 
 
211
 
::
212
 
 
213
 
    import ivle.svn
214
 
    svnclient = ivle.svn.create_auth_svn_client(username, password)
215
 
 
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)::
220
 
 
221
 
    import pysvn
222
 
    svnclient = pysvn.Client()
223
 
 
224
 
In either case, the client object will raise `pysvn.ClientError` objects, so
225
 
you should be handling those.
226
 
 
227
 
You may wish to make error messages simpler using this line::
228
 
 
229
 
    svnclient.exception_style = 0
230
 
 
231
 
A good example of Subversion client code is in
232
 
``ivle/fileservice_lib/action.py``.
233
 
 
234
 
.. _ref-dev-faq-where: