hdx-python-utilities 4.0.0__tar.gz → 4.0.2__tar.gz

{hdx_python_utilities-4.0.0 → hdx_python_utilities-4.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hdx-python-utilities
-Version: 4.0.0
+Version: 4.0.2
 Summary: HDX Python Utilities for streaming tabular data, date and time handling and other helpful functions
 Project-URL: Homepage, https://github.com/OCHA-DAP/hdx-python-utilities
 Author-email: Michael Rans <rans@email.com>

{hdx_python_utilities-4.0.0 → hdx_python_utilities-4.0.2}/documentation/index.md

@@ -33,7 +33,12 @@ The code for the library is [here](https://github.com/OCHA-DAP/hdx-python-utilit
 The library has detailed API documentation which can be found in the menu at the top.
 
 ## Breaking Changes
-From 4.0.0, Python 3.10 or later is required 
+From 4.0.1, Library is Path aware. The following methods return Path not str:
+download_file, get_path_for_url, stream_path, get_temp_dir, script_dir_plus_file,
+script_dir. The context managers in hdx.utilities.path where they yield a path
+do so as a Path object not a str.
+
+From 4.0.0, Python 3.10 or later is required
 
 From 3.8.0, multiple_replace, match_template_variables, earliest_index,
 get_matching_text_in_strs, get_matching_text,

{hdx_python_utilities-4.0.0 → hdx_python_utilities-4.0.2}/src/hdx/utilities/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '4.0.0'
-__version_tuple__ = version_tuple = (4, 0, 0)
+__version__ = version = '4.0.2'
+__version_tuple__ = version_tuple = (4, 0, 2)
 
 __commit_id__ = commit_id = None

{hdx_python_utilities-4.0.0 → hdx_python_utilities-4.0.2}/src/hdx/utilities/base_downloader.py

@@ -1,5 +1,6 @@
 from abc import ABC, abstractmethod
 from collections.abc import Iterator, Sequence
+from pathlib import Path
 from typing import Any
 
 
@@ -32,7 +33,7 @@ class BaseDownload(ABC):
         """
 
     @abstractmethod
-    def download_file(self, url: str, *args: Any, **kwargs: Any) -> str:
+    def download_file(self, url: str, *args: Any, **kwargs: Any) -> Path:
         """Download file from url.
 
         Args:

{hdx_python_utilities-4.0.0 → hdx_python_utilities-4.0.2}/src/hdx/utilities/compare.py

@@ -1,6 +1,7 @@
 """File compare utilities."""
 
 from os import linesep
+from pathlib import Path
 
 try:
     from cydifflib import ndiff
@@ -8,7 +9,9 @@ except ImportError:
     from difflib import ndiff
 
 
-def compare_files(path1: str, path2: str, encoding: str = "utf-8") -> list[str]:
+def compare_files(
+    path1: Path | str, path2: Path | str, encoding: str = "utf-8"
+) -> list[str]:
     """Returns the delta between two files using -, ?, + format excluding lines
     that are the same.
 
@@ -26,7 +29,9 @@ def compare_files(path1: str, path2: str, encoding: str = "utf-8") -> list[str]:
     return [x for x in diff if x[0] in ["-", "+", "?"]]
 
 
-def assert_files_same(path1: str, path2: str, encoding: str = "utf-8") -> None:
+def assert_files_same(
+    path1: Path | str, path2: Path | str, encoding: str = "utf-8"
+) -> None:
     """Asserts that two files are the same and returns delta using.
 
     -, ?, + format if not

{hdx_python_utilities-4.0.0 → hdx_python_utilities-4.0.2}/src/hdx/utilities/dictandlist.py

@@ -3,6 +3,7 @@
 import itertools
 import warnings
 from collections.abc import Callable, Mapping, MutableMapping, Sequence
+from pathlib import Path
 from typing import Any
 
 from hdx.utilities.frictionless_wrapper import get_frictionless_tableresource
@@ -410,7 +411,7 @@ def read_list_from_csv(
 
 
 def write_list_to_csv(
-    filepath: str,
+    filepath: Path | str,
     rows: list[Sequence | Mapping],
     headers: int | Sequence[str] | None = None,
     columns: Sequence[int] | Sequence[str] | None = None,

{hdx_python_utilities-4.0.0 → hdx_python_utilities-4.0.2}/src/hdx/utilities/downloader.py

@@ -5,7 +5,7 @@ import logging
 from collections.abc import Callable, Iterator, Sequence
 from copy import deepcopy
 from os import remove
-from os.path import exists, isfile, join, split, splitext
+from os.path import exists, isfile, split, splitext
 from pathlib import Path
 from typing import Any
 from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
@@ -65,7 +65,7 @@ class Download(BaseDownload):
     def __init__(
         self,
         user_agent: str | None = None,
-        user_agent_config_yaml: str | None = None,
+        user_agent_config_yaml: Path | str | None = None,
         user_agent_lookup: str | None = None,
         use_env: bool = True,
         fail_on_missing_file: bool = True,
@@ -133,12 +133,12 @@ class Download(BaseDownload):
     @staticmethod
     def get_path_for_url(
         url: str,
-        folder: str | None = None,
+        folder: Path | str | None = None,
         filename: str | None = None,
-        path: str | None = None,
+        path: Path | str | None = None,
         overwrite: bool = False,
         keep: bool = False,
-    ) -> str:
+    ) -> Path:
         """Get filename from url and join to provided folder or temporary
         folder if no folder supplied, ensuring uniqueness.
 
@@ -164,7 +164,8 @@ class Download(BaseDownload):
         filename, extension = splitext(filename)
         if not folder:
             folder = get_temp_dir()
-        path = join(folder, f"{filename}{extension}")
+        folder = Path(folder)
+        path = folder / f"{filename}{extension}"
         if overwrite:
             try:
                 remove(path)
@@ -174,7 +175,7 @@ class Download(BaseDownload):
             count = 0
             while exists(path):
                 count += 1
-                path = join(folder, f"{filename}{count}{extension}")
+                path = folder / f"{filename}{count}{extension}"
         return path
 
     def get_full_url(self, url: str) -> str:
@@ -254,7 +255,7 @@ class Download(BaseDownload):
 
     def normal_setup(
         self,
-        url: str,
+        url: Path | str,
         stream: bool = True,
         post: bool = False,
         parameters: dict | None = None,
@@ -281,6 +282,7 @@ class Download(BaseDownload):
         self.close_response()
         self.response = None
         try:
+            url = str(url)
             spliturl = urlsplit(url)
             if not spliturl.scheme:
                 if isfile(url):
@@ -336,7 +338,7 @@ class Download(BaseDownload):
             }
         )
 
-    def hash_stream(self, url: str) -> str:
+    def hash_stream(self, url: Path | str) -> str:
         """Stream file from url and hash it using MD5. Must call setup method
         first.
 
@@ -357,7 +359,7 @@ class Download(BaseDownload):
                 f"Download of {url} failed in retrieval of stream!" % url
             )
 
-    def stream_path(self, path: str, errormsg: str):
+    def stream_path(self, path: Path | str, errormsg: str) -> Path:
         """Stream file from url and store in provided path. Must call setup
         method first.
 
@@ -370,12 +372,13 @@ class Download(BaseDownload):
         """
         f = None
         try:
-            f = open(path, "wb")
+            path = Path(path)
+            f = path.open("wb")
             for chunk in self.response.iter_content(chunk_size=10240):
                 if chunk:  # filter out keep-alive new chunks
                     f.write(chunk)
                     f.flush()
-            return f.name
+            return path
         except Exception as e:
             raise DownloadError(errormsg) from e
         finally:
@@ -384,10 +387,10 @@ class Download(BaseDownload):
 
     def stream_file(
         self,
-        url: str,
-        folder: str | None = None,
+        url: Path | str,
+        folder: Path | str | None = None,
         filename: str | None = None,
-        path: str | None = None,
+        path: Path | str | None = None,
         overwrite: bool = False,
         keep: bool = False,
     ) -> str:
@@ -414,9 +417,9 @@ class Download(BaseDownload):
 
     def download_file(
         self,
-        url: str,
+        url: Path | str,
         **kwargs: Any,
-    ) -> str:
+    ) -> Path:
         """Download file from url and store in provided folder or temporary
         folder if no folder supplied.
 
@@ -460,7 +463,7 @@ class Download(BaseDownload):
             path, f"Download of {url} failed in retrieval of stream!"
         )
 
-    def download(self, url: str, **kwargs: Any) -> requests.Response:
+    def download(self, url: Path | str, **kwargs: Any) -> requests.Response:
         """Download url.
 
         Args:
@@ -539,7 +542,7 @@ class Download(BaseDownload):
         """
         return self.response.json()
 
-    def download_text(self, url: str, **kwargs: Any) -> str:
+    def download_text(self, url: Path | str, **kwargs: Any) -> str:
         """Download url as text.
 
         Args:
@@ -557,7 +560,7 @@ class Download(BaseDownload):
         self.download(url, **kwargs)
         return self.get_text()
 
-    def download_yaml(self, url: str, **kwargs: Any) -> Any:
+    def download_yaml(self, url: Path | str, **kwargs: Any) -> Any:
         """Download url as YAML.
 
         Args:
@@ -575,7 +578,7 @@ class Download(BaseDownload):
         self.download(url, **kwargs)
         return self.get_yaml()
 
-    def download_json(self, url: str, **kwargs: Any) -> Any:
+    def download_json(self, url: Path | str, **kwargs: Any) -> Any:
         """Download url as JSON.
 
         Args:
@@ -595,7 +598,7 @@ class Download(BaseDownload):
 
     def get_frictionless_tableresource(
         self,
-        url: str,
+        url: Path | str,
         ignore_blank_rows: bool = True,
         infer_types: bool = False,
         **kwargs: Any,
@@ -641,7 +644,7 @@ class Download(BaseDownload):
 
     def _get_tabular_rows(
         self,
-        url: str,
+        url: Path | str,
         headers: int | Sequence[int] | Sequence[str] = 1,
         dict_form: bool = False,
         include_headers: bool = False,
@@ -704,7 +707,7 @@ class Download(BaseDownload):
         xlsx2csv = kwargs.pop("xlsx2csv", False)
         if xlsx2csv:
             path = self.download_file(url)
-            outpath = path.replace(".xlsx", ".csv")
+            outpath = path.with_suffix(".csv")
             sheet = kwargs.pop("sheet", 1)
             if isinstance(sheet, int):
                 sheet_args = {"sheetid": sheet}
@@ -1276,7 +1279,7 @@ class Download(BaseDownload):
         cls,
         custom_configs: dict[str, dict],
         user_agent: str | None = None,
-        user_agent_config_yaml: str | None = None,
+        user_agent_config_yaml: Path | str | None = None,
         user_agent_lookup: str | None = None,
         use_env: bool = True,
         fail_on_missing_file: bool = True,

{hdx_python_utilities-4.0.0 → hdx_python_utilities-4.0.2}/src/hdx/utilities/email.py

@@ -5,7 +5,8 @@ import smtplib
 from collections.abc import Sequence
 from email.mime.multipart import MIMEMultipart
 from email.mime.text import MIMEText
-from os.path import expanduser, join
+from os.path import expanduser
+from pathlib import Path
 from typing import Any
 
 from hdx.utilities.loader import load_json, load_yaml
@@ -45,7 +46,7 @@ class Email:
         email_config_yaml (str): Path to YAML HDX configuration. Defaults to ~/hdx_email_configuration.yaml.
     """
 
-    default_email_config_yaml = join(expanduser("~"), "hdx_email_configuration.yaml")
+    default_email_config_yaml = Path(expanduser("~")) / "hdx_email_configuration.yaml"
 
     def __init__(self, **kwargs: Any) -> None:
         email_config_found = False

{hdx_python_utilities-4.0.0 → hdx_python_utilities-4.0.2}/src/hdx/utilities/file_hashing.py

@@ -3,6 +3,7 @@ import logging
 import zipfile
 from io import BytesIO, IOBase
 from os import fstat
+from pathlib import Path
 
 from openpyxl import load_workbook
 from openpyxl.utils.exceptions import InvalidFileException
@@ -90,7 +91,7 @@ def crc_zip_fp(fp: IOBase) -> str:
     return get_crc_sum(file_crcs)
 
 
-def get_size_and_hash(filepath: str, file_format: str) -> tuple[int, str]:
+def get_size_and_hash(filepath: Path | str, file_format: str) -> tuple[int, str]:
     """Return the size and hash of file
 
     Args:

{hdx_python_utilities-4.0.0 → hdx_python_utilities-4.0.2}/src/hdx/utilities/frictionless_wrapper.py

@@ -188,7 +188,7 @@ def get_frictionless_tableresource(
     http_session = kwargs.pop("http_session", session)
     with system.use_context(http_session=http_session):
         if url:
-            resource = TableResource(path=url, **kwargs)
+            resource = TableResource(path=str(url), **kwargs)
         else:
             resource = TableResource(data=data, **kwargs)
         resource.open()

{hdx_python_utilities-4.0.0 → hdx_python_utilities-4.0.2}/src/hdx/utilities/html.py

@@ -1,6 +1,7 @@
 """HTML parsing utilities."""
 
 import logging
+from pathlib import Path
 from typing import Any
 
 try:
@@ -20,7 +21,7 @@ if BeautifulSoup is not None:
         url: str,
         downloader: Download = None,
         user_agent: str | None = None,
-        user_agent_config_yaml: str | None = None,
+        user_agent_config_yaml: Path | str | None = None,
         user_agent_lookup: str | None = None,
         **kwargs: Any,
     ) -> BeautifulSoup:

{hdx_python_utilities-4.0.0 → hdx_python_utilities-4.0.2}/src/hdx/utilities/loader.py

@@ -1,7 +1,8 @@
 """Loading utilities for YAML, JSON etc."""
 
 import json
-from collections.abc import Mapping, Sequence
+from collections.abc import Mapping, MutableMapping, Sequence
+from pathlib import Path
 from typing import Any
 from warnings import warn
 
@@ -15,7 +16,7 @@ class LoadError(Exception):
 
 
 def load_text(
-    path: str,
+    path: Path | str,
     encoding: str = "utf-8",
     strip: bool = False,
     replace_newlines: str | None = None,
@@ -59,7 +60,7 @@ def load_text(
 
 
 def load_yaml(
-    path: str, encoding: str = "utf-8", loaderror_if_empty: bool = True
+    path: Path | str, encoding: str = "utf-8", loaderror_if_empty: bool = True
 ) -> Any:
     """Load YAML file into an ordered dictionary.
 
@@ -83,7 +84,7 @@ def load_yaml(
 
 
 def load_json(
-    path: str, encoding: str = "utf-8", loaderror_if_empty: bool = True
+    path: Path | str, encoding: str = "utf-8", loaderror_if_empty: bool = True
 ) -> Any:
     """Load JSON file into an ordered dictionary (dict for Python 3.7+)
 
@@ -152,11 +153,11 @@ def load_and_merge_json(
 
 
 def load_yaml_into_existing_dict(
-    data: dict,
-    path: str,
+    data: MutableMapping,
+    path: Path | str,
     encoding: str = "utf-8",
     loaderror_if_empty: bool = True,
-) -> Mapping:
+) -> MutableMapping:
     """Merge YAML file that is in dictionary form into existing dictionary.
 
     Args:
@@ -173,11 +174,11 @@ def load_yaml_into_existing_dict(
 
 
 def load_json_into_existing_dict(
-    data: dict,
-    path: str,
+    data: MutableMapping,
+    path: Path | str,
     encoding: str = "utf-8",
     loaderror_if_empty: bool = True,
-) -> Mapping:
+) -> MutableMapping:
     """Merge JSON file that is in dictionary form into existing dictionary.
 
     Args:

{hdx_python_utilities-4.0.0 → hdx_python_utilities-4.0.2}/src/hdx/utilities/path.py

@@ -4,17 +4,15 @@ import contextlib
 import inspect
 import logging
 import sys
-from collections.abc import Generator, Iterable, Sequence
+from collections.abc import Iterable, Iterator, Sequence
 from os import getenv, makedirs, remove
 from os.path import (
-    abspath,
     basename,
     dirname,
     exists,
-    join,
-    realpath,
     splitext,
 )
+from pathlib import Path
 from shutil import rmtree
 from tempfile import gettempdir
 from typing import Any
@@ -33,7 +31,7 @@ class NotFoundError(Exception):
     pass
 
 
-def script_dir(pyobject: Any, follow_symlinks: bool = True) -> str:
+def script_dir(pyobject: Any, follow_symlinks: bool = True) -> Path:
     """Get current script's directory.
 
     Args:
@@ -43,36 +41,42 @@ def script_dir(pyobject: Any, follow_symlinks: bool = True) -> str:
     Returns:
         Current script's directory
     """
-    if getattr(sys, "frozen", False):  # py2exe, PyInstaller, cx_Freeze
-        path = abspath(sys.executable)  # pragma: no cover
+    if getattr(sys, "frozen", False):
+        # Frozen (PyInstaller, etc.): Use the executable path
+        path = Path(sys.executable)  # pragma: no cover
     else:
-        path = inspect.getabsfile(pyobject)
-    if follow_symlinks:
-        path = realpath(path)
-    return dirname(path)
+        # Standard: Use the object's file path
+        path = Path(inspect.getfile(pyobject))
+
+    # Resolve symlinks if requested, otherwise just make absolute
+    path = path.resolve() if follow_symlinks else path.absolute()
+
+    return path.parent
 
 
 def script_dir_plus_file(
     filename: str, pyobject: Any, follow_symlinks: bool = True
-) -> str:
+) -> Path:
     """Get current script's directory and then append a filename.
 
     Args:
         filename: Filename to append to directory path
         pyobject: Any Python object in the script
+        return_path: Whether to return a Path object. Defaults to returning str.
+
         follow_symlinks: Follow symlinks or not. Defaults to True.
 
     Returns:
         Current script's directory and with filename appended
     """
-    return join(script_dir(pyobject, follow_symlinks), filename)
+    return script_dir(pyobject, follow_symlinks) / filename
 
 
 def get_temp_dir(
-    folder: str | None = None,
+    folder: Path | str | None = None,
     delete_if_exists: bool = False,
-    tempdir: str | None = None,
-) -> str:
+    tempdir: Path | str | None = None,
+) -> Path:
     """Get a temporary directory. Looks for environment variable TEMP_DIR and
     falls back on os.gettempdir if a root temporary directory is not supplied.
     If a folder is supplied, creates that folder within the temporary
@@ -88,8 +92,9 @@ def get_temp_dir(
     """
     if tempdir is None:
         tempdir = getenv("TEMP_DIR", gettempdir())
+    tempdir = Path(tempdir)
     if folder:
-        tempdir = join(tempdir, folder)
+        tempdir = tempdir / folder
         if exists(tempdir):
             if delete_if_exists:
                 rmtree(tempdir)
@@ -101,12 +106,12 @@ def get_temp_dir(
 
 @contextlib.contextmanager
 def temp_dir(
-    folder: str | None = None,
+    folder: Path | str | None = None,
     delete_if_exists: bool = False,
     delete_on_success: bool = True,
     delete_on_failure: bool = True,
-    tempdir: str | None = None,
-) -> Generator[str, Any, None]:
+    tempdir: Path | str | None = None,
+) -> Iterator[Path]:
     """Get a temporary directory optionally with folder appended (and created
     if it doesn't exist)
 
@@ -132,7 +137,7 @@ def temp_dir(
             raise
 
 
-def read_or_create_batch(folder: str, batch: str | None = None) -> str:
+def read_or_create_batch(folder: Path, batch: str | None = None) -> str:
     """Get batch or create it if it doesn't exist.
 
     Args:
@@ -142,7 +147,7 @@ def read_or_create_batch(folder: str, batch: str | None = None) -> str:
     Returns:
         Batch
     """
-    batch_file = join(folder, "batch.txt")
+    batch_file = folder / "batch.txt"
     if exists(batch_file):
         batch = load_text(batch_file, strip=True)
         logger.info(f"File BATCH = {batch}")
@@ -156,13 +161,13 @@ def read_or_create_batch(folder: str, batch: str | None = None) -> str:
 
 @contextlib.contextmanager
 def temp_dir_batch(
-    folder: str | None = None,
+    folder: Path | str | None = None,
     delete_if_exists: bool = False,
     delete_on_success: bool = True,
     delete_on_failure: bool = True,
     batch: str | None = None,
-    tempdir: str | None = None,
-) -> Generator[dict, Any, None]:
+    tempdir: Path | str | None = None,
+) -> Iterator[dict]:
     """Get a temporary directory and batch id. Yields a dictionary with key
     folder which is the temporary directory optionally with folder appended
     (and created if it doesn't exist). In key batch is a batch code to be
@@ -219,7 +224,7 @@ def progress_storing_folder(
     iterator: Iterable[dict],
     key: str,
     wheretostart: str | None = None,
-) -> Generator[tuple[dict, dict], Any, None]:
+) -> Iterator[tuple[dict, dict]]:
     """Store progress in folder in key folder of info dictionary parameter.
     Yields 2 dictionaries. The first is the info dictionary. It contains in key
     folder the folder being used to store progress and in key progress the
@@ -238,7 +243,7 @@ def progress_storing_folder(
         A tuple of the form (info dictionary, next object in iterator)
     """
     folder = info["folder"]
-    progress_file = join(folder, "progress.txt")
+    progress_file = folder / "progress.txt"
 
     if not wheretostart:
         contents = getenv("WHERETOSTART")
@@ -277,8 +282,8 @@ def progress_storing_folder(
 
 @contextlib.contextmanager
 def wheretostart_tempdir_batch(
-    folder: str, batch: str | None = None, tempdir: str | None = None
-) -> Generator[dict, Any, None]:
+    folder: Path | str, batch: str | None = None, tempdir: Path | str | None = None
+) -> Iterator[dict]:
     """Get a temporary directory and batch id. Deletes any existing folder if
     WHERETOSTART environment variable is set to RESET. Yields a dictionary with
     key folder which is the temporary directory optionally with folder appended
@@ -311,12 +316,12 @@ def wheretostart_tempdir_batch(
 
 
 def progress_storing_tempdir(
-    folder: str,
+    folder: Path | str,
     iterator: Iterable[dict],
     key: str,
     batch: str | None = None,
-    tempdir: str | None = None,
-) -> Generator[tuple[dict, dict], Any, None]:
+    tempdir: Path | str | None = None,
+) -> Iterator[tuple[dict, dict]]:
     """Store progress in temporary directory. The folder persists until the
     final iteration allowing which iteration to start at and the batch code to
     be persisted between runs. Yields 2 dictionaries. The first contains key
@@ -344,11 +349,11 @@ def progress_storing_tempdir(
 
 
 def multiple_progress_storing_tempdir(
-    folder: str,
+    folder: Path | str,
     iterators: Sequence[Iterable[dict]],
     keys: Sequence[str],
     batch: str | None = None,
-) -> Generator[tuple[int, dict, dict], Any, None]:
+) -> Iterator[tuple[int, dict, dict]]:
     """Store progress in temporary directory. The folder persists until the
     final iteration of the last iterator allowing which iteration to start at
     and the batch code to be persisted between runs. Yields 2 dictionaries. The
@@ -387,7 +392,7 @@ def multiple_progress_storing_tempdir(
         tempdir = info["folder"]
         batch = info["batch"]
         for i, key in enumerate(keys):
-            progress_file = join(tempdir, "progress.txt")
+            progress_file = tempdir / "progress.txt"
             if wheretostartenv:
                 wheretostart = get_wheretostart(
                     wheretostartenv, "Environment variable", key
@@ -416,18 +421,19 @@ def multiple_progress_storing_tempdir(
 
 
 def get_filename_extension_from_url(
-    url: str, second_last: bool = False, use_query: bool = False
+    url: Path | str, second_last: bool = False, use_query: bool = False
 ) -> tuple[str, str]:
     """Get separately filename and extension from url.
 
     Args:
-        url: URL to download
+        url: URL or path to download
         second_last: Get second last segment of url as well. Defaults to False.
         use_query: Include query parameters as well. Defaults to False.
 
     Returns:
         Tuple of (filename, extension)
     """
+    url = str(url)
     split_url = urlsplit(unquote_plus(url))
     urlpath = split_url.path
     last_part = basename(urlpath)
@@ -448,12 +454,12 @@ def get_filename_extension_from_url(
 
 
 def get_filename_from_url(
-    url: str, second_last: bool = False, use_query: bool = False
+    url: Path | str, second_last: bool = False, use_query: bool = False
 ) -> str:
     """Get filename including extension from url.
 
     Args:
-        url: URL
+        url: URL or path
         second_last: Get second last segment of url as well. Defaults to False.
         use_query: Include query parameters as well. Defaults to False.