Merge branch 'master' of github.com:Pylons/pyramid_cookbook

CONTRIBUTORS.txt

@@ -111,3 +111,4 @@ Paul Winkler, 1/30/2012
 Doug Morgan, 03/12/2012
 Josh Finnie, 03/13/2012
 Tom Willis, 03/22/2012
+Larry Reed, 03/20/2013

auth/akhet_sqlalchemy.rst

@@ -0,0 +1,6 @@
+Pyramid Auth with Akhet and SQLAlchemy
+======================================
+
+Learn how to set up Pyramid authorization using Akhet and SQLAlchemy at
+http://pyramid.chromaticleaves.com/simpleauth/.
+

auth/auth_tutorial.rst

@@ -0,0 +1,7 @@
+Auth Tutorial
+=============
+
+See Michael Merickel's authentication/authorization tutorial at
+http://michael.merickel.org/projects/pyramid_auth_demo/ with code on Github at
+https://github.com/mmerickel/pyramid_auth_demo.
+

auth/enterprise.rst

@@ -0,0 +1,26 @@
+Integration with Enterprise Systems
+===================================
+
+When using Pyramid within an "enterprise" (or an intranet), it is often desirable to
+integrate with existing authentication and authorization (entitlement) systems.
+For example, in Microsoft Network environments, the user database is typically
+maintained in Active Directory. At present, there is no ready-to-use recipe, but we
+are listing places that may be worth looking at for ideas when developing one:
+
+Authentication
+--------------
+
+* `adpasswd project on pypi <http://pypi.python.org/pypi/adpasswd/0.2>`_
+* `Tim Golden's Active Directory Cookbook <http://timgolden.me.uk/python/ad_cookbook.html>`_
+* `python-ad <http://code.google.com/p/python-ad/>`_
+* `python-ldap.org <http://www.python-ldap.org/>`_
+* `python-ntmlm <http://code.google.com/p/python-ntlm/>`_
+* `Blog post on managing AD from Python in Linux <http://marcitland.blogspot.com/2011/02/python-active-directory-linux.html>`_
+
+Authorization
+-------------
+
+* `Microsoft Authorization Manager <http://msdn.microsoft.com/en-us/library/aa480244.aspx>`_
+* `Fundamentals of WCF Security <http://www.code-magazine.com/article.aspx?quickid=0611051>`_
+* `Calling WCF Services from C++ using gSOAP <http://coab.wordpress.com/2009/10/15/calling-wcf-services-from-a-linux-c-client-using-gsoap/>`_
+

auth/index.rst

@@ -1,61 +1,18 @@
 Authentication and Authorization
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
 .. toctree::
    :maxdepth: 1
 
-   user_object
-   custom
    basic
+   custom
+   user_object
    wiki2_auth
-
-Auth Tutorial
-=============
-
-See Michael Merickel's authentication/authorization tutorial at
-http://michael.merickel.org/projects/pyramid_auth_demo/ with code on Github at
-https://github.com/mmerickel/pyramid_auth_demo.
-
-Pyramid Auth with Akhet and SQLAlchemy
-======================================
-
-Learn how to set up Pyramid authorization using Akhet and SQLAlchemy at
-http://pyramid.chromaticleaves.com/simpleauth/.
-
-Google, Facebook, Tweeter, and any OpenID Authentication
-========================================================
-
-See `Wayne Witzel III's blog post
-<http://pieceofpy.com/blog/2011/07/24/pyramid-and-velruse-for-google-authentication/>`_
-about using Velruse and Pyramid together to do Google OAuth authentication.
-
-See Matthew Housden and Chris Davies pyramid_apex project for any basic and openid
-authentication such as Google, Facebook, Tweeter and more at 
-https://github.com/cd34/pyramid_apex.
-
-Integration with Enterprise Systems
-===================================
-
-When using Pyramid within an "enterprise" (or an intranet), it is often desirable to
-integrate with existing authentication and authorization (entitlement) systems.
-For example, in Microsoft Network environments, the user database is typically
-maintained in Active Directory. At present, there is no ready-to-use recipe, but we
-are listing places that may be worth looking at for ideas when developing one:
-
-Authentication
---------------
-
-* `adpasswd project on pypi <http://pypi.python.org/pypi/adpasswd/0.2>`_
-* `Tim Golden's Active Directory Cookbook <http://timgolden.me.uk/python/ad_cookbook.html>`_
-* `python-ad <http://code.google.com/p/python-ad/>`_
-* `python-ldap.org <http://www.python-ldap.org/>`_
-* `python-ntmlm <http://code.google.com/p/python-ntlm/>`_
-* `Blog post on managing AD from Python in Linux <http://marcitland.blogspot.com/2011/02/python-active-directory-linux.html>`_
-
-Authorization
--------------
-
-* `Microsoft Authorization Manager <http://msdn.microsoft.com/en-us/library/aa480244.aspx>`_
-* `Fundamentals of WCF Security <http://www.code-magazine.com/article.aspx?quickid=0611051>`_
-* `Calling WCF Services from C++ using gSOAP <http://coab.wordpress.com/2009/10/15/calling-wcf-services-from-a-linux-c-client-using-gsoap/>`_
+   auth_tutorial
+   akhet_sqlalchemy
+   open_id_auth
+   enterprise
+
+For basic information on authentication and authorization, see the
+`security <http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/security.html>`_
+section of the Pyramid documentation.
 

