rfc3986
=======
A Python implementation of `RFC 3986`_ including validation and authority
parsing.
Installation
------------
Use pip to install ``rfc3986`` like so::
pip install rfc3986
License
-------
`Apache License Version 2.0`_
Example Usage
-------------
The following are the two most common use cases envisioned for ``rfc3986``.
Replacing ``urlparse``
``````````````````````
To parse a URI and receive something very similar to the standard library's
``urllib.parse.urlparse``
.. code-block:: python
from rfc3986 import urlparse
ssh = urlparse('ssh://user@git.openstack.org:29418/openstack/glance.git')
print(ssh.scheme) # => ssh
print(ssh.userinfo) # => user
print(ssh.params) # => None
print(ssh.port) # => 29418
To create a copy of it with new pieces you can use ``copy_with``:
.. code-block:: python
new_ssh = ssh.copy_with(
scheme='https'
userinfo='',
port=443,
path='/openstack/glance'
)
print(new_ssh.scheme) # => https
print(new_ssh.userinfo) # => None
# etc.
Strictly Parsing a URI and Applying Validation
``````````````````````````````````````````````
To parse a URI into a convenient named tuple, you can simply:
.. code-block:: python
from rfc3986 import uri_reference
example = uri_reference('http://example.com')
email = uri_reference('mailto:user@domain.com')
ssh = uri_reference('ssh://user@git.openstack.org:29418/openstack/keystone.git')
With a parsed URI you can access data about the components:
.. code-block:: python
print(example.scheme) # => http
print(email.path) # => user@domain.com
print(ssh.userinfo) # => user
print(ssh.host) # => git.openstack.org
print(ssh.port) # => 29418
It can also parse URIs with unicode present:
.. code-block:: python
uni = uri_reference(b'http://httpbin.org/get?utf8=\xe2\x98\x83') # ☃
print(uni.query) # utf8=%E2%98%83
With a parsed URI you can also validate it:
.. code-block:: python
if ssh.is_valid():
subprocess.call(['git', 'clone', ssh.unsplit()])
You can also take a parsed URI and normalize it:
.. code-block:: python
mangled = uri_reference('hTTp://exAMPLe.COM')
print(mangled.scheme) # => hTTp
print(mangled.authority) # => exAMPLe.COM
normal = mangled.normalize()
print(normal.scheme) # => http
print(mangled.authority) # => example.com
But these two URIs are (functionally) equivalent:
.. code-block:: python
if normal == mangled:
webbrowser.open(normal.unsplit())
Your paths, queries, and fragments are safe with us though:
.. code-block:: python
mangled = uri_reference('hTTp://exAMPLe.COM/Some/reallY/biZZare/pAth')
normal = mangled.normalize()
assert normal == 'hTTp://exAMPLe.COM/Some/reallY/biZZare/pAth'
assert normal == 'http://example.com/Some/reallY/biZZare/pAth'
assert normal != 'http://example.com/some/really/bizzare/path'
If you do not actually need a real reference object and just want to normalize
your URI:
.. code-block:: python
from rfc3986 import normalize_uri
assert (normalize_uri('hTTp://exAMPLe.COM/Some/reallY/biZZare/pAth') ==
'http://example.com/Some/reallY/biZZare/pAth')
You can also very simply validate a URI:
.. code-block:: python
from rfc3986 import is_valid_uri
assert is_valid_uri('hTTp://exAMPLe.COM/Some/reallY/biZZare/pAth')
Requiring Components
~~~~~~~~~~~~~~~~~~~~
You can validate that a particular string is a valid URI and require
independent components:
.. code-block:: python
from rfc3986 import is_valid_uri
assert is_valid_uri('http://localhost:8774/v2/resource',
require_scheme=True,
require_authority=True,
require_path=True)
# Assert that a mailto URI is invalid if you require an authority
# component
assert is_valid_uri('mailto:user@example.com', require_authority=True) is False
If you have an instance of a ``URIReference``, you can pass the same arguments
to ``URIReference#is_valid``, e.g.,
.. code-block:: python
from rfc3986 import uri_reference
http = uri_reference('http://localhost:8774/v2/resource')
assert uri.is_valid(require_scheme=True,
require_authority=True,
require_path=True)
# Assert that a mailto URI is invalid if you require an authority
# component
mailto = uri_reference('mailto:user@example.com')
assert uri.is_valid(require_authority=True) is False
Alternatives
------------
- `rfc3987 <https://pypi.python.org/pypi/rfc3987/1.3.4>`_
This is a direct competitor to this library, with extra features,
licensed under the GPL.
- `uritools <https://pypi.python.org/pypi/uritools/0.5.1>`_
This can parse URIs in the manner of RFC 3986 but provides no validation and
only recently added Python 3 support.
- Standard library's `urlparse`/`urllib.parse`
The functions in these libraries can only split a URI (valid or not) and
provide no validation.
Contributing
------------
This project follows and enforces the Python Software Foundation's `Code of
Conduct <https://www.python.org/psf/codeofconduct/>`_.
If you would like to contribute but do not have a bug or feature in mind, feel
free to email Ian and find out how you can help.
The git repository for this project is maintained at
https://github.com/python-hyper/rfc3986
.. _RFC 3986: https://datatracker.ietf.org/doc/html/rfc3986/
.. _Apache License Version 2.0: https://www.apache.org/licenses/LICENSE-2.0
Raw data
{
"_id": null,
"home_page": "http://rfc3986.readthedocs.io",
"name": "rfc3986",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Ian Stapleton Cordasco",
"author_email": "graffatcolmingov@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/85/40/1520d68bfa07ab5a6f065a186815fb6610c86fe957bc065754e47f7b0840/rfc3986-2.0.0.tar.gz",
"platform": "",
"description": "rfc3986\n=======\n\nA Python implementation of `RFC 3986`_ including validation and authority\nparsing.\n\nInstallation\n------------\n\nUse pip to install ``rfc3986`` like so::\n\n pip install rfc3986\n\nLicense\n-------\n\n`Apache License Version 2.0`_\n\nExample Usage\n-------------\n\nThe following are the two most common use cases envisioned for ``rfc3986``.\n\nReplacing ``urlparse``\n``````````````````````\n\nTo parse a URI and receive something very similar to the standard library's\n``urllib.parse.urlparse``\n\n.. code-block:: python\n\n from rfc3986 import urlparse\n\n ssh = urlparse('ssh://user@git.openstack.org:29418/openstack/glance.git')\n print(ssh.scheme) # => ssh\n print(ssh.userinfo) # => user\n print(ssh.params) # => None\n print(ssh.port) # => 29418\n\nTo create a copy of it with new pieces you can use ``copy_with``:\n\n.. code-block:: python\n\n new_ssh = ssh.copy_with(\n scheme='https'\n userinfo='',\n port=443,\n path='/openstack/glance'\n )\n print(new_ssh.scheme) # => https\n print(new_ssh.userinfo) # => None\n # etc.\n\nStrictly Parsing a URI and Applying Validation\n``````````````````````````````````````````````\n\nTo parse a URI into a convenient named tuple, you can simply:\n\n.. code-block:: python\n\n from rfc3986 import uri_reference\n\n example = uri_reference('http://example.com')\n email = uri_reference('mailto:user@domain.com')\n ssh = uri_reference('ssh://user@git.openstack.org:29418/openstack/keystone.git')\n\nWith a parsed URI you can access data about the components:\n\n.. code-block:: python\n\n print(example.scheme) # => http\n print(email.path) # => user@domain.com\n print(ssh.userinfo) # => user\n print(ssh.host) # => git.openstack.org\n print(ssh.port) # => 29418\n\nIt can also parse URIs with unicode present:\n\n.. code-block:: python\n\n uni = uri_reference(b'http://httpbin.org/get?utf8=\\xe2\\x98\\x83') # \u2603\n print(uni.query) # utf8=%E2%98%83\n\nWith a parsed URI you can also validate it:\n\n.. code-block:: python\n\n if ssh.is_valid():\n subprocess.call(['git', 'clone', ssh.unsplit()])\n\nYou can also take a parsed URI and normalize it:\n\n.. code-block:: python\n\n mangled = uri_reference('hTTp://exAMPLe.COM')\n print(mangled.scheme) # => hTTp\n print(mangled.authority) # => exAMPLe.COM\n\n normal = mangled.normalize()\n print(normal.scheme) # => http\n print(mangled.authority) # => example.com\n\nBut these two URIs are (functionally) equivalent:\n\n.. code-block:: python\n\n if normal == mangled:\n webbrowser.open(normal.unsplit())\n\nYour paths, queries, and fragments are safe with us though:\n\n.. code-block:: python\n\n mangled = uri_reference('hTTp://exAMPLe.COM/Some/reallY/biZZare/pAth')\n normal = mangled.normalize()\n assert normal == 'hTTp://exAMPLe.COM/Some/reallY/biZZare/pAth'\n assert normal == 'http://example.com/Some/reallY/biZZare/pAth'\n assert normal != 'http://example.com/some/really/bizzare/path'\n\nIf you do not actually need a real reference object and just want to normalize\nyour URI:\n\n.. code-block:: python\n\n from rfc3986 import normalize_uri\n\n assert (normalize_uri('hTTp://exAMPLe.COM/Some/reallY/biZZare/pAth') ==\n 'http://example.com/Some/reallY/biZZare/pAth')\n\nYou can also very simply validate a URI:\n\n.. code-block:: python\n\n from rfc3986 import is_valid_uri\n\n assert is_valid_uri('hTTp://exAMPLe.COM/Some/reallY/biZZare/pAth')\n\nRequiring Components\n~~~~~~~~~~~~~~~~~~~~\n\nYou can validate that a particular string is a valid URI and require\nindependent components:\n\n.. code-block:: python\n\n from rfc3986 import is_valid_uri\n\n assert is_valid_uri('http://localhost:8774/v2/resource',\n require_scheme=True,\n require_authority=True,\n require_path=True)\n\n # Assert that a mailto URI is invalid if you require an authority\n # component\n assert is_valid_uri('mailto:user@example.com', require_authority=True) is False\n\nIf you have an instance of a ``URIReference``, you can pass the same arguments\nto ``URIReference#is_valid``, e.g.,\n\n.. code-block:: python\n\n from rfc3986 import uri_reference\n\n http = uri_reference('http://localhost:8774/v2/resource')\n assert uri.is_valid(require_scheme=True,\n require_authority=True,\n require_path=True)\n\n # Assert that a mailto URI is invalid if you require an authority\n # component\n mailto = uri_reference('mailto:user@example.com')\n assert uri.is_valid(require_authority=True) is False\n\nAlternatives\n------------\n\n- `rfc3987 <https://pypi.python.org/pypi/rfc3987/1.3.4>`_\n\n This is a direct competitor to this library, with extra features,\n licensed under the GPL.\n\n- `uritools <https://pypi.python.org/pypi/uritools/0.5.1>`_\n\n This can parse URIs in the manner of RFC 3986 but provides no validation and\n only recently added Python 3 support.\n\n- Standard library's `urlparse`/`urllib.parse`\n\n The functions in these libraries can only split a URI (valid or not) and\n provide no validation.\n\nContributing\n------------\n\nThis project follows and enforces the Python Software Foundation's `Code of\nConduct <https://www.python.org/psf/codeofconduct/>`_.\n\nIf you would like to contribute but do not have a bug or feature in mind, feel\nfree to email Ian and find out how you can help.\n\nThe git repository for this project is maintained at\nhttps://github.com/python-hyper/rfc3986\n\n.. _RFC 3986: https://datatracker.ietf.org/doc/html/rfc3986/\n.. _Apache License Version 2.0: https://www.apache.org/licenses/LICENSE-2.0\n\n\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Validating URI References per RFC 3986",
"version": "2.0.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "5710e7a2eadc951d2a690a327747f3a2",
"sha256": "50b1502b60e289cb37883f3dfd34532b8873c7de9f49bb546641ce9cbd256ebd"
},
"downloads": -1,
"filename": "rfc3986-2.0.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "5710e7a2eadc951d2a690a327747f3a2",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.7",
"size": 31326,
"upload_time": "2022-01-10T00:52:29",
"upload_time_iso_8601": "2022-01-10T00:52:29.594625Z",
"url": "https://files.pythonhosted.org/packages/ff/9a/9afaade874b2fa6c752c36f1548f718b5b83af81ed9b76628329dab81c1b/rfc3986-2.0.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "bbf20302bf26bc771e88cc775fbde3bc",
"sha256": "97aacf9dbd4bfd829baad6e6309fa6573aaf1be3f6fa735c8ab05e46cecb261c"
},
"downloads": -1,
"filename": "rfc3986-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "bbf20302bf26bc771e88cc775fbde3bc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 49026,
"upload_time": "2022-01-10T00:52:30",
"upload_time_iso_8601": "2022-01-10T00:52:30.832978Z",
"url": "https://files.pythonhosted.org/packages/85/40/1520d68bfa07ab5a6f065a186815fb6610c86fe957bc065754e47f7b0840/rfc3986-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-01-10 00:52:30",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "rfc3986"
}
JSON