source: uri/PKG-INFO@ 230

Last change on this file since 230 was 230, checked in by wouter, 3 years ago

#91 clone ​https://pypi.org/project/rfc3986/
File size: 7.9 KB
Line 
1Metadata-Version: 2.1
2Name: rfc3986
3Version: 1.5.0
4Summary: Validating URI References per RFC 3986
5Home-page: http://rfc3986.readthedocs.io
6Author: Ian Stapleton Cordasco
7Author-email: graffatcolmingov@gmail.com
8License: Apache 2.0
9Description: rfc3986
10 =======
11
12 A Python implementation of `RFC 3986`_ including validation and authority
13 parsing.
14
15 Installation
16 ------------
17
18 Use pip to install ``rfc3986`` like so::
19
20 pip install rfc3986
21
22 License
23 -------
24
25 `Apache License Version 2.0`_
26
27 Example Usage
28 -------------
29
30 The following are the two most common use cases envisioned for ``rfc3986``.
31
32 Replacing ``urlparse``
33 ``````````````````````
34
35 To parse a URI and receive something very similar to the standard library's
36 ``urllib.parse.urlparse``
37
38 .. code-block:: python
39
40 from rfc3986 import urlparse
41
42 ssh = urlparse('ssh://user@git.openstack.org:29418/openstack/glance.git')
43 print(ssh.scheme) # => ssh
44 print(ssh.userinfo) # => user
45 print(ssh.params) # => None
46 print(ssh.port) # => 29418
47
48 To create a copy of it with new pieces you can use ``copy_with``:
49
50 .. code-block:: python
51
52 new_ssh = ssh.copy_with(
53 scheme='https'
54 userinfo='',
55 port=443,
56 path='/openstack/glance'
57 )
58 print(new_ssh.scheme) # => https
59 print(new_ssh.userinfo) # => None
60 # etc.
61
62 Strictly Parsing a URI and Applying Validation
63 ``````````````````````````````````````````````
64
65 To parse a URI into a convenient named tuple, you can simply:
66
67 .. code-block:: python
68
69 from rfc3986 import uri_reference
70
71 example = uri_reference('http://example.com')
72 email = uri_reference('mailto:user@domain.com')
73 ssh = uri_reference('ssh://user@git.openstack.org:29418/openstack/keystone.git')
74
75 With a parsed URI you can access data about the components:
76
77 .. code-block:: python
78
79 print(example.scheme) # => http
80 print(email.path) # => user@domain.com
81 print(ssh.userinfo) # => user
82 print(ssh.host) # => git.openstack.org
83 print(ssh.port) # => 29418
84
85 It can also parse URIs with unicode present:
86
87 .. code-block:: python
88
89 uni = uri_reference(b'http://httpbin.org/get?utf8=\xe2\x98\x83') # ☃
90 print(uni.query) # utf8=%E2%98%83
91
92 With a parsed URI you can also validate it:
93
94 .. code-block:: python
95
96 if ssh.is_valid():
97 subprocess.call(['git', 'clone', ssh.unsplit()])
98
99 You can also take a parsed URI and normalize it:
100
101 .. code-block:: python
102
103 mangled = uri_reference('hTTp://exAMPLe.COM')
104 print(mangled.scheme) # => hTTp
105 print(mangled.authority) # => exAMPLe.COM
106
107 normal = mangled.normalize()
108 print(normal.scheme) # => http
109 print(mangled.authority) # => example.com
110
111 But these two URIs are (functionally) equivalent:
112
113 .. code-block:: python
114
115 if normal == mangled:
116 webbrowser.open(normal.unsplit())
117
118 Your paths, queries, and fragments are safe with us though:
119
120 .. code-block:: python
121
122 mangled = uri_reference('hTTp://exAMPLe.COM/Some/reallY/biZZare/pAth')
123 normal = mangled.normalize()
124 assert normal == 'hTTp://exAMPLe.COM/Some/reallY/biZZare/pAth'
125 assert normal == 'http://example.com/Some/reallY/biZZare/pAth'
126 assert normal != 'http://example.com/some/really/bizzare/path'
127
128 If you do not actually need a real reference object and just want to normalize
129 your URI:
130
131 .. code-block:: python
132
133 from rfc3986 import normalize_uri
134
135 assert (normalize_uri('hTTp://exAMPLe.COM/Some/reallY/biZZare/pAth') ==
136 'http://example.com/Some/reallY/biZZare/pAth')
137
138 You can also very simply validate a URI:
139
140 .. code-block:: python
141
142 from rfc3986 import is_valid_uri
143
144 assert is_valid_uri('hTTp://exAMPLe.COM/Some/reallY/biZZare/pAth')
145
146 Requiring Components
147 ~~~~~~~~~~~~~~~~~~~~
148
149 You can validate that a particular string is a valid URI and require
150 independent components:
151
152 .. code-block:: python
153
154 from rfc3986 import is_valid_uri
155
156 assert is_valid_uri('http://localhost:8774/v2/resource',
157 require_scheme=True,
158 require_authority=True,
159 require_path=True)
160
161 # Assert that a mailto URI is invalid if you require an authority
162 # component
163 assert is_valid_uri('mailto:user@example.com', require_authority=True) is False
164
165 If you have an instance of a ``URIReference``, you can pass the same arguments
166 to ``URIReference#is_valid``, e.g.,
167
168 .. code-block:: python
169
170 from rfc3986 import uri_reference
171
172 http = uri_reference('http://localhost:8774/v2/resource')
173 assert uri.is_valid(require_scheme=True,
174 require_authority=True,
175 require_path=True)
176
177 # Assert that a mailto URI is invalid if you require an authority
178 # component
179 mailto = uri_reference('mailto:user@example.com')
180 assert uri.is_valid(require_authority=True) is False
181
182 Alternatives
183 ------------
184
185 - `rfc3987 <https://pypi.python.org/pypi/rfc3987/1.3.4>`_
186
187 This is a direct competitor to this library, with extra features,
188 licensed under the GPL.
189
190 - `uritools <https://pypi.python.org/pypi/uritools/0.5.1>`_
191
192 This can parse URIs in the manner of RFC 3986 but provides no validation and
193 only recently added Python 3 support.
194
195 - Standard library's `urlparse`/`urllib.parse`
196
197 The functions in these libraries can only split a URI (valid or not) and
198 provide no validation.
199
200 Contributing
201 ------------
202
203 This project follows and enforces the Python Software Foundation's `Code of
204 Conduct <https://www.python.org/psf/codeofconduct/>`_.
205
206 If you would like to contribute but do not have a bug or feature in mind, feel
207 free to email Ian and find out how you can help.
208
209 The git repository for this project is maintained at
210 https://github.com/python-hyper/rfc3986
211
212 .. _RFC 3986: http://tools.ietf.org/html/rfc3986
213 .. _Apache License Version 2.0: https://www.apache.org/licenses/LICENSE-2.0
214
215Platform: UNKNOWN
216Classifier: Development Status :: 5 - Production/Stable
217Classifier: Intended Audience :: Developers
218Classifier: Natural Language :: English
219Classifier: License :: OSI Approved :: Apache Software License
220Classifier: Programming Language :: Python
221Classifier: Programming Language :: Python :: 2.7
222Classifier: Programming Language :: Python :: 3
223Classifier: Programming Language :: Python :: 3.4
224Classifier: Programming Language :: Python :: 3.5
225Classifier: Programming Language :: Python :: 3.6
226Classifier: Programming Language :: Python :: 3.7
227Provides-Extra: idna2008
Note: See TracBrowser for help on using the repository browser.