Cutlery/calibre
1
0
Fork 0
mirror of https://github.com/kovidgoyal/calibre.git synced 2025-07-09 03:04:10 -04:00
Code Issues Packages Projects Releases Wiki Activity

Improvements to the documentation, and allow the "authority" in make_url_extended() to be empty.

Browse Source
This commit is contained in:
Charles Haley 2025-02-12 13:55:54 +00:00
parent 749b421066
commit 1b70314705
1 changed files with 7 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
src/calibre/utils/formatter_functions.py
View File

@ -3225,7 +3225,7 @@ r'''
to construct a query URL. It uses a ``path``, the web site and page you want to to construct a query URL. It uses a ``path``, the web site and page you want to
query, and ``query_name``, ``query_value`` pairs from which the query is built. query, and ``query_name``, ``query_value`` pairs from which the query is built.
In general, the ``query_value`` must be URL-encoded. With this function it is always In general, the ``query_value`` must be URL-encoded. With this function it is always
encoded and spaces are always replaced with ``'+'`` signs. encoded and spaces are always replaced with ``'+'`` signs.[/]
At least one ``query_name, query_value`` pair must be provided. At least one ``query_name, query_value`` pair must be provided.
@ -3283,6 +3283,7 @@ make_url_extended(scheme, authority, path, query_string)
[/] [/]
This function returns a URL constructed from the ``scheme``, ``authority``, ``path``, This function returns a URL constructed from the ``scheme``, ``authority``, ``path``,
and either the ``query_string`` or a query string constructed from the query argument pairs. and either the ``query_string`` or a query string constructed from the query argument pairs.
The ``authority`` can be empty, which is the case for ``calibre`` scheme URLs.
You must supply either a ``query_string`` or at least one ``query_name, query_value`` pair. You must supply either a ``query_string`` or at least one ``query_name, query_value`` pair.
If you supply ``query_string`` and it is empty then the resulting URL will not have a query string section. If you supply ``query_string`` and it is empty then the resulting URL will not have a query string section.
@ -3307,7 +3308,7 @@ make_url_extended('https', 'en.wikipedia.org', '/w/index.php', 'search', $item_n
See also the functions :ref:`make_url`, :ref:`query_string` and :ref:`encode_for_url`. See also the functions :ref:`make_url`, :ref:`query_string` and :ref:`encode_for_url`.
''') ''')
def evaluate(self, formatter, kwargs, mi, locals, scheme, host, path, *args): def evaluate(self, formatter, kwargs, mi, locals, scheme, authority, path, *args):
if len(args) != 1: if len(args) != 1:
if (len(args) % 2) != 0: if (len(args) % 2) != 0:
raise ValueError(_('{} requires an odd number of arguments').format('make_url_extended')) raise ValueError(_('{} requires an odd number of arguments').format('make_url_extended'))
@ -3321,7 +3322,8 @@ See also the functions :ref:`make_url`, :ref:`query_string` and :ref:`encode_for
qs = args[0] qs = args[0]
if qs: if qs:
qs = '?' + qs qs = '?' + qs
return f"{scheme}://{host}/{path[1:] if path.startswith('/') else path}{qs}" return (f"{scheme}://{authority}{'/' if authority else ''}"
f"{path[1:] if path.startswith('/') else path}{qs}")
class BuiltinQueryString(BuiltinFormatterFunction): class BuiltinQueryString(BuiltinFormatterFunction):
@ -3334,7 +3336,7 @@ r'''
constructed from the ``query_name, query_value, how_to_encode`` triads. constructed from the ``query_name, query_value, how_to_encode`` triads.
A query string is a series of items where each item looks like ``query_name=query_value`` A query string is a series of items where each item looks like ``query_name=query_value``
where ``query_value`` is URL-encoded as instructed. The query items are separated by where ``query_value`` is URL-encoded as instructed. The query items are separated by
``'&'`` (ampersand) characters. ``'&'`` (ampersand) characters.[/]
If ``how_to_encode`` is ``0`` then ``query_value`` is encoded and spaces are replaced If ``how_to_encode`` is ``0`` then ``query_value`` is encoded and spaces are replaced
with ``'+'`` (plus) signs. If ``how_to_encode`` is ``1`` then ``query_value`` is with ``'+'`` (plus) signs. If ``how_to_encode`` is ``1`` then ``query_value`` is
@ -3397,7 +3399,7 @@ class BuiltinEncodeForURL(BuiltinFormatterFunction):
r''' r'''
``encode_for_url(value, use_plus)`` -- returns the ``value`` encoded for use in a URL as ``encode_for_url(value, use_plus)`` -- returns the ``value`` encoded for use in a URL as
specified by ``use_plus``. The value is first URL-encoded. Next, if ``use_plus`` is ``0`` then specified by ``use_plus``. The value is first URL-encoded. Next, if ``use_plus`` is ``0`` then
spaces are replaced by ``'+'`` (plus) signs. If it is ``1`` then spaces are replaced by ``%20``. spaces are replaced by ``'+'`` (plus) signs. If it is ``1`` then spaces are replaced by ``%20``.[/]
If you do not want the value to be encoding but to have spaces replaced then use the If you do not want the value to be encoding but to have spaces replaced then use the
:ref:`re` function, as in ``re($series, ' ', '%20')`` :ref:`re` function, as in ``re($series, ' ', '%20')``