diff options
Diffstat (limited to 'docs')
31 files changed, 279 insertions, 430 deletions
diff --git a/docs/Makefile b/docs/Makefile index c98fdc65e..12dc88bf8 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -63,8 +63,13 @@ latex: cp _static/latex-note.png _build/latex @echo @echo "Build finished; the LaTeX files are in _build/latex." - @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ - "run these through (pdf)latex." + @echo "Run \`make latexpdf' to build a PDF file from them." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C _build/latex all-pdf + @echo "pdflatex finished; the PDF file is in _build/latex." changes: mkdir -p _build/changes _build/doctrees diff --git a/docs/api/config.rst b/docs/api/config.rst index 39d504348..1f65be9f1 100644 --- a/docs/api/config.rst +++ b/docs/api/config.rst @@ -135,3 +135,4 @@ will only exist for the lifetime of the actual applications for which they are being used. +.. autoclass:: not_ diff --git a/docs/api/request.rst b/docs/api/request.rst index b1f5918d7..a90cb1ac0 100644 --- a/docs/api/request.rst +++ b/docs/api/request.rst @@ -156,7 +156,7 @@ .. attribute:: matched_route If a :term:`route` has matched during this request, this attribute will - be an obect representing the route matched by the URL pattern + be an object representing the route matched by the URL pattern associated with the route. If a route has not matched during this request, the value of this attribute will be ``None``. See :ref:`matched_route`. @@ -238,7 +238,7 @@ .. attribute:: response_* In Pyramid 1.0, you could set attributes on a - :class:`pyramid.request.Request` which influenced the behavor of + :class:`pyramid.request.Request` which influenced the behavior of *rendered* responses (views which use a :term:`renderer` and which don't directly return a response). These attributes began with ``response_``, such as ``response_headerlist``. If you needed to diff --git a/docs/authorintro.rst b/docs/authorintro.rst index f1a9d1484..b3cd68494 100644 --- a/docs/authorintro.rst +++ b/docs/authorintro.rst @@ -73,7 +73,7 @@ This book is divided into three major parts: concepts in terms of the sample. You should read the tutorials if you want a guided tour of :app:`Pyramid`. -:ref:`api_reference` +:ref:`api_documentation` Comprehensive reference material for every public API exposed by :app:`Pyramid`. The API documentation is organized diff --git a/docs/conf.py b/docs/conf.py index 84b01a791..ff5f325d8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -93,7 +93,7 @@ copyright = '2008-%s, Agendaless Consulting' % thisyear # other places throughout the built documents. # # The short X.Y version. -version = '1.4' +version = '1.5dev' # The full version, including alpha/beta/rc tags. release = version diff --git a/docs/foreword.rst b/docs/foreword.rst index aa8d7c77b..cc8271bdf 100644 --- a/docs/foreword.rst +++ b/docs/foreword.rst @@ -1,3 +1,5 @@ +:orphan: + Foreword ======== diff --git a/docs/index.rst b/docs/index.rst index 93b550d60..5dfbbce1e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -37,6 +37,7 @@ What's New .. toctree:: :maxdepth: 1 + whatsnew-1.5 whatsnew-1.4 whatsnew-1.3 whatsnew-1.2 @@ -45,7 +46,7 @@ What's New .. _html_narrative_documentation: -Narrative documentation +Narrative Documentation ======================= Narrative documentation in chapter form explaining how to use @@ -108,10 +109,9 @@ platforms. tutorials/wiki/index.rst tutorials/bfg/index.rst tutorials/modwsgi/index.rst - tutorials/pycharm/index.rst API Documentation -================== +================= Comprehensive reference material for every public API exposed by :app:`Pyramid`: @@ -216,13 +216,8 @@ Index and Glossary * :ref:`genindex` * :ref:`search` - -.. add glossary, foreword, and latexindex in a hidden toc to avoid warnings - .. toctree:: :hidden: glossary - foreword.rst - latexindex.rst diff --git a/docs/latexindex.rst b/docs/latexindex.rst index 6bb875f73..e2ba108ee 100644 --- a/docs/latexindex.rst +++ b/docs/latexindex.rst @@ -1,13 +1,15 @@ +:orphan: + .. _latexindex: -@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ -The :app:`Pyramid` Web Application Framework -@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ +================================================= +The Pyramid Web Application Development Framework +================================================= .. frontmatter:: Front Matter -@@@@@@@@@@@@ +============ .. toctree:: :maxdepth: 1 @@ -21,15 +23,15 @@ Front Matter .. _narrative_documentation: Narrative Documentation -@@@@@@@@@@@@@@@@@@@@@@@ +======================= .. toctree:: :maxdepth: 1 narr/introduction narr/install - narr/configuration narr/firstapp + narr/configuration narr/project narr/startup narr/router @@ -50,6 +52,7 @@ Narrative Documentation narr/vhosting narr/testing narr/resources + narr/hellotraversal narr/muchadoabouttraversal narr/traversal narr/security @@ -60,58 +63,39 @@ Narrative Documentation narr/extending narr/advconfig narr/extconfig + narr/scaffolding + narr/upgrading narr/threadlocals narr/zca .. _tutorials: Tutorials -@@@@@@@@@ +========= .. toctree:: :maxdepth: 1 - tutorials/wiki/index.rst tutorials/wiki2/index.rst + tutorials/wiki/index.rst tutorials/bfg/index.rst tutorials/modwsgi/index.rst -.. _api_reference: +.. _api_documentation: -API Reference -@@@@@@@@@@@@@ +API Documentation +================= .. toctree:: :maxdepth: 1 + :glob: - api/authorization - api/authentication - api/config - api/events - api/exceptions - api/httpexceptions - api/i18n - api/interfaces - api/location - api/paster - api/registry - api/renderers - api/request - api/response - api/scripting - api/security - api/settings - api/testing - api/threadlocal - api/traversal - api/url - api/view - api/wsgi + api/* .. backmatter:: Glossary and Index -@@@@@@@@@@@@@@@@@@ +================== .. toctree:: :maxdepth: 1 diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index e1347f3ca..17e5227fa 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -474,6 +474,30 @@ input of the ``prequest`` process is used as the ``POST`` body:: $ $VENV/bin/prequest -mPOST development.ini / < somefile +Showing All Installed Distributions and their Versions +------------------------------------------------------ + +.. versionadded:: 1.5 + +You can use the ``pdistreport`` command to show the Pyramid version in use, the +Python version in use, and all installed versions of Python distributions in +your Python environment:: + + $ $VENV/bin/pdistreport + Pyramid version: 1.5dev + Platform Linux-3.2.0-51-generic-x86_64-with-debian-wheezy-sid + Packages: + authapp 0.0 + /home/chrism/projects/foo/src/authapp + beautifulsoup4 4.1.3 + /home/chrism/projects/foo/lib/python2.7/site-packages/beautifulsoup4-4.1.3-py2.7.egg + ... more output ... + +``pdistreport`` takes no options. Its output is useful to paste into a +pastebin when you are having problems and need someone with more familiarity +with Python packaging and distribution than you have to look at your +environment. + .. _writing_a_script: Writing a Script diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 74765f8e2..2964686d3 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -808,7 +808,7 @@ If this setting is supplied within the :app:`Pyramid` application default_locale_name = settings['pyramid.default_locale_name'] .. index:: - single: detecting langauges + single: detecting languages "Detecting" Available Languages ------------------------------- @@ -984,7 +984,7 @@ requires no additional coding or configuration. The default locale negotiator implementation named :class:`~pyramid.i18n.default_locale_negotiator` uses the following -set of steps to dermine the locale name. +set of steps to determine the locale name. - First, the negotiator looks for the ``_LOCALE_`` attribute of the request object (possibly set directly by view code or by a listener diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 48164d323..032f4be6b 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -217,6 +217,8 @@ that the Pyramid core doesn't. Add-on packages already exist which let you easily send email, let you use the Jinja2 templating system, let you use XML-RPC or JSON-RPC, let you integrate with jQuery Mobile, etc. +Examples: http://docs.pylonsproject.org/en/latest/docs/pyramid.html#pyramid-add-on-documentation + Class-based and function-based views ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -857,7 +859,7 @@ It's our goal that no Pyramid question go unanswered. Whether you ask a question on IRC, on the Pylons-discuss maillist, or on StackOverflow, you're likely to get a reasonably prompt response. We don't tolerate "support trolls" or other people who seem to get their rocks off by berating fellow -users in our various offical support channels. We try to keep it well-lit +users in our various official support channels. We try to keep it well-lit and new-user-friendly. Example: Visit irc\://freenode.net#pyramid (the ``#pyramid`` channel on diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 9d69a65a5..e25f3012a 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -1005,12 +1005,12 @@ Pyramid application based on the data in the file. application. As we saw in :ref:`firstapp_chapter`, ``pserve`` needn't be invoked at all to run a :app:`Pyramid` application. The use of ``pserve`` to run a :app:`Pyramid` application is purely conventional based on the output -of its scaffolding. But we strongly recommend using while developing your -application, because many other convenience introspection commands (such as -``pviews``, ``prequest``, ``proutes`` and others) are also implemented in -terms of configuration availability of this ``.ini`` file format. It also -configures Pyramid logging and provides the ``--reload`` switch for -convenient restarting of the server when code changes. +of its scaffolding. But we strongly recommend using ``pserve`` while +developing your application, because many other convenience introspection +commands (such as ``pviews``, ``prequest``, ``proutes`` and others) are also +implemented in terms of configuration availability of this ``.ini`` file +format. It also configures Pyramid logging and provides the ``--reload`` +switch for convenient restarting of the server when code changes. .. _alternate_wsgi_server: diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 20a9eda31..a2811dbae 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -198,7 +198,7 @@ representing the JSON serialization of the return value: .. code-block:: python - '{"content": "Hello!"}' + {"content": "Hello!"} The return value needn't be a dictionary, but the return value must contain values serializable by the configured serializer (by default ``json.dumps``). diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index 7ec280c8a..82440060c 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -148,6 +148,7 @@ Some gotchas: .. index:: single: pyramid_beaker single: Beaker + single: pyramid_redis_sessions single: session factory (alternates) .. _using_alternate_session_factories: @@ -155,11 +156,17 @@ Some gotchas: Using Alternate Session Factories --------------------------------- -At the time of this writing, exactly one alternate session factory -implementation exists, named ``pyramid_beaker``. This is a session factory -that uses the `Beaker <http://beaker.groovie.org/>`_ library as a backend. -Beaker has support for file-based sessions, database based sessions, and -encrypted cookie-based sessions. See `the pyramid_beaker documentation +At the time of this writing, exactly two alternate session factories +exist. + +The first is named ``pyramid_redis_sessions``. It can be downloaded from PyPI. +It uses Redis as a backend. It is the recommended persistent session solution +at the time of this writing. + +The second is named ``pyramid_beaker``. This is a session factory that uses the +`Beaker <http://beaker.groovie.org/>`_ library as a backend. Beaker has +support for file-based sessions, database based sessions, and encrypted +cookie-based sessions. See `the pyramid_beaker documentation <http://docs.pylonsproject.org/projects/pyramid_beaker/en/latest/>`_ for more information about ``pyramid_beaker``. diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst index 2eb6ece13..a60c5ba56 100644 --- a/docs/narr/traversal.rst +++ b/docs/narr/traversal.rst @@ -289,7 +289,7 @@ system uses this algorithm to find a :term:`context` resource and a return resource "C". #. Traversal ends when a) the entire path is exhausted or b) when any - resouce raises a :exc:`KeyError` from its ``__getitem__`` or c) when any + resource raises a :exc:`KeyError` from its ``__getitem__`` or c) when any non-final path element traversal does not have a ``__getitem__`` method (resulting in a :exc:`AttributeError`) or d) when any path element is prefixed with the set of characters ``@@`` (indicating that the characters diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 18cb3e4db..310c160c0 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -865,7 +865,7 @@ Debugging Route Matching ------------------------ It's useful to be able to take a peek under the hood when requests that enter -your application arent matching your routes as you expect them to. To debug +your application aren't matching your routes as you expect them to. To debug route matching, use the ``PYRAMID_DEBUG_ROUTEMATCH`` environment variable or the ``pyramid.debug_routematch`` configuration file setting (set either to ``true``). Details of the route matching decision for a particular request to the diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index 241ce62b5..6a064c209 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -290,9 +290,9 @@ configured view. of the ``REQUEST_METHOD`` of the :term:`WSGI` environment. ``request_param`` - This value can be any string or a sequence of strings. A view declaration - with this argument ensures that the view will only be called when the - :term:`request` has a key in the ``request.params`` dictionary (an HTTP + This value can be any string or a sequence of strings. A view declaration + with this argument ensures that the view will only be called when the + :term:`request` has a key in the ``request.params`` dictionary (an HTTP ``GET`` or ``POST`` variable) that has a name which matches the supplied value. @@ -306,8 +306,6 @@ configured view. consideration of keys and values in the ``request.params`` dictionary. ``match_param`` - .. versionadded:: 1.2 - This param may be either a single string of the format "key=value" or a dict of key/value pairs. @@ -324,6 +322,8 @@ configured view. If ``match_param`` is not supplied, the view will be invoked without consideration of the keys and values in ``request.matchdict``. + .. versionadded:: 1.2 + ``containment`` This value should be a reference to a Python class or :term:`interface` that a parent object in the context resource's :term:`lineage` must provide @@ -505,7 +505,7 @@ configuration stanza: .. code-block:: python :linenos: - config.add_view('mypackage.views.my_view', route_name='ok', + config.add_view('mypackage.views.my_view', route_name='ok', request_method='POST', permission='read') All arguments to ``view_config`` may be omitted. For example: @@ -557,6 +557,35 @@ form of :term:`declarative configuration`, while :meth:`pyramid.config.Configurator.add_view` is a form of :term:`imperative configuration`. However, they both do the same thing. +Inverting Predicate Values +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can invert the meaning of any predicate value by wrapping it in a call to +:class:`pyramid.config.not_`. + +.. code-block:: python + :linenos: + + from pyramid.config import not_ + + config.add_view( + 'mypackage.views.my_view', + route_name='ok', + request_method=not_('POST') + ) + +The above example will ensure that the view is called if the request method +is *not* ``POST``, at least if no other view is more specific. + +This technique of wrapping a predicate value in ``not_`` can be used anywhere +predicate values are accepted: + +- :meth:`pyramid.config.Configurator.add_view` + +- :meth:`pyramid.view.view_config` + +.. versionadded:: 1.5 + .. index:: single: view_config placement @@ -802,7 +831,7 @@ of this: config.add_view( RESTView, route_name='rest', attr='delete', request_method='DELETE') -To reduce the amount of repetion in the ``config.add_view`` statements, we +To reduce the amount of repetition in the ``config.add_view`` statements, we can move the ``route_name='rest'`` argument to a ``@view_default`` class decorator on the RESTView class: diff --git a/docs/tutorials/pycharm/images/create_new_project.png b/docs/tutorials/pycharm/images/create_new_project.png Binary files differdeleted file mode 100644 index f15068b65..000000000 --- a/docs/tutorials/pycharm/images/create_new_project.png +++ /dev/null diff --git a/docs/tutorials/pycharm/images/create_setup.png b/docs/tutorials/pycharm/images/create_setup.png Binary files differdeleted file mode 100644 index de4cb364b..000000000 --- a/docs/tutorials/pycharm/images/create_setup.png +++ /dev/null diff --git a/docs/tutorials/pycharm/images/create_virtual_environment.png b/docs/tutorials/pycharm/images/create_virtual_environment.png Binary files differdeleted file mode 100644 index 0bd3c9263..000000000 --- a/docs/tutorials/pycharm/images/create_virtual_environment.png +++ /dev/null diff --git a/docs/tutorials/pycharm/images/edit_run_debug_configurations.png b/docs/tutorials/pycharm/images/edit_run_debug_configurations.png Binary files differdeleted file mode 100644 index 7708fa9dc..000000000 --- a/docs/tutorials/pycharm/images/edit_run_debug_configurations.png +++ /dev/null diff --git a/docs/tutorials/pycharm/images/install_package.png b/docs/tutorials/pycharm/images/install_package.png Binary files differdeleted file mode 100644 index 944a05f6a..000000000 --- a/docs/tutorials/pycharm/images/install_package.png +++ /dev/null diff --git a/docs/tutorials/pycharm/images/install_package_pyramid.png b/docs/tutorials/pycharm/images/install_package_pyramid.png Binary files differdeleted file mode 100644 index 05a209b6c..000000000 --- a/docs/tutorials/pycharm/images/install_package_pyramid.png +++ /dev/null diff --git a/docs/tutorials/pycharm/images/install_package_setuptools.png b/docs/tutorials/pycharm/images/install_package_setuptools.png Binary files differdeleted file mode 100644 index 8932a3f40..000000000 --- a/docs/tutorials/pycharm/images/install_package_setuptools.png +++ /dev/null diff --git a/docs/tutorials/pycharm/images/python_interpreters_1.png b/docs/tutorials/pycharm/images/python_interpreters_1.png Binary files differdeleted file mode 100644 index 6b1455001..000000000 --- a/docs/tutorials/pycharm/images/python_interpreters_1.png +++ /dev/null diff --git a/docs/tutorials/pycharm/images/python_interpreters_2.png b/docs/tutorials/pycharm/images/python_interpreters_2.png Binary files differdeleted file mode 100644 index 61c3de2b1..000000000 --- a/docs/tutorials/pycharm/images/python_interpreters_2.png +++ /dev/null diff --git a/docs/tutorials/pycharm/images/run_configuration.png b/docs/tutorials/pycharm/images/run_configuration.png Binary files differdeleted file mode 100644 index 4612b2b3c..000000000 --- a/docs/tutorials/pycharm/images/run_configuration.png +++ /dev/null diff --git a/docs/tutorials/pycharm/images/start_up_screen.png b/docs/tutorials/pycharm/images/start_up_screen.png Binary files differdeleted file mode 100644 index c65e01eeb..000000000 --- a/docs/tutorials/pycharm/images/start_up_screen.png +++ /dev/null diff --git a/docs/tutorials/pycharm/index.rst b/docs/tutorials/pycharm/index.rst deleted file mode 100644 index f2e3b7bcb..000000000 --- a/docs/tutorials/pycharm/index.rst +++ /dev/null @@ -1,355 +0,0 @@ -************************** -Using PyCharm with Pyramid -************************** - -This tutorial is a very brief overview of how to use PyCharm with Pyramid. -`PyCharm <http://www.jetbrains.com/pycharm/>`_ is an Integrated Development -Environment (IDE) for Python programmers. It has numerous features including -code completion, project management, version control system (git, Subversion, -etc.), debugger, and more. - -This tutorial is a continual evolving document. Both PyCharm and Pyramid are -under active development, and changes to either may necessitate changes to -this document. In addition, there may be errors or omissions in this -document, and corrections and improvements through a pull request are most -welcome. - -To get started with Pyramid in PyCharm, we need to install prerequisite -software. - -* Python -* PyCharm and certain Python packages -* Pyramid and its requirements - -Install Python -============== - -You can download installers for Mac OS X and Windows, or source tarballs for -Linux, Unix, or Mac OS X from `python.org Download -<http://python.org/download/>`_. Follow the instructions in the README files. - -Install PyCharm -=============== - -PyCharm is a commercial application that requires a license. Several license -types are available depending on your usage. - -Pyramid is an open source project, and on an annual basis fulfills the terms of -the Open Source License with JetBrains for the use of PyCharm to develop for -Pyramid under the Pylons Project. If you contribute to Pyramid or the Pylons -Project, and would like to use our 1-year license, please contact the license -maintainer `stevepiercy` in the `#pyramid` channel on `irc.freenode.net`. - -Alternatively you can download a 30-day trial of PyCharm or `purchase a license -<http://www.jetbrains.com/pycharm/buy/index.jsp>`_ for development or training -purposes under any other license. - -`Download PyCharm <http://www.jetbrains.com/pycharm/download/index.html>`_ and -follow the installation instructions on that web page. - -Configure PyCharm -================= - -Create a New Project --------------------- - -Launch the PyCharm application. - -From the Start Up screen, click Create New Project. - -.. image:: images/start_up_screen.png - -If the Start Up screen does not appear, you probably have an existing project -open. Close the existing project and the Start Up screen will appear. - -.. image:: images/create_new_project.png - -In the Create New Project dialog window do the following. - -* Enter a Project name. The Location should automatically populate as you - type. You can change the path as you wish. It is common practice to use the - path `~/projects/` to contain projects. This location shall be referred to - as your "project directory" throughout the rest of this document. -* Project type should be Empty project. -* For Interpreter, click the ellipsis button to create a new virtual - environment. - -A new window appears, "Python Interpreters". - -Create or Select a Python Interpreter -------------------------------------- - -.. image:: images/python_interpreters_1.png - -* Either click the `+` button to add a new Python interpreter for Python - 2.7 (the Python 2.7 installer uses the path - `/Library/Frameworks/Python.framework/Versions/2.7/bin`), or use an existing - Python interpreter for Python 2.7. PyCharm will take a few seconds to add a - new interpreter. - -.. image:: images/python_interpreters_2.png - -Create a Virtual Environment ----------------------------- - -* Click the button with the Python logo and a green "V". A new window appears, - "Create Virtual Environment". - -.. image:: images/create_virtual_environment.png - -* Enter a Virtual Environment name. -* The Location should automatically populate as you type. You can change the - path as you wish. -* The Base interpreter should be already selected, but if not, select - `/Library/Frameworks/Python.framework/Versions/2.7/bin` or other Python 2.7 - interpreter. -* Leave the box unchecked for "Inherit global site packages". -* Click "OK". PyCharm will set up libraries and packages, and return you to - the Python Interpreters window. - -Install setuptools and pyramid Packages ---------------------------------------- - -If you already have setuptools installed, you can skip this step. - -In the Python Interpreters window with the just-created virtual environment -selected in the top pane, in the lower pane select the Packages tab, and click -the Install button. The Available Packages window appears. - -.. image:: images/install_package.png - -In the Available Packages window, in the search bar, enter "setuptools". -Select the plain old "setuptools" package, and click the Install Package button -and wait for the status message to disappear. PyCharm will install the package -and any dependencies. - -.. image:: images/install_package_setuptools.png - -Repeat the previous step, except use "pyramid" for searching and selecting. - -.. image:: images/install_package_pyramid.png - -When PyCharm finishes installing the packages, close the Available Packages -window. - -In the Python Interpreters window, click the OK button. - -In the Create New Project window, click the OK button. - -If PyCharm displays a warning, click the Yes button. PyCharm opens the new -project. - -Clone the Pyramid repository -============================ - -By cloning the Pyramid repository, you can contribute changes to the code or -documentation. We recommend that you fork the Pyramid repository to your own -GitHub account, then clone your forked repository, so that you can commit your -changes to your GitHub repository and submit pull requests to the Pyramid -project. - -In PyCharm, select *VCS > Enable Version Control Integration...*, then select -Git as your VCS and click the OK button. - -See `Cloning a Repository from GitHub <http://www.jetbrains.com/pycharm/webhelp/cloning-a-repository-from-github.html>`_ -in the PyCharm documentation for more information on using GitHub and git in -PyCharm. - -We will refer to the cloned repository of Pyramid on your computer as your -"local Pyramid repository". - -Install development and documentation requirements -================================================== - -In order to contribute bug fixes, features, and documentation changes to -Pyramid, you must install development and documentation requirements into your -virtual environment. Pyramid uses Sphinx and reStructuredText for -documentation. - -* In PyCharm, select *Run > Edit Configurations...*. The Run/Debug - Configurations window appears. - - .. image:: images/edit_run_debug_configurations.png - -* Click the "+" button, then select Python to add a new Python run - configuration. -* Name the configuration "setup dev". -* Either manually enter the path to the `setup.py` script or click the ellipsis - button to navigate to the `pyramid/setup.py` path and select it. -* For Script parameters enter `dev`. -* Click the "Apply" button to save the run configuration. - -While we're here, let's duplicate this run configuration for installing the -documentation requirements. - -* Click the "Copy Configuration" button. Its icon looks like two dog-eared - pages, with a blue page on top of a grey page. -* Name the configuration "setup docs". -* Leave the path as is. -* For Script parameters enter `docs`. -* Click the "Apply" button to save the run configuration. -* Click the "OK" button to return to the project window. - -In the PyCharm toolbar, you will see a Python icon and your run configurations. - -.. image:: images/run_configuration.png - -First select "setup dev", and click the "run" button (the green triangle). It -may take some time to install the requirements. Second select "setup docs", -and click the "run" button again. - -As of this writing, PyCharm does not yet have a command line interface to a -shell. So there are some things that require you to go into a shell to enter -commands. This next step requires doing just so. - -* In your shell, navigate to your project directory, e.g., `cd - ~/projects/pycharm_pyramid/`. -* Enter the command `source bin/activate` to activate your virtual environment. -* Navigate into your local Pyramid repository, e.g., `cd pyramid`. -* Issue the command `git submodule update --init --recursive`. -* Navigate to the `docs` directory in your local Pyramid repository with the - command `cd docs`. -* Issue the command `make clean html` to generate the HTML documentation from - reStructuredText files. -* The HTML files are in `_build/html`. Open up `index.html` in a web browser - to see the result. -* Whenever you want to edit existing docs and see the effect of your changes, - simply run `make html` from within the `docs` directory. - -Unfortunately, the author was unable to figure out how to generate docs in -PyCharm using either a "Python docs" or "Python" run configuration. If anyone -knows, please submit a pull request. - -You will now be ready to hack in and contribute to Pyramid. - -Template Languages -================== - -To configure the template languages Mako and Jinja, see the PyCharm -documentation `Templates -<http://www.jetbrains.com/pycharm/webhelp/templates.html>`_. - -To configure the template language Chameleon, see `Creating and Registering -File Types -<http://www.jetbrains.com/pycharm/webhelp/creating-and-registering-file-types. -html>`_. Specifically for Chameleon, we want to associate XML to the `*.pt` -extension. - -* Open *PyCharm > Preferences...*, then the File Types dialog box. -* From the Recognized File Types list, select "XML files". -* In the Registered Patterns area, click the "+" button, and the Add Wildcard - window opens. Enter `*.pt` in the Add Wildcard window, and click the OK - button. Click OK again to save the settings. - -Creating a Pyramid Project -========================== - -The information for this section is derived from `Creating a Pyramid Project -<http://docs.pylonsproject.org/projects/pyramid/en/master/narr/project.html>`_ -and adapted for use in PyCharm. - -Creating a Pyramid Project Using Scaffolds ------------------------------------------- - -Within PyCharm, you can start a project using a scaffold by doing the -following. - -* Select *Run > Edit Configurations...*. -* Click the "+" button, then select Python to add a new Python run - configuration. -* Name the configuration "pcreate". -* Either manually enter the path to the `pcreate` script or click the ellipsis - button to navigate to the `$VENV/bin/pcreate` path and select it. -* For Script parameters enter `-s starter MyProject`. "starter" is the name of - one of the scaffolds included with Pyramid, but you can use any scaffold. - "MyProject" is the name of your project. -* Select the directory into which you want to place `MyProject`. A common - practice is `~/projects/`. -* Click the OK button to save the run configuration. -* Select *Run > Run 'pcreate'* to run the run configuration. Your project will - be created. -* Select *File > Open directory*, select the directory where you created your - project `MyProject`, and click the Choose button. You will be prompted to - open the project, and you may find it convenient to select "Open in current - window", and check "Add to currently open projects". -* Finally set the Project Interpreter to your virtual environment or verify it - as such. Select *PyCharm > Preferences... > Project Interpreter*, and verify - that the project is using the same virtual environment as the parent project. -* If a yellow bar warns you to install requirements, then click link to do so. - -Installing your Newly Created Project for Development ------------------------------------------------------ - -We will create another run configuration, just like before. - -* In PyCharm, select the `setup.py` script in the `MyProject` folder. This - should populate some fields with the proper values. -* Select *Run > Edit Configurations...*. -* Click the "+" button, then select Python to add a new Python run - configuration. -* Name the configuration "MyProject setup develop". -* Either manually enter the path to the `setup.py` script in the `MyProject` - folder or click the ellipsis button to navigate to the path and select it. -* For Script parameters enter `develop`. -* For Project, select "MyProject". -* For Working directory, enter or select the path to `MyProject`. -* Click the "Apply" button to save the run configuration. -* Finally run the run configuration "MyProject setup develop". Your project - will be installed. - -Running The Tests For Your Application --------------------------------------- - -We will create yet another run configuration. [If you know of an easier method -while in PyCharm, please submit a pull request.] - -* Select *Run > Edit Configurations...*. -* Select the previous run configuration "MyProject setup develop", and click - the Copy Configuration button. -* Name the configuration "MyProject setup test". -* The path to the `setup.py` script in the `MyProject` folder should already be - entered. -* For Script parameters enter `test -q`. -* For Project "MyProject" should be selected. -* For Working directory, the path to `MyProject` should be selected. -* Click the "Apply" button to save the run configuration. -* Finally run the run configuration "MyProject setup test". Your project will - run its unit tests. - -Running The Project Application -------------------------------- - -When will creation of run configurations end? Not today! - -* Select *Run > Edit Configurations...*. -* Select the previous run configuration "MyProject setup develop", and click - the Copy Configuration button. -* Name the configuration "MyProject pserve". -* Either manually enter the path to the `pserve` script or click the ellipsis - button to navigate to the `$VENV/bin/pserve` path and select it. -* For Script parameters enter `development.ini`. -* For Project "MyProject" should be selected. -* For Working directory, the path to `MyProject` should be selected. -* Click the "Apply" button to save the run configuration. -* Finally run the run configuration "MyProject pserve". Your project will run. - Click the link in the Python console or visit the URL http://0.0.0.0:6543/ in - a web browser. - -You can also reload any changes to your project's `.py` or `.ini` files -automatically by using the Script parameters `development.ini --reload`. - -Debugging -========= - -See the PyCharm documentation `Running and Debugging -<http://www.jetbrains.com/pycharm/webhelp/running-and-debugging.html>`_ for -details on how to debug your Pyramid app in PyCharm. - -First, you cannot simultaneously run and debug your app. Terminate your app if -it is running before you debug it. - -To debug your app, open a file in your app that you want to debug and click on -the gutter (the space between line numbers and the code) to set a breakpoint. -Then select "MyProject pserve" in the PyCharm toolbar, then click the debug -icon (which looks like a green ladybug). Your app will run up to the first -breakpoint. diff --git a/docs/whatsnew-1.1.rst b/docs/whatsnew-1.1.rst index 5cba8dd3e..cc63017df 100644 --- a/docs/whatsnew-1.1.rst +++ b/docs/whatsnew-1.1.rst @@ -13,7 +13,7 @@ Terminology Changes The term "template" used by the Pyramid documentation used to refer to both "paster templates" and "rendered templates" (templates created by a rendering engine. i.e. Mako, Chameleon, Jinja, etc.). "Paster templates" will now be -refered to as "scaffolds", whereas the name for "rendered templates" will +referred to as "scaffolds", whereas the name for "rendered templates" will remain as "templates." Major Feature Additions @@ -397,7 +397,7 @@ Deprecations and Behavior Differences shell you use to invoke ``paster serve`` to see these warnings, e.g. on UNIX, ``PYTHONWARNINGS=all $VENV/bin/paster serve development.ini``. Python 2.5 and 2.6 show deprecation warnings by default, - so this is unecessary there. + so this is unnecessary there. All deprecation warnings are emitted to the console. - The :class:`pyramid.view.static` class has been deprecated in favor of the diff --git a/docs/whatsnew-1.5.rst b/docs/whatsnew-1.5.rst new file mode 100644 index 000000000..b987fa77f --- /dev/null +++ b/docs/whatsnew-1.5.rst @@ -0,0 +1,155 @@ +What's New In Pyramid 1.5 +========================= + +This article explains the new features in :app:`Pyramid` version 1.5 as +compared to its predecessor, :app:`Pyramid` 1.4. It also documents backwards +incompatibilities between the two versions and deprecations added to +:app:`Pyramid` 1.5, as well as software dependency changes and notable +documentation additions. + +Feature Additions +----------------- + +The feature additions in Pyramid 1.5 follow. + +- Add ``pdistreport`` script, which prints the Python version in use, the + Pyramid version in use, and the version number and location of all Python + distributions currently installed. + +- Add the ability to invert the result of any view, route, or subscriber + predicate value using the ``not_`` class. For example: + + .. code-block:: python + + from pyramid.config import not_ + + @view_config(route_name='myroute', request_method=not_('POST')) + def myview(request): ... + + The above example will ensure that the view is called if the request method + is not POST, at least if no other view is more specific. + + The :class:`pyramid.config.not_` class can be used against any value that is + a predicate value passed in any of these contexts: + + - :meth:`pyramid.config.Configurator.add_view` + + - :meth:`pyramid.config.Configurator.add_route` + + - :meth:`pyramid.config.Configurator.add_subscriber` + + - :meth:`pyramid.view.view_config` + + - :meth:`pyramid.events.subscriber` + +- View lookup will now search for valid views based on the inheritance + hierarchy of the context. It tries to find views based on the most specific + context first, and upon predicate failure, will move up the inheritance chain + to test views found by the super-type of the context. In the past, only the + most specific type containing views would be checked and if no matching view + could be found then a PredicateMismatch would be raised. Now predicate + mismatches don't hide valid views registered on super-types. Here's an + example that now works: + + .. code-block:: python + + class IResource(Interface): + + ... + + @view_config(context=IResource) + def get(context, request): + + ... + + @view_config(context=IResource, request_method='POST') + def post(context, request): + + ... + + @view_config(context=IResource, request_method='DELETE') + def delete(context, request): + + ... + + @implementor(IResource) + class MyResource: + + ... + + @view_config(context=MyResource, request_method='POST') + def override_post(context, request): + + ... + + Previously the override_post view registration would hide the get + and delete views in the context of MyResource -- leading to a + predicate mismatch error when trying to use GET or DELETE + methods. Now the views are found and no predicate mismatch is + raised. + See https://github.com/Pylons/pyramid/pull/786 and + https://github.com/Pylons/pyramid/pull/1004 and + https://github.com/Pylons/pyramid/pull/1046 + +- ``scripts/prequest.py`` (aka the ``prequest`` console script): added support + for submitting ``PUT`` and ``PATCH`` requests. See + https://github.com/Pylons/pyramid/pull/1033. add support for submitting + ``OPTIONS`` and ``PROPFIND`` requests, and allow users to specify basic + authentication credentials in the request via a ``--login`` argument to the + script. See https://github.com/Pylons/pyramid/pull/1039. + +- :class:`pyramid.authorization.ACLAuthorizationPolicy` supports ``__acl__`` as + a callable. This removes the ambiguity between the potential + ``AttributeError`` that would be raised on the ``context`` when the property + was not defined and the ``AttributeError`` that could be raised from any + user-defined code within a dynamic property. It is recommended to define a + dynamic ACL as a callable to avoid this ambiguity. See + https://github.com/Pylons/pyramid/issues/735. + +- Allow a protocol-relative URL (e.g. ``//example.com/images``) to be passed to + :meth:`pyramid.config.Configurator.add_static_view`. This allows + externally-hosted static URLs to be generated based on the current protocol. + +- The :class:`pyramid.authentication.AuthTktAuthenticationPolicy` has a new + ``parent_domain`` option to set the authentication cookie as a wildcard + cookie on the parent domain. This is useful if you have multiple sites + sharing the same domain. It also now supports IPv6 addresses when using + the ``include_ip=True`` option. This is possibly incompatible with + alternative ``auth_tkt`` implementations, as the specification does not + define how to properly handle IPv6. See + https://github.com/Pylons/pyramid/issues/831. + +- Make it possible to use variable arguments via + :func:`pyramid.paster.get_appsettings`. This also allowed the generated + ``initialize_db`` script from the ``alchemy`` scaffold to grow support for + options in the form ``a=1 b=2`` so you can fill in values in a parameterized + ``.ini`` file, e.g. ``initialize_myapp_db etc/development.ini a=1 b=2``. See + https://github.com/Pylons/pyramid/pull/911 + +- The ``request.session.check_csrf_token()`` method and the ``check_csrf`` view + predicate now take into account the value of the HTTP header named + ``X-CSRF-Token`` (as well as the ``csrf_token`` form parameter, which they + always did). The header is tried when the form parameter does not exist. + +Backwards Incompatibilities +--------------------------- + +This release has no known backwards incompatibilities with Pyramid 1.4.X. + +Deprecations +------------ + +This release has no new deprecations as compared to Pyramid 1.4.X. + + +Documentation Enhancements +-------------------------- + +Many documentation enhancements have been added, but we did not track them as +they were added. + +Dependency Changes +------------------ + +No dependency changes from Pyramid 1.4.X were made in Pyramid 1.5. + |
