pynojo Documentation Release unknown pynojo development team

Transcription

1 pynojo Documentation Release unknown pynojo development team November 05, 2013

2

3 Contents i

4 ii

5 Welcome! This documentation is generated on November 05, 2013 for pynojo unknown. Contents: Contents 1

6 2 Contents

7 CHAPTER 1 Notes for Developers Contents Notes for Developers Getting Started * Environment Setup * Configuration Miscellaneous Specifications and Instructions * Framework * Code Style * Documenting * Threading * Native Language Support (NLS) * Stylesheets and Javascripts Contact Kai Jia <jia.kai66@gmail.com> if you have any question about this page. 1.1 Getting Started Environment Setup 1. Install SQLite3 and its development packages if you don t already have them installed. Usually this is via your system s package manager. For example, on a Debian Linux system, do sudo apt-get install libsqlite3-dev. 2. Install virtualenv: $ sudo pip install virtualenv 3. Setup a workplace using virtualenv. Note that you may need to specify -p python2 option to tell virtualenv to use Python 2. Replace <path-to-your-workplace> with something you like: $ virtualenv <path-to-your-workplace> 4. Write your own init.sh (note that it has already been added to.gitignore): 3

8 $ cd <path-to-pynojo-source-root> $ echo export PATH=<path-to-your-workplace>/bin:$PATH > init.sh $../init.sh Note: the following steps assume that you have put init.sh at the right place and have executed../init.sh. 5. Use pip to get the dependencies installed: $ pip install pyramid sqlalchemy python-cjson # runtime dependencies $ pip install sphinx pyenchant babel \ sphinxcontrib-spelling pylint # development dependencies 6. Generate the.mo files and documents, which are not tracked by the version control system (see also Native Language Support (NLS) and Documenting): $ cd <path-to-pynojo-source-root>/utils/nls $./genmo $ cd../../docs $./gendoc 7. Download all the 3rd party utils according to utils/3rd-party/list: $ cd <path-to-pynojo-source-root>/utils/3rd-party $./download-all.sh 8. Generate the CSS and javascript files (see also Stylesheets and Javascripts): $ cd <path-to-pynojo-source-root>/utils $./gencss $./genjs Configuration The static system configuration package is pynojo.config. To allow the developers applying their local settings without having to change the system defaults, pynojo/config/overwrite.py has been added to.gitignore. Define a function named overwrite in that file and change the configuration there. An example file: # pylint: disable=c0111,r0201 from pynojo.config.db import DBConfig _engine = None _DBFILE = /tmp/pynojo.db # _DBFILE = :memory: class def get_session_maker(engine): from sqlalchemy.orm import sessionmaker, scoped_session ses = scoped_session(sessionmaker(bind = engine)) return def get_engine(): global _engine if _engine is not None: 4 Chapter 1. Notes for Developers

9 return _engine from sqlalchemy import create_engine, event _engine = create_engine( sqlite:/// + _DBFILE) event.listen(_engine, connect, lambda con, record: con.execute( PRAGMA foreign_keys=on )) return _engine def _init(): import logging class SQLFilter(logging.Filter): def filter(self, record): record.name = SQL return True logging.basicconfig( filename = /tmp/pynojo.log, format = %(asctime)s [%(name)s] %(message)s, datefmt = %H:%M:%S ) logging.getlogger( sqlalchemy.engine ).setlevel(logging.info) logging.getlogger( sqlalchemy.engine.base.engine ).addfilter(sqlfilter()) def overwrite(conf): _init() from os.path import isfile db_exists = isfile(_dbfile) conf.pyramid.settings[ reload_templates ] = True conf.db = MyDB() # install_db must be imported after conf.db is set from pynojo.model import install_db if not db_exists: install_db(conf.db.get_engine()) 1.2 Miscellaneous Specifications and Instructions Framework Pyramid is used as the web framework, and SQLAlchemy as the ORM. Note that pynojo uses a subclass of pyramid.request.request as the request factory; see pynojo. init.request Code Style Follow the Style Guide for Python Code. Use pylint to check the style and find potential bugs. Execute the run-pylint script to invoke pylint. The following lines should be included in every Python source file: # $File: <file name> # $Date: <last modification time> # # Copyright (C) 2012 the pynojo development team <see AUTHORS file> 1.2. Miscellaneous Specifications and Instructions 5

10 # # Contributors to this file: # <you name and here> # # This file is part of pynojo # # pynojo 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 3 of the License, or # (at your option) any later version. # # pynojo 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 pynojo. If not, see < # Configure your editor to update the $File and $Date fields automatically. Add your name to the contributors field and the AUTHORS file. By the way, if vim is your favorite, you can add the following lines to your vimrc: autocmd filetype python set expandtab autocmd filetype python set textwidth= Documenting Write docstrings for every package, module, public class, public method, public function, etc. The documents should be written in English. Register all the global names in Global Name List. These documents are generated from restructuredtext sources and docstrings by Sphinx. Issue the following command to generate all the documents: $ cd <path-to-pynojo-source-root>/docs $./gendoc If environment variable PYNOJO_DOC_SPELLCHECK exists, then sphinxcontrib.spelling will be used for spellchecking of all the documents. The extra word list file is located at docs/wordlist.txt Threading Although current CPython implementation does not fully support multithreading, keep in mind that all the code should be thread-safe, so be careful when modifying global variables. To avoid confusion, unexpected behavior or overuse of resource (exceeding the thread limit in the server configuration), do not use multithreading unless absolutely necessary. If it is really necessary to spawn a child thread, remember to call pynojo.lib.register_thread_request() in the child thread to ensure that functions depending on pynojo.lib.get_thread_request() work correctly. 6 Chapter 1. Notes for Developers

11 1.2.5 Native Language Support (NLS) All the human-readable messages in pynojo python source code and templates should be written in English. There should NOT be any non-ascii characters in the source, except in nls/config.py, where TRANS_LIST describes the available translations. pynojo dose not use the NLS mechanism provided by Pyramid and Chameleon. Instead, pynojo has its own pynojo.nls package, which is based on GNU gettext. To generate the pot file, cd to utils/nls and execute./genpot. The pot file will be stored in the current directory. The locale directory is pynojo/nls/locale. To update the po files or generate the mo files, cd to utils/nls and execute./update-po or./genmo respectively. To localize: In a pyramid view callable, the request parameter passed to it will include the translation functions as methods named _ and _pl. They are appropriate for the locale of the client, which is already determined according to the information provided by request. _ and _pl are also added to the builtin namespace, so they can be invoked directly. This method is slightly slower than the one above, for it has to access thread local variable. It is assumed that the caller resides in the same thread as that of the pyramid view callable, otherwise pynojo.lib.register_thread_request() has to be called explicitly before calling _ or _pl. In a page template, the appropriate translation functions are the global functions named _ and _pl. See pynojo.nls.init() and pynojo.view for some further explanations. To add a new translation, use msginit to generate the po file from the pot file. Move the output po file to pynojo/nls/locale/<lang>/lc_messages/pynojo.po and append corresponding pynojo.nls.config.transinfo instance to TRANS_LIST defined in pynojo/nls/config.py. DO NOT change the order of the translations already listed there. Here are two examples: In a pyramid view = mkroute(pattern = ), renderer = template/index.pt ) def _index(request): return { msg : request._( msgfrompython ) + _( builtin-trans )} In a page template: <div metal:use-macro="layout"> <div metal:fill-slot="content"> ${_( {0}from{t}, msg, t = template )} <br /> ${msg} <br /> ${_pl( singular, plural, 1)} <br /> ${_pl( singular, plural, 2)} <br /> </div> </div> Locale detection details: If the user does not login, detect the locale via Accept-Language field in the HTTP request header. Cookie: TODO Stylesheets and Javascripts pynojo uses closure-stylesheets to minify the stylesheets. Put all the GSS files in pynojo/view/static/gss/, and generate the all-in-one CSS file using the following: 1.2. Miscellaneous Specifications and Instructions 7

