~aelkner/schooltool/cambodia_fixes : revision 2

1

SchoolTool

2

==========

3

4

SchoolTool - a common information systems platform for school administration.

5

6

Website: http://www.schooltool.org/

7

8

Mailing list: http://lists.schooltool.org/mailman/listinfo/schooltool

9

10

Bug tracker: http://issues.schooltool.org/

11

12

13

Overview

14

--------

15

16

SchoolTool is an open source school management information system. It is

17

a distributed client/server system. The SchoolTool server presents two

18

interfaces to clients:

19

20

- a traditional web application interface, usable with an ordinary browser.

21

22

- HTTP-based programming interface suitable for fat clients, adhering to

23

the Representational State Transfer (REST) architectural style (see

24

http://rest.blueoxen.net/).

25

26

The web application interface is the primary one. The RESTive interface is

27

there for potential interoperability with other systems and fat clients to

28

perform data entry that is inconvenient to do via the web application

29

interface.

30

31

There are several clients that demonstrate the usage of the REST interface

32

(a command-line client that is used for functional tests, a wxWidgets GUI

33

client, and a command-line client for data import).

34

35

Any modern web browser is suitable for the web application interface. The

36

interface degrades gracefully, so a browser that does not support CSS or

37

Javascript will be usable, although perhaps not very nice or convenient.

38

39

40

System requirements

41

-------------------

42

43

- Python 2.3 (http://www.python.org/)

44

(Debian users will need both python2.3 and python2.3-xml packages)

45

46

- libxml2 Python bindings (http://xmlsoft.org/)

47

48

- Twisted 1.3.0 or newer (http://www.twistedmatrix.com/)

49

(needed for the server only)

50

51

- Python Imaging library (http://www.pythonware.com/products/pil/index.htm)

52

(needed for the server only)

53

54

- wxPython 2.4 (http://www.wxpython.org/)

55

(needed for the wxWidgets client only)

56

57

- pyOpenSSL (http://sourceforge.net/projects/pyopenssl/)

58

(needed for the server only)

59

60

- Development environment and a C compiler

61

(precompiled binaries are available for Windows users)

62

63

64

Optional Extras

65

---------------

66

67

- PyTCPWrap (http://ples.sourceforge.net/index.cgi?PyTCPWrap)

68

(useful for the server only)

69

70

71

Building SchoolTool

72

-------------------

73

74

Run 'make' to build the necessary extension modules.

75

76

It is a good idea to run 'make test' and 'make ftest' to check if all the

77

essential unit and functional tests pass.

78

79

80

Installing and Configuring with Distutils

81

-----------------------------------------

82

83

It is possible to install SchoolTool and SchoolBell using the python distutils.

84

To do this, you have to use one of the distributed tarballs/zip files, which

85

you unpack in a directory with the tools appropriate to your OS. First, it is

86

necessary to install the version of Zope included with the tarballs, this can

87

be done by running

88

89

python setup.py install

90

91

from the Zope3/ directory included with the SchoolBell distribution. From the

92

top level directory, the commands

93

94

python setup.py schoolbell install (inside the unpacked schoolbell tarball/zip)

95

python setup.py schooltool install (inside the unpacked schooltool tarball/zip)

96

97

will install SchoolBell and SchoolTool respectively. Note that SchoolTool

98

depends on SchoolBell, so you will have to install both if you want to run

99

SchoolTool.

100

101

Finally, to setup a SchoolBell / SchoolTool instance, copy the installed script

102

into a separate directory and create a config file with the name of the script

103

and an extension .conf. A good template can be found in the top level of the

104

tarball (.conf.in). Running this script will then run an instance in that

105

directory.

106

107

Those interested in installing into a non-standard location should investigate

108

the --paths and --default-config option for the install distutils commands.

109

110

NOTE: If you are using a Linux distribution for which packages exist, you

111

should consider using those packages instead of this procedure.

112

113

114

Running SchoolTool

115

------------------

116

117

The top-level project directory contains the following executable Python

118

scripts:

119

120

schooltool-server.py starts the SchoolTool server

121

schoolbell-server.py starts the SchoolBell server

122

schooltool-client.py starts the command line client

123

generate-sampleschool.py generates sample school data

124

import-sampleschool.py imports sample data into the server

125

126

The SchoolTool server automatically creates an empty database if it cannot find

127

an existing one. You can customize the location of the database and a few

128

other parameters in a configuration file called schooltool.conf. There's

129

an example file called schooltool.conf.in, you can simply rename it and modify

130

to suit your needs.

131

132

By default a user with manager privileges is created in the new database.

133

The username is 'manager', and the password is 'schooltool'. The database

134

is otherwise mostly empty, but you can run import-sampleschool.py to populate

135

it with some sample data.

136

137

The default web application port is 7080. Once the server is running, you can

138

connect to it with a web browser.

139

140

The Makefile also contains several shortcuts, which are kept mainly for

141

backwards-compatibility:

142

143

make sampleschool generates and imports sample data into the server

144

145

make run starts the SchoolTool server

146

make runtestserver starts the SchoolTool server using test.conf as the

147

configuration file (this is used for running

148

automated functional tests)

149

150

make runclient starts the command line client

151

152

These commands are superseded by executable Python scripts in the top-level

153

directory.

154

155

156

Project structure

157

-----------------

158

159

GPL the GNU General Public License, version 2

160

README this file

161

README.schoolbell README for SchoolBell

162

RELEASE release notes for the latest release

163

164

Makefile makefile for building extension modules

165

setup.py distutils setup script for building extension modules

166

test.py test runner

167

remove-stale-bytecode.py

168

script to remove stale *.pyc files

169

170

schooltool-server.py script to start the SchoolTool server

171

schoolbell-server.py script to start the SchoolBell server

172

generate-sampleschool.py

173

script to generate sample school data

174

import-sampleschool.py

175

script to import sample school data

176

schooltool-client.py script to start the command-line client

177

178

test.conf configuration file used for functional tests

179

testserver.pem sample SSL certificate used for functional tests

180

schooltool.conf.in sample configuration file

181

schoolbell.conf.in sample configuration file for SchoolBell

182

ttconfig.data sample timetable configuration

183

184

build/ temporary files are placed here during build process

185

coverage/ unit test coverage reports are placed here

186

debian/ Debian packaging support

187

doc/ documentation

188

src/ source code

189

schooltool/ Python package 'schooltool'

190

main.py the SchoolTool server

191

*.py other modules (see docstrings)

192

schema.xml ZConfig schema definition for the configuration file

193

tests/ unit tests for the schooltool package

194

ftests/ functional tests for the schooltool package

195

browser/ web application views for the server

196

www/ page templates

197

tests/ unit tests for the schooltool.browser package

198

rest/ RESTive views for the server

199

www/ page templates

200

tests/ unit tests for the schooltool.rest package

201

clients/ SchoolTool clients

202

client.py executable command line client

203

wxclient.py executable wxWindows client

204

205

206

Testing

207

-------

208

209

There are two sets of automated tests: unit tests and functional tests.

210

Unit tests (sometimes also called programmer tests) test individual components

211

of the system. Functional tests (also called customer or acceptance tests)

212

test only externally visible behaviour of the whole system.

213

214

Tests themselves are scattered through the whole source tree. Subdirectories

215

named 'tests' contain unit tests, while subdirectories named 'ftests' contain

216

functional tests.

217

218

To run all unit tests, do

219

220

python2.3 test.py -pv

221

222

To run all functional tests, start the SchoolTool server using the test.conf

223

configuration file (hint: make runtestserver) and then do

224

225

python2.3 test.py -fpv

226

227

The test runner has more options and features. To find out about them, do

228

229

python2.3 test.py -h

230

231

Functional tests are are not completely isolated. Some functional tests

232

create named database state snapshots, while other tests reuse those snapshots

233

of known database state. The test runner does not know which tests create

234

which snapshots, so if you want to run just one (or a couple) of functional

235

tests in isolation, it is likely that you will have first run the full suite

236

to create the necessary snapshots. Do not restart the test server, or all

237

saved snapshots will be gone.

238

239

240

Unit test coverage

241

------------------

242

243

All code should be covered by unit tests. The test runner can help you look

244

for untested code by producing code coverage reports.

245

246

To generate unit test coverage reports, run

247

248

make coverage

249

250

This command will run the full SchoolTool unit test suite and produce a

251

number of files (one for each Python module) in ./coverage/. Every

252

report file contains the source of the corresponding Python module.

253

Each source line is annotated with a number that shows how many times

254

this line was reached during testing. Watch out for lines marked with

255

'>>>>>>' as they indicate code that is not unit tested.

256

257

There are some more helpful make targets:

258

259

make coverage-report-list

260

261

Lists all non-test modules from the schooltool package that contain

262

untested code.

263

264

make coverage-report

265

266

Like 'make coverage-report-list', but is somewhat slower and also

267

shows the number of untested lines in each module.

268

269

make vi-coverage-reports

270

271

Launches vi for all coverage reports listed by 'make

272

coverage-report-list'. Type />>>>>> to search for untested code,

273

then type :next to look at the next report.

274

275

make edit-coverage-reports

276

277

Like 'make vi-coverage-reports' but uses $EDITOR rather than

278

hardcoding 'vi'.

279

280

281

Translation

282

-----------

283

284

Translation files live in src/schooltool/translation. There is a directory

285

for each language that contains a subdirectory called LC_MESSAGES that

286

contains two files: schooltool.po and schooltool.mo.

287

288

To start a new translation, create a language directory and LC_MESSAGES and

289

use src/schooltool/translation/schooltool.pot as a template. Generate

290

schooltool.mo with msgfmt (or by calling make update-translations).

291

292

When you change the translatable strings in the source code or page templates,

293

be sure to run

294

295

make extract-translations

296

297

298

Virtual hosting

299

---------------

300

301

SchoolTool provides support for virtual hosting with Apache's mod_rewrite.

302

For example, let's say you have two SchoolTool instances running on ports

303

7001 and 7002, and you want to make them available as school1.example.org

304

and school2.example.org, both on port 80. In order to do that, add the

305

following to your Apache configuration file:

306

307

NameVirtualHost *:80

308

309

310

ServerName school1.example.org

311

RewriteEngine On

312

RewriteRule ^/(.*) http://localhost:7001/++vh++http:school1.example.org:80/$1 [P]

313

</VirtualHost>

314

315

316

ServerName school2.example.org

317

RewriteEngine On

318

RewriteRule ^/(.*) http://localhost:7002/++vh++http:school2.example.org:80/$1 [P]

319

</VirtualHost>

320

321

Also, enable mod_proxy and mod_rewrite.

322

323

See http://issues.schooltool.org/issue91 if you're interested why two rewrite rules

324

are needed for each virtual host.

325

326

You can also get SSL support in the same way, as an alternative to the build-in

327

SSL support:

328

329

NameVirtualHost *:443

330

331

332

ServerName school1.example.org

333

SSLEnable # Apache 1.3

334

# SSLEngine On # Apache 2.0

335

RewriteEngine On

336

RewriteRule ^/(.*) http://localhost:7001/++vh++https:school1.example.org:443/$1 [P]

337

</VirtualHost>

338

339

The web application interface also supports virtual hosting in this manner,

340

the only differing thing would be the local port number.

341

342

343

Copyright information

344

---------------------

345

346

347

348

All files in the src/schooltool directory (with some exceptions in

349

src/schooltool/translation) are part of SchoolTool, and are (c) Shuttleworth

350

Foundation.

351

352

Unless otherwise stated, files in src/schooltool are released under the

353

terms of the GNU General Public License as published by the Free

354

Software Foundation; either version 2 of the License, or (at your option)

355

any later version.

356

357

Files in the following directories are (c) their respective owners. See

358

the individual files and directories for details of the licences.

359

360

Zope3

361

src/schooltool/translation

362

363

The following files are (c) the GNOME Foundation under the GPL.

364

365

src/schooltool/browser/www/booking.png

366

src/schooltool/browser/www/calendar.png

367

src/schooltool/browser/www/current.png

368

src/schooltool/browser/www/day.png

369

src/schooltool/browser/www/information.png

370

src/schooltool/browser/www/manage.png

371

src/schooltool/browser/www/meeting.png

372

src/schooltool/browser/www/month.png

373

src/schooltool/browser/www/next.png

374

src/schooltool/browser/www/previous.png

375

src/schooltool/browser/www/week.png

376

src/schooltool/browser/www/year.png

377

378

379

Files in the same directory as this README file are (c) Shuttleworth

380

Foundation, with the exception of GPL, which is a copy of the Free Software

381

Foundation's General Public License, and is (c) FSF.

382

383

Files in the debian/ subdirectory are (c) Shuttleworth Foundation and

384

contributors.

385

386

387

SchoolTool is distributed in the hope that it will be useful,

388

but WITHOUT ANY WARRANTY; without even the implied warranty of

389

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

390

GNU General Public License for more details.

391

392

You should have received a copy of the GNU General Public License

393

along with this program; if not, write to the Free Software

394

Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

395

396

You can find the full copy of the GNU General Public License in a file called

397

GPL in the project directory.