.. -*- coding: utf-8 -*- .. role:: sref(numref) .. role:: xref(numref) .. Copyright (C) 2019, Wolfgang Scherer, .. .. This file is part of Work Package for Applicants. .. .. Permission is granted to copy, distribute and/or modify this document .. under the terms of the GNU Free Documentation License, Version 1.3 .. or any later version published by the Free Software Foundation; .. with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. .. A copy of the license is included in the section entitled "GNU .. Free Documentation License". .. inline comments (with du_comment_role) .. role:: rem(comment) .. role:: html(raw) :format: html .. role:: shx(code) :language: sh .. >>CODD Introduction ================================================== :rem:`|||:sec:|||`\ Introduction ================================================== The development environment is - Linux (ubuntu) - emacs(1) (with home-grown extensions) - snippets(1) tool (templating) - terminal/shell/make - Python 2.x/3.x - `Mercurial`_ (TortoiseHg thg(1) is installed as GUI) - `Kallithea`_ at http://sw-amt.ws/kallithea/applicants/@user@ Although it is possible to use editors other than emacs for the current task, the missing highlighting support and tag navigation make comprehension and work quite hard. The task can be completed in a terminal with ssh(1) access to `sw-amt.ws`. It is perfectly possible to use `PuTTY`_ under windows. A more comfortable graphical environment is available with a VNC viewer (e.g. `UltraVNC`_) via SSH-Tunnel. MacOS X comes with a builtin VNC client, press :kbd:`⌘-k` (:kbd:`CMD-k`) in Finder and enter `vnc://host:port`. Since the project is under version control, it is also possible to clone the repository and complete the project entirely off-site. .. _`PuTTY`: https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html .. _`UltraVNC`: https://www.uvnc.com/downloads/ultravnc.html .. >>CODD Chapter ================================================== :rem:`|||:sec:|||`\ Task outline ================================================== Access `sw-amt.ws` with ssh(1) in terminal. #. Initialize :file:`workpackage` directory from repository: .. code-block:: sh hg clone http://@user@:@passwd@@sw-amt.ws/kallithea/applicants/@user@ workpackage #. Initialize documentation in :file:`workpackage` directory: .. code-block:: sh cd workpackage sda init Workpackage Commit initial revision to version control system (VCS): .. code-block:: sh hg add hg commit -m 'README.txt: project documenatation initial revision' hg push #. Create database :file:`workpackage.db`: .. code-block:: sh snn --key sqlite_db_base --value workpackage workpackage.sql emacs workpackage.sql # create table ... sqlite3 workpackage.db 'workpackage_db.py' emacs 'workpackage_db.py' | Fill out variable DSN with `workpackage.db`. | Analyze test/example code at end of file. Commit initial revision to VCS: .. code-block:: sh hg add workpackage_db.py hg commit -m 'workpackage_db.py: define sqlalchemy ORM tables' hg push .. note:: Use :mod:`sqlalchemy` ORM classes from :mod:`workpackage_db` to access the database tables. **Do not use low-level SQL statements** based on `PEP 249 -- Python Database API Specification v2.0`_. #. Build and view documentation: .. code-block:: sh sda make xdg-open https://sw-amt.ws/@user@/doc/html Accessing the generated documentation at https://sw-amt.ws/@user@/doc/html requires the username `@user@` and the same password as for the VNC server. Examples for diagrams and pointers to definitions can be found in `Documentation Standard`_. .. note:: The documentation ist embedded into a framework based on `Sphinx`_. There is no need to use any facilities provided by the framework. The documentation goes between the lines .. code-block:: rst .. >>CODD Introduction -- DOCUMENTATION GOES HERE -- .. >>CODD Notes #. Design :mod:`workpackage` module in :file:`README.txt`. Create bottle app. In function :func:`run` start HTTP server on port supplied with option --port, default: 50@offset@. On index page display buttons `Fill` and `Clear`. Also display all persons and their car(s) in a table. - `Fill` => fill database with sample records, display index - `Clear` => clear database, display index Use `PlantUML`_ UML diagrams for design: - class diagram for class `person` and class `car` with relations - activity diagram for functions Commit changes into VCS: .. code-block:: sh hg commit -m 'README.txt: program design' hg push Submit for review. #. Implement :mod:`workpackage` module: .. code-block:: sh snn workpackage.py emacs 'workpackage.py' Commit initial revision and meaningful increments to VCS. .. note:: missing python packages can be installed in a `virtualenv` or with :samp:`pip install --user`, e.g.: .. code-block:: sh pip install --user bottle #. Serve :mod:`workpackage` application and view it: .. code-block:: sh python workpackage.py xdg-open https://sw-amt.ws/@user@/persons The URL https://sw-amt.ws/@user@/persons is served by Apache with a reverse proxy configuration to http://localhost:50@offset@ #. Complete documentation of project `workpackage`: .. code-block:: sh emacs 'README.txt' ================================================== :rem:`|||:sec:|||`\ Task details ================================================== #. Create a `sqlite3` database from an SQL file :file:`workpackage.sql`, with tables `person` (see :xref:`tab:person`) and `car` (see :xref:`tab:car`): .. note:: Do not declare the foreign key relation for `driver_id` explicitely. .. _`tab:person`: .. table:: person +------------+---------+----------------------------+ | column | type | attributes | +============+=========+============================+ | _id | INTEGER | AUTOINCREMENT, PRIMARY KEY | +------------+---------+----------------------------+ | name | TEXT | | +------------+---------+----------------------------+ | first_name | TEXT | | +------------+---------+----------------------------+ .. _`tab:car`: .. table:: car +--------------+---------+----------------------------+ | column | type | attributes | +==============+=========+============================+ | _id | INTEGER | AUTOINCREMENT, PRIMARY KEY | +--------------+---------+----------------------------+ | manufacturer | TEXT | | +--------------+---------+----------------------------+ | model | TEXT | | +--------------+---------+----------------------------+ | driver_id | INTEGER | | +--------------+---------+----------------------------+ .. >>CODD Conclusion .. >>CODD Appendix A .. \|:here:| .. >>CODD Notes .. ================================================== .. :rem:`|||:sec:|||`\ Footnotes .. ================================================== :html:`
` .. \[#] .. include:: doc_defs.inc .. include:: abbrev_defs.inc .. include:: doc_defs_combined.inc .. .. \||<-snap->|| doc_standalone .. include:: doc/doc_defs_secret.inc .. \||<-snap->|| doc_standalone .. \||<-snap->|| not_doc_standalone .. include:: doc_defs_secret.inc .. \||<-snap->|| not_doc_standalone .. _`Wolfgang Scherer`: wolfgang.scherer@gmx.de