Changeset 4535

Timestamp:

04/28/08 17:35:03 (4 months ago)

Author:

alberto

Message:

documenting...

Files:

• projects/ToscaWidgets/trunk/docs/source/api.rst (modified) (3 diffs)
• projects/ToscaWidgets/trunk/docs/source/conf.py (modified) (1 diff)
• projects/ToscaWidgets/trunk/tests/__init__.py (modified) (1 diff)
• projects/ToscaWidgets/trunk/tw/core/base.py (modified) (10 diffs)

projects/ToscaWidgets/trunk/docs/source/api.rst

@@ -4 +4 @@
-==========
-
-
-
+
+
+
+
+
+
+
+
+
+
-
-Widget
@@ -18 +26 @@
-   :members:
-
+   .. autoattribute:: tw.api.Widget.id
+   .. autoattribute:: tw.api.Widget.is_root
+   .. autoattribute:: tw.api.Widget.root
+   .. autoattribute:: tw.api.Widget.displays_on
+   .. autoattribute:: tw.api.Widget.path
+   .. autoattribute:: tw.api.Widget.key
+   .. attribute:: params
+
+      A set with all the params declared in all the widget's bases and itself.
+      This set is computed by :class:`tw.core.meta.WidgetType` from the class
+      attribute.
+
+      Example:
+
+      .. doctest::
+
+         >>> from tw.api import Widget
+         >>> class SomeWidget(Widget):
+         ...    params = ["a", "b"]
+         ...
+         >>> "a" in SomeWidget.params
+         True
+         
+         All params from Widget are present in SomeWidget's set too.
+
+         >>> "id" in SomeWidget.params
+         True
+
+
+
+
+WidgetsList
+-----------
+
+This object is just syntax sugar to have a DSL-like way to declare a list
+of widgets. Although it's subclasses appear to have attributes, there's some
+metaclass magic behind the scenes which turns the class into a list factory.
+
+Example:
+
+.. doctest::
+    
+    >>> from tw.api import Widget, WidgetsList
+    >>> class SomeWidgets(WidgetsList):
+    ...     a = Widget()
+    ...     b = Widget()
+    ...     c = Widget()
+    ...
+    >>> [w.id for w in SomeWidgets()]
+    ['a', 'b', 'c']
+
+Notice how we don't need to pass and ``id`` parameter and the widgets are
+sorted by ascending declaration time.
+
+.. autoclass:: tw.api.WidgetsList
+   :members:
+
-
-.. rubric:: Footnotes
@@ -26 +91 @@
-
- 
-
-

projects/ToscaWidgets/trunk/docs/source/conf.py

@@ -27 +27 @@
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-
+, 'sphinx.ext.doctest'
-
-# Add any paths that contain templates here, relative to this directory.

projects/ToscaWidgets/trunk/tests/__init__.py

@@ -14 +14 @@
-
-DOCTEST_MODULES = [
-
+.base
-    "tw.core.meta",
-    "tw.core.util",

projects/ToscaWidgets/trunk/tw/core/base.py

@@ -183 +183 @@
-
-    #XXX: Some of these properties could be implemented as static attributes
-
-    @property
-    def id(self):
-        return '_'.join(reversed(
-            [w.id_path_elem for w in self.path if w.id_path_elem]
-            )) or None
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-    def key(self):
-        return '.' + '.'.join(reversed(
-            [w.id_path_elem for w in self.path if w.id_path_elem][:-1]
-            )) or None
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-    def path(self):
-        yield self
@@ -203 +233 @@
-            for i in self.parent.path:
-                yield i
-
-
+
+
+
+
-    def displays_on(self):
-        if self.is_root:
@@ -210 +242 @@
-        else:
-            return self.parent.engine_name
+    displays_on = property(displays_on, doc="""\
+        Where the widget is being displayed on
+        """)
-
-    @property
@@ -216 +251 @@
-
-
-    @property
-    def root(self):
-        return list(self.path)[-1]
-
-
+
+
-    def is_root(self):
-        return self.parent is None
+    is_root = property(is_root, doc="True if the widget doesn't have a parent")
-
-    def __new__(cls, id=None, parent=None, children=[], **kw):
@@ -294 +329 @@
-    @only_if_initialized
-    def clone(self, *args, **kw):
-
+
+
-        overriding initialization parameters.
-
-Example:
-
-.. sourcecode:: python
+This is the only way to safely "modify" a widget instance.
+
+Example::
-
-            >>> w = Widget('foo', a=2)
@@ -364 +400 @@
-
-    def post_init(self, *args, **kw):
+        """
+        This method is called for all :class:`tw.api.Widget` base classes to
+        perform final setup after the widget is initialized but before it is
+        locked.
+        """
-        self._collect_resources() 
-        if len(self._js_calls) > 0:
@@ -381 +422 @@
-
-    def walk(self, filter=None, recur_if_filtered=True):
-
+
+
-        applying a filter on them.
-        
-.. sourcecode:: python
+Example::
-    
-            >>> W = Widget
@@ -414 +456 @@
-
-    def add_call(self, call):
-
-
+
+
+
+
-        if self._is_initialized and self.include_dynamic_js_calls:
-            log.debug("Adding call <%s> for %r dynamically.", call, self)
@@ -460 +504 @@
-
-    def render(self, value=None, **kw):
+        """
+        Renders a widget as an unicode string.
+        """
-        kw = self.prepare_dict(value, kw)
-        if self.is_root:
@@ -466 +513 @@
-
-    def display(self, value=None, **kw):
+        """
+        Renders a widget and adapts the output. This method **must** be used
+        to display child widgets inside their parent's template so output is
+        adapted.
+        
+        Unlike :meth:`tw.api.Widget.render`, :meth:`tw.api.Widget.display`
+        returns adapted output compatible with the template the widget is being
+        rendered on. For example, this is needed so Genshi doesn't autoescape
+        string output from mako and to serialize Genshi output on the other way
+        around.
+        """
-        kw = self.prepare_dict(value, kw)
-        if self.is_root: