Commit | Line | Data |
---|---|---|
a61373d3 RB |
1 | Architecture |
2 | ============ | |
3 | ||
4 | The plat/al project relies heavily on Django's notion of applications. | |
5 | ||
6 | ||
7 | Applications | |
8 | ------------ | |
9 | ||
10 | Each functional unit (events, news, groups, accounts, profiles, payments, ...) | |
11 | should live in its own Django app. | |
12 | ||
13 | Such apps should follow the following layout: | |
14 | ||
15 | - ``__init__.py``: Mandatory for Python, should be empty | |
16 | - ``models.py``: Required by Django, contains all models | |
17 | - ``admin.py``: A (properly designed) Admin for each model | |
18 | - ``factories.py``: The set of `factories <http://factoryboy.rtfd.org/>`_ related to the models | |
19 | - ``tests.py``: The set of tests for the app | |
20 | ||
21 | If the application contains views, it should include the following files: | |
22 | ||
23 | - ``forms.py``: Home of the forms used in the app (if any) | |
24 | - ``views.py``: All view definitions | |
25 | - ``urls.py``: URL map of the application, to be included in ``xnet.urls`` | |
26 | - ``templates/my_app/base.html``: Base template for the application. | |
27 | Can be simply: | |
28 | ||
29 | .. code-block:: html | |
30 | ||
31 | {% extends "base.html" %} | |
32 | ||
33 | - ``templates/my_app/foo.html``: app-specific templates. They should all inherit | |
34 | from ``my_app/base.html``. | |
35 | ||
36 | ||
37 | External libraries | |
38 | ------------------ | |
39 | ||
40 | Whenever a functionality can be provided by an external, existing library, | |
41 | that library should be added to the dependencies (and not copied to our code). | |
42 | ||
43 | - If it's a "production" dependency, add it to ``requirements.txt``. | |
44 | - If the dependency is only useful for development / testing / ..., add it to ``dev_requirements.txt`` | |
45 | - Until plat/al has reached production, avoid too specific version ranges; | |
46 | use ``foo>=1.1.3`` if using a feature only available in v1.1.3, | |
47 | and avoid ``foo=1.1.3`` that would prevent us from seeing new features of the lib. | |
48 | ||
49 | ||
50 | Internal libraries (utilities) | |
51 | ------------------------------ | |
52 | ||
53 | Utilities should be placed in the ``xnet/utils/`` folder, with one "app" per subject. | |
54 | For instance, time-related functions could be provided in ``xnet/utils/time`` while | |
55 | image-related tools would live in ``xnet/utils/image``. | |
56 | ||
57 | ||
58 |