1Metadata-Version: 2.1 2Name: yarl 3Version: 1.6.3 4Summary: Yet another URL library 5Home-page: https://github.com/aio-libs/yarl/ 6Author: Andrew Svetlov 7Author-email: andrew.svetlov@gmail.com 8License: Apache 2 9Description: yarl 10 ==== 11 12 .. image:: https://github.com/aio-libs/yarl/workflows/CI/badge.svg 13 :target: https://github.com/aio-libs/yarl/actions?query=workflow%3ACI 14 :align: right 15 16 .. image:: https://codecov.io/gh/aio-libs/yarl/branch/master/graph/badge.svg 17 :target: https://codecov.io/gh/aio-libs/yarl 18 19 .. image:: https://badge.fury.io/py/yarl.svg 20 :target: https://badge.fury.io/py/yarl 21 22 23 .. image:: https://readthedocs.org/projects/yarl/badge/?version=latest 24 :target: https://yarl.readthedocs.io 25 26 27 .. image:: https://img.shields.io/pypi/pyversions/yarl.svg 28 :target: https://pypi.python.org/pypi/yarl 29 30 .. image:: https://badges.gitter.im/Join%20Chat.svg 31 :target: https://gitter.im/aio-libs/Lobby 32 :alt: Chat on Gitter 33 34 Introduction 35 ------------ 36 37 Url is constructed from ``str``: 38 39 .. code-block:: pycon 40 41 >>> from yarl import URL 42 >>> url = URL('https://www.python.org/~guido?arg=1#frag') 43 >>> url 44 URL('https://www.python.org/~guido?arg=1#frag') 45 46 All url parts: *scheme*, *user*, *password*, *host*, *port*, *path*, 47 *query* and *fragment* are accessible by properties: 48 49 .. code-block:: pycon 50 51 >>> url.scheme 52 'https' 53 >>> url.host 54 'www.python.org' 55 >>> url.path 56 '/~guido' 57 >>> url.query_string 58 'arg=1' 59 >>> url.query 60 <MultiDictProxy('arg': '1')> 61 >>> url.fragment 62 'frag' 63 64 All url manipulations produce a new url object: 65 66 .. code-block:: pycon 67 68 >>> url = URL('https://www.python.org') 69 >>> url / 'foo' / 'bar' 70 URL('https://www.python.org/foo/bar') 71 >>> url / 'foo' % {'bar': 'baz'} 72 URL('https://www.python.org/foo?bar=baz') 73 74 Strings passed to constructor and modification methods are 75 automatically encoded giving canonical representation as result: 76 77 .. code-block:: pycon 78 79 >>> url = URL('https://www.python.org/путь') 80 >>> url 81 URL('https://www.python.org/%D0%BF%D1%83%D1%82%D1%8C') 82 83 Regular properties are *percent-decoded*, use ``raw_`` versions for 84 getting *encoded* strings: 85 86 .. code-block:: pycon 87 88 >>> url.path 89 '/путь' 90 91 >>> url.raw_path 92 '/%D0%BF%D1%83%D1%82%D1%8C' 93 94 Human readable representation of URL is available as ``.human_repr()``: 95 96 .. code-block:: pycon 97 98 >>> url.human_repr() 99 'https://www.python.org/путь' 100 101 For full documentation please read https://yarl.readthedocs.org. 102 103 104 Installation 105 ------------ 106 107 :: 108 109 $ pip install yarl 110 111 The library is Python 3 only! 112 113 PyPI contains binary wheels for Linux, Windows and MacOS. If you want to install 114 ``yarl`` on another operating system (like *Alpine Linux*, which is not 115 manylinux-compliant because of the missing glibc and therefore, cannot be 116 used with our wheels) the the tarball will be used to compile the library from 117 the source code. It requires a C compiler and and Python headers installed. 118 119 To skip the compilation you must explicitly opt-in by setting the `YARL_NO_EXTENSIONS` 120 environment variable to a non-empty value, e.g.: 121 122 .. code-block:: bash 123 124 $ YARL_NO_EXTENSIONS=1 pip install yarl 125 126 Please note that the pure-Python (uncompiled) version is much slower. However, 127 PyPy always uses a pure-Python implementation, and, as such, it is unaffected 128 by this variable. 129 130 Dependencies 131 ------------ 132 133 YARL requires multidict_ library. 134 135 136 API documentation 137 ------------------ 138 139 The documentation is located at https://yarl.readthedocs.org 140 141 142 Why isn't boolean supported by the URL query API? 143 ------------------------------------------------- 144 145 There is no standard for boolean representation of boolean values. 146 147 Some systems prefer ``true``/``false``, others like ``yes``/``no``, ``on``/``off``, 148 ``Y``/``N``, ``1``/``0``, etc. 149 150 ``yarl`` cannot make an unambiguous decision on how to serialize ``bool`` values because 151 it is specific to how the end-user's application is built and would be different for 152 different apps. The library doesn't accept booleans in the API; a user should convert 153 bools into strings using own preferred translation protocol. 154 155 156 Comparison with other URL libraries 157 ------------------------------------ 158 159 * furl (https://pypi.python.org/pypi/furl) 160 161 The library has rich functionality but the ``furl`` object is mutable. 162 163 I'm afraid to pass this object into foreign code: who knows if the 164 code will modify my url in a terrible way while I just want to send URL 165 with handy helpers for accessing URL properties. 166 167 ``furl`` has other non-obvious tricky things but the main objection 168 is mutability. 169 170 * URLObject (https://pypi.python.org/pypi/URLObject) 171 172 URLObject is immutable, that's pretty good. 173 174 Every URL change generates a new URL object. 175 176 But the library doesn't do any decode/encode transformations leaving the 177 end user to cope with these gory details. 178 179 180 Source code 181 ----------- 182 183 The project is hosted on GitHub_ 184 185 Please file an issue on the `bug tracker 186 <https://github.com/aio-libs/yarl/issues>`_ if you have found a bug 187 or have some suggestion in order to improve the library. 188 189 The library uses `Azure Pipelines <https://dev.azure.com/aio-libs/yarl>`_ for 190 Continuous Integration. 191 192 Discussion list 193 --------------- 194 195 *aio-libs* google group: https://groups.google.com/forum/#!forum/aio-libs 196 197 Feel free to post your questions and ideas here. 198 199 200 Authors and License 201 ------------------- 202 203 The ``yarl`` package is written by Andrew Svetlov. 204 205 It's *Apache 2* licensed and freely available. 206 207 208 .. _GitHub: https://github.com/aio-libs/yarl 209 210 .. _multidict: https://github.com/aio-libs/multidict 211 212 213 ========= 214 Changelog 215 ========= 216 217 .. 218 You should *NOT* be adding new change log entries to this file, this 219 file is managed by towncrier. You *may* edit previous change logs to 220 fix problems like typo corrections or such. 221 To add a new change log entry, please see 222 https://pip.pypa.io/en/latest/development/#adding-a-news-entry 223 we named the news folder "changes". 224 225 WARNING: Don't drop the next directive! 226 227 .. towncrier release notes start 228 229 1.6.3 (2020-11-14) 230 ================== 231 232 Bugfixes 233 -------- 234 235 - No longer loose characters when decoding incorrect percent-sequences (like ``%e2%82%f8``). All non-decodable percent-sequences are now preserved. 236 `#517 <https://github.com/aio-libs/yarl/issues/517>`_ 237 - Provide x86 Windows wheels. 238 `#535 <https://github.com/aio-libs/yarl/issues/535>`_ 239 240 241 ---- 242 243 244 1.6.2 (2020-10-12) 245 ================== 246 247 248 Bugfixes 249 -------- 250 251 - Provide generated ``.c`` files in TarBall distribution. 252 `#530 <https://github.com/aio-libs/multidict/issues/530>`_ 253 254 1.6.1 (2020-10-12) 255 ================== 256 257 Features 258 -------- 259 260 - Provide wheels for ``aarch64``, ``i686``, ``ppc64le``, ``s390x`` architectures on 261 Linux as well as ``x86_64``. 262 `#507 <https://github.com/aio-libs/yarl/issues/507>`_ 263 - Provide wheels for Python 3.9. 264 `#526 <https://github.com/aio-libs/yarl/issues/526>`_ 265 266 Bugfixes 267 -------- 268 269 - ``human_repr()`` now always produces valid representation equivalent to the original URL (if the original URL is valid). 270 `#511 <https://github.com/aio-libs/yarl/issues/511>`_ 271 - Fixed requoting a single percent followed by a percent-encoded character in the Cython implementation. 272 `#514 <https://github.com/aio-libs/yarl/issues/514>`_ 273 - Fix ValueError when decoding ``%`` which is not followed by two hexadecimal digits. 274 `#516 <https://github.com/aio-libs/yarl/issues/516>`_ 275 - Fix decoding ``%`` followed by a space and hexadecimal digit. 276 `#520 <https://github.com/aio-libs/yarl/issues/520>`_ 277 - Fix annotation of ``with_query()``/``update_query()`` methods for ``key=[val1, val2]`` case. 278 `#528 <https://github.com/aio-libs/yarl/issues/528>`_ 279 280 Removal 281 ------- 282 283 - Drop Python 3.5 support; Python 3.6 is the minimal supported Python version. 284 285 286 ---- 287 288 289 1.6.0 (2020-09-23) 290 ================== 291 292 Features 293 -------- 294 295 - Allow for int and float subclasses in query, while still denying bool. 296 `#492 <https://github.com/aio-libs/yarl/issues/492>`_ 297 298 299 Bugfixes 300 -------- 301 302 - Do not requote arguments in ``URL.build()``, ``with_xxx()`` and in ``/`` operator. 303 `#502 <https://github.com/aio-libs/yarl/issues/502>`_ 304 - Keep IPv6 brackets in ``origin()``. 305 `#504 <https://github.com/aio-libs/yarl/issues/504>`_ 306 307 308 ---- 309 310 311 1.5.1 (2020-08-01) 312 ================== 313 314 Bugfixes 315 -------- 316 317 - Fix including relocated internal ``yarl._quoting_c`` C-extension into published PyPI dists. 318 `#485 <https://github.com/aio-libs/yarl/issues/485>`_ 319 320 321 Misc 322 ---- 323 324 - `#484 <https://github.com/aio-libs/yarl/issues/484>`_ 325 326 327 ---- 328 329 330 1.5.0 (2020-07-26) 331 ================== 332 333 Features 334 -------- 335 336 - Convert host to lowercase on URL building. 337 `#386 <https://github.com/aio-libs/yarl/issues/386>`_ 338 - Allow using ``mod`` operator (`%`) for updating query string (an alias for ``update_query()`` method). 339 `#435 <https://github.com/aio-libs/yarl/issues/435>`_ 340 - Allow use of sequences such as ``list`` and ``tuple`` in the values 341 of a mapping such as ``dict`` to represent that a key has many values:: 342 343 url = URL("http://example.com") 344 assert url.with_query({"a": [1, 2]}) == URL("http://example.com/?a=1&a=2") 345 346 `#443 <https://github.com/aio-libs/yarl/issues/443>`_ 347 - Support URL.build() with scheme and path (creates a relative URL). 348 `#464 <https://github.com/aio-libs/yarl/issues/464>`_ 349 - Cache slow IDNA encode/decode calls. 350 `#476 <https://github.com/aio-libs/yarl/issues/476>`_ 351 - Add ``@final`` / ``Final`` type hints 352 `#477 <https://github.com/aio-libs/yarl/issues/477>`_ 353 - Support URL authority/raw_authority properties and authority argument of ``URL.build()`` method. 354 `#478 <https://github.com/aio-libs/yarl/issues/478>`_ 355 - Hide the library implementation details, make the exposed public list very clean. 356 `#483 <https://github.com/aio-libs/yarl/issues/483>`_ 357 358 359 Bugfixes 360 -------- 361 362 - Fix tests with newer Python (3.7.6, 3.8.1 and 3.9.0+). 363 `#409 <https://github.com/aio-libs/yarl/issues/409>`_ 364 - Fix a bug where query component, passed in a form of mapping or sequence, is unquoted in unexpected way. 365 `#426 <https://github.com/aio-libs/yarl/issues/426>`_ 366 - Hide `Query` and `QueryVariable` type aliases in `__init__.pyi`, now they are prefixed with underscore. 367 `#431 <https://github.com/aio-libs/yarl/issues/431>`_ 368 - Keep ipv6 brackets after updating port/user/password. 369 `#451 <https://github.com/aio-libs/yarl/issues/451>`_ 370 371 372 ---- 373 374 375 1.4.2 (2019-12-05) 376 ================== 377 378 Features 379 -------- 380 381 - Workaround for missing `str.isascii()` in Python 3.6 382 `#389 <https://github.com/aio-libs/yarl/issues/389>`_ 383 384 385 ---- 386 387 388 1.4.1 (2019-11-29) 389 ================== 390 391 * Fix regression, make the library work on Python 3.5 and 3.6 again. 392 393 1.4.0 (2019-11-29) 394 ================== 395 396 * Distinguish an empty password in URL from a password not provided at all (#262) 397 398 * Fixed annotations for optional parameters of ``URL.build`` (#309) 399 400 * Use None as default value of ``user`` parameter of ``URL.build`` (#309) 401 402 * Enforce building C Accelerated modules when installing from source tarball, use 403 ``YARL_NO_EXTENSIONS`` environment variable for falling back to (slower) Pure Python 404 implementation (#329) 405 406 * Drop Python 3.5 support 407 408 * Fix quoting of plus in path by pure python version (#339) 409 410 * Don't create a new URL if fragment is unchanged (#292) 411 412 * Included in error msg the path that produces starting slash forbidden error (#376) 413 414 * Skip slow IDNA encoding for ASCII-only strings (#387) 415 416 417 1.3.0 (2018-12-11) 418 ================== 419 420 * Fix annotations for ``query`` parameter (#207) 421 422 * An incoming query sequence can have int variables (the same as for 423 Mapping type) (#208) 424 425 * Add ``URL.explicit_port`` property (#218) 426 427 * Give a friendlier error when port cant be converted to int (#168) 428 429 * ``bool(URL())`` now returns ``False`` (#272) 430 431 1.2.6 (2018-06-14) 432 ================== 433 434 * Drop Python 3.4 trove classifier (#205) 435 436 1.2.5 (2018-05-23) 437 ================== 438 439 * Fix annotations for ``build`` (#199) 440 441 1.2.4 (2018-05-08) 442 ================== 443 444 * Fix annotations for ``cached_property`` (#195) 445 446 1.2.3 (2018-05-03) 447 ================== 448 449 * Accept ``str`` subclasses in ``URL`` constructor (#190) 450 451 1.2.2 (2018-05-01) 452 ================== 453 454 * Fix build 455 456 1.2.1 (2018-04-30) 457 ================== 458 459 * Pin minimal required Python to 3.5.3 (#189) 460 461 1.2.0 (2018-04-30) 462 ================== 463 464 * Forbid inheritance, replace ``__init__`` with ``__new__`` (#171) 465 466 * Support PEP-561 (provide type hinting marker) (#182) 467 468 1.1.1 (2018-02-17) 469 ================== 470 471 * Fix performance regression: don't encode enmpty netloc (#170) 472 473 1.1.0 (2018-01-21) 474 ================== 475 476 * Make pure Python quoter consistent with Cython version (#162) 477 478 1.0.0 (2018-01-15) 479 ================== 480 481 * Use fast path if quoted string does not need requoting (#154) 482 483 * Speed up quoting/unquoting by ``_Quoter`` and ``_Unquoter`` classes (#155) 484 485 * Drop ``yarl.quote`` and ``yarl.unquote`` public functions (#155) 486 487 * Add custom string writer, reuse static buffer if available (#157) 488 Code is 50-80 times faster than Pure Python version (was 4-5 times faster) 489 490 * Don't recode IP zone (#144) 491 492 * Support ``encoded=True`` in ``yarl.URL.build()`` (#158) 493 494 * Fix updating query with multiple keys (#160) 495 496 0.18.0 (2018-01-10) 497 =================== 498 499 * Fallback to IDNA 2003 if domain name is not IDNA 2008 compatible (#152) 500 501 0.17.0 (2017-12-30) 502 =================== 503 504 * Use IDNA 2008 for domain name processing (#149) 505 506 0.16.0 (2017-12-07) 507 =================== 508 509 * Fix raising ``TypeError`` by ``url.query_string()`` after 510 ``url.with_query({})`` (empty mapping) (#141) 511 512 0.15.0 (2017-11-23) 513 =================== 514 515 * Add ``raw_path_qs`` attribute (#137) 516 517 0.14.2 (2017-11-14) 518 =================== 519 520 * Restore ``strict`` parameter as no-op in ``quote`` / ``unquote`` 521 522 0.14.1 (2017-11-13) 523 =================== 524 525 * Restore ``strict`` parameter as no-op for sake of compatibility with 526 aiohttp 2.2 527 528 0.14.0 (2017-11-11) 529 =================== 530 531 * Drop strict mode (#123) 532 533 * Fix ``"ValueError: Unallowed PCT %"`` when there's a ``"%"`` in the url (#124) 534 535 0.13.0 (2017-10-01) 536 =================== 537 538 * Document ``encoded`` parameter (#102) 539 540 * Support relative urls like ``'?key=value'`` (#100) 541 542 * Unsafe encoding for QS fixed. Encode ``;`` char in value param (#104) 543 544 * Process passwords without user names (#95) 545 546 0.12.0 (2017-06-26) 547 =================== 548 549 * Properly support paths without leading slash in ``URL.with_path()`` (#90) 550 551 * Enable type annotation checks 552 553 0.11.0 (2017-06-26) 554 =================== 555 556 * Normalize path (#86) 557 558 * Clear query and fragment parts in ``.with_path()`` (#85) 559 560 0.10.3 (2017-06-13) 561 =================== 562 563 * Prevent double URL args unquoting (#83) 564 565 0.10.2 (2017-05-05) 566 =================== 567 568 * Unexpected hash behaviour (#75) 569 570 571 0.10.1 (2017-05-03) 572 =================== 573 574 * Unexpected compare behaviour (#73) 575 576 * Do not quote or unquote + if not a query string. (#74) 577 578 579 0.10.0 (2017-03-14) 580 =================== 581 582 * Added ``URL.build`` class method (#58) 583 584 * Added ``path_qs`` attribute (#42) 585 586 587 0.9.8 (2017-02-16) 588 ================== 589 590 * Do not quote ``:`` in path 591 592 593 0.9.7 (2017-02-16) 594 ================== 595 596 * Load from pickle without _cache (#56) 597 598 * Percent-encoded pluses in path variables become spaces (#59) 599 600 601 0.9.6 (2017-02-15) 602 ================== 603 604 * Revert backward incompatible change (BaseURL) 605 606 607 0.9.5 (2017-02-14) 608 ================== 609 610 * Fix BaseURL rich comparison support 611 612 613 0.9.4 (2017-02-14) 614 ================== 615 616 * Use BaseURL 617 618 619 0.9.3 (2017-02-14) 620 ================== 621 622 * Added BaseURL 623 624 625 0.9.2 (2017-02-08) 626 ================== 627 628 * Remove debug print 629 630 631 0.9.1 (2017-02-07) 632 ================== 633 634 * Do not lose tail chars (#45) 635 636 637 0.9.0 (2017-02-07) 638 ================== 639 640 * Allow to quote ``%`` in non strict mode (#21) 641 642 * Incorrect parsing of query parameters with %3B (;) inside (#34) 643 644 * Fix core dumps (#41) 645 646 * tmpbuf - compiling error (#43) 647 648 * Added ``URL.update_path()`` method 649 650 * Added ``URL.update_query()`` method (#47) 651 652 653 0.8.1 (2016-12-03) 654 ================== 655 656 * Fix broken aiohttp: revert back ``quote`` / ``unquote``. 657 658 659 0.8.0 (2016-12-03) 660 ================== 661 662 * Support more verbose error messages in ``.with_query()`` (#24) 663 664 * Don't percent-encode ``@`` and ``:`` in path (#32) 665 666 * Don't expose ``yarl.quote`` and ``yarl.unquote``, these functions are 667 part of private API 668 669 0.7.1 (2016-11-18) 670 ================== 671 672 * Accept not only ``str`` but all classes inherited from ``str`` also (#25) 673 674 0.7.0 (2016-11-07) 675 ================== 676 677 * Accept ``int`` as value for ``.with_query()`` 678 679 0.6.0 (2016-11-07) 680 ================== 681 682 * Explicitly use UTF8 encoding in setup.py (#20) 683 * Properly unquote non-UTF8 strings (#19) 684 685 0.5.3 (2016-11-02) 686 ================== 687 688 * Don't use namedtuple fields but indexes on URL construction 689 690 0.5.2 (2016-11-02) 691 ================== 692 693 * Inline ``_encode`` class method 694 695 0.5.1 (2016-11-02) 696 ================== 697 698 * Make URL construction faster by removing extra classmethod calls 699 700 0.5.0 (2016-11-02) 701 ================== 702 703 * Add cython optimization for quoting/unquoting 704 * Provide binary wheels 705 706 0.4.3 (2016-09-29) 707 ================== 708 709 * Fix typing stubs 710 711 0.4.2 (2016-09-29) 712 ================== 713 714 * Expose ``quote()`` and ``unquote()`` as public API 715 716 0.4.1 (2016-09-28) 717 ================== 718 719 * Support empty values in query (``'/path?arg'``) 720 721 0.4.0 (2016-09-27) 722 ================== 723 724 * Introduce ``relative()`` (#16) 725 726 0.3.2 (2016-09-27) 727 ================== 728 729 * Typo fixes #15 730 731 0.3.1 (2016-09-26) 732 ================== 733 734 * Support sequence of pairs as ``with_query()`` parameter 735 736 0.3.0 (2016-09-26) 737 ================== 738 739 * Introduce ``is_default_port()`` 740 741 0.2.1 (2016-09-26) 742 ================== 743 744 * Raise ValueError for URLs like 'http://:8080/' 745 746 0.2.0 (2016-09-18) 747 ================== 748 749 * Avoid doubling slashes when joining paths (#13) 750 751 * Appending path starting from slash is forbidden (#12) 752 753 0.1.4 (2016-09-09) 754 ================== 755 756 * Add kwargs support for ``with_query()`` (#10) 757 758 0.1.3 (2016-09-07) 759 ================== 760 761 * Document ``with_query()``, ``with_fragment()`` and ``origin()`` 762 763 * Allow ``None`` for ``with_query()`` and ``with_fragment()`` 764 765 0.1.2 (2016-09-07) 766 ================== 767 768 * Fix links, tune docs theme. 769 770 0.1.1 (2016-09-06) 771 ================== 772 773 * Update README, old version used obsolete API 774 775 0.1.0 (2016-09-06) 776 ================== 777 778 * The library was deeply refactored, bytes are gone away but all 779 accepted strings are encoded if needed. 780 781 0.0.1 (2016-08-30) 782 ================== 783 784 * The first release. 785 786Platform: UNKNOWN 787Classifier: License :: OSI Approved :: Apache Software License 788Classifier: Intended Audience :: Developers 789Classifier: Programming Language :: Python 790Classifier: Programming Language :: Python :: 3 791Classifier: Programming Language :: Python :: 3.6 792Classifier: Programming Language :: Python :: 3.7 793Classifier: Programming Language :: Python :: 3.8 794Classifier: Programming Language :: Python :: 3.9 795Classifier: Topic :: Internet :: WWW/HTTP 796Requires-Python: >=3.6 797Description-Content-Type: text/x-rst 798