From bfa4994ab0d1327c451509f466ccebbad8fa2320 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 12 Nov 2015 03:02:11 -0800 Subject: update wiki2/src/models and wiki2/definingmodels.rst --- docs/tutorials/wiki2/definingmodels.rst | 49 +++++++++++++++++++++++---------- 1 file changed, 34 insertions(+), 15 deletions(-) (limited to 'docs/tutorials/wiki2/definingmodels.rst') diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst index b2d9bf83a..b38177d04 100644 --- a/docs/tutorials/wiki2/definingmodels.rst +++ b/docs/tutorials/wiki2/definingmodels.rst @@ -4,27 +4,27 @@ Defining the Domain Model The first change we'll make to our stock ``pcreate``-generated application will be to define a :term:`domain model` constructor representing a wiki page. -We'll do this inside our ``models.py`` file. +We'll do this inside our ``mymodel.py`` file. -Edit ``models.py`` ------------------- +Edit ``mymodel.py`` +------------------- .. note:: - There is nothing special about the filename ``models.py``. A + There is nothing special about the filename ``mymodel.py``. A project may have many models throughout its codebase in arbitrarily named files. Files implementing models often have ``model`` in their filenames or they may live in a Python subpackage of your application package named - ``models``, but this is only by convention. + ``models`` (as we've done in this tutorial), but this is only by convention. -Open ``tutorial/tutorial/models.py`` file and edit it to look like the -following: +Open the ``tutorial/tutorial/models/mymodel.py`` file and edit it to look like +the following: -.. literalinclude:: src/models/tutorial/models.py +.. literalinclude:: src/models/tutorial/models/mymodel.py :linenos: :language: py - :emphasize-lines: 20-22,24,25 + :emphasize-lines: 9-11,13,14 The highlighted lines are the ones that need to be changed, as well as removing lines that reference ``Index``. @@ -33,11 +33,11 @@ The first thing we've done is remove the stock ``MyModel`` class from the generated ``models.py`` file. The ``MyModel`` class is only a sample and we're not going to use it. -Then, we added a ``Page`` class. Because this is a SQLAlchemy application, +Then we added a ``Page`` class. Because this is an SQLAlchemy application, this class inherits from an instance of :func:`sqlalchemy.ext.declarative.declarative_base`. -.. literalinclude:: src/models/tutorial/models.py +.. literalinclude:: src/models/tutorial/models/mymodel.py :pyobject: Page :linenos: :language: python @@ -45,15 +45,33 @@ this class inherits from an instance of As you can see, our ``Page`` class has a class level attribute ``__tablename__`` which equals the string ``'pages'``. This means that SQLAlchemy will store our wiki data in a SQL table named ``pages``. Our -``Page`` class will also have class-level attributes named ``id``, ``name`` +``Page`` class will also have class-level attributes named ``id``, ``name``, and ``data`` (all instances of :class:`sqlalchemy.schema.Column`). These will map to columns in the ``pages`` table. The ``id`` attribute will be the primary key in the table. The ``name`` attribute will be a text attribute, each value of which needs to be unique within the column. The ``data`` attribute is a text attribute that will hold the body of each page. -Changing ``scripts/initializedb.py`` ------------------------------------- + +Edit ``models/__init__.py`` +--------------------------- + +Since we are using a package for our models, we also need to update our +``__init__.py`` file. + +Open the ``tutorial/tutorial/models/__init__.py`` file and edit it to look like +the following: + +.. literalinclude:: src/models/tutorial/models/__init__.py + :linenos: + :language: py + :emphasize-lines: 4 + +Here we need to align our import with the name of the model ``Page``. + + +Edit ``scripts/initializedb.py`` +-------------------------------- We haven't looked at the details of this file yet, but within the ``scripts`` directory of your ``tutorial`` package is a file named ``initializedb.py``. @@ -72,12 +90,13 @@ the following: .. literalinclude:: src/models/tutorial/scripts/initializedb.py :linenos: :language: python - :emphasize-lines: 14,31,36 + :emphasize-lines: 16,31,41 Only the highlighted lines need to be changed, as well as removing the lines referencing ``pyramid.scripts.common`` and ``options`` under the ``main`` function. + Installing the project and re-initializing the database ------------------------------------------------------- -- cgit v1.2.3 From d1cb34643e086ac74965455b486ce0058764324f Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Sun, 7 Feb 2016 13:57:51 -0600 Subject: assume the user is in the tutorial folder this is already assumed inside of installation where commands are run relative to setup.py --- docs/tutorials/wiki2/definingmodels.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'docs/tutorials/wiki2/definingmodels.rst') diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst index b38177d04..9b517994f 100644 --- a/docs/tutorials/wiki2/definingmodels.rst +++ b/docs/tutorials/wiki2/definingmodels.rst @@ -14,11 +14,12 @@ Edit ``mymodel.py`` There is nothing special about the filename ``mymodel.py``. A project may have many models throughout its codebase in arbitrarily named - files. Files implementing models often have ``model`` in their filenames - or they may live in a Python subpackage of your application package named - ``models`` (as we've done in this tutorial), but this is only by convention. + modules. Modules implementing models often have ``model`` in their + names or they may live in a Python subpackage of your application package + named ``models`` (as we've done in this tutorial), but this is only a + convention and not a requirement. -Open the ``tutorial/tutorial/models/mymodel.py`` file and edit it to look like +Open the ``tutorial/models/mymodel.py`` file and edit it to look like the following: .. literalinclude:: src/models/tutorial/models/mymodel.py @@ -59,7 +60,7 @@ Edit ``models/__init__.py`` Since we are using a package for our models, we also need to update our ``__init__.py`` file. -Open the ``tutorial/tutorial/models/__init__.py`` file and edit it to look like +Open the ``tutorial/models/__init__.py`` file and edit it to look like the following: .. literalinclude:: src/models/tutorial/models/__init__.py @@ -84,7 +85,7 @@ Since we've changed our model, we need to make changes to our to create a ``Page`` rather than a ``MyModel`` and add it to our ``DBSession``. -Open ``tutorial/tutorial/scripts/initializedb.py`` and edit it to look like +Open ``tutorial/scripts/initializedb.py`` and edit it to look like the following: .. literalinclude:: src/models/tutorial/scripts/initializedb.py -- cgit v1.2.3 From d6243ac1e7724cce26a738de5b86f187ef444e77 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Sun, 7 Feb 2016 15:29:17 -0600 Subject: update definingmodels chapter of wiki2 tutorial --- docs/tutorials/wiki2/definingmodels.rst | 32 +++++++++++++++----------------- 1 file changed, 15 insertions(+), 17 deletions(-) (limited to 'docs/tutorials/wiki2/definingmodels.rst') diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst index 9b517994f..b90bf77e6 100644 --- a/docs/tutorials/wiki2/definingmodels.rst +++ b/docs/tutorials/wiki2/definingmodels.rst @@ -3,7 +3,7 @@ Defining the Domain Model ========================= The first change we'll make to our stock ``pcreate``-generated application will -be to define a :term:`domain model` constructor representing a wiki page. +be to define a wiki page :term:`domain model`. We'll do this inside our ``mymodel.py`` file. @@ -12,12 +12,12 @@ Edit ``mymodel.py`` .. note:: - There is nothing special about the filename ``mymodel.py``. A - project may have many models throughout its codebase in arbitrarily named - modules. Modules implementing models often have ``model`` in their - names or they may live in a Python subpackage of your application package - named ``models`` (as we've done in this tutorial), but this is only a - convention and not a requirement. + There is nothing special about the filename ``mymodel.py`` except that it + is a Python module. A project may have many models throughout its codebase + in arbitrarily named modules. Modules implementing models often have + ``model`` in their names or they may live in a Python subpackage of your + application package named ``models`` (as we've done in this tutorial), but + this is only a convention and not a requirement. Open the ``tutorial/models/mymodel.py`` file and edit it to look like the following: @@ -25,7 +25,7 @@ the following: .. literalinclude:: src/models/tutorial/models/mymodel.py :linenos: :language: py - :emphasize-lines: 9-11,13,14 + :emphasize-lines: 10-12,14-15 The highlighted lines are the ones that need to be changed, as well as removing lines that reference ``Index``. @@ -34,7 +34,7 @@ The first thing we've done is remove the stock ``MyModel`` class from the generated ``models.py`` file. The ``MyModel`` class is only a sample and we're not going to use it. -Then we added a ``Page`` class. Because this is an SQLAlchemy application, +Then we added a ``Page`` class. Because this is a SQLAlchemy application, this class inherits from an instance of :func:`sqlalchemy.ext.declarative.declarative_base`. @@ -43,7 +43,7 @@ this class inherits from an instance of :linenos: :language: python -As you can see, our ``Page`` class has a class level attribute +As you can see, our ``Page`` class has a class-level attribute ``__tablename__`` which equals the string ``'pages'``. This means that SQLAlchemy will store our wiki data in a SQL table named ``pages``. Our ``Page`` class will also have class-level attributes named ``id``, ``name``, @@ -58,7 +58,7 @@ Edit ``models/__init__.py`` --------------------------- Since we are using a package for our models, we also need to update our -``__init__.py`` file. +``__init__.py`` file to ensure that the model is attached to the metadata. Open the ``tutorial/models/__init__.py`` file and edit it to look like the following: @@ -66,7 +66,7 @@ the following: .. literalinclude:: src/models/tutorial/models/__init__.py :linenos: :language: py - :emphasize-lines: 4 + :emphasize-lines: 8 Here we need to align our import with the name of the model ``Page``. @@ -83,7 +83,7 @@ Since we've changed our model, we need to make changes to our ``initializedb.py`` script. In particular, we'll replace our import of ``MyModel`` with one of ``Page`` and we'll change the very end of the script to create a ``Page`` rather than a ``MyModel`` and add it to our -``DBSession``. +``dbsession``. Open ``tutorial/scripts/initializedb.py`` and edit it to look like the following: @@ -91,11 +91,9 @@ the following: .. literalinclude:: src/models/tutorial/scripts/initializedb.py :linenos: :language: python - :emphasize-lines: 16,31,41 + :emphasize-lines: 18,44-45 -Only the highlighted lines need to be changed, as well as removing the lines -referencing ``pyramid.scripts.common`` and ``options`` under the ``main`` -function. +Only the highlighted lines need to be changed. Installing the project and re-initializing the database -- 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/definingmodels.rst | 65 ++++++++++++++++++++++----------- 1 file changed, 43 insertions(+), 22 deletions(-) (limited to 'docs/tutorials/wiki2/definingmodels.rst') diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst index b90bf77e6..5af8110da 100644 --- a/docs/tutorials/wiki2/definingmodels.rst +++ b/docs/tutorials/wiki2/definingmodels.rst @@ -106,28 +106,49 @@ made to both the models.py file and to the initializedb.py file. See Success will look something like this:: - 2015-05-24 15:34:14,542 INFO [sqlalchemy.engine.base.Engine:1192][MainThread] SELECT CAST('test plain returns' AS VARCHAR(60)) AS anon_1 - 2015-05-24 15:34:14,542 INFO [sqlalchemy.engine.base.Engine:1193][MainThread] () - 2015-05-24 15:34:14,543 INFO [sqlalchemy.engine.base.Engine:1192][MainThread] SELECT CAST('test unicode returns' AS VARCHAR(60)) AS anon_1 - 2015-05-24 15:34:14,543 INFO [sqlalchemy.engine.base.Engine:1193][MainThread] () - 2015-05-24 15:34:14,543 INFO [sqlalchemy.engine.base.Engine:1097][MainThread] PRAGMA table_info("pages") - 2015-05-24 15:34:14,544 INFO [sqlalchemy.engine.base.Engine:1100][MainThread] () - 2015-05-24 15:34:14,544 INFO [sqlalchemy.engine.base.Engine:1097][MainThread] - CREATE TABLE pages ( - id INTEGER NOT NULL, - name TEXT, - data TEXT, - PRIMARY KEY (id), - UNIQUE (name) - ) - - - 2015-05-24 15:34:14,545 INFO [sqlalchemy.engine.base.Engine:1100][MainThread] () - 2015-05-24 15:34:14,546 INFO [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT - 2015-05-24 15:34:14,548 INFO [sqlalchemy.engine.base.Engine:646][MainThread] BEGIN (implicit) - 2015-05-24 15:34:14,549 INFO [sqlalchemy.engine.base.Engine:1097][MainThread] INSERT INTO pages (name, data) VALUES (?, ?) - 2015-05-24 15:34:14,549 INFO [sqlalchemy.engine.base.Engine:1100][MainThread] ('FrontPage', 'This is the front page') - 2015-05-24 15:34:14,550 INFO [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT + 2016-02-12 01:06:35,855 INFO [sqlalchemy.engine.base.Engine:1192][MainThread] SELECT CAST('test plain returns' AS VARCHAR(60)) AS anon_1 + 2016-02-12 01:06:35,855 INFO [sqlalchemy.engine.base.Engine:1193][MainThread] () + 2016-02-12 01:06:35,855 INFO [sqlalchemy.engine.base.Engine:1192][MainThread] SELECT CAST('test unicode returns' AS VARCHAR(60)) AS anon_1 + 2016-02-12 01:06:35,855 INFO [sqlalchemy.engine.base.Engine:1193][MainThread] () + 2016-02-12 01:06:35,856 INFO [sqlalchemy.engine.base.Engine:1097][MainThread] PRAGMA table_info("pages") + 2016-02-12 01:06:35,856 INFO [sqlalchemy.engine.base.Engine:1100][MainThread] () + 2016-02-12 01:06:35,856 INFO [sqlalchemy.engine.base.Engine:1097][MainThread] PRAGMA table_info("users") + 2016-02-12 01:06:35,856 INFO [sqlalchemy.engine.base.Engine:1100][MainThread] () + 2016-02-12 01:06:35,857 INFO [sqlalchemy.engine.base.Engine:1097][MainThread] + CREATE TABLE users ( + id INTEGER NOT NULL, + name TEXT NOT NULL, + role TEXT NOT NULL, + password_hash TEXT, + CONSTRAINT pk_users PRIMARY KEY (id), + CONSTRAINT uq_users_name UNIQUE (name) + ) + + + 2016-02-12 01:06:35,857 INFO [sqlalchemy.engine.base.Engine:1100][MainThread] () + 2016-02-12 01:06:35,858 INFO [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT + 2016-02-12 01:06:35,858 INFO [sqlalchemy.engine.base.Engine:1097][MainThread] + CREATE TABLE pages ( + id INTEGER NOT NULL, + name TEXT NOT NULL, + data INTEGER NOT NULL, + creator_id INTEGER NOT NULL, + CONSTRAINT pk_pages PRIMARY KEY (id), + CONSTRAINT uq_pages_name UNIQUE (name), + CONSTRAINT fk_pages_creator_id_users FOREIGN KEY(creator_id) REFERENCES users (id) + ) + + + 2016-02-12 01:06:35,859 INFO [sqlalchemy.engine.base.Engine:1100][MainThread] () + 2016-02-12 01:06:35,859 INFO [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT + 2016-02-12 01:06:36,383 INFO [sqlalchemy.engine.base.Engine:646][MainThread] BEGIN (implicit) + 2016-02-12 01:06:36,384 INFO [sqlalchemy.engine.base.Engine:1097][MainThread] INSERT INTO users (name, role, password_hash) VALUES (?, ?, ?) + 2016-02-12 01:06:36,384 INFO [sqlalchemy.engine.base.Engine:1100][MainThread] ('editor', 'editor', '$2b$12$bSr5QR3wFs1LAnld7R94e.TXPj7DVoTxu2hA1kY6rm.Q3cAhD.AQO') + 2016-02-12 01:06:36,384 INFO [sqlalchemy.engine.base.Engine:1097][MainThread] INSERT INTO users (name, role, password_hash) VALUES (?, ?, ?) + 2016-02-12 01:06:36,384 INFO [sqlalchemy.engine.base.Engine:1100][MainThread] ('basic', 'basic', '$2b$12$.v0BQK2xWEQOnywbX2BFs.qzXo5Qf9oZohGWux/MOSj6Z.pVaY2Z6') + 2016-02-12 01:06:36,385 INFO [sqlalchemy.engine.base.Engine:1097][MainThread] INSERT INTO pages (name, data, creator_id) VALUES (?, ?, ?) + 2016-02-12 01:06:36,385 INFO [sqlalchemy.engine.base.Engine:1100][MainThread] ('FrontPage', 'This is the front page', 1) + 2016-02-12 01:06:36,385 INFO [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT View the application in a browser --------------------------------- -- cgit v1.2.3 From 574ba1aa6d81498220d123d149192eeba81afee7 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Fri, 12 Feb 2016 02:22:48 -0600 Subject: update the models chapter with the new user model --- docs/tutorials/wiki2/definingmodels.rst | 119 +++++++++++++++++++++----------- 1 file changed, 77 insertions(+), 42 deletions(-) (limited to 'docs/tutorials/wiki2/definingmodels.rst') diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst index 5af8110da..beb6cee5a 100644 --- a/docs/tutorials/wiki2/definingmodels.rst +++ b/docs/tutorials/wiki2/definingmodels.rst @@ -4,61 +4,84 @@ Defining the Domain Model The first change we'll make to our stock ``pcreate``-generated application will be to define a wiki page :term:`domain model`. -We'll do this inside our ``mymodel.py`` file. +.. note:: -Edit ``mymodel.py`` -------------------- + There is nothing special about the filename ``user.py`` or ``page.py`` except + that they are Python modules. A project may have many models throughout its + codebase in arbitrarily named modules. Modules implementing models often + have ``model`` in their names or they may live in a Python subpackage of + your application package named ``models`` (as we've done in this tutorial), + but this is only a convention and not a requirement. -.. note:: - There is nothing special about the filename ``mymodel.py`` except that it - is a Python module. A project may have many models throughout its codebase - in arbitrarily named modules. Modules implementing models often have - ``model`` in their names or they may live in a Python subpackage of your - application package named ``models`` (as we've done in this tutorial), but - this is only a convention and not a requirement. +Remove ``mymodel.py`` +--------------------- + +The first thing we'll do is delete the file ``tutorial/models/mymodel.py``. +The ``MyModel`` class is only a sample and we're not going to use it. -Open the ``tutorial/models/mymodel.py`` file and edit it to look like -the following: -.. literalinclude:: src/models/tutorial/models/mymodel.py +Add ``user.py`` +--------------- + +Create a new file ``tutorial/models/user.py`` with the following contents: + +.. literalinclude:: src/models/tutorial/models/user.py :linenos: :language: py - :emphasize-lines: 10-12,14-15 -The highlighted lines are the ones that need to be changed, as well as -removing lines that reference ``Index``. +This is a very basic model for a user who can authenticate with our wiki. + +We discussed briefly in the previous chapter that our models will inherit +from a SQLAlchemy :func:`sqlalchemy.ext.declarative.declarative_base`. This +will attach the model to our schema. + +As you can see, our ``User`` class has a class-level attribute +``__tablename__`` which equals the string ``users``. Our ``User`` class +will also have class-level attributes named ``id``, ``name``, +``password_hash`` and ``role`` (all instances of +:class:`sqlalchemy.schema.Column`). These will map to columns in the ``users`` +table. The ``id`` attribute will be the primary key in the table. The ``name`` +attribute will be a text column, each value of which needs to be unique within +the column. The ``password_hash`` is a nullable text attribute that will +contain a securely hashed password [1]_. Finally, the ``role`` text attribute +will hold the role of the user. -The first thing we've done is remove the stock ``MyModel`` class -from the generated ``models.py`` file. The ``MyModel`` class is only a -sample and we're not going to use it. +There are two helper methods that will help us later when using the +user objects. The first is ``set_password`` which will take a raw password +and transform it using bcrypt_ into an irreversible representation. The +``check_password`` method will allow us to compare input passwords to +see if they resolve to the same hash signifying a match. -Then we added a ``Page`` class. Because this is a SQLAlchemy application, -this class inherits from an instance of -:func:`sqlalchemy.ext.declarative.declarative_base`. -.. literalinclude:: src/models/tutorial/models/mymodel.py - :pyobject: Page +Add ``page.py`` +--------------- + +Create a new file ``tutorial/models/page.py`` with the following contents: + +.. literalinclude:: src/models/tutorial/models/page.py :linenos: - :language: python + :language: py -As you can see, our ``Page`` class has a class-level attribute -``__tablename__`` which equals the string ``'pages'``. This means that -SQLAlchemy will store our wiki data in a SQL table named ``pages``. Our -``Page`` class will also have class-level attributes named ``id``, ``name``, -and ``data`` (all instances of :class:`sqlalchemy.schema.Column`). These will -map to columns in the ``pages`` table. The ``id`` attribute will be the -primary key in the table. The ``name`` attribute will be a text attribute, -each value of which needs to be unique within the column. The ``data`` -attribute is a text attribute that will hold the body of each page. +As you can see, our ``Page`` class is very similar to the ``User`` defined +above except with attributes focused on storing information about a wiki +page including ``id``, ``name``, and ``data``. The only new construct +introduced here is the ``creator_id`` column which is a foreign key +referencing the ``users`` table. Foreign keys are very useful at the +schema-level but since we want to relate ``User`` objects with ``Page`` +objects we also define a the ``creator`` attribute which is an ORM-level +mapping between the two tables. SQLAlchemy will automatically populate this +value using the foreign key referencing the user. Since the foreign key +has ``nullable=False`` we are guaranteed that an instance of ``page`` will +have a corresponding ``page.creator`` which will be a ``User`` instance. Edit ``models/__init__.py`` --------------------------- Since we are using a package for our models, we also need to update our -``__init__.py`` file to ensure that the model is attached to the metadata. +``__init__.py`` file to ensure that the models are attached to the metadata. Open the ``tutorial/models/__init__.py`` file and edit it to look like the following: @@ -66,9 +89,10 @@ the following: .. literalinclude:: src/models/tutorial/models/__init__.py :linenos: :language: py - :emphasize-lines: 8 + :emphasize-lines: 8,9 -Here we need to align our import with the name of the model ``Page``. +Here we need to align our imports with the names of the models ``User``, +and ``Page``. Edit ``scripts/initializedb.py`` @@ -77,13 +101,13 @@ Edit ``scripts/initializedb.py`` We haven't looked at the details of this file yet, but within the ``scripts`` directory of your ``tutorial`` package is a file named ``initializedb.py``. Code in this file is executed whenever we run the ``initialize_tutorial_db`` -command, as we did in the installation step of this tutorial. +command, as we did in the installation step of this tutorial [2]_. Since we've changed our model, we need to make changes to our ``initializedb.py`` script. In particular, we'll replace our import of -``MyModel`` with one of ``Page`` and we'll change the very end of the script -to create a ``Page`` rather than a ``MyModel`` and add it to our -``dbsession``. +``MyModel`` with those of ``User`` and ``Page`` and we'll change the very end +of the script to create two ``User`` objects (``basic`` and ``editor``) and a +``Page`` rather than a ``MyModel`` and add them to our ``dbsession``. Open ``tutorial/scripts/initializedb.py`` and edit it to look like the following: @@ -91,7 +115,7 @@ the following: .. literalinclude:: src/models/tutorial/scripts/initializedb.py :linenos: :language: python - :emphasize-lines: 18,44-45 + :emphasize-lines: 18,44-57 Only the highlighted lines need to be changed. @@ -164,3 +188,14 @@ up with a Python traceback on your console that ends with this exception: ImportError: cannot import name MyModel This will also happen if you attempt to run the tests. + +.. _bcrypt: https://pypi.python.org/pypi/bcrypt + +.. [1] We are using the bcrypt_ package from PyPI to hash our passwords + securely. There are other one-way hash algorithms for passwords if + bcrypt is an issue on your system. Just make sure that it's an + algorithm approved for storing passwords versus a generic one-way hash. + +.. [2] The command is named ``initialize_tutorial_db`` because of the mapping + defined in the ``[console_scripts]`` entry point of our project's + ``setup.py`` file. -- 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/definingmodels.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) (limited to 'docs/tutorials/wiki2/definingmodels.rst') diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst index beb6cee5a..33e7beb4f 100644 --- a/docs/tutorials/wiki2/definingmodels.rst +++ b/docs/tutorials/wiki2/definingmodels.rst @@ -15,6 +15,28 @@ be to define a wiki page :term:`domain model`. but this is only a convention and not a requirement. +Declaring dependencies in our ``setup.py`` file +=============================================== + +The models code in our application will depend on a package which is not a +dependency of the original "tutorial" application. The original "tutorial" +application was generated by the ``pcreate`` command; it doesn't know +about our custom application requirements. + +We need to add a dependency on the ``bcrypt`` package to our ``tutorial`` +package's ``setup.py`` file by assigning this dependency to the ``requires`` +parameter in the ``setup()`` function. + +Open ``tutorial/setup.py`` and edit it to look like the following: + +.. literalinclude:: src/models/setup.py + :linenos: + :emphasize-lines: 12 + :language: python + +Only the highlighted line needs to be added. + + Remove ``mymodel.py`` --------------------- -- 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/definingmodels.rst | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) (limited to 'docs/tutorials/wiki2/definingmodels.rst') diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst index 33e7beb4f..41f36fa26 100644 --- a/docs/tutorials/wiki2/definingmodels.rst +++ b/docs/tutorials/wiki2/definingmodels.rst @@ -37,6 +37,36 @@ Open ``tutorial/setup.py`` and edit it to look like the following: Only the highlighted line needs to be added. +Running ``setup.py develop`` +============================ + +Since a new software dependency was added, you will need to run ``python +setup.py develop`` again inside the root of the ``tutorial`` package to obtain +and register the newly added dependency distribution. + +Make sure your current working directory is the root of the project (the +directory in which ``setup.py`` lives) and execute the following command. + +On UNIX: + +.. code-block:: bash + + $ cd tutorial + $ $VENV/bin/python setup.py develop + +On Windows: + +.. code-block:: text + + c:\pyramidtut> cd tutorial + c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop + +Success executing this command will end with a line to the console something +like this:: + + Finished processing dependencies for tutorial==0.0 + + Remove ``mymodel.py`` --------------------- -- cgit v1.2.3 From 15fb09b473e55f1edf60466f9fa499a5c8fbb93b Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 23 Feb 2016 02:10:50 -0800 Subject: update definingmodels (WIP) - minor grammar and syntax - define hashing and its purpose --- docs/tutorials/wiki2/definingmodels.rst | 54 ++++++++++++++++++--------------- 1 file changed, 30 insertions(+), 24 deletions(-) (limited to 'docs/tutorials/wiki2/definingmodels.rst') diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst index 41f36fa26..b0781dfe4 100644 --- a/docs/tutorials/wiki2/definingmodels.rst +++ b/docs/tutorials/wiki2/definingmodels.rst @@ -20,10 +20,10 @@ Declaring dependencies in our ``setup.py`` file The models code in our application will depend on a package which is not a dependency of the original "tutorial" application. The original "tutorial" -application was generated by the ``pcreate`` command; it doesn't know -about our custom application requirements. +application was generated by the ``pcreate`` command; it doesn't know about our +custom application requirements. -We need to add a dependency on the ``bcrypt`` package to our ``tutorial`` +We need to add a dependency, the ``bcrypt`` package, to our ``tutorial`` package's ``setup.py`` file by assigning this dependency to the ``requires`` parameter in the ``setup()`` function. @@ -56,7 +56,7 @@ On UNIX: On Windows: -.. code-block:: text +.. code-block:: ps1con c:\pyramidtut> cd tutorial c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop @@ -70,8 +70,8 @@ like this:: Remove ``mymodel.py`` --------------------- -The first thing we'll do is delete the file ``tutorial/models/mymodel.py``. -The ``MyModel`` class is only a sample and we're not going to use it. +Let's delete the file ``tutorial/models/mymodel.py``. The ``MyModel`` class is +only a sample and we're not going to use it. Add ``user.py`` @@ -85,26 +85,32 @@ Create a new file ``tutorial/models/user.py`` with the following contents: This is a very basic model for a user who can authenticate with our wiki. -We discussed briefly in the previous chapter that our models will inherit -from a SQLAlchemy :func:`sqlalchemy.ext.declarative.declarative_base`. This -will attach the model to our schema. +We discussed briefly in the previous chapter that our models will inherit from +an SQLAlchemy :func:`sqlalchemy.ext.declarative.declarative_base`. This will +attach the model to our schema. As you can see, our ``User`` class has a class-level attribute -``__tablename__`` which equals the string ``users``. Our ``User`` class -will also have class-level attributes named ``id``, ``name``, -``password_hash`` and ``role`` (all instances of -:class:`sqlalchemy.schema.Column`). These will map to columns in the ``users`` -table. The ``id`` attribute will be the primary key in the table. The ``name`` -attribute will be a text column, each value of which needs to be unique within -the column. The ``password_hash`` is a nullable text attribute that will -contain a securely hashed password [1]_. Finally, the ``role`` text attribute -will hold the role of the user. - -There are two helper methods that will help us later when using the -user objects. The first is ``set_password`` which will take a raw password -and transform it using bcrypt_ into an irreversible representation. The -``check_password`` method will allow us to compare input passwords to -see if they resolve to the same hash signifying a match. +``__tablename__`` which equals the string ``users``. Our ``User`` class will +also have class-level attributes named ``id``, ``name``, ``password_hash``, +and ``role`` (all instances of :class:`sqlalchemy.schema.Column`). These will +map to columns in the ``users`` table. The ``id`` attribute will be the primary +key in the table. The ``name`` attribute will be a text column, each value of +which needs to be unique within the column. The ``password_hash`` is a nullable +text attribute that will contain a securely hashed password [1]_. Finally, the +``role`` text attribute will hold the role of the user. + +There are two helper methods that will help us later when using the user +objects. The first is ``set_password`` which will take a raw password and +transform it using bcrypt_ into an irreversible representation, a process known +as "hashing". The second method, ``check_password``, will allow us to compare +the hashed value of the submitted password against the hashed value of the +password stored in the user's record in the database. If the two hashed values +match, then the submitted password is valid, and we can authenticate the user. + +We hash passwords so that it is impossible to decrypt them and use them to +authenticate in the application. If we stored passwords foolishly in clear +text, then anyone with access to the database could retrieve any password to +authenticate as any user. Add ``page.py`` -- cgit v1.2.3 From 2dc061b569fcfc8d370efb358576a71d233f514f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 24 Feb 2016 01:10:22 -0800 Subject: update definingmodels (done) - minor grammar and syntax --- docs/tutorials/wiki2/definingmodels.rst | 45 ++++++++++++++++----------------- 1 file changed, 22 insertions(+), 23 deletions(-) (limited to 'docs/tutorials/wiki2/definingmodels.rst') diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst index b0781dfe4..14099582c 100644 --- a/docs/tutorials/wiki2/definingmodels.rst +++ b/docs/tutorials/wiki2/definingmodels.rst @@ -123,16 +123,16 @@ Create a new file ``tutorial/models/page.py`` with the following contents: :language: py As you can see, our ``Page`` class is very similar to the ``User`` defined -above except with attributes focused on storing information about a wiki -page including ``id``, ``name``, and ``data``. The only new construct -introduced here is the ``creator_id`` column which is a foreign key -referencing the ``users`` table. Foreign keys are very useful at the -schema-level but since we want to relate ``User`` objects with ``Page`` -objects we also define a the ``creator`` attribute which is an ORM-level -mapping between the two tables. SQLAlchemy will automatically populate this -value using the foreign key referencing the user. Since the foreign key -has ``nullable=False`` we are guaranteed that an instance of ``page`` will -have a corresponding ``page.creator`` which will be a ``User`` instance. +above, except with attributes focused on storing information about a wiki page, +including ``id``, ``name``, and ``data``. The only new construct introduced +here is the ``creator_id`` column, which is a foreign key referencing the +``users`` table. Foreign keys are very useful at the schema-level, but since we +want to relate ``User`` objects with ``Page`` objects, we also define a +``creator`` attribute as an ORM-level mapping between the two tables. +SQLAlchemy will automatically populate this value using the foreign key +referencing the user. Since the foreign key has ``nullable=False``, we are +guaranteed that an instance of ``page`` will have a corresponding +``page.creator``, which will be a ``User`` instance. Edit ``models/__init__.py`` @@ -149,8 +149,7 @@ the following: :language: py :emphasize-lines: 8,9 -Here we need to align our imports with the names of the models ``User``, -and ``Page``. +Here we align our imports with the names of the models, ``User`` and ``Page``. Edit ``scripts/initializedb.py`` @@ -163,12 +162,12 @@ command, as we did in the installation step of this tutorial [2]_. Since we've changed our model, we need to make changes to our ``initializedb.py`` script. In particular, we'll replace our import of -``MyModel`` with those of ``User`` and ``Page`` and we'll change the very end -of the script to create two ``User`` objects (``basic`` and ``editor``) and a -``Page`` rather than a ``MyModel`` and add them to our ``dbsession``. +``MyModel`` with those of ``User`` and ``Page``. We'll also change the very end +of the script to create two ``User`` objects (``basic`` and ``editor``) as well +as a ``Page``, rather than a ``MyModel``, and add them to our ``dbsession``. -Open ``tutorial/scripts/initializedb.py`` and edit it to look like -the following: +Open ``tutorial/scripts/initializedb.py`` and edit it to look like the +following: .. literalinclude:: src/models/tutorial/scripts/initializedb.py :linenos: @@ -181,9 +180,9 @@ Only the highlighted lines need to be changed. Installing the project and re-initializing the database ------------------------------------------------------- -Because our model has changed, in order to reinitialize the database, we need -to rerun the ``initialize_tutorial_db`` command to pick up the changes you've -made to both the models.py file and to the initializedb.py file. See +Because our model has changed, and in order to reinitialize the database, we +need to rerun the ``initialize_tutorial_db`` command to pick up the changes +we've made to both the models.py file and to the initializedb.py file. See :ref:`initialize_db_wiki2` for instructions. Success will look something like this:: @@ -237,9 +236,9 @@ View the application in a browser We can't. At this point, our system is in a "non-runnable" state; we'll need to change view-related files in the next chapter to be able to start the -application successfully. If you try to start the application (See -:ref:`wiki2-start-the-application`), you'll wind -up with a Python traceback on your console that ends with this exception: +application successfully. If you try to start the application (see +:ref:`wiki2-start-the-application`), you'll wind up with a Python traceback on +your console that ends with this exception: .. code-block:: text -- cgit v1.2.3