diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api/paster.rst | 2 | ||||
| -rw-r--r-- | docs/conf.py | 11 | ||||
| -rw-r--r-- | docs/narr/install.rst | 25 | ||||
| -rw-r--r-- | docs/narr/security.rst | 31 | ||||
| -rw-r--r-- | docs/tutorials/wiki2/basiclayout.rst | 8 | ||||
| -rw-r--r-- | docs/tutorials/wiki2/definingmodels.rst | 9 | ||||
| -rw-r--r-- | docs/tutorials/wiki2/definingviews.rst | 2 | ||||
| -rw-r--r-- | docs/tutorials/wiki2/installation.rst | 117 |
8 files changed, 158 insertions, 47 deletions
diff --git a/docs/api/paster.rst b/docs/api/paster.rst index bde128e05..edc3738fc 100644 --- a/docs/api/paster.rst +++ b/docs/api/paster.rst @@ -9,6 +9,6 @@ .. autofunction:: get_app(config_uri, name=None, options=None) - .. autofunction:: get_appsettings(config_uri, name=None) + .. autofunction:: get_appsettings(config_uri, name=None, options=None) .. autofunction:: setup_logging(config_uri) diff --git a/docs/conf.py b/docs/conf.py index 8d22d4d42..eff6db488 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -55,13 +55,14 @@ extensions = [ # Looks for objects in external projects intersphinx_mapping = { - 'who': ('http://docs.repoze.org/who/2.0', None), - 'python': ('http://docs.python.org', None), - 'python3': ('http://docs.python.org/3', None), - 'tstring': + 'sqla': ('http://docs.sqlalchemy.org/en/latest', None), + 'who': ('http://docs.repoze.org/who/latest', None), + 'python': ('http://docs.python.org', None), + 'python3': ('http://docs.python.org/3', None), + 'tstring': ('http://docs.pylonsproject.org/projects/translationstring/en/latest', None), - 'venusian': + 'venusian': ('http://docs.pylonsproject.org/projects/venusian/en/latest', None), } diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 04a060ac3..0a03d9170 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -19,13 +19,32 @@ run :app:`Pyramid`. run under any version of Python before 2.6. :app:`Pyramid` is known to run on all popular UNIX-like systems such as -Linux, MacOS X, and FreeBSD as well as on Windows platforms. It is also -known to run on :term:`PyPy` (1.9+). +Linux, Mac OS X, and FreeBSD as well as on Windows platforms. It is +also known to run on :term:`PyPy` (1.9+). :app:`Pyramid` installation does not require the compilation of any C code, so you need only a Python interpreter that meets the requirements mentioned. +For Mac OS X Users +~~~~~~~~~~~~~~~~~~ + +From `Python.org <http://python.org/download/mac/>`_: + + Python comes pre-installed on Mac OS X, but due to Apple's release + cycle, it's often one or even two years old. The overwhelming + recommendation of the "MacPython" community is to upgrade your + Python by downloading and installing a newer version from + `the Python standard release page <http://python.org/download/releases/>`_. + +It is recommended to download one of the *installer* versions, unless you prefer to install your Python through a packgage manager (e.g., macports or homebrew) or to build your Python from source. + +Unless you have a need for a specific earlier version, it is recommended +to install the latest 2.x or 3.x version of Python. + +If you use an installer for your Python, then you can skip to the +section :ref:`installing_unix`. + If You Don't Yet Have A Python Interpreter (UNIX) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -269,7 +288,7 @@ you can then create a virtual environment. To do so, invoke the following: .. code-block:: text - $ export $VENV=~/env + $ export VENV=~/env $ virtualenv --no-site-packages $VENV New python executable in /home/foo/env/bin/python Installing setuptools.............done. diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 5b79edd19..203aa2404 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -234,8 +234,8 @@ class: .. code-block:: python :linenos: - from pyramid.security import Everyone from pyramid.security import Allow + from pyramid.security import Everyone class Blog(object): __acl__ = [ @@ -250,8 +250,8 @@ Or, if your resources are persistent, an ACL might be specified via the .. code-block:: python :linenos: - from pyramid.security import Everyone from pyramid.security import Allow + from pyramid.security import Everyone class Blog(object): pass @@ -270,6 +270,27 @@ resource instances with an ACL (as opposed to just decorating their class) in applications such as "CMS" systems where fine-grained access is required on an object-by-object basis. +Dynamic ACLs are also possible by turning the ACL into a callable on the +resource. This may allow the ACL to dynamically generate rules based on +properties of the instance. + +.. code-block:: python + :linenos: + + from pyramid.security import Allow + from pyramid.security import Everyone + + class Blog(object): + def __acl__(self): + return [ + (Allow, Everyone, 'view'), + (Allow, self.owner, 'edit'), + (Allow, 'group:editors', 'edit'), + ] + + def __init__(self, owner): + self.owner = owner + .. index:: single: ACE single: access control entry @@ -282,8 +303,8 @@ Here's an example ACL: .. code-block:: python :linenos: - from pyramid.security import Everyone from pyramid.security import Allow + from pyramid.security import Everyone __acl__ = [ (Allow, Everyone, 'view'), @@ -321,9 +342,9 @@ order dictated by the ACL*. So if you have an ACL like this: .. code-block:: python :linenos: - from pyramid.security import Everyone from pyramid.security import Allow from pyramid.security import Deny + from pyramid.security import Everyone __acl__ = [ (Allow, Everyone, 'view'), @@ -359,8 +380,8 @@ ACE, as below. .. code-block:: python :linenos: - from pyramid.security import Everyone from pyramid.security import Allow + from pyramid.security import Everyone __acl__ = [ (Allow, Everyone, 'view'), diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 68be4ee7c..eb2445864 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -43,9 +43,9 @@ above is executed. It accepts some settings and returns a :term:`WSGI` application. (See :ref:`startup_chapter` for more about ``pserve``.) The main function first creates a :term:`SQLAlchemy` database engine using -``engine_from_config`` from the ``sqlalchemy.`` prefixed settings in the -``development.ini`` file's ``[app:main]`` section. This will be a URI -(something like ``sqlite://``): +:func:`sqlalchemy.engine_from_config` from the ``sqlalchemy.`` prefixed +settings in the ``development.ini`` file's ``[app:main]`` section. +This will be a URI (something like ``sqlite://``): .. literalinclude:: src/basiclayout/tutorial/__init__.py :lines: 13 @@ -226,7 +226,7 @@ To give a simple example of a model class, we define one named ``MyModel``: :linenos: :language: py -Our example model has an ``__init__`` method that takes a two arguments +Our example model has an ``__init__`` method that takes two arguments (``name``, and ``value``). It stores these values as ``self.name`` and ``self.value`` within the ``__init__`` function itself. The ``MyModel`` class also has a diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst index 99f7969bc..60427a911 100644 --- a/docs/tutorials/wiki2/definingmodels.rst +++ b/docs/tutorials/wiki2/definingmodels.rst @@ -34,7 +34,7 @@ sample and we're not going to use it. Then, we added a ``Page`` class. Because this is a SQLAlchemy application, this class inherits from an instance of -:class:`sqlalchemy.ext.declarative.declarative_base`. +:func:`sqlalchemy.ext.declarative.declarative_base`. .. literalinclude:: src/models/tutorial/models.py :pyobject: Page @@ -45,9 +45,10 @@ As you can see, our ``Page`` class has a class level attribute ``__tablename__`` which equals the string ``'pages'``. This means that SQLAlchemy will store our wiki data in a SQL table named ``pages``. Our ``Page`` class will also have class-level attributes named ``id``, ``name`` and -``data`` (all instances of :class:`sqlalchemy.Column`). These will map to -columns in the ``pages`` table. The ``id`` attribute will be the primary key -in the table. The ``name`` attribute will be a text attribute, each value of +``data`` (all instances of :class:`sqlalchemy.schema.Column`). +These will map to columns in the ``pages`` table. +The ``id`` attribute will be the primary key in the table. +The ``name`` attribute will be a text attribute, each value of which needs to be unique within the column. The ``data`` attribute is a text attribute that will hold the body of each page. diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst index 5727816c8..f2ac2f85f 100644 --- a/docs/tutorials/wiki2/definingviews.rst +++ b/docs/tutorials/wiki2/definingviews.rst @@ -126,7 +126,7 @@ The ``view_page`` view function ------------------------------- ``view_page()`` is used to display a single page of our -wiki. It renders the :term:`ReStructuredText` body of a page (stored as +wiki. It renders the :term:`reStructuredText` body of a page (stored as the ``data`` attribute of a ``Page`` model object) as HTML. Then it substitutes an HTML anchor for each *WikiWord* reference in the rendered HTML using a compiled regular expression. diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst index 255a60ec2..e646f63d2 100644 --- a/docs/tutorials/wiki2/installation.rst +++ b/docs/tutorials/wiki2/installation.rst @@ -2,34 +2,93 @@ Installation ============ -Preparation -=========== +Before You Begin +================ + +This tutorial assumes that you have already followed the steps in +:ref:`installing_chapter`, thereby satisfying the following +requirements. + +* Python interpreter is installed on your operating system +* :term:`setuptools` or :term:`distribute` is installed +* :term:`virtualenv` is installed + +Create and Use a Virtual Python Environment +------------------------------------------- + +Next let's create a `virtualenv` workspace for our project. We will +use the `VENV` environment variable instead of absolute path of the +virtual environment. -Follow the steps in :ref:`installing_chapter`, but name the virtualenv -directory ``pyramidtut``. +**On UNIX:** -Preparation, UNIX ------------------ +.. code-block:: text + + $ export VENV=~/pyramidtut + $ virtualenv --no-site-packages $VENV + New python executable in /home/foo/env/bin/python + Installing setuptools.............done. + +**On Windows:** -#. Install SQLite3 and its development packages if you don't already - have them installed. Usually this is via your system's package - manager. On a Debian system, this would be: +Set the `VENV` environment variable. + +.. code-block:: text + + c:\> set VENV=c:\pyramidtut + +Versions of Python use different paths, so you will need to adjust the +path to the command for your Python version. + +Python 2.7: + +.. code-block:: text + + c:\> c:\Python27\Scripts\virtualenv --no-site-packages %VENV% + +Python 3.2: + +.. code-block:: text + + c:\> c:\Python32\Scripts\virtualenv --no-site-packages %VENV% + +Install Pyramid Into the Virtual Python Environment +--------------------------------------------------- + +**On UNIX:** + +.. code-block:: text + + $ $VENV/bin/easy_install pyramid + +**On Windows** + +.. code-block:: text + + c:\env> %VENV%\Scripts\easy_install pyramid + +SQLite3 +------- + +Install SQLite3 and its development packages if you don't already +have them installed. Usually this is via your system's package +manager. On a Debian system, this would be: .. code-block:: text $ sudo apt-get install libsqlite3-dev -#. Switch to the ``pyramidtut`` directory: +Entering the virtualenv +----------------------- + +Do not forget to switch to the ``pyramidtut`` directory. +In order to do so, run this command if you are on Unix: .. code-block:: text $ cd pyramidtut - -Preparation, Windows --------------------- - -#. Switch to the ``pyramidtut`` directory: +And run this if you are on Windows: .. code-block:: text @@ -40,10 +99,20 @@ Preparation, Windows Making a Project ================ -Your next step is to create a project. For this tutorial, we will use the -:term:`scaffold` named ``alchemy``, which generates an application -that uses :term:`SQLAlchemy` and :term:`URL dispatch`. :app:`Pyramid` -supplies a variety of scaffolds to generate sample projects. +Your next step is to create a project. For this tutorial we will use +the :term:`scaffold` named ``alchemy`` which generates an application +that uses :term:`SQLAlchemy` and :term:`URL dispatch`. + +:app:`Pyramid` supplies a variety of scaffolds to generate sample +projects. We will use `pcreate`—a script that comes with Pyramid to +quickly and easily generate scaffolds usually with a single command—to +create the scaffold for our project. + +By passing in `alchemy` into the `pcreate` command, the script creates +the files needed to use SQLAlchemy. By passing in our application name +`tutorial`, the script inserts that application name into all the +required files. For example, `pcreate` creates the +``initialize_tutorial_db`` in the ``pyramidtut/bin`` directory. The below instructions assume your current working directory is the "virtualenv" named "pyramidtut". @@ -66,11 +135,10 @@ On Windows: startup problems, try putting both the virtualenv and the project into directories that do not contain spaces in their paths. - .. _installing_project_in_dev_mode: -Installing the Project in "Development Mode" -============================================ +Installing the Project in Development Mode +========================================== In order to do development on the project easily, you must "register" the project as a development egg in your workspace using the @@ -92,8 +160,9 @@ On Windows: c:\pyramidtut> cd tutorial c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop -Success executing this command will end with a line to the console something -like:: +The console will show `setup.py` checking for packages and installing +missing packages. Success executing this command will show a line like +the following:: Finished processing dependencies for tutorial==0.0 |