From 904981635bcaa54b9cd94538ac5c3db07cfe3ee7 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 13 Jul 2013 16:11:24 -0600 Subject: New tutorial: Using PyCharm with Pyramid --- docs/index.rst | 1 + .../pycharm/images/create_new_project.png | Bin 0 -> 118472 bytes docs/tutorials/pycharm/images/create_setup.png | Bin 0 -> 123209 bytes .../pycharm/images/create_virtual_environment.png | Bin 0 -> 42991 bytes .../images/edit_run_debug_configurations.png | Bin 0 -> 106932 bytes docs/tutorials/pycharm/images/install_package.png | Bin 0 -> 69633 bytes .../pycharm/images/install_package_pyramid.png | Bin 0 -> 125125 bytes .../pycharm/images/install_package_setuptools.png | Bin 0 -> 107886 bytes .../pycharm/images/python_interpreters_1.png | Bin 0 -> 130060 bytes .../pycharm/images/python_interpreters_2.png | Bin 0 -> 130852 bytes .../tutorials/pycharm/images/run_configuration.png | Bin 0 -> 57129 bytes docs/tutorials/pycharm/images/start_up_screen.png | Bin 0 -> 70500 bytes docs/tutorials/pycharm/index.rst | 356 +++++++++++++++++++++ 13 files changed, 357 insertions(+) create mode 100644 docs/tutorials/pycharm/images/create_new_project.png create mode 100644 docs/tutorials/pycharm/images/create_setup.png create mode 100644 docs/tutorials/pycharm/images/create_virtual_environment.png create mode 100644 docs/tutorials/pycharm/images/edit_run_debug_configurations.png create mode 100644 docs/tutorials/pycharm/images/install_package.png create mode 100644 docs/tutorials/pycharm/images/install_package_pyramid.png create mode 100644 docs/tutorials/pycharm/images/install_package_setuptools.png create mode 100644 docs/tutorials/pycharm/images/python_interpreters_1.png create mode 100644 docs/tutorials/pycharm/images/python_interpreters_2.png create mode 100644 docs/tutorials/pycharm/images/run_configuration.png create mode 100644 docs/tutorials/pycharm/images/start_up_screen.png create mode 100644 docs/tutorials/pycharm/index.rst (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index bc711f8ff..93b550d60 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -108,6 +108,7 @@ platforms. tutorials/wiki/index.rst tutorials/bfg/index.rst tutorials/modwsgi/index.rst + tutorials/pycharm/index.rst API Documentation ================== diff --git a/docs/tutorials/pycharm/images/create_new_project.png b/docs/tutorials/pycharm/images/create_new_project.png new file mode 100644 index 000000000..f15068b65 Binary files /dev/null and b/docs/tutorials/pycharm/images/create_new_project.png differ diff --git a/docs/tutorials/pycharm/images/create_setup.png b/docs/tutorials/pycharm/images/create_setup.png new file mode 100644 index 000000000..de4cb364b Binary files /dev/null and b/docs/tutorials/pycharm/images/create_setup.png differ diff --git a/docs/tutorials/pycharm/images/create_virtual_environment.png b/docs/tutorials/pycharm/images/create_virtual_environment.png new file mode 100644 index 000000000..0bd3c9263 Binary files /dev/null and b/docs/tutorials/pycharm/images/create_virtual_environment.png differ diff --git a/docs/tutorials/pycharm/images/edit_run_debug_configurations.png b/docs/tutorials/pycharm/images/edit_run_debug_configurations.png new file mode 100644 index 000000000..7708fa9dc Binary files /dev/null and b/docs/tutorials/pycharm/images/edit_run_debug_configurations.png differ diff --git a/docs/tutorials/pycharm/images/install_package.png b/docs/tutorials/pycharm/images/install_package.png new file mode 100644 index 000000000..944a05f6a Binary files /dev/null and b/docs/tutorials/pycharm/images/install_package.png differ diff --git a/docs/tutorials/pycharm/images/install_package_pyramid.png b/docs/tutorials/pycharm/images/install_package_pyramid.png new file mode 100644 index 000000000..05a209b6c Binary files /dev/null and b/docs/tutorials/pycharm/images/install_package_pyramid.png differ diff --git a/docs/tutorials/pycharm/images/install_package_setuptools.png b/docs/tutorials/pycharm/images/install_package_setuptools.png new file mode 100644 index 000000000..8932a3f40 Binary files /dev/null and b/docs/tutorials/pycharm/images/install_package_setuptools.png differ diff --git a/docs/tutorials/pycharm/images/python_interpreters_1.png b/docs/tutorials/pycharm/images/python_interpreters_1.png new file mode 100644 index 000000000..6b1455001 Binary files /dev/null and b/docs/tutorials/pycharm/images/python_interpreters_1.png differ diff --git a/docs/tutorials/pycharm/images/python_interpreters_2.png b/docs/tutorials/pycharm/images/python_interpreters_2.png new file mode 100644 index 000000000..61c3de2b1 Binary files /dev/null and b/docs/tutorials/pycharm/images/python_interpreters_2.png differ diff --git a/docs/tutorials/pycharm/images/run_configuration.png b/docs/tutorials/pycharm/images/run_configuration.png new file mode 100644 index 000000000..4612b2b3c Binary files /dev/null and b/docs/tutorials/pycharm/images/run_configuration.png differ diff --git a/docs/tutorials/pycharm/images/start_up_screen.png b/docs/tutorials/pycharm/images/start_up_screen.png new file mode 100644 index 000000000..c65e01eeb Binary files /dev/null and b/docs/tutorials/pycharm/images/start_up_screen.png differ diff --git a/docs/tutorials/pycharm/index.rst b/docs/tutorials/pycharm/index.rst new file mode 100644 index 000000000..1b7c07f98 --- /dev/null +++ b/docs/tutorials/pycharm/index.rst @@ -0,0 +1,356 @@ +************************** +Using PyCharm with Pyramid +************************** + +This tutorial is a very brief overview of how to use PyCharm with Pyramid. +`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 +`_. 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 +`_ for development or training +purposes under any other license. + +`Download PyCharm `_ 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 +`_ 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 +`_. + +To configure the template language Chameleon, see `Creating and Registering +File Types +`_. 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 +`_ +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 +`_ 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. -- cgit v1.2.3 From ffdb7b6892be1952f9ac45091c80aa0500cb6507 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 13 Jul 2013 18:32:07 -0600 Subject: New tutorial: Using PyCharm with Pyramid --- docs/tutorials/pycharm/index.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/pycharm/index.rst b/docs/tutorials/pycharm/index.rst index 1b7c07f98..f2e3b7bcb 100644 --- a/docs/tutorials/pycharm/index.rst +++ b/docs/tutorials/pycharm/index.rst @@ -151,10 +151,9 @@ 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 -`_ in the PyCharm documentation for more information on using GitHub and git -in PyCharm. +See `Cloning a Repository from GitHub `_ +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". -- cgit v1.2.3 From 09d131cd5a3dd387ebf46d6a31f3969fb8239600 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 16 Jul 2013 05:44:10 -0600 Subject: - Correct title - Synch order of chapters --- docs/latexindex.rst | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/latexindex.rst b/docs/latexindex.rst index 6bb875f73..21cea8256 100644 --- a/docs/latexindex.rst +++ b/docs/latexindex.rst @@ -1,8 +1,8 @@ .. _latexindex: -@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ -The :app:`Pyramid` Web Application Framework -@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ +@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ +The :app:`Pyramid` Web Application Development Framework +@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ .. frontmatter:: @@ -28,8 +28,8 @@ Narrative Documentation narr/introduction narr/install - narr/configuration narr/firstapp + narr/configuration narr/project narr/startup narr/router @@ -50,6 +50,7 @@ Narrative Documentation narr/vhosting narr/testing narr/resources + narr/hellotraversal narr/muchadoabouttraversal narr/traversal narr/security @@ -60,6 +61,8 @@ Narrative Documentation narr/extending narr/advconfig narr/extconfig + narr/scaffolding + narr/upgrading narr/threadlocals narr/zca @@ -71,10 +74,11 @@ Tutorials .. toctree:: :maxdepth: 1 - tutorials/wiki/index.rst tutorials/wiki2/index.rst + tutorials/wiki/index.rst tutorials/bfg/index.rst tutorials/modwsgi/index.rst + tutorials/pycharm/index.rst .. _api_reference: -- cgit v1.2.3 From a70d54c9ce1e635feb931eea63e41ea56bae4fb5 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 17 Jul 2013 04:53:03 -0600 Subject: Improve consistency between latexindex.rst and index.rst. --- docs/authorintro.rst | 2 +- docs/index.rst | 4 ++-- docs/latexindex.rst | 18 +++++++++--------- 3 files changed, 12 insertions(+), 12 deletions(-) (limited to 'docs') 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/index.rst b/docs/index.rst index 93b550d60..d1a1e8ee7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -45,7 +45,7 @@ What's New .. _html_narrative_documentation: -Narrative documentation +Narrative Documentation ======================= Narrative documentation in chapter form explaining how to use @@ -111,7 +111,7 @@ platforms. tutorials/pycharm/index.rst API Documentation -================== +================= Comprehensive reference material for every public API exposed by :app:`Pyramid`: diff --git a/docs/latexindex.rst b/docs/latexindex.rst index 21cea8256..416fc9bf1 100644 --- a/docs/latexindex.rst +++ b/docs/latexindex.rst @@ -1,13 +1,13 @@ .. _latexindex: -@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ -The :app:`Pyramid` Web Application Development Framework -@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ +================================================= +The Pyramid Web Application Development Framework +================================================= .. frontmatter:: Front Matter -@@@@@@@@@@@@ +============ .. toctree:: :maxdepth: 1 @@ -21,7 +21,7 @@ Front Matter .. _narrative_documentation: Narrative Documentation -@@@@@@@@@@@@@@@@@@@@@@@ +======================= .. toctree:: :maxdepth: 1 @@ -69,7 +69,7 @@ Narrative Documentation .. _tutorials: Tutorials -@@@@@@@@@ +========= .. toctree:: :maxdepth: 1 @@ -80,10 +80,10 @@ Tutorials tutorials/modwsgi/index.rst tutorials/pycharm/index.rst -.. _api_reference: +.. _api_documentation: -API Reference -@@@@@@@@@@@@@ +API Documentation +================= .. toctree:: :maxdepth: 1 -- cgit v1.2.3 From 4d6281d1c06d85ce64a6cd6d6a8da423053e7d7a Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 17 Jul 2013 05:06:00 -0600 Subject: Remove PyCharm tutorial, since it now resides under pyramid_tutorials --- .../pycharm/images/create_new_project.png | Bin 118472 -> 0 bytes docs/tutorials/pycharm/images/create_setup.png | Bin 123209 -> 0 bytes .../pycharm/images/create_virtual_environment.png | Bin 42991 -> 0 bytes .../images/edit_run_debug_configurations.png | Bin 106932 -> 0 bytes docs/tutorials/pycharm/images/install_package.png | Bin 69633 -> 0 bytes .../pycharm/images/install_package_pyramid.png | Bin 125125 -> 0 bytes .../pycharm/images/install_package_setuptools.png | Bin 107886 -> 0 bytes .../pycharm/images/python_interpreters_1.png | Bin 130060 -> 0 bytes .../pycharm/images/python_interpreters_2.png | Bin 130852 -> 0 bytes .../tutorials/pycharm/images/run_configuration.png | Bin 57129 -> 0 bytes docs/tutorials/pycharm/images/start_up_screen.png | Bin 70500 -> 0 bytes docs/tutorials/pycharm/index.rst | 355 --------------------- 12 files changed, 355 deletions(-) delete mode 100644 docs/tutorials/pycharm/images/create_new_project.png delete mode 100644 docs/tutorials/pycharm/images/create_setup.png delete mode 100644 docs/tutorials/pycharm/images/create_virtual_environment.png delete mode 100644 docs/tutorials/pycharm/images/edit_run_debug_configurations.png delete mode 100644 docs/tutorials/pycharm/images/install_package.png delete mode 100644 docs/tutorials/pycharm/images/install_package_pyramid.png delete mode 100644 docs/tutorials/pycharm/images/install_package_setuptools.png delete mode 100644 docs/tutorials/pycharm/images/python_interpreters_1.png delete mode 100644 docs/tutorials/pycharm/images/python_interpreters_2.png delete mode 100644 docs/tutorials/pycharm/images/run_configuration.png delete mode 100644 docs/tutorials/pycharm/images/start_up_screen.png delete mode 100644 docs/tutorials/pycharm/index.rst (limited to 'docs') diff --git a/docs/tutorials/pycharm/images/create_new_project.png b/docs/tutorials/pycharm/images/create_new_project.png deleted file mode 100644 index f15068b65..000000000 Binary files a/docs/tutorials/pycharm/images/create_new_project.png and /dev/null differ diff --git a/docs/tutorials/pycharm/images/create_setup.png b/docs/tutorials/pycharm/images/create_setup.png deleted file mode 100644 index de4cb364b..000000000 Binary files a/docs/tutorials/pycharm/images/create_setup.png and /dev/null differ diff --git a/docs/tutorials/pycharm/images/create_virtual_environment.png b/docs/tutorials/pycharm/images/create_virtual_environment.png deleted file mode 100644 index 0bd3c9263..000000000 Binary files a/docs/tutorials/pycharm/images/create_virtual_environment.png and /dev/null differ diff --git a/docs/tutorials/pycharm/images/edit_run_debug_configurations.png b/docs/tutorials/pycharm/images/edit_run_debug_configurations.png deleted file mode 100644 index 7708fa9dc..000000000 Binary files a/docs/tutorials/pycharm/images/edit_run_debug_configurations.png and /dev/null differ diff --git a/docs/tutorials/pycharm/images/install_package.png b/docs/tutorials/pycharm/images/install_package.png deleted file mode 100644 index 944a05f6a..000000000 Binary files a/docs/tutorials/pycharm/images/install_package.png and /dev/null differ diff --git a/docs/tutorials/pycharm/images/install_package_pyramid.png b/docs/tutorials/pycharm/images/install_package_pyramid.png deleted file mode 100644 index 05a209b6c..000000000 Binary files a/docs/tutorials/pycharm/images/install_package_pyramid.png and /dev/null differ diff --git a/docs/tutorials/pycharm/images/install_package_setuptools.png b/docs/tutorials/pycharm/images/install_package_setuptools.png deleted file mode 100644 index 8932a3f40..000000000 Binary files a/docs/tutorials/pycharm/images/install_package_setuptools.png and /dev/null differ diff --git a/docs/tutorials/pycharm/images/python_interpreters_1.png b/docs/tutorials/pycharm/images/python_interpreters_1.png deleted file mode 100644 index 6b1455001..000000000 Binary files a/docs/tutorials/pycharm/images/python_interpreters_1.png and /dev/null differ diff --git a/docs/tutorials/pycharm/images/python_interpreters_2.png b/docs/tutorials/pycharm/images/python_interpreters_2.png deleted file mode 100644 index 61c3de2b1..000000000 Binary files a/docs/tutorials/pycharm/images/python_interpreters_2.png and /dev/null differ diff --git a/docs/tutorials/pycharm/images/run_configuration.png b/docs/tutorials/pycharm/images/run_configuration.png deleted file mode 100644 index 4612b2b3c..000000000 Binary files a/docs/tutorials/pycharm/images/run_configuration.png and /dev/null differ diff --git a/docs/tutorials/pycharm/images/start_up_screen.png b/docs/tutorials/pycharm/images/start_up_screen.png deleted file mode 100644 index c65e01eeb..000000000 Binary files a/docs/tutorials/pycharm/images/start_up_screen.png and /dev/null differ 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 `_ 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 -`_. 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 -`_ for development or training -purposes under any other license. - -`Download PyCharm `_ 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 `_ -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 -`_. - -To configure the template language Chameleon, see `Creating and Registering -File Types -`_. 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 -`_ -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 -`_ 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. -- cgit v1.2.3 From 5028d84aeb6ac79ee7db4dc4012ff4caaba10e77 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 18 Jul 2013 18:09:20 -0400 Subject: normalize notations used for string and json renderer return values, closes #1005 --- docs/narr/renderers.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') 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``). -- cgit v1.2.3 From 0d96b77150f1283a44acd0d9c2d2f74453d298a1 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 18 Jul 2013 18:17:20 -0400 Subject: version bump in setup.py conf.py CHANGES.txt, rejigger changes bugs vs. features --- docs/conf.py | 2 +- docs/index.rst | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') 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/index.rst b/docs/index.rst index 93b550d60..35646f3d2 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 -- cgit v1.2.3 From e7638bfd959811bb85f681ff2ad8d43d716018ad Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 18 Jul 2013 18:17:38 -0400 Subject: add whatsnew-1.5 --- docs/whatsnew-1.5.rst | 125 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 docs/whatsnew-1.5.rst (limited to 'docs') diff --git a/docs/whatsnew-1.5.rst b/docs/whatsnew-1.5.rst new file mode 100644 index 000000000..47b768eb9 --- /dev/null +++ b/docs/whatsnew-1.5.rst @@ -0,0 +1,125 @@ +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. + +- 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. + -- cgit v1.2.3 From 456c171e31f166d48d1faf65273096f3a5b33d43 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 23 Jul 2013 05:18:06 -0600 Subject: Remove references to relocated PyCharm tutorial --- docs/index.rst | 1 - docs/latexindex.rst | 3 +-- 2 files changed, 1 insertion(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index 4be0ecd26..22b27039c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -109,7 +109,6 @@ platforms. tutorials/wiki/index.rst tutorials/bfg/index.rst tutorials/modwsgi/index.rst - tutorials/pycharm/index.rst API Documentation ================= diff --git a/docs/latexindex.rst b/docs/latexindex.rst index 416fc9bf1..83641d8b3 100644 --- a/docs/latexindex.rst +++ b/docs/latexindex.rst @@ -78,7 +78,6 @@ Tutorials tutorials/wiki/index.rst tutorials/bfg/index.rst tutorials/modwsgi/index.rst - tutorials/pycharm/index.rst .. _api_documentation: @@ -115,7 +114,7 @@ API Documentation .. backmatter:: Glossary and Index -@@@@@@@@@@@@@@@@@@ +================== .. toctree:: :maxdepth: 1 -- cgit v1.2.3 From 32333e4d84fe0e71ce097a5dca57025353956dbe Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 24 Jul 2013 17:22:48 -0400 Subject: add not_ predicate feature --- docs/api/config.rst | 1 + docs/narr/viewconfig.rst | 27 +++++++++++++++++++++++++++ docs/whatsnew-1.5.rst | 26 ++++++++++++++++++++++++++ 3 files changed, 54 insertions(+) (limited to 'docs') 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/narr/viewconfig.rst b/docs/narr/viewconfig.rst index 241ce62b5..388371a0d 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -557,6 +557,33 @@ 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` + .. index:: single: view_config placement diff --git a/docs/whatsnew-1.5.rst b/docs/whatsnew-1.5.rst index 47b768eb9..ee2250017 100644 --- a/docs/whatsnew-1.5.rst +++ b/docs/whatsnew-1.5.rst @@ -12,6 +12,32 @@ Feature Additions The feature additions in Pyramid 1.5 follow. +- 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 -- cgit v1.2.3 From bb9948168a9540d7b1b574ca8ee02bd07cbdede9 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 24 Jul 2013 18:00:03 -0400 Subject: indicate version in which not_ was added --- docs/narr/viewconfig.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index 388371a0d..b78b9b497 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -584,6 +584,8 @@ predicate values are accepted: - :meth:`pyramid.view.view_config` +.. versionadded:: 1.5 + .. index:: single: view_config placement -- cgit v1.2.3 From a6291243051b1977832b0b9a45c27eb68d7ba867 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 27 Jul 2013 03:03:08 -0600 Subject: Move .. versionadded:: 1.2 to end of ``match_param`` definition so that when building PDF it does not pause and wait for user to hit RETURN. This is now consistent with other placements of this directive as well. --- docs/narr/viewconfig.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index b78b9b497..fd3229339 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: @@ -570,7 +570,7 @@ You can invert the meaning of any predicate value by wrapping it in a call to config.add_view( 'mypackage.views.my_view', - route_name='ok', + route_name='ok', request_method=not_('POST') ) -- cgit v1.2.3 From 7a4c7c49441395a45e85f5649856ac3982081316 Mon Sep 17 00:00:00 2001 From: Darren Slatten Date: Sat, 27 Jul 2013 20:09:42 -0500 Subject: Added the `:orphan:` file-wide metadata field The :orphan: field suppresses the Sphinx error that occurs when a file in the source directory doesn't appear in a `toctree` directive. --- docs/foreword.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') 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 ======== -- cgit v1.2.3 From 133323b00defc9a8a6fbd8247cbb7125c2377f91 Mon Sep 17 00:00:00 2001 From: Darren Slatten Date: Sat, 27 Jul 2013 20:14:04 -0500 Subject: Removed `foreword.rst` from hidden `toctree` The `foreword.rst` file was used in printed versions, but currently it is not being used, so it shouldn't appear in any `toctree` directives. --- docs/index.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index 22b27039c..52b30df45 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -223,6 +223,5 @@ Index and Glossary :hidden: glossary - foreword.rst latexindex.rst -- cgit v1.2.3 From 2057f2d7a71604fa40a02ee88a3cacf7b73e94c8 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 28 Jul 2013 11:02:16 +0200 Subject: Improve consistency between latexindex.rst and index.rst some more this adds to a70d54c --- docs/latexindex.rst | 25 ++----------------------- 1 file changed, 2 insertions(+), 23 deletions(-) (limited to 'docs') diff --git a/docs/latexindex.rst b/docs/latexindex.rst index 83641d8b3..08c3157b3 100644 --- a/docs/latexindex.rst +++ b/docs/latexindex.rst @@ -86,30 +86,9 @@ 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:: -- cgit v1.2.3 From 239485e0722a580115173833b432d85c44c3a34c Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 28 Jul 2013 17:45:03 +0200 Subject: [docs] add latexpdf target I looked at latest Sphinx sources (in sphinx/quickstart.py) on how this is done --- docs/Makefile | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'docs') 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 -- cgit v1.2.3 From 0ed2c8f00d31caa224875a51b6a7723098b570ef Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 28 Jul 2013 14:06:49 -0400 Subject: use :orphan: for latexindex too --- docs/index.rst | 4 ---- docs/latexindex.rst | 2 ++ 2 files changed, 2 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index 52b30df45..5dfbbce1e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -216,12 +216,8 @@ Index and Glossary * :ref:`genindex` * :ref:`search` - -.. add glossary, foreword, and latexindex in a hidden toc to avoid warnings - .. toctree:: :hidden: glossary - latexindex.rst diff --git a/docs/latexindex.rst b/docs/latexindex.rst index 83641d8b3..c0cfb7696 100644 --- a/docs/latexindex.rst +++ b/docs/latexindex.rst @@ -1,3 +1,5 @@ +:orphan: + .. _latexindex: ================================================= -- cgit v1.2.3 From ff00405c65a901d5a952e27ec96ff4239c58b012 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 2 Aug 2013 13:00:52 -0400 Subject: point at add-on documentation --- docs/narr/introduction.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 48164d323..fa2646134 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From b210ce350a3856166376f63a32725cc1516ba294 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 2 Aug 2013 19:14:29 -0400 Subject: add pdistreport command --- docs/narr/commandline.rst | 24 ++++++++++++++++++++++++ docs/whatsnew-1.5.rst | 4 ++++ 2 files changed, 28 insertions(+) (limited to 'docs') 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/whatsnew-1.5.rst b/docs/whatsnew-1.5.rst index ee2250017..b987fa77f 100644 --- a/docs/whatsnew-1.5.rst +++ b/docs/whatsnew-1.5.rst @@ -12,6 +12,10 @@ 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: -- cgit v1.2.3 From a5da4dbbb2f5876740004c5fc9ffb15ae600d35e Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 6 Aug 2013 03:34:52 -0400 Subject: add redis session mention --- docs/narr/sessions.rst | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) (limited to 'docs') 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 `_ 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 `_ library as a backend. Beaker has +support for file-based sessions, database based sessions, and encrypted +cookie-based sessions. See `the pyramid_beaker documentation `_ for more information about ``pyramid_beaker``. -- cgit v1.2.3 From 1670e45561674bed100583665eccce5e5284439f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 6 Aug 2013 02:24:48 -0700 Subject: add missing word ``pserve`` --- docs/narr/project.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs') 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: -- cgit v1.2.3 From 268e1d1d8168376700031678379fe356db96afea Mon Sep 17 00:00:00 2001 From: tisdall Date: Thu, 8 Aug 2013 14:30:44 -0400 Subject: changed "obect" to "object" --- docs/api/request.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/api/request.rst b/docs/api/request.rst index b1f5918d7..8958d2abc 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`. -- cgit v1.2.3 From 0240e91af1616be75305ac5b7a57099ef42210bf Mon Sep 17 00:00:00 2001 From: tisdall Date: Thu, 8 Aug 2013 14:36:10 -0400 Subject: "behavor" to "behavior" --- docs/api/request.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/api/request.rst b/docs/api/request.rst index 8958d2abc..a90cb1ac0 100644 --- a/docs/api/request.rst +++ b/docs/api/request.rst @@ -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 -- cgit v1.2.3 From 00f9fe4dc2425d58d4c30253c53695bdf2a21e99 Mon Sep 17 00:00:00 2001 From: tisdall Date: Thu, 8 Aug 2013 14:44:23 -0400 Subject: "langauges" to "languages" --- docs/narr/i18n.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 74765f8e2..bb336784f 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 ------------------------------- -- cgit v1.2.3 From 86254fc545bc67f0a0050252dfcd297cc4b49f20 Mon Sep 17 00:00:00 2001 From: tisdall Date: Thu, 8 Aug 2013 14:49:59 -0400 Subject: "unecessary" to "unnecessary" --- docs/whatsnew-1.1.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/whatsnew-1.1.rst b/docs/whatsnew-1.1.rst index 5cba8dd3e..f1b8ec6f9 100644 --- a/docs/whatsnew-1.1.rst +++ b/docs/whatsnew-1.1.rst @@ -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 -- cgit v1.2.3 From 6714a5e945d46b456f6e54c4b982566b25640949 Mon Sep 17 00:00:00 2001 From: tisdall Date: Thu, 8 Aug 2013 14:53:24 -0400 Subject: "refered" to "referred" --- docs/whatsnew-1.1.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/whatsnew-1.1.rst b/docs/whatsnew-1.1.rst index f1b8ec6f9..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 -- cgit v1.2.3 From dcc7d67cb55304483b3c9931fbec17e98447279a Mon Sep 17 00:00:00 2001 From: tisdall Date: Thu, 8 Aug 2013 15:11:43 -0400 Subject: "resouce" to "resource" --- docs/narr/traversal.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') 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 -- cgit v1.2.3 From bfd928b5424c49343c6680715013d61bf4991cfa Mon Sep 17 00:00:00 2001 From: tisdall Date: Fri, 9 Aug 2013 14:42:49 -0400 Subject: "dermine" to "determine" --- docs/narr/i18n.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index bb336784f..2964686d3 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -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 -- cgit v1.2.3 From 4a7ab035275b20b9a2926d65a3936b6fc8c35c3a Mon Sep 17 00:00:00 2001 From: tisdall Date: Fri, 9 Aug 2013 14:51:35 -0400 Subject: "offical" to "official" --- docs/narr/introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index fa2646134..032f4be6b 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -859,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 -- cgit v1.2.3 From c40d20b20c3a8d0b3ac6f2e7ee1632889a69bfe5 Mon Sep 17 00:00:00 2001 From: tisdall Date: Fri, 9 Aug 2013 14:54:36 -0400 Subject: "repetion" to "repetition" --- docs/narr/viewconfig.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index fd3229339..6a064c209 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -831,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: -- cgit v1.2.3 From 866944efa58accab20abca15409803d9e13368b4 Mon Sep 17 00:00:00 2001 From: tisdall Date: Fri, 9 Aug 2013 14:56:29 -0400 Subject: "arent" to "aren't" --- docs/narr/urldispatch.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') 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 -- cgit v1.2.3 From 95d5b72927484fa3882c5c47bf79d591a5af50a5 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Sun, 4 Aug 2013 05:20:26 -0500 Subject: update sphinx to use the version from the package automatically --- docs/conf.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index ff5f325d8..e50c0c60a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -19,6 +19,8 @@ import warnings warnings.simplefilter('ignore', DeprecationWarning) +import pkg_resources + # skip raw nodes from sphinx.writers.text import TextTranslator from sphinx.writers.latex import LaTeXTranslator @@ -93,7 +95,7 @@ copyright = '2008-%s, Agendaless Consulting' % thisyear # other places throughout the built documents. # # The short X.Y version. -version = '1.5dev' +version = pkg_resources.get_distribution('pyramid').version # The full version, including alpha/beta/rc tags. release = version -- cgit v1.2.3 From 0b175c6e675391cbc7a4ad56b265dcbc2c5aa976 Mon Sep 17 00:00:00 2001 From: Blaise Laflamme Date: Sun, 11 Aug 2013 12:01:59 -0400 Subject: updated doc _theme --- docs/_themes | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/_themes b/docs/_themes index f59f7bfce..8673c4a14 160000 --- a/docs/_themes +++ b/docs/_themes @@ -1 +1 @@ -Subproject commit f59f7bfce5259f50fbb67b9040c03ecb080130b4 +Subproject commit 8673c4a14f192c15f1949dc9862821e60f31604a -- cgit v1.2.3 From 7683e22a93a3df2a541dddb9afac540ef9094f49 Mon Sep 17 00:00:00 2001 From: Jeff Szusz Date: Mon, 12 Aug 2013 11:10:09 -0400 Subject: #967 fixed 'Sommetime' -> 'Sometime' in templates.rst --- docs/narr/templates.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index d4cf20b93..ddebb3fa2 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -723,7 +723,7 @@ This template doesn't use any advanced features of Mako, only the Using A Mako def name Within a Renderer Name ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Sommetime you'd like to render a ``def`` inside of a Mako template instead of +Sometime you'd like to render a ``def`` inside of a Mako template instead of the full Mako template. To render a def inside a Mako template, given a :term:`Mako` template file named ``foo.mak`` and a def named ``bar``, you can configure the template as a :term:`renderer` like so: -- cgit v1.2.3 From fc9d4cbc8b3ccbd2c2b5c942595bf420eeae4596 Mon Sep 17 00:00:00 2001 From: Jeff Szusz Date: Mon, 12 Aug 2013 11:28:53 -0400 Subject: Update templates.rst --- docs/narr/templates.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index ddebb3fa2..af5ad6c5c 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -723,7 +723,7 @@ This template doesn't use any advanced features of Mako, only the Using A Mako def name Within a Renderer Name ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Sometime you'd like to render a ``def`` inside of a Mako template instead of +Sometimes you'd like to render a ``def`` inside of a Mako template instead of the full Mako template. To render a def inside a Mako template, given a :term:`Mako` template file named ``foo.mak`` and a def named ``bar``, you can configure the template as a :term:`renderer` like so: -- cgit v1.2.3 From 9d0643063615ef7ce54fe062461c5dbf92cde3b4 Mon Sep 17 00:00:00 2001 From: Amos Latteier Date: Mon, 12 Aug 2013 16:04:00 -0400 Subject: Add documentation for creating and firing custom events. See issue #982. --- docs/api/registry.rst | 8 ++++++ docs/narr/events.rst | 79 +++++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 85 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/api/registry.rst b/docs/api/registry.rst index db348495c..f96b23b68 100644 --- a/docs/api/registry.rst +++ b/docs/api/registry.rst @@ -29,6 +29,14 @@ This attribute is often accessed as ``request.registry.introspector`` in a typical Pyramid application. + .. method:: notify(*events) + + Fire one or more event. All event subscribers to the event(s) + will be notified. This method is often accessed as + ``request.registry.notify`` in Pyramid applications to fire + custom events. See :ref:`custom_events` for more information. + + .. class:: Introspectable .. versionadded:: 1.3 diff --git a/docs/narr/events.rst b/docs/narr/events.rst index 929208083..6065b67fd 100644 --- a/docs/narr/events.rst +++ b/docs/narr/events.rst @@ -53,7 +53,7 @@ method (see also :term:`Configurator`): from subscribers import mysubscriber - # "config" below is assumed to be an instance of a + # "config" below is assumed to be an instance of a # pyramid.config.Configurator object config.add_subscriber(mysubscriber, NewRequest) @@ -113,7 +113,7 @@ your application like so: :linenos: def handle_new_request(event): - print 'request', event.request + print 'request', event.request def handle_new_response(event): print 'response', event.response @@ -150,3 +150,78 @@ application, because the interface defined at :class:`pyramid.interfaces.INewResponse` says it must (:class:`pyramid.events.NewResponse` objects also have a ``request``). +.. _custom_events: + +Creating Your Own Events +------------------------ + +In addition to using the events that the Pyramid framework creates, +you can create your own events for use in your application. This can +be useful to decouple parts of your application. + +For example, suppose your application has to do many things when a new +document is created. Rather than putting all this logic in the view +that creates the document, you can create the document in your view +and then fire a custom event. Subscribers to the custom event can take +other actions, such as indexing the document, sending email, or +sending a message to a remote system. + +An event is simply an object. There are no required attributes or +method for your custom events. In general, your events should keep +track of the information that subscribers will need. Here are some +example custom event classes: + +.. code-block:: python + :linenos: + + class DocCreated(object): + def __init__(self, doc, request): + self.doc = doc + self.request = request + + class UserEvent(object): + def __init__(self, user): + self.user = user + + class UserLoggedIn(UserEvent): + pass + +Some Pyramid applications choose to define custom events classes in an +``events`` module. + +You can subscribe to custom events in the same way what you subscribe +to Pyramid events -- either imperatively or with a decorator. Here's +an example of subscribing to a custom event with a decorator: + +.. code-block:: python + :linenos: + + from pyramid.events import subscriber + from .events import DocCreated + from .index import index_doc + + @subscriber(DocCreated) + def index_doc(event): + # index the document using our application's index_doc function + index_doc(event.doc, event.request) + +The above example assumes that the application defines a +``DocCreated`` event class and an ``index_doc`` function. + +To fire your custom events use the +:meth:`pyramid.registry.Registry.notify` method, which is most often +accessed as ``request.registry.notify``. For example: + +.. code-block:: python + :linenos: + + from .events import DocCreated + + def new_doc_view(request): + doc = MyDoc() + event = DocCreated(doc, request) + request.registry.notify(event) + return {'document': doc} + +This example view will notify all subscribers to the custom +``DocCreated`` event. -- cgit v1.2.3 From 387051c91d5a3844db5fa0938a19c19f5881e056 Mon Sep 17 00:00:00 2001 From: Amos Latteier Date: Mon, 12 Aug 2013 16:27:41 -0400 Subject: Fix tab/space snafu. --- docs/narr/events.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/narr/events.rst b/docs/narr/events.rst index 6065b67fd..702618843 100644 --- a/docs/narr/events.rst +++ b/docs/narr/events.rst @@ -177,7 +177,7 @@ example custom event classes: class DocCreated(object): def __init__(self, doc, request): self.doc = doc - self.request = request + self.request = request class UserEvent(object): def __init__(self, user): @@ -219,9 +219,9 @@ accessed as ``request.registry.notify``. For example: def new_doc_view(request): doc = MyDoc() - event = DocCreated(doc, request) - request.registry.notify(event) - return {'document': doc} + event = DocCreated(doc, request) + request.registry.notify(event) + return {'document': doc} This example view will notify all subscribers to the custom ``DocCreated`` event. -- cgit v1.2.3 From 29ab2b964164844daa012c3e80d276f49ccbe217 Mon Sep 17 00:00:00 2001 From: Amos Latteier Date: Mon, 12 Aug 2013 16:45:11 -0400 Subject: Minor fixes suggested by @tshepang and @mmerickel thanks! --- docs/api/registry.rst | 5 +++-- docs/narr/events.rst | 8 ++++++-- 2 files changed, 9 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/api/registry.rst b/docs/api/registry.rst index f96b23b68..42a405a32 100644 --- a/docs/api/registry.rst +++ b/docs/api/registry.rst @@ -31,8 +31,9 @@ .. method:: notify(*events) - Fire one or more event. All event subscribers to the event(s) - will be notified. This method is often accessed as + Fire one or more events. All event subscribers to the event(s) + will be notified. The subscribers will be called synchronously on + the current thread. This method is often accessed as ``request.registry.notify`` in Pyramid applications to fire custom events. See :ref:`custom_events` for more information. diff --git a/docs/narr/events.rst b/docs/narr/events.rst index 702618843..485247afc 100644 --- a/docs/narr/events.rst +++ b/docs/narr/events.rst @@ -77,7 +77,7 @@ type via the :func:`pyramid.events.subscriber` function. @subscriber(NewRequest) def mysubscriber(event): - event.request.foo = 1 + event.request.foo = 1 When the :func:`~pyramid.events.subscriber` decorator is used a :term:`scan` must be performed against the package containing the @@ -189,7 +189,7 @@ example custom event classes: Some Pyramid applications choose to define custom events classes in an ``events`` module. -You can subscribe to custom events in the same way what you subscribe +You can subscribe to custom events in the same way that you subscribe to Pyramid events -- either imperatively or with a decorator. Here's an example of subscribing to a custom event with a decorator: @@ -225,3 +225,7 @@ accessed as ``request.registry.notify``. For example: This example view will notify all subscribers to the custom ``DocCreated`` event. + +Note that when you fire an event, all subscribers are run +synchronously on the current thread. So it's generally not a good idea +to create event handlers that may take a long time to run. -- cgit v1.2.3 From 970dfae46bb398e862f57d89c3f6efe10c45e715 Mon Sep 17 00:00:00 2001 From: Amos Latteier Date: Mon, 12 Aug 2013 17:00:29 -0400 Subject: Mention subscriber predicates. --- docs/narr/events.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/narr/events.rst b/docs/narr/events.rst index 485247afc..5004a1787 100644 --- a/docs/narr/events.rst +++ b/docs/narr/events.rst @@ -190,8 +190,10 @@ Some Pyramid applications choose to define custom events classes in an ``events`` module. You can subscribe to custom events in the same way that you subscribe -to Pyramid events -- either imperatively or with a decorator. Here's -an example of subscribing to a custom event with a decorator: +to Pyramid events -- either imperatively or with a decorator. You can +also use custom events with :ref:`subscriber predicates +`. Here's an example of subscribing to a custom +event with a decorator: .. code-block:: python :linenos: -- cgit v1.2.3 From 8339cd1095be5e49fe41662e3618b8da6055a4f0 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Mon, 12 Aug 2013 16:28:57 -0500 Subject: remove the "thread" reference --- docs/api/registry.rst | 8 ++++---- docs/narr/events.rst | 6 ++++-- 2 files changed, 8 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/api/registry.rst b/docs/api/registry.rst index 42a405a32..7736cf075 100644 --- a/docs/api/registry.rst +++ b/docs/api/registry.rst @@ -32,10 +32,10 @@ .. method:: notify(*events) Fire one or more events. All event subscribers to the event(s) - will be notified. The subscribers will be called synchronously on - the current thread. This method is often accessed as - ``request.registry.notify`` in Pyramid applications to fire - custom events. See :ref:`custom_events` for more information. + will be notified. The subscribers will be called synchronously. + This method is often accessed as ``request.registry.notify`` + in Pyramid applications to fire custom events. See + :ref:`custom_events` for more information. .. class:: Introspectable diff --git a/docs/narr/events.rst b/docs/narr/events.rst index 5004a1787..11af89ca6 100644 --- a/docs/narr/events.rst +++ b/docs/narr/events.rst @@ -229,5 +229,7 @@ This example view will notify all subscribers to the custom ``DocCreated`` event. Note that when you fire an event, all subscribers are run -synchronously on the current thread. So it's generally not a good idea -to create event handlers that may take a long time to run. +synchronously so it's generally not a good idea +to create event handlers that may take a long time to run. Although +event handlers could be used as a central place to spawn tasks on your +own message queues. -- cgit v1.2.3