auth/open_id_auth.rst

@@ -0,0 +1,11 @@
+Google, Facebook, Twitter, and any OpenID Authentication
+========================================================
+
+See `Wayne Witzel III's blog post
+<http://pieceofpy.com/blog/2011/07/24/pyramid-and-velruse-for-google-authentication/>`_
+about using Velruse and Pyramid together to do Google OAuth authentication.
+
+See Matthew Housden and Chris Davies apex project for any basic and 
+openid authentication such as Google, Facebook, Twitter and more at 
+https://github.com/cd34/apex.
+

conf.py

@@ -34,7 +34,11 @@
     'sphinx.ext.intersphinx'
     ]
 
-intersphinx_mapping = {'http://docs.pylonsproject.org/projects/pyramid/en/latest/': None}
+intersphinx_mapping = {
+     'python': ('http://docs.python.org', None),
+     'python3': ('http://docs.python.org/3', None),
+     'pyramid': ('http://docs.pylonsproject.org/projects/pyramid/en/latest', None),
+}
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

configuration/index.rst

@@ -3,6 +3,14 @@ Configuration
 
 .. toctree::
   :maxdepth: 2
-
+  
   whirlwind_tour
   django_settings
+
+For more information on configuration see the following sections of the Pyramid documentation:
+
+- `basic configuration <http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/configuration.html>`_
+- `advanced configuration <http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/advconfig.html>`_
+- `configuration introspection <http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/introspector.html>`_
+- `extending configuration <http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/extconfig.html>`_
+- `PasteDeploy configuration <http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/paste.html>`_

configuration/whirlwind_tour.rst

@@ -350,7 +350,7 @@ the pending configuration action impled by the first call to ``add_view`` by
 calling ``config.commit()`` explicitly.  When we called the ``add_view`` the
 second time, the discriminator of the first call to ``add_view`` was no
 longer in the pending actions list to conflict with.  The conflict was
-resolved because conflict the actions list got flushed.  Why do we see ``Hi
+resolved because the pending actions list got flushed.  Why do we see ``Hi
 world!`` in our browser instead of ``Hello world!``?  Because the call to
 ``config.make_wsgi_app()`` implies a second commit.  The second commit caused
 the second ``add_view`` configuration callback to be called, and this

debugging.rst → debugging/debugging_pyramid.rst

