Mike Orr committed b9c1e7b

Usage chapter.

  • Participants
  • Parent commits 79da587

Comments (0)

Files changed (8)

 Delete 'akhet' scaffold and 'paster_templates' directory; remove entry points.
+Does Akhet without scaffolds require 'pyramid' dependency? If so, which
+versions, and how will it handle future Pyramid version changes? Is it still
+depending on Paste or PasteScript?

File docs/appendix/changes.rst

+Appendix: Full Changelog
+.. include:: ../../CHANGES.txt

File docs/appendix/no_site_packages.rst

+Appendix: --no-site-packages
+The ``--no-site-packages`` option to virtualenv avoids conflicts between Python
+packages inside the virtualenv and possibly-incompatible packages installed
+globally. It's generally recommended for Pyramid. I needed --no-site-packages
+for Ubuntu 10, which uses certain Zope packages in the OS.  ``zope`` is a
+namespace package, and distributions under namespace packages can't be split
+between multiple site-packages directories.  I'm not sure if Ubuntu 11.11 has
+the same limitation.
+The tradeoff is that with --no-site-packages, you have to install your own
+packages with C extensions (database libraries, PIL, NumPy, etc) rather
+than relying on the OS packages. Some of these can be difficult to install
+if they involve C. You may be able to get around this by making a symlink
+from the virtulenv's site-packages directory to the global package, but it
+may take some work to make the package happy.

File docs/appendix/uninstalling.rst

+Appendix: Uninstalling
+To uninstall an application that was installed with "pip install" or "pip
+install -e", run "pip uninstall Zzz". 
+If you used easy_install or "python install" or "python
+develop" instead of pip, you'll have to uninstall it manually. Chdir to the
+virtualenv's *site-packages* directory. Delete any subdirectories and files
+corresponding to the Python package, its metadata, or its egg link. For our
+sample application these would be *zzz* (Python package), *Zzz.egg-info*
+(pip egg_info), *Zzz.egg* (easy_install directory or ZIP file), and
+*Zzz.egg-link* (egg link file). Also edit *easy-install.pth* and delete
+the application's line if present.

File docs/changes.rst

-Full Changelog
-.. include:: ../CHANGES.txt

File docs/index.rst

-   paster
-   changes
+   appendix/changes
+   appendix/no_site_packages
+   appendix/uninstalling
 * :ref:`genindex`
 * :ref:`modindex`

File docs/paster.rst

-Paster Commands
-As in Pylons, the "paster" command creates and runs applications.
-paster create
-**paster create** works the same in both Pylons and Pyramid:
-.. code-block:: sh
-    $ paster create -t akhet Zzz
-This is how you create a new application, as described earlier in the Usage
-chapter. Our sample application is named "Zzz". It will ask certain questions.
-Currently it asks whether to preconfigure SQLAlchemy in the application; the
-default is true. Answer 'n' to skip SQLAlchemy. You can also pass the answer on
-the command line:
-.. code-block:: sh
-    $ paster create -t akhet Zzz sqlalchemy=n
-The SQLAlchemy question is specific to the 'akhet' application skeleton. Other
-skeletons may have other questions or no questions. (Paster calls the
-application skeleton a "template" but we avoid that term because it can be
-confused with a template file.)
-paster serve
-**paster serve** also works the same as in Pylons:
-.. code-block:: sh
-    $ paster serve development.ini
-    $ paster serve --reload development.ini
-This runs the application under PasteHTTPServer or another server specified in
-the INI file. Running it under Apache or another Python webserver works the
-same way as in Pylons; see the Pyramid manual for details.
-paster proutes
-**paster proutes** prints the current route definitions. You have to specify
-both the INI file and the application section in the file, which for Akhet is
-"myapp" regardless of the actual application name:
-.. code-block:: sh
-    $ paster proutes development.ini myapp
-This replaces "paster routes" in Pylons.
-Other paster commands
-**paster pshell** is covered in the Shell_ section of the Architecture chapter.
-It replaces "paster shell" in Pylons.
-"paster make-config" is not supported in Pyramid. Instead, all Pyramid
-skeletons include a *production.ini*. You can copy it to make other
-INI files.
-"paster setup-app" is not supported in Pyramid. Instead, Akhet includes a
-** script. After you have defined your models, run it to create the
-database tables:
-.. code-block:: sh
-    $ python -m zzz.scripts.create_db development.ini
-You can customize the script if you want to prepopulate the
-databse with certain initial records.
-You can also put other utility scripts in the "scripts" package and run them
-the same way.
-"paster controller" and "paster restcontroller" do not exist in Pyramid. You'll
-have to create your handler modules by hand or copy an existing module.
-.. _Shell: architecture.html#shell

