You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

5.8KB

Development of Debian Member Portfolio Service

The Debian Member Portfolio Service is implemented in Python 3 using the Flask web application framework.

The following sections describe how to setup a local development environment for the Debian Member Portfolio Service.

All instructions assume that you work on a Debian system. You should use Python 3 for development.

Setup of a local development

To start working on the source code you need to have git installed:

sudo aptitude install git

The canonical git repository for the Debian Member Portfolio Service is available at https://debianstuff.dittberner.info/git/debianmemberportfolio.git. To get a clone of the source code you change to a directory of your choice and invoke git clone:

cd ~/src
git clone https://debianstuff.dittberner.info/git/debianmemberportfolio.git

You should use venv to separate the development environment from your system wide Python installation. You can install virtualenv using:

sudo aptitude install python3-venv

When you have :command:`pyvenv` installed you should create a virtual environment for Debian Member Portfolio Service development and install the requirements using pip:

System Message: ERROR/3 (<stdin>, line 38); backlink

Unknown interpreted text role "command".
mkdir ~/.virtualenvs
pyvenv ~/.virtualenvs/dmportfolio
. ~/.virtualenvs/dmportfolio/bin/activate
cd ~/src/debianmemberportfolio
pip install -r stretchreq.pip

Note

The Debian Member Portfolio Service instance at http://portfolio.debian.net/ is running on a Debian Stretch server, therefore :file:`stretchreq.pip` contains dependency versions matching that Debian release.

System Message: ERROR/3 (<stdin>, line 50); backlink

Unknown interpreted text role "file".

The dependency download and installation into the virtual environment takes some time.

Debian Member Portfolio Service needs the JQuery JavaScript library to function properly. The JQuery library is not included in the git clone and must be copied into the subdirectory :file:`debianmemberportfolio/static/javascript/jquery`. On Debian systems you can install the package libjs-jquery and place a symlink to the directory :file:`/usr/share/javascript` into :file:`debianmemberportfolio/static`:

System Message: ERROR/3 (<stdin>, line 57); backlink

Unknown interpreted text role "file".

System Message: ERROR/3 (<stdin>, line 57); backlink

Unknown interpreted text role "file".

System Message: ERROR/3 (<stdin>, line 57); backlink

Unknown interpreted text role "file".
sudo aptitude install libjs-jquery
ln -s /usr/share/javascript debianmemberportfolio/static

Prepare for first startup

The Debian Member Portfolio Service uses data from the Debian keyring to get information regarding PGP keys and names related to email addresses. Before you can run the service you need to fetch a copy of the keyring and prepare it for use by the code.

Note

You need rsync and gnupg for these tasks:

sudo aptitude install rsync gnupg

When you have both installed you can run:

. ~/.virtualenvs/dmportfolio/bin/activate
./synckeyrings.sh
python debianmemberportfolio/model/keyringanalyzer.py

The first synchronizes the keyrings in :file:`$HOME/debian/keyring.debian.org` with files on the keyring.debian.org host. And the second generates a key/value database in :file:`debianmemberportfolio/model/keyringcache.db` that is used by the code.

System Message: ERROR/3 (<stdin>, line 87); backlink

Unknown interpreted text role "file".

System Message: ERROR/3 (<stdin>, line 87); backlink

Unknown interpreted text role "file".

Run a development server

You can run a development server using:

python3 run.py

The output of this command should look like the following:

* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
* Restarting with stat

You can now access your development server at the URL that is printed by the command.

If you want to stop the development server press :kbd:`Ctrl + C`.

System Message: ERROR/3 (<stdin>, line 106); backlink

Unknown interpreted text role "kbd".

Common development tasks

Add new URL

Debian Member Portfolio Service uses a ini style configuration file :file:`debianmemberportfolio/model/portfolio.ini` to configure the generated URL patterns. The actual URL generation is done in :py:func:`~debianmemberportfolio.views.urllist`.

System Message: ERROR/3 (<stdin>, line 114); backlink

Unknown interpreted text role "file".

System Message: ERROR/3 (<stdin>, line 114); backlink

Unknown interpreted text role "py:func".

If you want to add a new URL type you have to add a line in :file:`portfolio.ini` and an entry in :py:mod:`~debianmemberportfolio.views`'s :py:attr:`~debianmemberportfolio.views._LABELS` dictionary. The top level dictionary keys correspond to sections in the ini file. The dictionary values are dictionaries themselves that contain a special key label that defines the label of the section in the output and keys for each entry to be rendered in that section. The values in these sub-dictionaries are strings marked for translation using the :py:func:`~flask_babel.lazy_gettext` function from :py:mod:`flask_babel`.

System Message: ERROR/3 (<stdin>, line 119); backlink

Unknown interpreted text role "file".

System Message: ERROR/3 (<stdin>, line 119); backlink

Unknown interpreted text role "py:mod".

System Message: ERROR/3 (<stdin>, line 119); backlink

Unknown interpreted text role "py:attr".

System Message: ERROR/3 (<stdin>, line 119); backlink

Unknown interpreted text role "py:func".

System Message: ERROR/3 (<stdin>, line 119); backlink

Unknown interpreted text role "py:mod".

The patterns in :file:`portfolio.ini` can contain the following placeholders that are filled at runtime:

System Message: ERROR/3 (<stdin>, line 129); backlink

Unknown interpreted text role "file".
Placeholder Replacement
%(salsausername)s user name on salsa.debian.org
%(email)s email address (URL encoded)
%(emailnoq)s email address
%(firstchar)s first character of the email address
%(forumsid)s forum user id
%(gpgfp)s GNUPG/PGP key fingerprint
%(name)s full name (i.e. John Smith)
%(username)s Debian user name
%(wikihomepage)s full name in camel case (i.e. JohnSmith)

The replacement of placeholders is performed in the :py:func:`~debianmemberportfolio.views.urllist` function. And uses data from the Debian keyring. Access to the pre-parsed keyring data is performed using the :py:func:`~debianmemberportfolio.model.dddatabuilder.build_data` function of the module :py:mod:`debianmemberportfolio.model.dddatabuilder`, which uses several helper functions from :py:mod:`debianmemberportfolio.model.keyfinder` to access the key information.

System Message: ERROR/3 (<stdin>, line 148); backlink

Unknown interpreted text role "py:func".

System Message: ERROR/3 (<stdin>, line 148); backlink

Unknown interpreted text role "py:func".

System Message: ERROR/3 (<stdin>, line 148); backlink

Unknown interpreted text role "py:mod".

System Message: ERROR/3 (<stdin>, line 148); backlink

Unknown interpreted text role "py:mod".