12 $ cd <path-to-pynojo-source-root>/utils $./gencss UglifyJS is used to minify the javascripts. Note that you have to get nodejs installed. Put all the scripts in pynojo/view/static/gss/, and generate the all-in-one js file by: $ cd <path-to-pynojo-source-root>/utils $./genjs 8 Chapter 1. Notes for Developers

13 CHAPTER 2 The Permission Model Contents The Permission Model Users and User Groups Problem Access Control Event Access Control Access Limiter (ACL) Contact Kai Jia <jia.kai66@gmail.com> if you have any question about this page. 2.1 Users and User Groups Each user can be assigned to multiple user groups, and each user group can be given multiple permissions, which are used for authorization of system management tasks. The permissions are defined in pynojo.model.permdef.usergrp. For a user, the permissions that it has is the union of the permissions of groups that it belongs to. 2.2 Problem Access Control Whether a problem can be accessed by a particular user is determined by the user s accessibility to the problem groups(pg) that it belongs to. Each PG is associated to an ACL. A user is able to access a PG if the ACL associated with that PG allows the user s request. A user gains access to a problem if he has access to at least one of the PGs that it belongs to. Although this might weaken the access controllability, it is designed so to simplify overall design and speed up listing problems. A user can only see the PGs that he has access to, so under such design, when listing problems in a PG, it is not needed to consider for each problem the user s access to other PGs that the it belongs to. 9

14 2.3 Event Access Control An event is an activity that lasts for a period of time, associated with some problems and can be associated with an ACL. For example, it can be a time-limited assignment, a test or a contest. During an event, the problems in this event are locked. Locking a problem means that in the problem list, it can only be viewed, but the user can not post new submissions or read the sources of his previous submissions; instead, the user must go to the event page to submit the problem, and only sources submitted after the event starts might be viewed. There are different kinds of events, and each event implementation can have control over the accessibility of problems, submissions or any other related resource. 2.4 Access Limiter (ACL) ACL is an abstract access control mechanism used by pynojo. It can be viewed as an abstract base class, and the resource that needs access control can be associated with an instance of an implemented subclass of ACL. Each ACL instance is identified by a unique ACL id. This is the basic idea of ACL, and refer to pynojo.lib.acl and pynojo.model.acl for the detailed API descriptions. 10 Chapter 2. The Permission Model

15 CHAPTER 3 Global Name List The global names that are not documented in the API Reference should be listed here. Contents Global Name List Database Session Renderers Cookies Views 3.1 Database Session A contextual session defined in pynojo.model is used. To create a session instance ses in some function, just do the following: from pynojo.model import Session def foo(): ses = Session() # do something with ses Direct invoking of Session.commit() is usually unnecessary, except when some operations that might fail and call Session.rollback() are performed, in which case Session.commit() should be called before starting any of those operations. The committing is performed in a subscriber defined in pynojo.model. 3.2 Renderers The following renderers are provided by pynojo (see the source of pynojo.view.setup_pyramid_conf()): cjson: replace the json renderer, to gain some efficiency. 11

16 3.3 Cookies Cookie Name Description Source Reference uid the id of the user that logged in pynojo.lib.user token the authentication code of the pynojo.lib.user 3.4 Views 12 Chapter 3. Global Name List

17 CHAPTER 4 API Reference 13

18 14 Chapter 4. API Reference

19 CHAPTER 5 Indices and tables genindex search 15