File docs/usage.rst

-Installing Akhet
+Creating a Pyramid/Akhet application
-Install Akhet like any Python package, using either "pip install Akhet" or
-"easy_install Akhet". To check out the development repository use "hg clone
-". Pyramid is a dependency of Akhet so it
-will be automatically installed.
-It's generally a good idea to install Akhet into a virtualenv_. If you're
-unfamiliar with installing Python, Virtualenv, and Setuptools/Distribute, see
-the `Installing Pyramid`_ chapter in the Pyramid manual. I use the OS packages
-in Ubuntu Linux 10.10: python-setuptools, python-virtualenv, and
+Here are the basic steps to install Pyramid and Akhet, create a virtualenv and
+activate it, create an application, and run it so you can see it in the
 .. code-block:: sh
+   :linenos:
     $ virtualenv --no-site-packages ~/directory/myvenv
     $ source ~/directory/myvenv/bin/activate
+    (myvenv)$ pip install Pyramid
     (myvenv)$ pip install Akhet
-    ...
+    (myvenv)$ pcreate -s alchemy Zzz
+    (myenv)$ cd Zzz
+    (myenv)$ python egg_info
+    (myenv)$ pserve development.ini
-You'll probably need Virtualenv's ``--no-site-packages`` option as above to
-avoid undesired interactions with with other Python packages installed globally
-(outside the virtualenv). I had particular trouble due to some Zope packages
-Ubuntu installs by default. If you need certain global packages (e.g., those
-with C dependencies that can be hard to install yourself), make symbolic links
-to them in the virtualenv's site-packages.
+* Line 1 creates the virtualenv. "--no-site-packages" is recommended with
+  Pyramid. `Why <appendix/no_site_packages.html>`_
+* Line 5 creates application "Zzz" based on the 'alchemy' scaffold.
+  (For Pyramid 1.2 and earlier, use "paster create -t routesalchemy Zzz"
+  instead.)
+* Line 7 generates the package metadata (the *Zzz.egg-info*
+  directory). Remember to do this whenever you add or delete files in the
+  package.
+* Line 8 launches the server using the configuration file
+  "development.ini". (For Pyramid 1.2 and earlier, use "paster serve
+  development.ini" instead.)
+See the `Installing Pyramid`_ chapter in the Pyramid manual if any of this is
-Creating an application
+    Go to the URL indicated in your web browser (  The
+    default application doesn't define any tables or models so it doesn't
+    actually do anything except display some help links. When you get bored,
+    press ctrl-C to quit the HTTP.
-Create an application with Paster using the "akhet" application skeleton.
+Throughout this manual we'll use "Zzz" for your application's name, and ``zzz``
+for the top-level Python module in the application.
-.. code-block:: sh
+See `Uninstalling <appendix/uninstalling.html>`_ if you want to uninstall
+things later.
-    (myvenv)$ paster create -t akhet Zzz
-        Selected and implied templates:
-      Akhet#akhet  A Pylons-like Pyramid project
-    Variables:
-      egg:      Zzz
-      package:  zzz
-      project:  Zzz
-    Enter sqlalchemy (Include SQLAlchemy configuration? (y/n)) [True]:
-    ...
-    Copying setup.py_tmpl to ./Zzz/
-    Running /home/sluggo/.virtualenvs/pyramid/bin/python egg_info
-    (myvenv)$ 
-You can answer the question on the command line so that it won't prompt you:
-.. code-block:: sh
-    (myvenv)$ paster create -t akhet Zzz sqlalchemy=y
-Our sample application is called "Zzz". It has a top-level directory "Zzz"
-containing a Python package ``zzz`` (lowercase). Throughout this manual we'll
-use Zzz and zzz as shorthands for your application name and package name. You
-can name your application anything, but don't use "Test" or any other name in
-the Python standard library, otherwise it won't run. It's easiest to stick with
-a valid Python identifier: a letter or underscore followed by zero or more
-letters, numbers, or underscores.
-Install the application's dependencies. For convenience these are listed both
-in a *requirements.txt* file and in **.
-.. code-block:: sh
-    (myvenv)$ cd Zzz
-    (myvenv)$ pip install -r requirements.txt
-    ...
-Generate the package's metadata ("egg_info" files):
-.. code-block:: sh
-    (myvenv)$ python egg_info
-    running egg_info
-    writing requirements to Zzz.egg-info/requires.txt
-    writing Zzz.egg-info/PKG-INFO
-    writing top-level names to Zzz.egg-info/top_level.txt
-    writing dependency_links to Zzz.egg-info/dependency_links.txt
-    writing entry points to Zzz.egg-info/entry_points.txt
-    writing paster_plugins to Zzz.egg-info/paster_plugins.txt
-    reading manifest file 'Zzz.egg-info/SOURCES.txt'
-    writing manifest file 'Zzz.egg-info/SOURCES.txt'
-The application should now run out of the box:
-.. code-block:: sh
-    (venv)$ paster serve development.ini
-Go to the URL indicated in your web browser (
-The default application doesn't define any tables or models so it doesn't
-actually do anything except display some help links. When you get bored, press
-ctrl-C to quit the HTTP.
-Building the application
-You can now customize the application as you see fit.
-If you've never built a (Pylons) web application before, there will be
-Akhet-specifc tutorials coming but they're not finished yet. In the meantime,
-skim over the Akhet documentation and then go to the Pyramid tutorials. Choose
-the ones that say "URL dispatch" and "view handlers" in their introduction;
-these are the most similar to Akhet. 
-If you're porting an existing Pylons application to Pyramid, the Architecture
-and Migration chapters should get you started.
-**Important**: Whenever you add or delete files in the application, remember to
-re-execute the "python egg_info" step before running the application
-again. This updates the package's metadata to reflect the new files. Otherwise
-Python may not be able to find them.
-Installing the application
+Using development versions
-So far we haven't installed the application, so Python is looking in the
-current directory for the ``zzz`` package and ``Zzz.egg-info`` metadata. This
-is convenient during early development because we can create and delete scrath
-applications quickly without installing them into the virtualenv and
-uninstalling them. However, for production and beta testing you should formally
-install the application; that way you can run it from any directory (by
-specifying the path to the INI file). 
+Akhet's development version works like most Python source repositories.
+Pyramid's development version requires additional work to install.
-You can install a link to the application's source directory by running "pip
-install -e .". This installs an "egg link" file pointing to the source
-directory, so that Python will immediately see any changes in the source. This
-is useful in development, and some production deployments also use this system.
+.. code-block::  sh
-The other option is to install a snapshot of the application's current state.
-This copies the package's files to the virtualenv's *site-packages* directory,
-so that Python will not see any subsequent changes in the source until you
-reinstall the application. The command for this is "pip install .". This is the
-same thing that happens when you install a third-party package (e.g., "pip
-install Akhet").
+    (myvenv)$ git clone git:// Pyramid
+    (myvenv)$ pip install setuptools-git
+    (myvenv)$ pip install -e ./Pyramid
+    (myvenv)$ hg clone Akhet
+    (myvenv)$ pip install -e ./Akhet
-If you're using easy_install rather than pip, the command to install an egg
-link is "python develop". The command to install a snapshot is
-"easy_install ." or "python install".
+Three things to note here:
-Uninstalling the application
+* Pyramid requires 'setuptools-git' because the repsository contains Git
+  submodules_.
+* Pyramid *must* be installed as a link (with "-e") because the repository does
+  not contain a file, so a regular install wouldn't copy the
+  scaffolds or other supplemental files.
+* Install Pyramid *before* Akhet in order to satisfy the dependency. Otherwise
+  installing Akhet would download the latest stable Pyramid from PyPI.
-To uninstall an application that was installed as a pip snapshot, cd to a
-distant directory (not the application source or its parent) and run "pip
-uninstall Zzz". This should supposedly work with a pip egg link too but it
-hasn't always worked for me. It also works with external packages that were
-installed with pip; e.g., "pip uninstall Akhet".
-Easy_install does not have an uninstall command, so you'll have to uninstall it
-manually in that case.
+The "p" commands
-To uninstall the application (or any Python package) manually, cd to the
-virtualenv's *site-packages* directory. Delete any subdirectories and files
-corresponding to the Python package, its metadata, or its egg link. For our
-sample application these would be *zzz* (Python package), *Zzz.egg-info*
-(pip egg_info), *Zzz.egg* (easy_install directory or ZIP file), and
-*Zzz.egg-link* (egg link file). Also look in *easy-install.pth* and delete
-the application's line if present.
+Pyramid 1.3 includes the following command-line utilities:
+* **pcreate**: Create a new application using a scaffold.
+* **pserve**: Launch an application and server based on an INI configuration
+  file.
+* **proutes**: List all routes in an application.
+* **pviews**: List all views in an application.
+* **pshell**: An interactive Python shell preloaded with your application
+  environment.
+* **ptweens**: List all tweens.
 .. _Pyramid documentation:
 .. _Pyramid tutorials:
 .. _virtualenv:
 .. _Installing Pyramid:
+.. _submodules: