Metadata-Version: 1.1
Name: purl
Version: 1.3.1
Summary: An immutable URL class for easy URL-building and manipulation
Home-page: https://github.com/codeinthehole/purl
Author: David Winterbottom
Author-email: david.winterbottom@gmail.com
License: MIT
Description: ================================
        purl - A simple Python URL class
        ================================
        
        A simple, immutable URL class with a clean API for interrogation and
        manipulation.  Supports Python 2.6, 2.7, 3.3, 3.4 and pypy.
        
        Also supports template URLs as per `RFC 6570`_
        
        Contents:
        
        .. contents:: :local:
            :depth: 1
        
        .. image:: https://secure.travis-ci.org/codeinthehole/purl.png
            :target: https://travis-ci.org/codeinthehole/purl
        
        .. image:: https://pypip.in/v/purl/badge.png
            :target: https://crate.io/packages/purl/
        
        .. image:: https://pypip.in/d/purl/badge.png
            :target: https://crate.io/packages/purl/
        
        .. _`RFC 6570`: http://tools.ietf.org/html/rfc6570
        
        Docs
        ----
        
        http://purl.readthedocs.org/en/latest/
        
        Install
        -------
        
        From PyPI (stable)::
        
            $ pip install purl
        
        From Github (unstable)::
        
            $ pip install git+git://github.com/codeinthehole/purl.git#egg=purl
        
        Use
        ---
        
        Construct:
        
        .. code:: python
        
            >>> from purl import URL
        
            # String constructor
            >>> from_str = URL('https://www.google.com/search?q=testing')
        
            # Keyword constructor
            >>> from_kwargs = URL(scheme='https', host='www.google.com', path='/search', query='q=testing')
        
            # Combine
            >>> from_combo = URL('https://www.google.com').path('search').query_param('q', 'testing')
        
        URL objects are immutable - all mutator methods return a new instance.
        
        Interrogate:
        
        .. code:: python
        
            >>> u = URL(u'https://www.google.com/search?q=testing')
            >>> u.scheme()
            u'https'
            >>> u.host()
            u'www.google.com'
            >>> u.domain()
            u'www.google.com'
            >>> u.username()
            >>> u.password()
            >>> u.netloc()
            u'www.google.com'
            >>> u.port()
            >>> u.path()
            u'/search'
            >>> u.query()
            u'q=testing'
            >>> u.fragment()
            u''
            >>> u.path_segment(0)
            u'search'
            >>> u.path_segments()
            (u'search',)
            >>> u.query_param('q')
            u'testing'
            >>> u.query_param('q', as_list=True)
            [u'testing']
            >>> u.query_param('lang', default=u'GB')
            u'GB'
            >>> u.query_params()
            {u'q': [u'testing']}
            >>> u.has_query_param('q')
            True
            >>> u.has_query_params(('q', 'r'))
            False
            >>> u.subdomains()
            [u'www', u'google', u'com']
            >>> u.subdomain(0)
            u'www'
        
        Note that each accessor method is overloaded to be a mutator method too, similar
        to the jQuery API.  Eg:
        
        .. code:: python
        
            >>> u = URL.from_string('https://github.com/codeinthehole')
        
            # Access
            >>> u.path_segment(0)
            u'codeinthehole'
        
            # Mutate (creates a new instance)
            >>> new_url = u.path_segment(0, 'tangentlabs')
            >>> new_url is u
            False
            >>> new_url.path_segment(0)
            u'tangentlabs'
        
        Hence, you can build a URL up in steps:
        
        .. code:: python
        
            >>> u = URL().scheme('http').domain('www.example.com').path('/some/path').query_param('q', 'search term')
            >>> u.as_string()
            u'http://www.example.com/some/path?q=search+term'
        
        Along with the above overloaded methods, there is also a ``add_path_segment``
        method for adding a segment at the end of the current path:
        
        .. code:: python
        
            >>> new_url = u.add_path_segment('here')
            >>> new_url.as_string()
            u'http://www.example.com/some/path/here?q=search+term'
        
        Couple of other things:
        
        * Since the URL class is immutable it can be used as a key in a dictionary
        * It can be pickled and restored
        * It supports equality operations
        * It supports equality operations
        
        URL templates can be used either via a ``Template`` class:
        
        .. code:: python
        
            >>> from purl import Template
            >>> tpl = Template("http://example.com{/list*}")
            >>> url = tpl.expand({'list': ['red', 'green', 'blue']})
            >>> url.as_string()
            u'http://example.com/red/green/blue'
        
        or the ``expand`` function:
        
        .. code:: python
        
            >>> from purl import expand
            >>> expand(u"{/list*}", {'list': ['red', 'green', 'blue']})
            u'/red/green/blue'
        
        A wide variety of expansions are possible - refer to the RFC_ for more details.
        
        .. _RFC: http://tools.ietf.org/html/rfc6570
        
        Changelog
        ---------
        
        v1.3.1
        ~~~~~~
        
        * Ensure paths always have a leading slash
        
        v1.3
        ~~~~
        
        * Allow absolute URLs to be converted into relative
        
        v1.2
        ~~~~
        
        * Support password-less URLs
        * Allow slashes to be passed as path segments
        
        v1.1
        ~~~~
        
        * Support setting username and password via mutator methods
        
        v1.0.3
        ~~~~~~
        
        * Handle some unicode compatibility edge-cases
        
        v1.0.2
        ~~~~~~
        
        * Fix template expansion bug with no matching variables being passed in. This
          ensures ``purl.Template`` works correctly with the URLs returned from the
          Github API.
        
        v1.0.1
        ~~~~~~
        
        * Fix bug with special characters in paths not being escaped.
        
        v1.0
        ~~~~
        
        * Slight tidy up. Document support for PyPy and Python 3.4.
        
        v0.8
        ~~~~
        
        * Support for RFC 6570 URI templates
        
        v0.7
        ~~~~
        
        * All internal strings are unicode.
        * Support for unicode chars in path, fragment, query, auth added.
        
        v0.6
        ~~~~
        
        * Added ``append_query_param`` method
        * Added ``remove_query_param`` method
        
        v0.5
        ~~~~
        
        * Added support for Python 3.2/3.3 (thanks @pmcnr and @mitchellrj)
        
        v0.4.1
        ~~~~~~
        
        * Added API docs
        * Added to readthedocs.org
        
        v0.4
        ~~~~
        
        * Modified constructor to accept full URL string as first arg
        * Added ``add_path_segment`` method
        
        v0.3.2
        ~~~~~~
        
        * Fixed bug port number in string when using from_string constructor
        
        v0.3.1
        ~~~~~~
        
        * Fixed bug with passing lists to query param setter methods
        
        v0.3
        ~~~~
        
        * Added support for comparison and equality
        * Added support for pickling
        * Added ``__slots__`` so instances can be used as keys within dictionaries
        
        Contribute
        ----------
        
        Clone, create a virtualenv then install purl and the packages required for
        testing::
        
            $ git clone git@github.com:codeinthehole/purl.git
            $ cd purl
            $ mkvirtualenv purl  # requires virtualenvwrapper
            (purl) $ make
        
        Ensure tests pass using::
        
            (purl) $ ./runtests.sh
        
        or::
        
            $ tox
            $ tox
            $ tox
            $ tox
        
        Hack away.
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Libraries :: Python Modules
