README.rst
1uritools
2========================================================================
3
4.. image:: https://img.shields.io/pypi/v/uritools
5 :target: https://pypi.org/project/uritools
6 :alt: Latest PyPI version
7
8.. image:: https://img.shields.io/readthedocs/uritools
9 :target: https://uritools.readthedocs.io
10 :alt: Documentation build status
11
12.. image:: https://img.shields.io/travis/tkem/uritools
13 :target: https://travis-ci.org/tkem/uritools
14 :alt: Travis CI build status
15
16.. image:: https://img.shields.io/coveralls/tkem/uritools
17 :target: https://coveralls.io/r/tkem/uritools
18 :alt: Test coverage
19
20.. image:: https://img.shields.io/github/license/tkem/uritools
21 :target: https://raw.github.com/tkem/uritools/master/LICENSE
22 :alt: License
23
24.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
25 :target: https://github.com/psf/black
26 :alt: Code style: black
27
28This module provides RFC 3986 compliant functions for parsing,
29classifying and composing URIs and URI references, largely replacing
30the Python Standard Library's ``urllib.parse`` module.
31
32.. code-block:: pycon
33
34 >>> from uritools import uricompose, urijoin, urisplit, uriunsplit
35 >>> uricompose(scheme='foo', host='example.com', port=8042,
36 ... path='/over/there', query={'name': 'ferret'},
37 ... fragment='nose')
38 'foo://example.com:8042/over/there?name=ferret#nose'
39 >>> parts = urisplit(_)
40 >>> parts.scheme
41 'foo'
42 >>> parts.authority
43 'example.com:8042'
44 >>> parts.getport(default=80)
45 8042
46 >>> parts.getquerydict().get('name')
47 ['ferret']
48 >>> parts.isuri()
49 True
50 >>> parts.isabsuri()
51 False
52 >>> urijoin(uriunsplit(parts), '/right/here?name=swallow#beak')
53 'foo://example.com:8042/right/here?name=swallow#beak'
54
55For various reasons, ``urllib.parse`` and its Python 2 predecessor
56``urlparse`` are not compliant with current Internet standards. As
57stated in `Lib/urllib/parse.py
58<https://github.com/python/cpython/blob/3.8/Lib/urllib/parse.py>`_:
59
60 RFC 3986 is considered the current standard and any future changes
61 to urlparse module should conform with it. The urlparse module is
62 currently not entirely compliant with this RFC due to defacto
63 scenarios for parsing, and for backward compatibility purposes,
64 some parsing quirks from older RFCs are retained.
65
66This module aims to provide fully RFC 3986 compliant replacements for
67the most commonly used functions found in ``urllib.parse``. It also
68includes functions for distinguishing between the different forms of
69URIs and URI references, and for conveniently creating URIs from their
70individual components.
71
72
73Installation
74------------------------------------------------------------------------
75
76uritools is available from PyPI_ and can be installed by running::
77
78 pip install uritools
79
80
81Project Resources
82------------------------------------------------------------------------
83
84- `Documentation`_
85- `Issue tracker`_
86- `Source code`_
87- `Change log`_
88
89
90License
91------------------------------------------------------------------------
92
93Copyright (c) 2014-2021 Thomas Kemmer.
94
95Licensed under the `MIT License`_.
96
97
98.. _PyPI: https://pypi.org/project/uritools/
99.. _Documentation: https://uritools.readthedocs.io/
100.. _Issue tracker: https://github.com/tkem/uritools/issues/
101.. _Source code: https://github.com/tkem/uritools/
102.. _Change log: https://github.com/tkem/uritools/blob/master/CHANGELOG.rst
103.. _MIT License: https://raw.github.com/tkem/uritools/master/LICENSE
104
