adding initial draft of parse and DecodedURL API docs. Also added default argument to DecodedURL() to ease programmatic construction. Fixes #125

Author: mahmoud

docs/api.rst

@@ -5,11 +5,43 @@ Hyperlink API
 
 .. automodule:: hyperlink._url
 
+.. contents::
+   :local:
+
 Creation
 --------
 
-Before you can work with URLs, you must create URLs. There are two
-ways to create URLs, from parts and from text.
+Before you can work with URLs, you must create URLs.
+
+Parsing Text
+^^^^^^^^^^^^
+
+If you already have a textual URL, the easiest way to get URL objects
+is with the :func:`parse()` function:
+
+.. autofunction:: hyperlink.parse
+
+By default, :func:`~hyperlink.parse()` returns an instance of
+:class:`DecodedURL`, a URL type that handles all encoding for you, by
+wrapping the lower-level :class:`URL`.
+
+DecodedURL
+^^^^^^^^^^
+
+.. autoclass:: hyperlink.DecodedURL
+.. automethod:: hyperlink.DecodedURL.from_text
+
+The Encoded URL
+^^^^^^^^^^^^^^^
+
+The lower-level :class:`URL` looks very similar to the
+:class:`DecodedURL`, but does not handle all encoding cases for
+you. Use with caution.
+
+.. note::
+
+   :class:`URL` is also available as an alias,
+   ``hyperlink.EncodedURL`` for more explicit usage.
 
 .. autoclass:: hyperlink.URL
 .. automethod:: hyperlink.URL.from_text

docs/index.rst

@@ -39,17 +39,17 @@ library. The easiest way to install is with pip::
 
 Then, URLs are just an import away::
 
-  from hyperlink import URL
+  import hyperlink
 
-  url = URL.from_text(u'http://github.com/python-hyper/hyperlink?utm_source=readthedocs')
+  url = hyperlink.parse(u'http://github.com/python-hyper/hyperlink?utm_source=readthedocs')
 
   better_url = url.replace(scheme=u'https', port=443)
   org_url = better_url.click(u'.')
 
   print(org_url.to_text())
   # prints: https://github.com/python-hyper/
 
-  print(better_url.get(u'utm_source'))
+  print(better_url.get(u'utm_source')[0])
   # prints: readthedocs
 
 See :ref:`the API docs <hyperlink_api>` for more usage examples.

src/hyperlink/_url.py

@@ -3,16 +3,18 @@
 
 Usage is straightforward::
 
-   >>> from hyperlink import URL
-   >>> url = URL.from_text(u'http://github.com/mahmoud/hyperlink?utm_source=docs')
+   >>> import hyperlink
+   >>> url = hyperlink.parse(u'http://github.com/mahmoud/hyperlink?utm_source=docs')
    >>> url.host
    u'github.com'
    >>> secure_url = url.replace(scheme=u'https')
    >>> secure_url.get('utm_source')[0]
    u'docs'
 
-As seen here, the API revolves around the lightweight and immutable
-:class:`URL` type, documented below.
+Hyperlink's API centers on the :class:`DecodedURL` type, which wraps
+the lower-level :class:`URL`, both of which can be returned by the
+:func:`parse()` convenience function.
+
 """  # noqa: E501
 
 import re
@@ -1743,13 +1745,23 @@ def remove(
 
 EncodedURL = URL  # An alias better describing what the URL really is
 
+_EMPTY_URL = URL()
 
 class DecodedURL(object):
-    """DecodedURL is a type meant to act as a higher-level interface to
-    the URL. It is the `unicode` to URL's `bytes`. `DecodedURL` has
-    almost exactly the same API as `URL`, but everything going in and
-    out is in its maximally decoded state. All percent decoding is
-    handled automatically.
+    """:class:`DecodedURL` is a type designed to act as a higher-level
+    interface to :class:`URL` and the recommended type for most
+    operations. By analogy, :class:`DecodedURL` is the
+    :class:`unicode` to URL's :class:`bytes`.
+
+    :class:`DecodedURL` automatically handles encoding and decoding
+    all its components, such that all inputs and outputs are in a
+    maximally-decoded state.  Note that this means, for some special
+    cases, a URL may not "roundtrip" character-for-character, but this
+    is considered a good tradeoff for the safety of automatic
+    encoding.
+
+    Otherwise, :class:`DecodedURL` has almost exactly the same API as
+    :class:`URL`.
 
     Where applicable, a UTF-8 encoding is presumed. Be advised that
     some interactions can raise :exc:`UnicodeEncodeErrors` and
@@ -1763,8 +1775,18 @@ class DecodedURL(object):
         lazy (bool): Set to True to avoid pre-decode all parts of the URL to
             check for validity. Defaults to False.
 
+    .. note::
+
+      The :class:`DecodedURL` initializer takes a :class:`URL` object,
+      not URL components, like :class:`URL`. To programmatically
+      construct a :class:`DecodedURL`, you can use this pattern:
+
+        >>>  DecodedURL().replace(host='pypi.org', path=('projects', 'hyperlink').to_text()
+        "http://pypi.org/projects/hyperlink"
+
+
     """
-    def __init__(self, url, lazy=False):
+    def __init__(self, url=_EMPTY_URL, lazy=False):
         # type: (URL, bool) -> None
         self._url = url
         if not lazy:
@@ -2098,7 +2120,7 @@ def parse(url, decoded=True, lazy=False):
         decoded (bool): Whether or not to return a :class:`DecodedURL`,
             which automatically handles all
             encoding/decoding/quoting/unquoting for all the various
-            accessors of parts of the URL, or an :class:`EncodedURL`,
+            accessors of parts of the URL, or a :class:`URL`,
             which has the same API, but requires handling of special
             characters for different parts of the URL.