Revision: 612
Author: batiste.bieler
Date: Wed Jul 22 00:07:24 2009
Log: Update documentation
http://code.google.com/p/django-page-cms/source/detail?r=612
Modified:
/trunk/docs/page-api.rst
/trunk/pages/http.py
/trunk/pages/managers.py
/trunk/pages/models.py
/trunk/pages/utils.py
=======================================
--- /trunk/docs/page-api.rst Mon Jul 20 23:57:02 2009
+++ /trunk/docs/page-api.rst Wed Jul 22 00:07:24 2009
@@ -6,40 +6,40 @@
==========
.. autoclass:: pages.models.Page
- :members:
- :undoc-members:
+ :members:
+ :undoc-members:
Page Manager
============
.. autoclass:: pages.managers.PageManager
- :members:
- :undoc-members:
+ :members:
+ :undoc-members:
Content Model
=============
.. autoclass:: pages.models.Content
- :members:
- :undoc-members:
+ :members:
+ :undoc-members:
Content Manager
===============
.. autoclass:: pages.managers.ContentManager
- :members:
- :undoc-members:
+ :members:
+ :undoc-members:
Utils
=====
.. automodule:: pages.utils
- :members:
- :undoc-members:
+ :members:
+ :undoc-members:
Http
====
.. automodule:: pages.http
- :members:
- :undoc-members:
+ :members:
+ :undoc-members:
=======================================
--- /trunk/pages/http.py Wed Jul 8 15:12:40 2009
+++ /trunk/pages/http.py Wed Jul 22 00:07:24 2009
@@ -7,15 +7,6 @@
from django.core.urlresolvers import reverse
from pages import settings
-def get_slug_and_relative_path(path):
- if path[-1] == '/':
- path = path[:-1]
- slug = path.split("/")[-1]
- root = reverse('pages-root')
- if path.startswith(root):
- path = path[len(root):]
- return slug, path
-
def get_request_mock():
"""Build a request mock that can be used for testing."""
bh = BaseHandler()
@@ -34,13 +25,15 @@
return request
class AutoRenderHttpError(Exception):
- """cannot return context dictionary because a view returned an HTTP
- response when a (template_name, context) tuple was expected"""
+ """Cannot return context dictionary because a view returned an HTTP
+ response when a (template_name, context) tuple was expected."""
pass
def auto_render(func):
- """A decorator which automatically inserts the template path into the
- context and calls the render_to_response shortcut
+ """
+ This view decorator automatically calls the ``render_to_response``
+ shortcut. A view that use this decorator should return a tuple of this
+ form : (template name, context) instead of a ``HttpRequest`` object.
"""
def _dec(request, *args, **kwargs):
template_override = kwargs.pop('template_name', None)
@@ -58,12 +51,23 @@
(template_name, context) = response
t = context['template_name'] = template_override or template_name
return render_to_response(t, context,
-context_instance=RequestContext(request))
+ context_instance=RequestContext(request))
return _dec
-
-def get_template_from_request(request, obj=None):
- """Gets a valid template from different sources or falls back to the
+def get_slug_and_relative_path(path):
+ """Split a page path into the slug, and the remaining left
+ part."""
+ if path[-1] == '/':
+ path = path[:-1]
+ slug = path.split("/")[-1]
+ root = reverse('pages-root')
+ if path.startswith(root):
+ path = path[len(root):]
+ return slug, path
+
+def get_template_from_request(request, page=None):
+ """
+ Gets a valid template from different sources or falls back to the
default template.
"""
if settings.PAGE_TEMPLATES is None:
@@ -73,8 +77,8 @@
(template in dict(settings.PAGE_TEMPLATES).keys() or
template == settings.DEFAULT_PAGE_TEMPLATE):
return template
- if obj is not None:
- return obj.get_template()
+ if page is not None:
+ return page.get_template()
return settings.DEFAULT_PAGE_TEMPLATE
def get_language_from_request(request, current_page=None):
=======================================
--- /trunk/pages/managers.py Tue Jul 21 01:02:49 2009
+++ /trunk/pages/managers.py Wed Jul 22 00:07:24 2009
@@ -22,7 +22,10 @@
from pages import settings
class PageManager(models.Manager):
- """Page manager methods"""
+ """
+ Page manager provide several filters to obtain pages ``QuerySet``
+ that respect the page settings.
+ """
def on_site(self, site_id=None):
if settings.PAGE_USE_SITE_ID:
@@ -51,15 +54,17 @@
return self.exclude(id__in=exclude_list)
def navigation(self):
- """Fisrt level navigation filter"""
- return
self.on_site().filter(status=self.model.PUBLISHED).filter(parent__isnull=True)
+ """Creates a ``QuerySet`` of the published root pages."""
+ return self.on_site().filter(
+ status=self.model.PUBLISHED).filter(parent__isnull=True)
def hidden(self):
- """Hidden page filter"""
+ """Creates a ``QuerySet`` of the hidden pages."""
return self.on_site().filter(status=self.model.HIDDEN)
def filter_published(self, queryset):
- """Published page filter"""
+ """Filter the given pages ``QuerySet`` to obtain only published
+ page."""
if settings.PAGE_USE_SITE_ID:
queryset = queryset.filter(sites=settings.SITE_ID)
@@ -76,9 +81,12 @@
return queryset
def published(self):
+ """Creates a ``QuerySet`` of published filter."""
return self.filter_published(self)
def drafts(self):
+ """Creates a ``QuerySet`` of drafts using the page's
+ status and ``publication_date``."""
pub = self.on_site().filter(status=self.model.DRAFT)
if settings.PAGE_SHOW_START_DATE:
pub = pub.filter(publication_date__gte=datetime.now())
@@ -89,7 +97,7 @@
publication_end_date__lte=datetime.now())
def from_path(self, path, lang, exclude_drafts=True):
- """Get the page according to a slug."""
+ """Get a page according to the page's path."""
from pages.models import Content, Page
from pages.http import get_slug_and_relative_path
slug, rpath = get_slug_and_relative_path(path)
=======================================
--- /trunk/pages/models.py Tue Jul 21 01:02:49 2009
+++ /trunk/pages/models.py Wed Jul 22 00:07:24 2009
@@ -29,7 +29,9 @@
class Page(models.Model):
- """A simple hierarchical page model"""
+ """
+ This model contain the status, dates, author, template.
+ The real content of the page can be found in the ``Content`` model."""
# some class constants to refer to, e.g. Page.DRAFT
DRAFT = 0
@@ -70,7 +72,7 @@
sites = models.ManyToManyField(Site, default=[settings.SITE_ID],
help_text=_('The site(s) the page is accessible at.'),
verbose_name=_('sites'))
-
+
redirect_to = models.ForeignKey('self', null=True, blank=True,
related_name='redirected_pages')
@@ -87,7 +89,7 @@
verbose_name_plural = _('pages')
def save(self, *args, **kwargs):
- """Override save method"""
+ """Override the save method."""
if not self.status:
self.status = self.DRAFT
# Published pages should always have a publication date
@@ -105,7 +107,7 @@
def get_calculated_status(self):
"""get the calculated status of the page based on
- published_date, published_end_date, and status"""
+ ``published_date``, ``published_end_date``, and ``status``."""
if settings.PAGE_SHOW_START_DATE and self.publication_date:
if self.publication_date > datetime.now():
return self.DRAFT
@@ -118,11 +120,11 @@
calculated_status = property(get_calculated_status)
def get_children_for_frontend(self):
- """Return the published children of the page for the frontend """
+ """Creates a ``QuerySet`` of published children page"""
return Page.objects.filter_published(self.get_children())
def invalidate(self, language_code=None):
- """Invalidate a page and it's descendants"""
+ """Invalidate this page and it's descendants."""
cache.delete(self.PAGE_LANGUAGES_KEY % (self.id))
#cache.delete(self.PAGE_TEMPLATE_KEY % (self.id))
@@ -142,7 +144,7 @@
def get_languages(self):
"""
- get the list of all existing languages for this page
+ return a list of all existing languages for this page.
"""
languages = cache.get(self.PAGE_LANGUAGES_KEY % (self.id))
if languages:
@@ -186,7 +188,10 @@
def slug(self, language=None, fallback=True):
"""
- get the slug of the page depending on the given language
+ Return the slug of the page depending on the given language.
+
+ If fallback is **True**, the slug will also be searched in other
+ languages.
"""
slug = Content.objects.get_content(self, language, 'slug',
@@ -196,7 +201,10 @@
def title(self, language=None, fallback=True):
"""
- get the title of the page depending on the given language
+ Return the title of the page depending on the given language.
+
+ If fallback is **True**, the title will also be searched in other
+ languages.
"""
if not language:
language = settings.PAGE_DEFAULT_LANGUAGE
@@ -252,6 +260,8 @@
return False
def with_level(self):
+ """Display the slug of the page prepended with insecable
+ spaces equal to the level of page in the hierarchy."""
level = ''
if self.level:
for n in range(0, self.level):
=======================================
--- /trunk/pages/utils.py Tue Jul 21 01:02:49 2009
+++ /trunk/pages/utils.py Wed Jul 22 00:07:24 2009
@@ -86,7 +86,7 @@
return False
def normalize_url(url):
- """ return a normalized url with trailing and without leading slash
+ """Return a normalized url with trailing and without leading slash.
>>> normalize_url(None)
'/'
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"pinax-updates" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/pinax-updates?hl=en
-~----------~----~----~----~------~----~------~--~---
