README.md
1# Hyperlink
2
3*Cool URLs that don't change.*
4
5<a href="https://hyperlink.readthedocs.io/en/latest/">
6 <img src="https://img.shields.io/badge/docs-latest-brightgreen.svg?style=flat" alt="Documentation">
7</a>
8<a href="https://pypi.org/project/hyperlink/">
9 <img src="https://img.shields.io/pypi/v/hyperlink.svg" alt="PyPI">
10</a>
11<a href="http://calver.org">
12 <img src="https://img.shields.io/badge/calver-YY.MINOR.MICRO-22bfda.svg" alt="Calendar Versioning">
13</a>
14<a href="https://pypi.org/project/hyperlink/">
15 <img src="https://img.shields.io/pypi/pyversions/hyperlink.svg" alt="Python Version Compatibility">
16</a>
17<a href="https://https://codecov.io/github/python-hyper/hyperlink?branch=master">
18 <img src="https://codecov.io/github/python-hyper/hyperlink/coverage.svg?branch=master" alt="Code Coverage">
19</a>
20<a href="https://requires.io/github/python-hyper/hyperlink/requirements/?branch=master">
21 <img src="https://requires.io/github/python-hyper/hyperlink/requirements.svg?branch=master" alt="Requirements Status">
22</a>
23
24Hyperlink provides a pure-Python implementation of immutable
25URLs. Based on [RFC 3986][rfc3986] and [3987][rfc3987], the Hyperlink URL
26makes working with both URIs and IRIs easy.
27
28Hyperlink is tested against Python 2.7, 3.4, 3.5, 3.6, 3.7, 3.8, and PyPy.
29
30Full documentation is available on [Read the Docs][docs].
31
32[rfc3986]: https://tools.ietf.org/html/rfc3986
33[rfc3987]: https://tools.ietf.org/html/rfc3987
34[docs]: http://hyperlink.readthedocs.io/en/latest/
35
36## Installation
37
38Hyperlink is a pure-Python package and requires nothing but
39Python. The easiest way to install is with pip:
40
41```
42pip install hyperlink
43```
44
45Then, hyperlink away!
46
47```python
48from hyperlink import URL
49
50url = URL.from_text(u'http://github.com/python-hyper/hyperlink?utm_source=README')
51utm_source = url.get(u'utm_source')
52better_url = url.replace(scheme=u'https', port=443)
53org_url = better_url.click(u'.')
54```
55
56See the full API docs on [Read the Docs][docs].
57
58## More information
59
60Hyperlink would not have been possible without the help of
61[Glyph Lefkowitz](https://glyph.twistedmatrix.com/) and many other
62community members, especially considering that it started as an
63extract from the Twisted networking library. Thanks to them,
64Hyperlink's URL has been production-grade for well over a decade.
65
66Still, should you encounter any issues, do file an issue, or submit a
67pull request.
68
