urllib.parse.rst - Issue 2827: [issue3300] urllib.quote and unquote Code Review (original) (raw)

OLD

NEW

1 :mod:`urllib.parse` --- Parse URLs into components

2 ==================================================

4 .. module:: urllib.parse

5 :synopsis: Parse URLs into or assemble them from components.

8 .. index::

9 single: WWW

10 single: World Wide Web

(...skipping 164 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading...

175 :func:`urlunsplit`, removing possible *scheme* and *netloc* parts.

176

177

178 .. function:: urldefrag(url)

179

180 If *url* contains a fragment identifier, return a modified version of *url*

181 with no fragment identifier, and the fragment identifier as a separate

182 string. If there is no fragment identifier in *url*, return *url* unmodified

183 and an empty string.

184

185 .. function:: quote(string[, safe])

185 .. function:: quote(string[, safe[, encoding[, errors]]])

186

187 Replace special characters in *string* using the ``%xx`` escape. Letters,

188 digits, and the characters ``'_.-'`` are never quoted. The optional *safe*

189 parameter specifies additional characters that should not be quoted --- its

190 default value is ``'/'``.

191

192 Example: ``quote('/~connolly/')`` yields ``'/%7econnolly/'``.

192 *string* may be either a :class:`str` or a :class:`bytes`.

193

194 The optional *encoding* and *errors* parameters specify how to deal with

195 non-ASCII characters, as accepted by the :meth:`str.encode` method.

196 *encoding* defaults to ``'utf-8'``.

197 *errors* defaults to ``'replace'``, meaning unsupported characters are

198 replaced by a placeholder character.

199 *encoding* and *errors* are ignored if *string* is a :class:`bytes`.

200

201 Example: ``quote('/El Niño/')`` yields ``'/El%20Ni%C3%B1o/'``.

193

202

194

203

195 .. function:: quote_plus(string[, safe])

204 .. function:: quote_plus(string[, safe[, encoding[, errors]]])

196

205

197 Like :func:`quote`, but also replace spaces by plus signs, as required for

206 Like :func:`quote`, but also replace spaces by plus signs, as required for

198 quoting HTML form values. Plus signs in the original string are escaped

207 quoting HTML form values. Plus signs in the original string are escaped

199 unless they are included in *safe*. It also does not have *safe* default to

208 unless they are included in *safe*. It also does not have *safe* default to

200 ``'/'``.

209 ``'/'``.

201

210

211 Example: ``quote_plus('/El Niño/')`` yields ``'%2FEl+Ni%C3%B1o%2F'``.

202

212

203 .. function:: unquote(string)

213 .. function:: quote_from_bytes(bytes[, safe])

214

215 An alias for :func:`quote`, intended for use with a :class:`bytes` object

216 rather than a :class:`str`.

217

218 Example: ``quote_from_bytes(b'/El Ni\xc3\xb1o/')`` yields

219 ``'/El%20Ni%C3%B1o/'``.

220

221 .. function:: unquote(string[, encoding[, errors]])

204

222

205 Replace ``%xx`` escapes by their single-character equivalent.

223 Replace ``%xx`` escapes by their single-character equivalent.

224 The optional *encoding* and *errors* parameters specify how to decode

225 percent-encoded sequences into Unicode characters, as accepted by the

226 :meth:`bytes.decode` method.

206

227

207 Example: ``unquote('/%7Econnolly/')`` yields ``'/~connolly/'``.

228 *encoding* defaults to ``'utf-8'``.

229 *errors* defaults to ``'replace'``, meaning invalid sequences are

230 replaced by a placeholder character.

231

232 Example: ``unquote('/El%20Ni%C3%B1o/')`` yields ``'/El Niño/'``.

208

233

209

234

210 .. function:: unquote_plus(string)

235 .. function:: unquote_plus(string[, encoding[, errors]])

211

236

212 Like :func:`unquote`, but also replace plus signs by spaces, as required for

237 Like :func:`unquote`, but also replace plus signs by spaces, as required for

213 unquoting HTML form values.

238 unquoting HTML form values.

214

239

240 Example: ``unquote_plus('/El+Ni%C3%B1o/')`` yields ``'/El Niño/'``.

241

242 .. function:: unquote_to_bytes(string)

243

244 Replace ``%xx`` escapes by their single-octet equivalent, and return a

245 :class:`bytes` object.

246

247 Unescaped non-ASCII characters in the input string are encoded into UTF-8

248 bytes.

249

250 Example: ``unquote_to_bytes('/El%20Ni%C3%B1o/')`` yields

251 ``b'/El Ni\xc3\xb1o/'``.

252

215

253

216 .. function:: urlencode(query[, doseq])

254 .. function:: urlencode(query[, doseq])

217

255

218 Convert a mapping object or a sequence of two-element tuples to a "url-encod ed"

256 Convert a mapping object or a sequence of two-element tuples to a "url-encod ed"

219 string, suitable to pass to :func:`urlopen` above as the optional *data*

257 string, suitable to pass to :func:`urlopen` above as the optional *data*

220 argument. This is useful to pass a dictionary of form fields to a ``POST``

258 argument. This is useful to pass a dictionary of form fields to a ``POST``

221 request. The resulting string is a series of ``key=value`` pairs separated b y

259 request. The resulting string is a series of ``key=value`` pairs separated b y

222 ``'&'`` characters, where both *key* and *value* are quoted using

260 ``'&'`` characters, where both *key* and *value* are quoted using

223 :func:`quote_plus` above. If the optional parameter *doseq* is present and

261 :func:`quote_plus` above. If the optional parameter *doseq* is present and

224 evaluates to true, individual ``key=value`` pairs are generated for each elem ent

262 evaluates to true, individual ``key=value`` pairs are generated for each elem ent

(...skipping 65 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading...

290

328

291 Concrete class for :func:`urlparse` results. The :meth:`__new__` method is

329 Concrete class for :func:`urlparse` results. The :meth:`__new__` method is

292 overridden to support checking that the right number of arguments are passed.

330 overridden to support checking that the right number of arguments are passed.

293

331

294

332

295 .. class:: SplitResult(scheme, netloc, path, query, fragment)

333 .. class:: SplitResult(scheme, netloc, path, query, fragment)

296

334

297 Concrete class for :func:`urlsplit` results. The :meth:`__new__` method is

335 Concrete class for :func:`urlsplit` results. The :meth:`__new__` method is

298 overridden to support checking that the right number of arguments are passed.

336 overridden to support checking that the right number of arguments are passed.

299

337

OLD

NEW