From 83fefbf3f92183d1d899c8449a03546dd3c022a3 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Sat, 3 Aug 2013 11:23:20 -0400 Subject: "Web Application Development Framework" -> "Web Framework". Yay. --- docs/conf.py | 10 +- docs/copyright.rst | 2 +- docs/getting_started/quick_glance.rst | 219 +++++++++++++++++++-- .../hello_world/templates/mytemplate.jinja2 | 6 +- docs/getting_started/top_ten.rst | 2 + docs/index.rst | 2 +- .../MyProject/myproject/templates/mytemplate.pt | 4 +- .../authorization/tutorial/templates/mytemplate.pt | 4 +- .../basiclayout/tutorial/templates/mytemplate.pt | 4 +- .../src/models/tutorial/templates/mytemplate.pt | 4 +- .../src/tests/tutorial/templates/mytemplate.pt | 4 +- .../src/views/tutorial/templates/mytemplate.pt | 4 +- .../authorization/tutorial/templates/mytemplate.pt | 4 +- .../basiclayout/tutorial/templates/mytemplate.pt | 4 +- .../src/models/tutorial/templates/mytemplate.pt | 4 +- .../src/tests/tutorial/templates/mytemplate.pt | 4 +- .../src/views/tutorial/templates/mytemplate.pt | 4 +- 17 files changed, 242 insertions(+), 43 deletions(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 84b01a791..9b2f2f083 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -85,7 +85,7 @@ source_suffix = '.rst' master_doc = 'index' # General substitutions. -project = 'The Pyramid Web Application Development Framework' +project = 'The Pyramid Web Framework' thisyear = datetime.datetime.now().year copyright = '2008-%s, Agendaless Consulting' % thisyear @@ -179,7 +179,7 @@ html_theme_options = dict( # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -html_title = 'The Pyramid Web Application Development Framework v%s' % release +html_title = 'The Pyramid Web Framework v%s' % release # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = 'Home' @@ -251,7 +251,7 @@ latex_additional_files = ['_static/latex-note.png', '_static/latex-warning.png'] # (source start file, target name, title, author, document class [howto/manual]). latex_documents = [ ('latexindex', 'pyramid.tex', - 'The Pyramid Web Application Development Framework', + 'The Pyramid Web Framework', 'Chris McDonough', 'manual'), ] @@ -491,7 +491,7 @@ def resig(app, what, name, obj, options, signature, return_annotation): # -- Options for Epub output --------------------------------------------------- # Bibliographic Dublin Core info. -epub_title = 'The Pyramid Web Application Development Framework, Version %s' \ +epub_title = 'The Pyramid Web Framework, Version %s' \ % release epub_author = 'Chris McDonough' epub_publisher = 'Agendaless Consulting' @@ -509,7 +509,7 @@ epub_scheme = 'ISBN' epub_identifier = '0615445675' # A unique identification for the text. -epub_uid = 'The Pyramid Web Application Development Framework, Version %s' \ +epub_uid = 'The Pyramid Web Framework, Version %s' \ % release # HTML files that should be inserted before the pages created by sphinx. # The format is a list of tuples containing the path and title. diff --git a/docs/copyright.rst b/docs/copyright.rst index 8f3a5f5e7..980335827 100644 --- a/docs/copyright.rst +++ b/docs/copyright.rst @@ -1,7 +1,7 @@ Copyright, Trademarks, and Attributions ======================================= -*The Pyramid Web Application Development Framework, Version 1.1* +*The Pyramid Web Framework, Version 1.1* by Chris McDonough diff --git a/docs/getting_started/quick_glance.rst b/docs/getting_started/quick_glance.rst index 13ae22ba5..da65f2e51 100644 --- a/docs/getting_started/quick_glance.rst +++ b/docs/getting_started/quick_glance.rst @@ -2,20 +2,48 @@ Quick Glance ============ -Pyramid lets you start small and finish big. The -:doc:`index` guide +Pyramid lets you start small and finish big. This :doc:`index` guide walks you through many of the key features. Let's put the emphasis on *start* by doing a quick tour through Pyramid. -This *Quick Glance* is shorthand, snippet-oriented. It is not intended -as full example. Instead, the other chapters will provide complete -examples. +This *Quick Glance* is provides snippets instead of full examples. For +working code, see the *Getting Started* chapters on each topic. .. note:: Like the rest of Getting Started, we're using Python 3 in our samples. You can too, or you can use Python 2.7. +Setup +===== + +This is just a "quick glance", so we won't kill ourselves showing +installation details. The guides fully cover each topic, +including setup. In a nutshell: + +.. code-block:: bash + + $ pyvenv-3.3 env33 + $ source env33/bin/activate + $ curl -O http://python-distribute.org/distribute_setup.py + $ python3.3 ./distribute_setup.py + $ rm distribute* + $ easy_install-3.3 pip + $ pip-3.3 install pyramid + +We use Python 3.3's builtin virtual environment tool ``pyvenv`` to make +an isolated Python. It is so isolated, we don't have package +installation tools! After setting those up and cleaning up, +we install Pyramid into our virtual environment. + +.. note:: + + Note the use of ``3.3`` on many of the commands, as a way to emphasize + in this document which versions of the commands we are using. This is + optional. + + + The Smallest ============ @@ -506,14 +534,183 @@ Pyramid supplies helpers for test writing, which we use in the test setup and teardown. Our one test imports the view, makes a dummy request, and sees if the view returns what we expected. +Logging +======= + +It's important to know what is going on inside our web application. +In development we might need to collect some output. In production, +we might need to detect situations when other people use the site. We +need *logging*. + +Fortunately Pyramid uses the normal Python approach to logging. The +scaffold generated, in your ``development.ini``, a number of lines that +configure the logging for you to some reasonable defaults. You then see +messages sent by Pyramid (for example, when a new request comes in.) + +Maybe you would like to log messages in your code? In your Python +module, import and setup the logging: + +.. code-block:: python + + import logging + log = logging.getLogger(__name__) + +You can now, in your code, log messages: + +.. code-block:: python + + log.debug('Some Message') +This will log ``Some Message`` at a ``debug`` log level, +to the application-configured logger in your ``development.ini``. What +controls that? These sections in the configuration file: + +.. code-block:: ini + + [loggers] + keys = root, hello_world + + [logger_hello_world] + level = DEBUG + handlers = + qualname = hello_world + +Our application, a package named ``hello_world``, is setup as a logger +and configured to log messages at a ``DEBUG`` or higher level. + +Sessions +======== + +When people use your web application, they frequently perform a task +that requires semi-permanent data to be saved. For example,a shopping +cart. These are frequently called *sessions*. + +Pyramid has basic built-in support for sessions, with add-ons such as +*Beaker* (or your own custom sessioning engine) that provide richer +session support. For the built-in session support, you first import +the "factory" which provides the sessioning: + +.. code-block:: python + + from pyramid.session import UnencryptedCookieSessionFactoryConfig + my_session_factory = UnencryptedCookieSessionFactoryConfig('itsaseekreet') + +We tell the configuration system that this is the source of our +sessioning support when setting up the ``Configurator``: + +.. code-block:: python + + config = Configurator(session_factory = my_session_factory) + +This now lets us use the session in our application code: + +.. code-block:: python + + session = request.session + if 'abc' in session: + session['fred'] = 'yes' + +Databases +========= - - logging +Web applications mean data. Data means databases. Frequently SQL +databases. SQL Databases frequently mean an "ORM" +(object-relational mapper.) In Python, ORM usually leads to the +mega-quality *SQLAlchemy*, a Python package that greatly eases working +with databases. - - resources, asset specs, tests, +Pyramid and SQLAlchemy are great friends. That friendship includes a +scaffold! + +.. code-block:: bash + + $ pcreate --scaffold alchemy hello_sqlalchemy + $ cd hello_sqlalchemy + $ python3.3 setup.py develop + +We now have a working sample SQLAlchemy application with all +dependencies installed. The sample project provides a console script to +initialize a SQLite database with tables. Let's run it and then start +the application: + +.. code-block:: bash + + $ initialize_hello_sqlalchemy_db development.ini + $ pserve development.ini + +We can now visit our sample at +`http://localhost:6543/ `_. Some choices that +the scaffold helped us with: + +- A ``setup.py`` with appropriate dependencies + +- Connection strings and integration in our ``development.ini`` file + +- A console script which we ran above to initialize the database + +- The SQLAlchemy engine integrated into the ``Configurator`` on + application startup + +- Python modules for the SQLAlchemy models and the Pyramid views that + go with them + +- Some unit tests...yummy! + +As mentioned above, an ORM is software that eases the mapping of +database structures into a programming language. SQLAlchemy uses models +for this, and its scaffold generated a sample model: + +.. code-block:: python + + class MyModel(Base): + __tablename__ = 'models' + id = Column(Integer, primary_key=True) + name = Column(Text, unique=True) + value = Column(Integer) + + def __init__(self, name, value): + self.name = name + self.value = value + +The Python module also includes this: + +.. code-block:: python + + from zope.sqlalchemy import ZopeTransactionExtension + +The generated application includes the optional support for +``pyramid_tm``, a unique transaction monitor that integrates your +database transactions with your code for transparent rollback and commit. + +View code, which mediates the logic between web requests and the rest +of the system, can then easily get at the data: + +.. code-block:: python + + one = DBSession.query(MyModel).filter(MyModel.name == 'one').first() + + +Forms +===== + +Developers have lots of opinions about forms, and thus there are many +form libraries for Python. Pyramid doesn't directly bundle a form +library, but *Deform* is a popular choice. Let's see it in action. +First we install it: + +.. code-block:: bash + + $ pip-3.3 install deform + + + +Authentication +============== + + +Authorization +============= -sessions, logging, special views -databases, forms, security Notes @@ -534,6 +731,6 @@ Notes - Debugging -- Template reloading +- Explain and link to WSGI, Python Packages -- Explain and link to WSGI, Python Packages \ No newline at end of file +- Richer routing \ No newline at end of file diff --git a/docs/getting_started/quick_glance/hello_world/hello_world/templates/mytemplate.jinja2 b/docs/getting_started/quick_glance/hello_world/hello_world/templates/mytemplate.jinja2 index a796c7273..998edfe12 100644 --- a/docs/getting_started/quick_glance/hello_world/hello_world/templates/mytemplate.jinja2 +++ b/docs/getting_started/quick_glance/hello_world/hello_world/templates/mytemplate.jinja2 @@ -1,7 +1,7 @@ - The Pyramid Web Application Development Framework + The Pyramid Web Framework @@ -21,14 +21,14 @@
Logo

Welcome to {{project}}, an application generated by
- the Pyramid web application development framework. + the Pyramid Web Framework.

diff --git a/docs/getting_started/top_ten.rst b/docs/getting_started/top_ten.rst index 071f41d1c..a11d2898c 100644 --- a/docs/getting_started/top_ten.rst +++ b/docs/getting_started/top_ten.rst @@ -28,3 +28,5 @@ Custom views - Asset specifications - Traversal + +- Transactions \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 3c3adb9a6..4bbd2fd93 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,7 +1,7 @@ .. _index: ================================================= -The Pyramid Web Application Development Framework +The Pyramid Web Framework ================================================= :app:`Pyramid` is a small, fast, down-to-earth Python web application diff --git a/docs/narr/MyProject/myproject/templates/mytemplate.pt b/docs/narr/MyProject/myproject/templates/mytemplate.pt index 0bfac946e..0fccba624 100644 --- a/docs/narr/MyProject/myproject/templates/mytemplate.pt +++ b/docs/narr/MyProject/myproject/templates/mytemplate.pt @@ -1,7 +1,7 @@ - The Pyramid Web Application Development Framework + The Pyramid Web Framework @@ -24,7 +24,7 @@

Welcome to ${project}, an application generated by
- the Pyramid web application development framework. + the Pyramid Web Framework.

diff --git a/docs/tutorials/wiki/src/authorization/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki/src/authorization/tutorial/templates/mytemplate.pt index e8672104d..13b41f823 100644 --- a/docs/tutorials/wiki/src/authorization/tutorial/templates/mytemplate.pt +++ b/docs/tutorials/wiki/src/authorization/tutorial/templates/mytemplate.pt @@ -1,7 +1,7 @@ - The Pyramid Web Application Development Framework + The Pyramid Web Framework @@ -24,7 +24,7 @@

Welcome to ${project}, an application generated by
- the Pyramid web application development framework. + the Pyramid Web Framework.

diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki/src/basiclayout/tutorial/templates/mytemplate.pt index e8672104d..13b41f823 100644 --- a/docs/tutorials/wiki/src/basiclayout/tutorial/templates/mytemplate.pt +++ b/docs/tutorials/wiki/src/basiclayout/tutorial/templates/mytemplate.pt @@ -1,7 +1,7 @@ - The Pyramid Web Application Development Framework + The Pyramid Web Framework @@ -24,7 +24,7 @@

Welcome to ${project}, an application generated by
- the Pyramid web application development framework. + the Pyramid Web Framework.

diff --git a/docs/tutorials/wiki/src/models/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki/src/models/tutorial/templates/mytemplate.pt index e8672104d..13b41f823 100644 --- a/docs/tutorials/wiki/src/models/tutorial/templates/mytemplate.pt +++ b/docs/tutorials/wiki/src/models/tutorial/templates/mytemplate.pt @@ -1,7 +1,7 @@ - The Pyramid Web Application Development Framework + The Pyramid Web Framework @@ -24,7 +24,7 @@

Welcome to ${project}, an application generated by
- the Pyramid web application development framework. + the Pyramid Web Framework.

diff --git a/docs/tutorials/wiki/src/tests/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki/src/tests/tutorial/templates/mytemplate.pt index e8672104d..13b41f823 100644 --- a/docs/tutorials/wiki/src/tests/tutorial/templates/mytemplate.pt +++ b/docs/tutorials/wiki/src/tests/tutorial/templates/mytemplate.pt @@ -1,7 +1,7 @@ - The Pyramid Web Application Development Framework + The Pyramid Web Framework @@ -24,7 +24,7 @@

Welcome to ${project}, an application generated by
- the Pyramid web application development framework. + the Pyramid Web Framework.

diff --git a/docs/tutorials/wiki/src/views/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki/src/views/tutorial/templates/mytemplate.pt index 84824f605..50102aa20 100644 --- a/docs/tutorials/wiki/src/views/tutorial/templates/mytemplate.pt +++ b/docs/tutorials/wiki/src/views/tutorial/templates/mytemplate.pt @@ -1,7 +1,7 @@ - The Pyramid Web Application Development Framework + The Pyramid Web Framework @@ -24,7 +24,7 @@

Welcome to ${project}, an application generated by
- the Pyramid web application development framework. + the Pyramid Web Framework.

diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki2/src/authorization/tutorial/templates/mytemplate.pt index 14b88d16a..cf3da2073 100644 --- a/docs/tutorials/wiki2/src/authorization/tutorial/templates/mytemplate.pt +++ b/docs/tutorials/wiki2/src/authorization/tutorial/templates/mytemplate.pt @@ -1,7 +1,7 @@ - The Pyramid Web Application Development Framework + The Pyramid Web Framework @@ -24,7 +24,7 @@

Welcome to ${project}, an application generated by
- the Pyramid web application development framework. + the Pyramid Web Framework.

diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/mytemplate.pt index ee9fdb7fa..ca4e0af26 100644 --- a/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/mytemplate.pt +++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/mytemplate.pt @@ -1,7 +1,7 @@ - The Pyramid Web Application Development Framework + The Pyramid Web Framework @@ -24,7 +24,7 @@

Welcome to ${project}, an application generated by
- the Pyramid web application development framework. + the Pyramid Web Framework.

diff --git a/docs/tutorials/wiki2/src/models/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki2/src/models/tutorial/templates/mytemplate.pt index ee9fdb7fa..ca4e0af26 100644 --- a/docs/tutorials/wiki2/src/models/tutorial/templates/mytemplate.pt +++ b/docs/tutorials/wiki2/src/models/tutorial/templates/mytemplate.pt @@ -1,7 +1,7 @@ - The Pyramid Web Application Development Framework + The Pyramid Web Framework @@ -24,7 +24,7 @@

Welcome to ${project}, an application generated by
- the Pyramid web application development framework. + the Pyramid Web Framework.

diff --git a/docs/tutorials/wiki2/src/tests/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki2/src/tests/tutorial/templates/mytemplate.pt index 9c077568d..6c1ca924a 100644 --- a/docs/tutorials/wiki2/src/tests/tutorial/templates/mytemplate.pt +++ b/docs/tutorials/wiki2/src/tests/tutorial/templates/mytemplate.pt @@ -1,7 +1,7 @@ - The Pyramid Web Application Development Framework + The Pyramid Web Framework @@ -24,7 +24,7 @@

Welcome to ${project}, an application generated by
- the Pyramid web application development framework. + the Pyramid Web Framework.

diff --git a/docs/tutorials/wiki2/src/views/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki2/src/views/tutorial/templates/mytemplate.pt index ee9fdb7fa..ca4e0af26 100644 --- a/docs/tutorials/wiki2/src/views/tutorial/templates/mytemplate.pt +++ b/docs/tutorials/wiki2/src/views/tutorial/templates/mytemplate.pt @@ -1,7 +1,7 @@ - The Pyramid Web Application Development Framework + The Pyramid Web Framework @@ -24,7 +24,7 @@

Welcome to ${project}, an application generated by
- the Pyramid web application development framework. + the Pyramid Web Framework.

-- cgit v1.2.3