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