Fixed #589 -- Added FilePathField. It's available as an ORM field and as a standalone field in django.core.formfields. Thanks, jay@skabber.com

git-svn-id: http://code.djangoproject.com/svn/django/trunk@846 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 34 insertions, 0 deletions

diff --git a/docs/model-api.txt b/docs/model-api.txt
index 2ad2b3594d..19b69b2d66 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -272,6 +272,40 @@ Here are all available field types:
 
     .. _`strftime formatting`: http://docs.python.org/lib/module-time.html#l2h-1941
 
+``FilePathField``
+    A field whose choices are limited to the filenames in a certain directory
+    on the filesystem. Has three special arguments, of which the first is
+    required:
+
+        ======================  ===================================================
+        Argument                Description
+        ======================  ===================================================
+        ``path``                Required. The absolute filesystem path to a
+                                directory from which this ``FilePathField`` should
+                                get its choices. Example: ``"/home/images"``.
+
+        ``match``               Optional. A regular expression, as a string, that
+                                ``FilePathField`` will use to filter filenames.
+                                Note that the regex will be applied to the
+                                base filename, not the full path. Example:
+                                ``"foo.*\.txt^"``, which will match a file called
+                                ``foo23.txt`` but not ``bar.txt`` or ``foo23.gif``.
+
+        ``recursive``           Optional. Either ``True`` or ``False``. Default is
+                                ``False``. Specifies whether all subdirectories of
+                                ``path`` should be included.
+
+    Of course, these arguments can be used together.
+
+    The one potential gotcha is that ``match`` applies to the base filename,
+    not the full path. So, this example::
+
+        FilePathField(path="/home/images", match="foo.*", recursive=True)
+
+    ...will match ``/home/images/foo.gif`` but not ``/home/images/foo/bar.gif``
+    because the ``match`` applies to the base filename (``foo.gif`` and
+    ``bar.gif``).
+
 ``FloatField``
     A floating-point number. Has two **required** arguments: