From bb754144b1c0d3c75156385ea8c6e20ddda6d430 Mon Sep 17 00:00:00 2001 From: Patricio Paez Date: Mon, 12 Mar 2012 14:32:54 -0700 Subject: Added the Design chapter on both wiki tutorials --- docs/tutorials/wiki2/design.rst | 132 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 docs/tutorials/wiki2/design.rst (limited to 'docs/tutorials/wiki2/design.rst') diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst new file mode 100644 index 000000000..ade40ab18 --- /dev/null +++ b/docs/tutorials/wiki2/design.rst @@ -0,0 +1,132 @@ +========== +Design +========== + +Following is a quick overview of our wiki application, to help +us understand the changes that we will be doing next in our +default files generated by the paster scafffold. + +Overall +------- + +We choose to use ``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 ``setup.py`` file. + +Models +------ + +We define a single table named `tables`, 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 whose `name` corresponds. + +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 page. + +Views +----- + +There will be four views to handle the normal operations of +viewing, editing and adding wiki pages. Two additional views +will handle the login and logout tasks related to security. + +Security +-------- + +- USERS, a dictionary mapping users names to their + corresponding passwords. +- GROUPS, a dictionary mapping user names to a + list of groups they belong to. +- *groupfinder*, an *authorization callback* that looks up + USERS and GROUPS. It will be provided in a new + *security.py* file. +- An :term:`ACL` is attached to the root resource. Each + row below details an :term:`ACE`: + + +----------+----------------+----------------+ + | Action | Principal | Permission | + +==========+================+================+ + | Allow | Everyone | View | + +----------+----------------+----------------+ + | Allow | group:editors | Edit | + +----------+----------------+----------------+ + +- Permission declarations for the views. + + +Summary +------- + +The URL, context, actions, template and permission associated to each view are +listed in the following table: + ++----------------------+-------------+-----------------+-----------------------+------------+------------+ +| URL | View | Context | Action | Template | Permission | +| | | | | | | ++======================+=============+=================+=======================+============+============+ +| / | view_wiki | Wiki | Redirect to | | | +| | | | /FrontPage | | | ++----------------------+-------------+-----------------+-----------------------+------------+------------+ +| /PageName | view_page | Page | Display existing | view.pt | view | +| | [1]_ | | page [2]_ | | | +| | | | | | | +| | | | | | | +| | | | | | | ++----------------------+-------------+-----------------+-----------------------+------------+------------+ +| /edit_page/PageName | edit_page | Page | Display edit form | edit.pt | edit | +| | | | with existing | | | +| | | | content. | | | +| | | | | | | +| | | | If the form was | | | +| | | | submitted, redirect | | | +| | | | to /PageName | | | ++----------------------+-------------+-----------------+-----------------------+------------+------------+ +| /add_page/PageName | add_page | Wiki | Create the page | edit.pt | edit | +| | | | *PageName* in | | | +| | | | storage, display | | | +| | | | the edit form | | | +| | | | without content. | | | +| | | | | | | +| | | | If the form was | | | +| | | | submitted, | | | +| | | | redirect to | | | +| | | | /PageName | | | ++----------------------+-------------+-----------------+-----------------------+------------+------------+ +| /login | login | Wiki, | Display login form. | login.pt | | +| | | Forbidden [3]_ | | | | +| | | | If the form was | | | +| | | | submitted, | | | +| | | | authenticate. | | | +| | | | | | | +| | | | - If authentication | | | +| | | | successful, | | | +| | | | redirect to the | | | +| | | | page that we | | | +| | | | came from. | | | +| | | | | | | +| | | | - If authentication | | | +| | | | fails, display | | | +| | | | login form with | | | +| | | | "login failed" | | | +| | | | message. | | | +| | | | | | | ++----------------------+-------------+-----------------+-----------------------+------------+------------+ +| /logout | logout | Wiki | Redirect to | | | +| | | | /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 95e70fb95b0783d380885d6c35d3925043f82531 Mon Sep 17 00:00:00 2001 From: Patricio Paez Date: Wed, 14 Mar 2012 12:26:00 -0700 Subject: Simplify the summary table - Removed the Context column - Swapped Action and View columns --- docs/tutorials/wiki2/design.rst | 110 ++++++++++++++++++++-------------------- 1 file changed, 55 insertions(+), 55 deletions(-) (limited to 'docs/tutorials/wiki2/design.rst') diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst index ade40ab18..36c4f19bc 100644 --- a/docs/tutorials/wiki2/design.rst +++ b/docs/tutorials/wiki2/design.rst @@ -65,63 +65,63 @@ Security Summary ------- -The URL, context, actions, template and permission associated to each view are +The URL, actions, template and permission associated to each view are listed in the following table: -+----------------------+-------------+-----------------+-----------------------+------------+------------+ -| URL | View | Context | Action | Template | Permission | -| | | | | | | -+======================+=============+=================+=======================+============+============+ -| / | view_wiki | Wiki | Redirect to | | | -| | | | /FrontPage | | | -+----------------------+-------------+-----------------+-----------------------+------------+------------+ -| /PageName | view_page | Page | Display existing | view.pt | view | -| | [1]_ | | page [2]_ | | | -| | | | | | | -| | | | | | | -| | | | | | | -+----------------------+-------------+-----------------+-----------------------+------------+------------+ -| /edit_page/PageName | edit_page | Page | Display edit form | edit.pt | edit | -| | | | with existing | | | -| | | | content. | | | -| | | | | | | -| | | | If the form was | | | -| | | | submitted, redirect | | | -| | | | to /PageName | | | -+----------------------+-------------+-----------------+-----------------------+------------+------------+ -| /add_page/PageName | add_page | Wiki | Create the page | edit.pt | edit | -| | | | *PageName* in | | | -| | | | storage, display | | | -| | | | the edit form | | | -| | | | without content. | | | -| | | | | | | -| | | | If the form was | | | -| | | | submitted, | | | -| | | | redirect to | | | -| | | | /PageName | | | -+----------------------+-------------+-----------------+-----------------------+------------+------------+ -| /login | login | Wiki, | Display login form. | login.pt | | -| | | Forbidden [3]_ | | | | -| | | | If the form was | | | -| | | | submitted, | | | -| | | | authenticate. | | | -| | | | | | | -| | | | - If authentication | | | -| | | | successful, | | | -| | | | redirect to the | | | -| | | | page that we | | | -| | | | came from. | | | -| | | | | | | -| | | | - If authentication | | | -| | | | fails, display | | | -| | | | login form with | | | -| | | | "login failed" | | | -| | | | message. | | | -| | | | | | | -+----------------------+-------------+-----------------+-----------------------+------------+------------+ -| /logout | logout | Wiki | Redirect to | | | -| | | | /FrontPage | | | -+----------------------+-------------+-----------------+-----------------------+------------+------------+ ++----------------------+-----------------------+-------------+------------+------------+ +| URL | Action | View | Template | Permission | +| | | | | | ++======================+=======================+=============+============+============+ +| / | Redirect to | view_wiki | | | +| | /FrontPage | | | | ++----------------------+-----------------------+-------------+------------+------------+ +| /PageName | Display existing | view_page | view.pt | view | +| | page [2]_ | [1]_ | | | +| | | | | | +| | | | | | +| | | | | | ++----------------------+-----------------------+-------------+------------+------------+ +| /edit_page/PageName | 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 | | +| | | | | | +| | If the form was | | | | +| | submitted, | | | | +| | authenticate. | | | | +| | | | | | +| | - If authentication | | | | +| | successful, | | | | +| | 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. -- cgit v1.2.3 From b3e608bac815a7d3fc639d78ec38edc5f97df859 Mon Sep 17 00:00:00 2001 From: Doug Latornell Date: Sat, 17 Mar 2012 09:27:13 -0700 Subject: Improve text of SQLAlchemy wiki tutorial. A mixture of typo fixes and wording improvements. --- docs/tutorials/wiki2/design.rst | 12 +++++++----- 1 file changed, 7 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 36c4f19bc..75122bd11 100644 --- a/docs/tutorials/wiki2/design.rst +++ b/docs/tutorials/wiki2/design.rst @@ -4,7 +4,7 @@ Design Following is a quick overview of our wiki application, to help us understand the changes that we will be doing next in our -default files generated by the paster scafffold. +default files generated by the ``alchemy`` scaffold. Overall ------- @@ -34,9 +34,10 @@ be used as the wiki home page. Views ----- -There will be four views to handle the normal operations of -viewing, editing and adding wiki pages. Two additional views -will handle the login and logout tasks related to security. +There will be four views to handle the normal operations of adding and +editing wiki pages, and viewing pages and the wiki front page. Two +additional views will handle the login and logout tasks related to +security. Security -------- @@ -59,7 +60,8 @@ Security | Allow | group:editors | Edit | +----------+----------------+----------------+ -- Permission declarations for the views. +- Permission declarations are added to the views to assert the + security policies as each request is handled. Summary -- cgit v1.2.3 From e9759f3ae42f68ab8dd6739dd07df0098d7e373a Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 17 Mar 2012 14:07:41 -0400 Subject: add various elements to design document --- docs/tutorials/wiki2/design.rst | 58 ++++++++++++++++++++++------------------- 1 file changed, 31 insertions(+), 27 deletions(-) (limited to 'docs/tutorials/wiki2/design.rst') diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst index 75122bd11..1ff000549 100644 --- a/docs/tutorials/wiki2/design.rst +++ b/docs/tutorials/wiki2/design.rst @@ -2,55 +2,59 @@ Design ========== -Following is a quick overview of our wiki application, to help -us understand the changes that we will be doing next in our -default files generated by the ``alchemy`` scaffold. +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 ``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 ``setup.py`` file. +We choose to use ``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 +``setup.py`` file. Models ------ -We define a single table named `tables`, whose elements will -store the wiki pages. There are two columns: `name` and -`data`. +We'll be using a 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 `tables`, 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 whose `name` corresponds. +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`. -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. +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 ----- There will be four views to handle the normal operations of adding and editing wiki pages, and viewing pages and the wiki front page. Two -additional views will handle the login and logout tasks related to -security. +additional views will handle the login and logout tasks related to security. Security -------- -- USERS, a dictionary mapping users names to their - corresponding passwords. -- GROUPS, a dictionary mapping user names to a - list of groups they belong to. -- *groupfinder*, an *authorization callback* that looks up - USERS and GROUPS. It will be provided in a new - *security.py* file. -- An :term:`ACL` is attached to the root resource. Each - row below details an :term:`ACE`: +We'll eventually be adding security to our application. The components we'll +use to do this are below. + +- USERS, a dictionary mapping users names to their corresponding passwords. + +- GROUPS, a dictionary mapping user names to a list of groups they belong to. + +- ``groupfinder``, an *authorization callback* that looks up USERS and + GROUPS. It will be provided in a new *security.py* file. + +- An :term:`ACL` is attached to the root :term:`resource`. Each row below + details an :term:`ACE`: +----------+----------------+----------------+ | Action | Principal | Permission | @@ -60,8 +64,8 @@ Security | Allow | group:editors | Edit | +----------+----------------+----------------+ -- Permission declarations are added to the views to assert the - security policies as each request is handled. +- Permission declarations are added to the views to assert the security + policies as each request is handled. Summary -- cgit v1.2.3 From 89e011e72ae8bbec1e6d91cfbe7be83e2352d6fd Mon Sep 17 00:00:00 2001 From: Patricio Paez Date: Fri, 6 Apr 2012 17:51:53 -0500 Subject: Added first level sections, fixed route in the summary --- 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 1ff000549..4481153a3 100644 --- a/docs/tutorials/wiki2/design.rst +++ b/docs/tutorials/wiki2/design.rst @@ -87,7 +87,7 @@ listed in the following table: | | | | | | | | | | | | +----------------------+-----------------------+-------------+------------+------------+ -| /edit_page/PageName | Display edit form | edit_page | edit.pt | edit | +| /PageName/edit_page | Display edit form | edit_page | edit.pt | edit | | | with existing | | | | | | content. | | | | | | | | | | -- cgit v1.2.3 From f97aa6332c08d5edb35665a7afda2aefd98f662b Mon Sep 17 00:00:00 2001 From: Patricio Paez Date: Fri, 13 Apr 2012 13:10:00 -0500 Subject: Simplify the introduction - Moved the selection of the templates to the Design chapter - Improved the Views section in the Design chapter - Normalize in both tutorials --- docs/tutorials/wiki2/design.rst | 15 ++++++++++++--- 1 file changed, 12 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 4481153a3..2e6fc0e77 100644 --- a/docs/tutorials/wiki2/design.rst +++ b/docs/tutorials/wiki2/design.rst @@ -36,9 +36,16 @@ page. Views ----- -There will be four views to handle the normal operations of adding and -editing wiki pages, and viewing pages and the wiki front page. Two -additional views will handle the login and logout tasks related to security. +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 for 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. Security -------- @@ -67,6 +74,8 @@ 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. Summary ------- -- cgit v1.2.3 From 70ba5b97f53ac178dac8f81109596fb47bbadde5 Mon Sep 17 00:00:00 2001 From: Siddhartha Kasivajhula Date: Sat, 21 Jul 2012 14:29:00 -0700 Subject: corrected table name tables->pages --- 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 2e6fc0e77..deaf32ef6 100644 --- a/docs/tutorials/wiki2/design.rst +++ b/docs/tutorials/wiki2/design.rst @@ -20,7 +20,7 @@ Models We'll be using a 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 `tables`, whose elements +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 -- cgit v1.2.3 From 2208c2cca8f44a9fff547131b3adda8fac8e2829 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 16 Sep 2012 14:45:07 -0400 Subject: add link to forbidden footnote ref issue #671 --- docs/tutorials/wiki2/design.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/tutorials/wiki2/design.rst') diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst index deaf32ef6..6e41e00aa 100644 --- a/docs/tutorials/wiki2/design.rst +++ b/docs/tutorials/wiki2/design.rst @@ -115,7 +115,8 @@ listed in the following table: | | redirect to | | | | | | /PageName | | | | +----------------------+-----------------------+-------------+------------+------------+ -| /login | Display login form. | login | login.pt | | +| /login | Display login form, | login | login.pt | | +| | Forbidden [3]_ | | | | | | | | | | | | If the form was | | | | | | submitted, | | | | -- cgit v1.2.3 From b9b2ee39c251dd68a12e717e1f6d9d02a29efe9a Mon Sep 17 00:00:00 2001 From: Marc Abramowitz Date: Fri, 30 Nov 2012 09:27:09 -0800 Subject: A bunch of minor tweaks to the wiki2 tutorial in docs/tutorials/wiki2 --- 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 6e41e00aa..c56d7fecf 100644 --- a/docs/tutorials/wiki2/design.rst +++ b/docs/tutorials/wiki2/design.rst @@ -9,7 +9,7 @@ tutorial. Overall ------- -We choose to use ``reStructuredText`` markup in the wiki text. Translation +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 ``setup.py`` file. -- cgit v1.2.3 From e9a4205c4c96471313d170f2c74eba1c3c36ca00 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Mon, 25 Mar 2013 22:11:56 +0200 Subject: use clearer language --- docs/tutorials/wiki2/design.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/tutorials/wiki2/design.rst') diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst index c56d7fecf..df2c83398 100644 --- a/docs/tutorials/wiki2/design.rst +++ b/docs/tutorials/wiki2/design.rst @@ -100,7 +100,7 @@ listed in the following table: | | with existing | | | | | | content. | | | | | | | | | | -| | If the form was | | | | +| | If the form is | | | | | | submitted, redirect | | | | | | to /PageName | | | | +----------------------+-----------------------+-------------+------------+------------+ @@ -110,15 +110,15 @@ listed in the following table: | | the edit form | | | | | | without content. | | | | | | | | | | -| | If the form was | | | | +| | If the form is | | | | | | submitted, | | | | | | redirect to | | | | | | /PageName | | | | +----------------------+-----------------------+-------------+------------+------------+ | /login | Display login form, | login | login.pt | | -| | Forbidden [3]_ | | | | +| | Forbidden [3]_ | | | | | | | | | | -| | If the form was | | | | +| | If the form is | | | | | | submitted, | | | | | | authenticate. | | | | | | | | | | -- cgit v1.2.3 From dc324784193a577bc039dcddb0651ef5ec9e6f57 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Tue, 12 Aug 2014 22:12:25 -0500 Subject: Docs: Make "userid" link to the glossary term. --- docs/tutorials/wiki2/design.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/tutorials/wiki2/design.rst') diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst index df2c83398..ff7413668 100644 --- a/docs/tutorials/wiki2/design.rst +++ b/docs/tutorials/wiki2/design.rst @@ -53,7 +53,8 @@ Security We'll eventually be adding security to our application. The components we'll use to do this are below. -- USERS, a dictionary mapping users names to their corresponding passwords. +- USERS, a dictionary mapping users names (the user's :term:`userids + `) to their corresponding passwords. - GROUPS, a dictionary mapping user names to a list of groups they belong to. -- cgit v1.2.3 From ee9676a8691dd18b88d3247fd8c1306c5aaa1543 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 24 May 2015 19:15:22 -0700 Subject: - make templates html5 compliant - punctuation, grammar, spelling - fix linenos references - update outputs --- 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 ff7413668..fa291cdc0 100644 --- a/docs/tutorials/wiki2/design.rst +++ b/docs/tutorials/wiki2/design.rst @@ -124,7 +124,7 @@ listed in the following table: | | authenticate. | | | | | | | | | | | | - If authentication | | | | -| | successful, | | | | +| | succeeds, | | | | | | redirect to the | | | | | | page that we | | | | | | came from. | | | | @@ -144,6 +144,6 @@ listed in the following table: 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 +.. [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 3e6b601d9bc557b5b698d5fd4d6eb20b151a424f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 25 May 2015 13:53:05 -0700 Subject: cherry pick from 1.5-branch --- docs/tutorials/wiki2/design.rst | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) (limited to 'docs/tutorials/wiki2/design.rst') diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst index fa291cdc0..e9f361e7d 100644 --- a/docs/tutorials/wiki2/design.rst +++ b/docs/tutorials/wiki2/design.rst @@ -9,7 +9,7 @@ tutorial. Overall ------- -We choose to use :term:`reStructuredText` markup in the wiki text. Translation +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 ``setup.py`` file. @@ -37,8 +37,8 @@ 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 for 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 @@ -53,13 +53,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 users names (the user's :term:`userids - `) to their corresponding passwords. +- USERS, a dictionary mapping :term:`userids ` to their + corresponding passwords. -- GROUPS, a dictionary mapping user names to a list of groups they belong to. +- 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. + GROUPS. It will be provided in a new ``security.py`` file. - An :term:`ACL` is attached to the root :term:`resource`. Each row below details an :term:`ACE`: @@ -101,7 +102,7 @@ listed in the following table: | | with existing | | | | | | content. | | | | | | | | | | -| | If the form is | | | | +| | If the form was | | | | | | submitted, redirect | | | | | | to /PageName | | | | +----------------------+-----------------------+-------------+------------+------------+ @@ -111,7 +112,7 @@ listed in the following table: | | the edit form | | | | | | without content. | | | | | | | | | | -| | If the form is | | | | +| | If the form was | | | | | | submitted, | | | | | | redirect to | | | | | | /PageName | | | | @@ -119,7 +120,7 @@ listed in the following table: | /login | Display login form, | login | login.pt | | | | Forbidden [3]_ | | | | | | | | | | -| | If the form is | | | | +| | If the form was | | | | | | submitted, | | | | | | authenticate. | | | | | | | | | | -- cgit v1.2.3 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 From 640d7779b69f49ab11d7e276a7548684524bc215 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 9 Apr 2016 13:36:11 -0700 Subject: - add intersphinx targets --- docs/tutorials/wiki2/design.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/tutorials/wiki2/design.rst') diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst index ba25b0697..523a6e6d8 100644 --- a/docs/tutorials/wiki2/design.rst +++ b/docs/tutorials/wiki2/design.rst @@ -1,3 +1,5 @@ +.. _wiki2_design: + ====== Design ====== -- cgit v1.2.3