Release 1.7.0, includes Ada 2.7.2 (#43)

README.rst

@@ -1,8 +1,12 @@
 ada-url
 ========
 
+This is ``ada_url``, a Python library for working with URLs based on the ``Ada`` URL
+parser.
 
-This is ``ada_url``, a Python library for parsing and joining URLs.
+* `Documentation <https://ada-url.readthedocs.io>`__
+* `Development <https://github.com/ada-url/ada-python/>`__
+* `Ada <https://www.ada-url.com/>`__ 
 
 Installation
 ------------
@@ -16,30 +20,20 @@ Install from `PyPI <https://pypi.org/project/ada-url/>`__:
 Usage examples
 --------------
 
-This package exposes a ``URL`` class that is intended to match the one described in the
-`WHATWG URL spec <https://url.spec.whatwg.org/#url-class>`__.
+Parsing URLs
+^^^^^^^^^^^^
 
-.. code-block:: python
-
-    >>> from ada_url import URL
-    >>> URL('https://example.org/path/../file.txt') as urlobj:
-    >>> urlobj.host = 'example.com'
-    >>> new_url = urlobj.href
-    >>> new_url
-    'https://example.com/file.txt'
-
-It also provides high level functions for parsing and manipulating URLs. Validating
-a URL:
+The ``URL`` class is intended to match the one described in the
+`WHATWG URL spec <https://url.spec.whatwg.org/#url-class>`_:.
 
 .. code-block:: python
 
-    >>> from ada_url import check_url
-    >>> check_url('https://example.org')
-    True
-    >>> check_url('http://example:bougus')
-    False
+    >>> from ada_url import URL
+    >>> urlobj = URL('https://example.org/path/../file.txt')
+    >>> urlobj.href
+    'https://example.org/path/file.txt'
 
-Parsing a URL:
+The ``parse_url`` function returns a dictionary of all URL elements:
 
 .. code-block:: python
 
@@ -61,19 +55,59 @@ Parsing a URL:
         'scheme_type': <SchemeType.HTTPS: 2>
     }
 
-Replacing URL components:
+Altering URLs
+^^^^^^^^^^^^^
+
+Replacing URL components with the ``URL`` class:
 
 .. code-block:: python
 
+    >>> from ada_url import URL
+    >>> urlobj = URL('https://example.org/path/../file.txt')
+    >>> urlobj.host = 'example.com'
+    >>> urlobj.href
+    'https://example.com/path/file.txt'
+
+Replacing URL components with the ``replace_url`` function:
+
     >>> from ada_url import replace_url
-    >>> ada_url.replace_url('http://example.org:80', protocol='https:')
-    'https://example.org/'
+    >>> replace_url('https://example.org/path/../file.txt', host='example.com')
+    'https://example.com/file.txt'
 
-Joining a URL with a relative fragment:
+Search parameters
+^^^^^^^^^^^^^^^^^
 
-    >>> from ada_url import join_url
-    >>> join_url('https://example.org/dir/child.txt', '../parent.txt')
-    'https://example.org/parent.txt'
+The ``URLSearchParams`` class is intended to match the one described in the
+`WHATWG URL spec <https://url.spec.whatwg.org/#interface-urlsearchparams>`__.
+
+.. code-block:: python
+
+    >>> from ada_url import URLSearchParams
+    >>> obj = URLSearchParams('key1=value1&key2=value2')
+    >>> list(obj.items())
+    [('key1', 'value1'), ('key2', 'value2')]
+
+The ``parse_search_params`` function returns a dictionary of search keys mapped to
+value lists:
+
+.. code-block:: python
+
+    >>> from ada_url import parse_search_params
+    >>> parse_search_params('key1=value1&key2=value2')
+    {'key1': ['value1'], 'key2': ['value2']}
+
+Internationalized domain names
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``idna`` class can encode and decode IDNs:
+
+.. code-block:: python
+
+    >>> from ada_url import idna
+    >>> idna.encode('Bücher.example')
+    b'xn--bcher-kva.example'
+    >>> idna.decode(b'xn--bcher-kva.example')
+    'bücher.example'
 
 WHATWG URL compliance
 ---------------------
@@ -100,10 +134,3 @@ Contrast that with the Python standard library's ``urlib.parse`` module:
     'www.googlé.com'
     >>> parsed_url.path
     '/./path/../path2/'
-
-More information
-----------------
-
-* ``ada-url`` is based on the `Ada <https://www.ada-url.com/>`__ project.
-* A full API reference is available at `Read the Docs <https://ada-url.readthedocs.io>`__.
-* Source code is available at `GitHub <https://github.com/ada-url/ada-python>`__.

ada_url/ada.cpp

@@ -1,4 +1,4 @@
-/* auto-generated on 2023-10-18 21:05:28 -0400. Do not edit! */
+/* auto-generated on 2023-10-22 19:50:50 -0400. Do not edit! */
 /* begin file src/ada.cpp */
 #include "ada.h"
 /* begin file src/checkers.cpp */

ada_url/ada.h

@@ -1,4 +1,4 @@
-/* auto-generated on 2023-10-18 21:05:28 -0400. Do not edit! */
+/* auto-generated on 2023-10-22 19:50:50 -0400. Do not edit! */
 /* begin file include/ada.h */
 /**
  * @file ada.h
@@ -1505,8 +1505,8 @@ struct url_base {
    * @return On failure, it returns zero.
    * @see https://url.spec.whatwg.org/#host-parsing
    */
-  virtual ada_really_inline size_t
-  parse_port(std::string_view view, bool check_trailing_content) noexcept = 0;
+  virtual size_t parse_port(std::string_view view,
+                            bool check_trailing_content) noexcept = 0;
 
   virtual ada_really_inline size_t parse_port(std::string_view view) noexcept {
     return this->parse_port(view, false);
@@ -7088,14 +7088,14 @@ url_search_params_entries_iter::next() {
 #ifndef ADA_ADA_VERSION_H
 #define ADA_ADA_VERSION_H
 
-#define ADA_VERSION "2.7.1"
+#define ADA_VERSION "2.7.2"
 
 namespace ada {
 
 enum {
   ADA_VERSION_MAJOR = 2,
   ADA_VERSION_MINOR = 7,
-  ADA_VERSION_REVISION = 1,
+  ADA_VERSION_REVISION = 2,
 };
 
 }  // namespace ada

docs/index.rst

@@ -53,13 +53,22 @@ API Documentation
 .. autoclass:: URL(url, base=None)
 .. autoclass:: HostType()
 .. autoclass:: SchemeType()
+
+----
+
 .. autofunction:: check_url(s)
 .. autofunction:: join_url(base_url, s)
 .. autofunction:: normalize_url(s)
 .. autofunction:: parse_url(s, [attributes])
 .. autofunction:: replace_url(s, **kwargs)
+
+----
+
 .. autoclass:: URLSearchParams(params)
 .. autoclass:: parse_search_params(s)
-.. autoclass:: replace_search_params(s)
+.. autoclass:: replace_search_params(s, *args)
+
+----
+
 .. autoclass:: idna
 

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = ada-url
-version = 1.6.0
+version = 1.7.0
 description = 'URL parser and manipulator based on the WHAT WG URL standard'
 long_description = file: README.rst
 long_description_content_type = text/x-rst