Merge pull request #590 from untitaker/url_classdoc

Document ``werkzeug.urls`` in full detail.

docs/contents.rst.inc

@@ -39,6 +39,7 @@ Reference
    http
    datastructures
    utils
+   urls
    local
    middlewares
    exceptions

docs/urls.rst

@@ -0,0 +1,6 @@
+===========
+URL Helpers
+===========
+
+.. automodule:: werkzeug.urls
+   :members:

docs/utils.rst

@@ -49,32 +49,7 @@ General Helpers
 URL Helpers
 ===========
 
-.. module:: werkzeug.urls
-
-.. autoclass:: Href
-
-.. autofunction:: url_decode
-
-.. autofunction:: url_decode_stream
-
-.. autofunction:: url_encode
-
-.. autofunction:: url_encode_stream
-
-.. autofunction:: url_quote
-
-.. autofunction:: url_quote_plus
-
-.. autofunction:: url_unquote
-
-.. autofunction:: url_unquote_plus
-
-.. autofunction:: url_fix
-
-.. autofunction:: uri_to_iri
-
-.. autofunction:: iri_to_uri
-
+Please refer to :doc:`urls`.
 
 UserAgent Parsing
 =================

werkzeug/urls.py

@@ -3,7 +3,14 @@
     werkzeug.urls
     ~~~~~~~~~~~~~
 
-    This module implements various URL related functions.
+    ``werkzeug.urls`` used to provide several wrapper functions for Python 2
+    urlparse, whose main purpose were to work around the behavior of the Py2
+    stdlib and its lack of unicode support. While this was already a somewhat
+    inconvenient situation, it got even more complicated because Python 3's
+    ``urllib.parse`` actually does handle unicode properly. In other words,
+    this module would wrap two libraries with completely different behavior. So
+    now this module contains a 2-and-3-compatible backport of Python 3's
+    ``urllib.parse``, which is mostly API-compatible.
 
     :copyright: (c) 2014 by the Werkzeug Team, see AUTHORS for more details.
     :license: BSD, see LICENSE for more details.
@@ -37,7 +44,8 @@
     ['scheme', 'netloc', 'path', 'query', 'fragment']))
 
 
-class _URLMixin(object):
+class BaseURL(_URLTuple):
+    '''Superclass of :py:class:`URL` and :py:class:`BytesURL`.'''
     __slots__ = ()
 
     def replace(self, **kwargs):
@@ -268,7 +276,7 @@ def _split_host(self):
 
 
 @implements_to_string
-class URL(_URLTuple, _URLMixin):
+class URL(BaseURL):
     """Represents a parsed URL.  This behaves like a regular tuple but
     also has some extra attributes that give further insight into the
     URL.
@@ -311,7 +319,7 @@ def encode(self, charset='utf-8', errors='replace'):
         )
 
 
-class BytesURL(_URLTuple, _URLMixin):
+class BytesURL(BaseURL):
     """Represents a parsed URL in bytes."""
     __slots__ = ()
     _at = b'@'