@@ -1,34 +1,3 @@
-Debugging
-=========
-
-Using PDB to Debug Your Application
-+++++++++++++++++++++++++++++++++++
-
-``pdb`` is an interactive tool that comes with Python, which allows you to
-break your program at an arbitrary point, examine values, and step through
-code.  It's often much more useful than print statements or logging
-statements to examine program state.  You can place a ``pdb.set_trace()``
-statement in your Pyramid application at a place where you'd like to examine
-program state.  When you issue a request to the application, and that point
-in your code is reached, you will be dropped into the ``pdb`` debugging
-console within the terminal that you used to start your application.
-
-There are lots of great resources that can help you learn PDB.
-
-- Doug Hellmann's PyMOTW blog entry entitled "pdb - Interactive Debugger" at
-  http://blog.doughellmann.com/2010/09/pymotw-pdb-interactive-debugger.html
-  is the canonical text resource to learning PDB.
-
-- The PyCon video presentation by Chris McDonough entitled "Introduction to
-  PDB" at http://pyvideo.org/video/644/introduction-to-pdb is a good place to
-  start learning PDB.
-
-- The video at http://marakana.com/forums/python/python/423.html shows you
-  how to start how to start to using pdb.  The video describes using ``pdb``
-  in a command-line program.
-
-Below is a debugging scenario using PDB to debug Pyramid.
-
 Debugging Pyramid
 +++++++++++++++++
 

debugging/index.rst

@@ -0,0 +1,10 @@
+Debugging
+%%%%%%%%%
+
+.. toctree::
+   :maxdepth: 2
+
+   using_pdb
+   debugging_pyramid
+   pydev
+

debugging/pydev.rst

