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