Anonymous avatar Anonymous committed 18ba0ab

Docs for converters and path.

Comments (0)

Files changed (4)

docs/modules/html/converters.rst

 .. automodule:: webhelpers.html.converters
 
 .. currentmodule:: webhelpers.html.converters
+
+.. autofunction:: format_paragraphs
+
+.. autofunction:: markdown
+
+.. autofunction:: nl2br
+
+.. autofunction:: render
+
+.. autofunction:: sanitize
+
+.. autofunction:: textilize

docs/modules/path.rst

 .. currentmodule:: webhelpers.path
 
 .. autoclass:: Path
-   :members:
+
+   **Constructors:**
+
+   .. automethod:: __new__
+   .. automethod:: cwd
+
+   **Properties:**
+
+   **parent**
+       The path without the final component; akin to os.path.dirname().
+       Example: Path('/usr/lib/libpython.so').parent => Path('/usr/lib')
+       
+
+   **name**
+       The final component of the path.
+       Example: path('/usr/lib/libpython.so').name => Path('libpython.so')
+
+   **stem**
+       Same as path.name but with one file extension stripped off.
+       Example: path('/home/guido/python.tar.gz').stem => Path('python.tar')
+
+   **ext**
+       The file extension, for example '.py'.
+
+   **Absolute paths:**
+
+   .. automethod:: isabsolute
+
+   .. automethod:: absolute
+
+   **Joining paths:**
+
+   .. automethod:: joinpath
+
+   .. automethod:: child
+
+   **Path modification:**
+
+   .. automethod:: ancestor
+
+   .. automethod:: norm
+   
+   .. automethod:: norm_case
+
+   .. automethod:: expand_user
+
+   .. automethod:: expand_vars
+
+   .. automethod:: expand
+
+   **Calculating paths:**
+
+   .. automethod:: relpath
+
+   .. automethod:: resolve
+
+   .. automethod:: strip_parents
+
+   **File reading and writing:**
+
+   .. automethod:: read_file
+
+   .. automethod:: write_file

webhelpers/html/converters.py

     original port, and version 2.x contains extensions for footnotes, RSS, etc. 
     `Markdown2 <http://code.google.com/p/python-markdown2/>`_ is another port
     which claims to be faster and to handle edge cases better. 
-    WebHelpers itself contains an old version of Markdown
-    (``webhelpers.markdown`` == Markdown 1.7 without the extensions), but it's 
-    deprecated.  Most WebHelpers users use Markdown from Freewisdom.com.
 
     You can pass the desired Markdown module as the ``markdown``
-    argument, or the helper will try to import ``markdown`` and fall back to
-    ``webhelpers.markdown`` if it can't. (The latter will trigger a deprecation
-    warning.)
+    argument, or the helper will try to import ``markdown``. If neither is
+    available, it will fall back to ``webhelpers.markdown``, which is
+    Freewisdom's Markdown 1.7 without extensions.
     
     IMPORTANT:
     If your source text is untrusted and may contain malicious HTML markup,

webhelpers/path.py

 _base = os.path.supports_unicode_filenames and unicode or str
 
 class Path(_base):
-    """An object-oriented approach to os.path functions."""
+    """A filesystem path with ``os.path``-like methods."""
     auto_norm = False
 
     #### Special Python methods.
     def __new__(class_, *args, **kw):
+        """Create a path object.
+
+        ``*args`` are one or more string paths, which will be joined using
+        ``os.path.join``. An argument can also be a ``Path`` object or a list
+        of strings, which will be interpolated and joined.
+
+
+        Only one keyword argument is allowed, ``norm``.  If ``norm`` is true
+        or the class attribute ``.auto_norm`` is true, call ``.norm()`` to
+        clean up redundant ".." and ".", double slashes, wrong-direction
+        slashes, etc. On case-insensitive filesystems it also converts
+        uppercase to lower case. Warning: if the filesystem contains symbolic
+        links, normalizing ".." goes to the parent of the symbolic link rather
+        than the parent of the linked-to file. Because normalization can 
+        sometimes produce a different path than expected, it's disabled by
+        default. If you want ``Path`` to always normalize paths, set the 
+        ``.auto_norm`` attribute to True at the beginning of your program.
+        """
+
         norm = kw.pop("norm", None)
         if norm is None:
             norm = class_.auto_norm
         if isinstance(newpath, class_):
             return newpath
         if norm:
-            newpath = class_.os.path.normpath(newpath)
+            newpath = os.path.normpath(newpath)
             # Can't call .norm() because the path isn't instantiated yet.
         return _base.__new__(class_, newpath)
 
             p = os.path.dirname(p)
         return self.__class__(p)
 
+    def joinpath(self, *children):
+        """Same as ``os.path.join`` or ``Path(self, \*children)``.
+
+        The children are not checked for special path characters
+        ("/", "..", ".").  See ``.child`` for a "safe" version of this 
+        method.
+        """
+        return self.__class__(self, *children)
+
     def child(self, *children):
         """Join paths in a safe manner.
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.