@@ -0,0 +1,176 @@
+Debugging with PyDev
+++++++++++++++++++++
+
+``pdb`` is a great tool for debugging python scripts, but it has some
+limitations to its usefulness. For example, you must modify your code
+to insert breakpoints, and its command line interface can be somewhat obtuse.
+
+Many developers use custom text editors that that allow them to add wrappers
+to the basic command line environment, with support for git and other
+development tools. In many cases, however, debugging support basically
+ends up being simply a wrapper around basic ``pdb`` functionality.
+
+`PyDev <http://pydev.org>`_ is an `Eclipse <http://eclipse.org>`_ plugin
+for the Python language, providing an integrated development environment
+that includes a built in python interpreter, Git support, integration with
+task management, and other useful development functionality.
+
+The PyDev debugger allows you to execute code without modifying the source
+to set breakpoints, and has a gui interface that allows you to inspect
+and modify internal state.
+
+Lars Vogella has provided a clear `tutorial
+<http://www.vogella.com/articles/Python/article.html>`_
+on setting up pydev and getting started with the PyDev debugger. Full
+documentation on using the PyDev debugger may be found `here
+<http://www.pydev.org/manual_adv_debugger.html>`_. You can also debug
+programs not running under Eclipse using the `Remote Debugging
+<http://www.pydev.org/manual_adv_remote_debugger.html>`_ feature.
+
+PyDev allows you to configure the system to use any python intepreter you
+have installed on your machine, and with proper configuration you can support
+both 2.x and 3.x syntax.
+
+Configuring PyDev for a virtualenv
+----------------------------------
+
+Most of the time you want to be running your code in a virtualenv in order
+to be sure that your code is isolated and all the right versions of your
+package dependencies are available. You can ``pip install virtualenv`` if
+you like, but I recommend `virtualenvwrapper
+<https://bitbucket.org/dhellmann/virtualenvwrapper>`_
+which eliminates much of the busywork of setting up virtualenvs.
+
+PyDev will look through all the libraries on your ``PYTHONPATH`` to resolve all
+your external references, such as imports, etc. So you will want the virtualenv
+libraries on your ``PYTHONPATH`` to avoid unnecessary name-resolution problems.
+
+To use PyDev with virtualenv takes some additional configuration that isn't
+covered in the above tutorial. Basically, you just need to make sure your
+virtualenv libraries are in the ``PYTHONPATH``.
+
+.. note::
+
+   If you have never configured a python interpreter for your workspace,
+   you will not be able to create a project without doing so. You should follow
+   the steps below to configure python, but you should NOT include any
+   virtualenv libraries for it. Then you will be able to create projects using
+   this primary python interpreter. After you create your project, you should
+   then follow the steps below to configure a new interpreter specifically for
+   your project which does include the virtualenv libraries. This way, each
+   project can be related to a specific virtualenv without confusion.
+
+First, open the project properties by right clicking over the project name
+and selecting *Properties*.
+
+In the Properties dialog, select *PyDev - Interpreter/Grammar*, and make
+sure that the project type *Python* is selected. Click on the "Click here
+to configure an interpreter not listed" link. The *Preferences* dialog will
+come up with *Python Interpreters* page, and your current interpreter
+selected. Click on the *New...* button.
+
+Enter a name (e.g. ``pytest_python``) and browse to your virtualenv bin 
+directory (e.g. ``~/.virtual_envs/pytest/bin/python``) to select
+the python interpreter in that location, then select *OK*.
+
+A dialog will then appear asking you to choose the libraries that should 
+be on the ``PYTHONPATH``. Most of the necessary libraries should be automatically
+selected. Hit *OK*, and your virtualenv python is now configured.
+
+.. note::
+
+   On the Mac, the system libraries are not selected. Select them all.
+
+You will finally be back on the dialog for configuring your project python
+interpreter/grammar. Choose the interpreter you just configured and click
+*OK*. You may also choose the grammar level (2.7, 3.0, etc.) at this time.
+
+At this point, formerly unresolved references to libraries installed in your
+virtualenv should no longer be called out as errors. (You will have to 
+close and reopen any python modules before the new interpreter will take
+effect.)
+
+Remember also when using the PyDev console, to choose the interpreter
+associated with the project so that references in the console will
+be properly resolved.
+
+Running/Debugging Pyramid under Pydev
+-------------------------------------
+
+(Thanks to Michael Wilson for much of this - see `Setting up Eclipse
+(PyDev) for Pyramid
+<http://mikeiz404-terminal.blogspot.com/2012/05/setting-up-eclipse-pydev-for-pyramid.html>`_)
+
+.. note::
+
+   This section assumes you have created a virtualenv with Pyramid installed,
+   and have configured your PyDev as above for this virtualenv.
+   We further assume you are using ``virtualenvwrapper`` (see above) so that
+   ``$WORKON_HOME`` is the location of your ``.virtualenvs`` directory
+   and ``proj_venv`` is the name of your virtualenv.
+   ``$WORKSPACE`` is the name of the PyDev workspace containing your project
+
+   To create a working example, copy the `pyramid tutorial step03 
+   <https://pyramid_tutorials.readthedocs.org/en/latest/getting_started/03-config/index.html>`_
+   code into $WORKSPACE/tutorial.
+
+   After copying the code, cd to ``$WORKSPACE/tutorial`` and run
+   ``python setup.py develop``
+
+   You should now be ready to setup PyDev to run the tutorial step03 code.
+
+We will set up PyDev to run pserve as part of a run or debug configuration.
+
+First, copy ``pserve.py`` from your virtualenv to a location outside of your
+project library path::
+
+	cp $WORKON_HOME/proj_venv/bin/pserve.py $WORKSPACE
+
+.. note::
+
+   IMPORTANT: Do not put this in your project library path!
+
+Now we need to have PyDev run this by default. To create a new run
+configuration, right click on the project and select
+*Run As -> Run Configurations...*. Select *Python Run* as your
+configuration type, and click on the new configuration icon. Add your
+project name (or browse to it), in this case "tutorial".
+
+Add these values to the *Main* tab::
+
+	Project: RunPyramid
+	Main Module: ${workspace_loc}/pserve.py
+	
+Add these values to the *Arguments* tab::
+
+	Program arguments: ${workspace_loc:tutorial/development.ini} --reload
+
+.. note::
+
+   Do not add ``--reload`` if you are trying to debug with
+   Eclipse. It has been reported that this causes problems.
+
+   We recommend you create a separate debug configuration
+   without the ``--reload``, and instead of checking "Run"
+   in the "Display in favorites menu", check "Debug".
+
+On the *Common* tab::
+
+	Uncheck "Launch in background"
+	In the box labeled "Display in favorites menu", check "Run"
+
+Hit *Run* (*Debug*) to run (debug) your configuration immediately,
+or *Apply* to create the configuration without running it.
+
+You can now run your application at any time by selecting the *Run/Play*
+button and selecting the *RunPyramid* command. Similarly, you can
+debug your application by selecting the *Debug* button and selecting
+the *DebugPyramid* command (or whatever you called it!).
+
+The console should show that the server has started. To verify, open
+your browser to 127.0.0.1:6547. You should see the hello world text.
+
+Note that when debugging, breakpoints can be set as with ordinary code,
+but they will only be hit when the view containing the breakpoint
+is served.
+