From 6fcd98abe5bf951eb993b1a6b24126a5681221a5 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 16 Nov 2015 00:49:58 -0800 Subject: - update wiki2/design.rst to use jinja templates - minor grammar - .rst fixes - rewrap to 79 columns --- docs/tutorials/wiki2/design.rst | 180 +++++++++++++++++++--------------------- 1 file changed, 87 insertions(+), 93 deletions(-) (limited to 'docs/tutorials/wiki2/design.rst') diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst index e9f361e7d..8e3bb4c13 100644 --- a/docs/tutorials/wiki2/design.rst +++ b/docs/tutorials/wiki2/design.rst @@ -1,10 +1,9 @@ -========== +====== Design -========== +====== -Following is a quick overview of the design of our wiki application, to help -us understand the changes that we will be making as we work through the -tutorial. +Following is a quick overview of the design of our wiki application to help us +understand the changes that we will be making as we work through the tutorial. Overall ------- @@ -17,17 +16,17 @@ Python module. We will add this module in the dependency list on the project Models ------ -We'll be using a SQLite database to hold our wiki data, and we'll be using +We'll be using an SQLite database to hold our wiki data, and we'll be using :term:`SQLAlchemy` to access the data in this database. Within the database, we define a single table named `pages`, whose elements will store the wiki pages. There are two columns: `name` and `data`. -URLs like ``/PageName`` will try to find an element in -the table that has a corresponding name. +URLs like ``/PageName`` will try to find an element in the table that has a +corresponding name. -To add a page to the wiki, a new row is created and the text -is stored in `data`. +To add a page to the wiki, a new row is created and the text is stored in +`data`. A page named ``FrontPage`` containing the text *This is the front page*, will be created when the storage is initialized, and will be used as the wiki home @@ -36,16 +35,14 @@ page. Views ----- -There will be three views to handle the normal operations of adding, -editing, and viewing wiki pages, plus one view for the wiki front page. -Two templates will be used, one for viewing, and one for both adding -and editing wiki pages. +There will be three views to handle the normal operations of adding, editing, +and viewing wiki pages, plus one view for the wiki front page. Two templates +will be used, one for viewing, and one for both adding and editing wiki pages. -The default templating systems in :app:`Pyramid` are -:term:`Chameleon` and :term:`Mako`. Chameleon is a variant of -:term:`ZPT`, which is an XML-based templating language. Mako is a -non-XML-based templating language. Because we had to pick one, -we chose Chameleon for this tutorial. +As of version 1.5 :app:`Pyramid` no longer ships with templating systems. In +this tutorial, we will use :term:`Jinja2`. Jinja2 is a modern and +designer-friendly templating language for Python, modeled after Django's +templates. Security -------- @@ -53,14 +50,14 @@ Security We'll eventually be adding security to our application. The components we'll use to do this are below. -- USERS, a dictionary mapping :term:`userids ` to their - corresponding passwords. +- USERS, a dictionary mapping :term:`userids ` to their corresponding + passwords. -- GROUPS, a dictionary mapping :term:`userids ` to a - list of groups to which they belong. +- GROUPS, a dictionary mapping :term:`userids ` to a list of groups to + which they belong. -- ``groupfinder``, an *authorization callback* that looks up USERS and - GROUPS. It will be provided in a new ``security.py`` file. +- ``groupfinder``, an *authorization callback* that looks up USERS and GROUPS. + It will be provided in a new ``security/default.py`` subpackage and file. - An :term:`ACL` is attached to the root :term:`resource`. Each row below details an :term:`ACE`: @@ -76,75 +73,72 @@ use to do this are below. - Permission declarations are added to the views to assert the security policies as each request is handled. -Two additional views and one template will handle the login and -logout tasks. +Two additional views and one template will handle the login and logout tasks. Summary ------- -The URL, actions, template and permission associated to each view are -listed in the following table: - -+----------------------+-----------------------+-------------+------------+------------+ -| URL | Action | View | Template | Permission | -| | | | | | -+======================+=======================+=============+============+============+ -| / | Redirect to | view_wiki | | | -| | /FrontPage | | | | -+----------------------+-----------------------+-------------+------------+------------+ -| /PageName | Display existing | view_page | view.pt | view | -| | page [2]_ | [1]_ | | | -| | | | | | -| | | | | | -| | | | | | -+----------------------+-----------------------+-------------+------------+------------+ -| /PageName/edit_page | Display edit form | edit_page | edit.pt | edit | -| | with existing | | | | -| | content. | | | | -| | | | | | -| | If the form was | | | | -| | submitted, redirect | | | | -| | to /PageName | | | | -+----------------------+-----------------------+-------------+------------+------------+ -| /add_page/PageName | Create the page | add_page | edit.pt | edit | -| | *PageName* in | | | | -| | storage, display | | | | -| | the edit form | | | | -| | without content. | | | | -| | | | | | -| | If the form was | | | | -| | submitted, | | | | -| | redirect to | | | | -| | /PageName | | | | -+----------------------+-----------------------+-------------+------------+------------+ -| /login | Display login form, | login | login.pt | | -| | Forbidden [3]_ | | | | -| | | | | | -| | If the form was | | | | -| | submitted, | | | | -| | authenticate. | | | | -| | | | | | -| | - If authentication | | | | -| | succeeds, | | | | -| | redirect to the | | | | -| | page that we | | | | -| | came from. | | | | -| | | | | | -| | - If authentication | | | | -| | fails, display | | | | -| | login form with | | | | -| | "login failed" | | | | -| | message. | | | | -| | | | | | -+----------------------+-----------------------+-------------+------------+------------+ -| /logout | Redirect to | logout | | | -| | /FrontPage | | | | -+----------------------+-----------------------+-------------+------------+------------+ - -.. [1] This is the default view for a Page context - when there is no view name. -.. [2] Pyramid will return a default 404 Not Found page - if the page *PageName* does not exist yet. -.. [3] ``pyramid.exceptions.Forbidden`` is reached when a - user tries to invoke a view that is - not authorized by the authorization policy. +The URL, actions, template, and permission associated to each view are listed +in the following table: + ++----------------------+-----------------------+-------------+----------------+------------+ +| URL | Action | View | Template | Permission | +| | | | | | ++======================+=======================+=============+================+============+ +| / | Redirect to | view_wiki | | | +| | /FrontPage | | | | ++----------------------+-----------------------+-------------+----------------+------------+ +| /PageName | Display existing | view_page | view.jinja2 | view | +| | page [2]_ | [1]_ | | | +| | | | | | +| | | | | | +| | | | | | ++----------------------+-----------------------+-------------+----------------+------------+ +| /PageName/edit_page | Display edit form | edit_page | edit.jinja2 | edit | +| | with existing | | | | +| | content. | | | | +| | | | | | +| | If the form was | | | | +| | submitted, redirect | | | | +| | to /PageName | | | | ++----------------------+-----------------------+-------------+----------------+------------+ +| /add_page/PageName | Create the page | add_page | edit.jinja2 | edit | +| | *PageName* in | | | | +| | storage, display | | | | +| | the edit form | | | | +| | without content. | | | | +| | | | | | +| | If the form was | | | | +| | submitted, | | | | +| | redirect to | | | | +| | /PageName | | | | ++----------------------+-----------------------+-------------+----------------+------------+ +| /login | Display login form, | login | login.jinja2 | | +| | Forbidden [3]_ | | | | +| | | | | | +| | If the form was | | | | +| | submitted, | | | | +| | authenticate. | | | | +| | | | | | +| | - If authentication | | | | +| | succeeds, | | | | +| | redirect to the | | | | +| | page that we | | | | +| | came from. | | | | +| | | | | | +| | - If authentication | | | | +| | fails, display | | | | +| | login form with | | | | +| | "login failed" | | | | +| | message. | | | | +| | | | | | ++----------------------+-----------------------+-------------+----------------+------------+ +| /logout | Redirect to | logout | | | +| | /FrontPage | | | | ++----------------------+-----------------------+-------------+----------------+------------+ + +.. [1] This is the default view for a Page context when there is no view name. +.. [2] Pyramid will return a default 404 Not Found page if the page *PageName* + does not exist yet. +.. [3] ``pyramid.exceptions.Forbidden`` is reached when a user tries to invoke + a view that is not authorized by the authorization policy. -- cgit v1.2.3 From e6e4f655f2abe8d1d5ff63ecd70255094af6de73 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Fri, 12 Feb 2016 01:09:01 -0600 Subject: let's go ahead and bite off more than we can chew by adding object-security we'll allow anyone to create pages, not just editors finally we'll allow page creators of pages to edit their pages even if they are not editors --- docs/tutorials/wiki2/design.rst | 82 ++++++++++++++++++++++++----------------- 1 file changed, 48 insertions(+), 34 deletions(-) (limited to 'docs/tutorials/wiki2/design.rst') diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst index 8e3bb4c13..42f06f7bf 100644 --- a/docs/tutorials/wiki2/design.rst +++ b/docs/tutorials/wiki2/design.rst @@ -19,11 +19,17 @@ Models We'll be using an SQLite database to hold our wiki data, and we'll be using :term:`SQLAlchemy` to access the data in this database. -Within the database, we define a single table named `pages`, whose elements -will store the wiki pages. There are two columns: `name` and `data`. +Within the database, we will define two tables: -URLs like ``/PageName`` will try to find an element in the table that has a -corresponding name. +- The `users` table which will store the `name`, `password_hash` and `role`. +- The `pages` table, whose elements will store the wiki pages. + There are three columns: `name`, `data` and `creator_id`. + +There is a one-to-many relationship between `users` and `pages` tracking +the user who created each wiki page. + +URLs like ``/PageName`` will try to find an element in the `pages` table that +has a corresponding name. To add a page to the wiki, a new row is created and the text is stored in `data`. @@ -32,8 +38,8 @@ A page named ``FrontPage`` containing the text *This is the front page*, will be created when the storage is initialized, and will be used as the wiki home page. -Views ------ +Wiki Views +---------- There will be three views to handle the normal operations of adding, editing, and viewing wiki pages, plus one view for the wiki front page. Two templates @@ -47,33 +53,41 @@ templates. Security -------- -We'll eventually be adding security to our application. The components we'll -use to do this are below. - -- USERS, a dictionary mapping :term:`userids ` to their corresponding - passwords. - -- GROUPS, a dictionary mapping :term:`userids ` to a list of groups to - which they belong. - -- ``groupfinder``, an *authorization callback* that looks up USERS and GROUPS. - It will be provided in a new ``security/default.py`` subpackage and file. - -- An :term:`ACL` is attached to the root :term:`resource`. Each row below - details an :term:`ACE`: - - +----------+----------------+----------------+ - | Action | Principal | Permission | - +==========+================+================+ - | Allow | Everyone | View | - +----------+----------------+----------------+ - | Allow | group:editors | Edit | - +----------+----------------+----------------+ - -- Permission declarations are added to the views to assert the security - policies as each request is handled. - -Two additional views and one template will handle the login and logout tasks. +We'll eventually be adding security to our application. To do this, we'll +be using a very simple role-based security model. We'll assign a single +role category to each user in our system. + +`basic` + An authenticated user who can view content and create new pages. A `basic` + user may also edit the pages they have created but not pages created by + other users. + +`editor` + An authenticated user who can create and edit any content in the system. + +In order to accomplish this we'll need to define an authentication policy +which can identify users by their :term:`userid` and role. Then we'll +need to define a page :term:`resource` which contains the appropriate +:term:`ACL`: + ++----------+--------------------+----------------+ +| Action | Principal | Permission | ++==========+====================+================+ +| Allow | Everyone | view | ++----------+--------------------+----------------+ +| Allow | group:basic | create | ++----------+--------------------+----------------+ +| Allow | group:editors | edit | ++----------+--------------------+----------------+ +| Allow | | edit | ++----------+--------------------+----------------+ + +Permission declarations will be added to the views to assert the security +policies as each request is handled. + +On the security side of the application there are two additional views for +handling login and logout as well as two exception views for handling +invalid access attempts and unhandled URLs. Summary ------- @@ -102,7 +116,7 @@ in the following table: | | submitted, redirect | | | | | | to /PageName | | | | +----------------------+-----------------------+-------------+----------------+------------+ -| /add_page/PageName | Create the page | add_page | edit.jinja2 | edit | +| /add_page/PageName | Create the page | add_page | edit.jinja2 | create | | | *PageName* in | | | | | | storage, display | | | | | | the edit form | | | | -- cgit v1.2.3 From a115c6d30fe8e497f67604370db4ffc8f2b124a9 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Fri, 12 Feb 2016 02:42:04 -0600 Subject: add the bcrypt dependency --- docs/tutorials/wiki2/design.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs/tutorials/wiki2/design.rst') diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst index 42f06f7bf..de43447d3 100644 --- a/docs/tutorials/wiki2/design.rst +++ b/docs/tutorials/wiki2/design.rst @@ -21,12 +21,14 @@ We'll be using an SQLite database to hold our wiki data, and we'll be using Within the database, we will define two tables: -- The `users` table which will store the `name`, `password_hash` and `role`. +- The `users` table which will store the `id`, `name`, `password_hash` and + `role` of each wiki user. - The `pages` table, whose elements will store the wiki pages. - There are three columns: `name`, `data` and `creator_id`. + There are four columns: `id`, `name`, `data` and `creator_id`. There is a one-to-many relationship between `users` and `pages` tracking -the user who created each wiki page. +the user who created each wiki page defined by the `creator_id` column on the +`pages` table. URLs like ``/PageName`` will try to find an element in the `pages` table that has a corresponding name. -- cgit v1.2.3 From 23c2d7b337a5873dba0ca6c146e1174136ac2187 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Fri, 12 Feb 2016 02:54:37 -0600 Subject: update the views/models with setup.py develop --- docs/tutorials/wiki2/design.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/tutorials/wiki2/design.rst') diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst index de43447d3..45e2fddd0 100644 --- a/docs/tutorials/wiki2/design.rst +++ b/docs/tutorials/wiki2/design.rst @@ -6,7 +6,7 @@ Following is a quick overview of the design of our wiki application to help us understand the changes that we will be making as we work through the tutorial. Overall -------- +======= We choose to use :term:`reStructuredText` markup in the wiki text. Translation from reStructuredText to HTML is provided by the widely used ``docutils`` @@ -14,7 +14,7 @@ Python module. We will add this module in the dependency list on the project ``setup.py`` file. Models ------- +====== We'll be using an SQLite database to hold our wiki data, and we'll be using :term:`SQLAlchemy` to access the data in this database. @@ -41,7 +41,7 @@ be created when the storage is initialized, and will be used as the wiki home page. Wiki Views ----------- +========== There will be three views to handle the normal operations of adding, editing, and viewing wiki pages, plus one view for the wiki front page. Two templates @@ -53,7 +53,7 @@ designer-friendly templating language for Python, modeled after Django's templates. Security --------- +======== We'll eventually be adding security to our application. To do this, we'll be using a very simple role-based security model. We'll assign a single @@ -92,7 +92,7 @@ handling login and logout as well as two exception views for handling invalid access attempts and unhandled URLs. Summary -------- +======= The URL, actions, template, and permission associated to each view are listed in the following table: -- cgit v1.2.3 From 6a2bdac1ec3b1fb6ed37bc8b92b807df6c0fa07d Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 21 Feb 2016 03:21:10 -0800 Subject: wiki2 docs update WIP - minor grammar, .rst syntax - add pip to glossary - add pip instructions, commented until 1.7 is released --- docs/tutorials/wiki2/design.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/tutorials/wiki2/design.rst') diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst index 45e2fddd0..929bc7806 100644 --- a/docs/tutorials/wiki2/design.rst +++ b/docs/tutorials/wiki2/design.rst @@ -10,7 +10,7 @@ Overall We choose to use :term:`reStructuredText` markup in the wiki text. Translation from reStructuredText to HTML is provided by the widely used ``docutils`` -Python module. We will add this module in the dependency list on the project +Python module. We will add this module to the dependency list in the project's ``setup.py`` file. Models -- cgit v1.2.3 From 93fa23ae1463e78230cc3af8ecb89a6813b5556b Mon Sep 17 00:00:00 2001 From: Bert JW Regeer Date: Sun, 21 Feb 2016 15:51:55 -0700 Subject: Remove references to pip --- docs/tutorials/wiki2/design.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/tutorials/wiki2/design.rst') diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst index 929bc7806..45e2fddd0 100644 --- a/docs/tutorials/wiki2/design.rst +++ b/docs/tutorials/wiki2/design.rst @@ -10,7 +10,7 @@ Overall We choose to use :term:`reStructuredText` markup in the wiki text. Translation from reStructuredText to HTML is provided by the widely used ``docutils`` -Python module. We will add this module to the dependency list in the project's +Python module. We will add this module in the dependency list on the project ``setup.py`` file. Models -- cgit v1.2.3 From 1c0a3d7e326b06dc4ea0e015ab25c4dedb754342 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 21 Feb 2016 23:12:19 -0800 Subject: revert a couple of the reversions --- docs/tutorials/wiki2/design.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/tutorials/wiki2/design.rst') diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst index 45e2fddd0..929bc7806 100644 --- a/docs/tutorials/wiki2/design.rst +++ b/docs/tutorials/wiki2/design.rst @@ -10,7 +10,7 @@ Overall We choose to use :term:`reStructuredText` markup in the wiki text. Translation from reStructuredText to HTML is provided by the widely used ``docutils`` -Python module. We will add this module in the dependency list on the project +Python module. We will add this module to the dependency list in the project's ``setup.py`` file. Models -- cgit v1.2.3 From 492b800ab252521380c465c259a78cc77c934309 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 26 Feb 2016 22:55:48 -0800 Subject: minor grammar --- docs/tutorials/wiki2/design.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/tutorials/wiki2/design.rst') diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst index 929bc7806..a57b318ca 100644 --- a/docs/tutorials/wiki2/design.rst +++ b/docs/tutorials/wiki2/design.rst @@ -139,8 +139,8 @@ in the following table: | | - If authentication | | | | | | succeeds, | | | | | | redirect to the | | | | -| | page that we | | | | -| | came from. | | | | +| | page that from | | | | +| | which we came. | | | | | | | | | | | | - If authentication | | | | | | fails, display | | | | -- cgit v1.2.3 From f63feb6c3f71f00389ce04f1100ae5675c748557 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 27 Feb 2016 03:47:53 -0800 Subject: grammar fix --- docs/tutorials/wiki2/design.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/tutorials/wiki2/design.rst') diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst index a57b318ca..ba25b0697 100644 --- a/docs/tutorials/wiki2/design.rst +++ b/docs/tutorials/wiki2/design.rst @@ -139,8 +139,8 @@ in the following table: | | - If authentication | | | | | | succeeds, | | | | | | redirect to the | | | | -| | page that from | | | | -| | which we came. | | | | +| | page from which | | | | +| | we came. | | | | | | | | | | | | - If authentication | | | | | | fails, display | | | | -- cgit v1.2.3