mkdocs-include-markdown-plugin 7.1.8__tar.gz → 7.2.0__tar.gz

{mkdocs_include_markdown_plugin-7.1.8 → mkdocs_include_markdown_plugin-7.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-include-markdown-plugin
-Version: 7.1.8
+Version: 7.2.0
 Summary: Mkdocs Markdown includer plugin.
 Project-URL: Source, https://github.com/mondeja/mkdocs-include-markdown-plugin
 Project-URL: Documentation, https://github.com/mondeja/mkdocs-include-markdown-plugin#documentation
@@ -226,6 +226,32 @@ content to include.
 - <a name="include-markdown_recursive" href="#include-markdown_recursive">#</a>
   **recursive** (_true_): When this option is disabled, included files are not
   processed for recursive includes. Possible values are `true` and `false`.
+- <a name="include-markdown_order" href="#include-markdown_order">#</a>
+  **order** (_'alpha-path'_): Define the order in which multiple files are included
+  when using globs. Possible values are:
+  - A combination of an optional order type and an optional order by separated
+    by a hyphen (`-`), and optionally prefixed by a hyphen (`-`) to indicate
+    ascending order. If an order type or an order by is not specified, the defaults
+    are used. It follows the form:
+    `[-]<order_type>-<order_by>` where:
+    - **Order type**:
+      - `'alpha'` (default): Alphabetical order.
+      - `'natural'`: Natural order, so that e.g. `file2.md` comes before `file10.md`.
+    - **Order by**:
+      - `'path'` (default): Order by full file path.
+      - `'name'`: Order by file name only.
+      - `'extension'`: Order by file extension.
+  - A combination of an optional prefix hyphen to denote ascending order and
+    one of the following values in the form `[-]<value>` where `<value>` is one of:
+    - `'size'`: Order by file size.
+    - `'mtime'`: Order by file modification time.
+    - `'ctime'`: Order by file creation time (or the last metadata change time
+      on Unix systems).
+    - `'atime'`: Order by file last access time.
+  - `'random'`: Random order.
+  - `'system'`: Order provided by the operating system. This is the same as not
+    specifying any order and relying on the default order of the filesystem. This
+    may be different between operating systems, so use it with care.
 - <a name="include-markdown_encoding" href="#include-markdown_encoding">#</a>
   **encoding** (_'utf-8'_): Specify the encoding of the included file.
   If not defined `'utf-8'` will be used.
@@ -284,6 +310,7 @@ content to include.
 {%
     include-markdown "**"
     exclude="./{index,LICENSE}.md"
+    order="name"
 %}
 ```
 
@@ -291,6 +318,13 @@ content to include.
 {% include-markdown '/escap\'ed/single-quotes/in/file\'/name.md' %}
 ```
 
+```jinja
+{%
+    include-markdown "**"
+    order="-natural-extension"
+%}
+```
+
 <!-- mdpo-disable-next-line -->
 
 #### **`include`**
@@ -317,6 +351,32 @@ Includes the content of a file or a group of files.
 - <a name="include_recursive" href="#include_recursive">#</a>
   **recursive** (_true_): When this option is disabled, included files are not
   processed for recursive includes. Possible values are `true` and `false`.
+- <a name="include_order" href="#include_order">#</a>
+  **order** (_'alpha-path'_): Define the order in which multiple files are included
+  when using globs. Possible values are:
+  - A combination of an optional order type and an optional order by separated
+    by a hyphen (`-`), and optionally prefixed by a hyphen (`-`) to indicate
+    ascending order. If an order type or an order by is not specified, the defaults
+    are used. It follows the form:
+    `[-]<order_type>-<order_by>` where:
+    - **Order type**:
+      - `'alpha'` (default): Alphabetical order.
+      - `'natural'`: Natural order, so that e.g. `file2.md` comes before `file10.md`.
+    - **Order by**:
+      - `'path'` (default): Order by full file path.
+      - `'name'`: Order by file name only.
+      - `'extension'`: Order by file extension.
+  - A combination of an optional prefix hyphen to denote ascending order and
+    one of the following values in the form `[-]<value>` where `<value>` is one of:
+    - `'size'`: Order by file size.
+    - `'mtime'`: Order by file modification time.
+    - `'ctime'`: Order by file creation time (or the last metadata change time
+      on Unix systems).
+    - `'atime'`: Order by file last access time.
+  - `'random'`: Random order.
+  - `'system'`: Order provided by the operating system. This is the same as not
+    specifying any order and relying on the default order of the filesystem. This
+    may be different between operating systems, so use it with care.
 - <a name="include_encoding" href="#include_encoding">#</a>
   **encoding** (_'utf-8'_): Specify the encoding of the included file.
   If not defined `'utf-8'` will be used.
@@ -341,6 +401,7 @@ Includes the content of a file or a group of files.
 {%
     include '**'
     exclude='./*.md'
+    order='random'
 %}
 ```
 

{mkdocs_include_markdown_plugin-7.1.8 → mkdocs_include_markdown_plugin-7.2.0}/README.md

@@ -191,6 +191,32 @@ content to include.
 - <a name="include-markdown_recursive" href="#include-markdown_recursive">#</a>
   **recursive** (_true_): When this option is disabled, included files are not
   processed for recursive includes. Possible values are `true` and `false`.
+- <a name="include-markdown_order" href="#include-markdown_order">#</a>
+  **order** (_'alpha-path'_): Define the order in which multiple files are included
+  when using globs. Possible values are:
+  - A combination of an optional order type and an optional order by separated
+    by a hyphen (`-`), and optionally prefixed by a hyphen (`-`) to indicate
+    ascending order. If an order type or an order by is not specified, the defaults
+    are used. It follows the form:
+    `[-]<order_type>-<order_by>` where:
+    - **Order type**:
+      - `'alpha'` (default): Alphabetical order.
+      - `'natural'`: Natural order, so that e.g. `file2.md` comes before `file10.md`.
+    - **Order by**:
+      - `'path'` (default): Order by full file path.
+      - `'name'`: Order by file name only.
+      - `'extension'`: Order by file extension.
+  - A combination of an optional prefix hyphen to denote ascending order and
+    one of the following values in the form `[-]<value>` where `<value>` is one of:
+    - `'size'`: Order by file size.
+    - `'mtime'`: Order by file modification time.
+    - `'ctime'`: Order by file creation time (or the last metadata change time
+      on Unix systems).
+    - `'atime'`: Order by file last access time.
+  - `'random'`: Random order.
+  - `'system'`: Order provided by the operating system. This is the same as not
+    specifying any order and relying on the default order of the filesystem. This
+    may be different between operating systems, so use it with care.
 - <a name="include-markdown_encoding" href="#include-markdown_encoding">#</a>
   **encoding** (_'utf-8'_): Specify the encoding of the included file.
   If not defined `'utf-8'` will be used.
@@ -249,6 +275,7 @@ content to include.
 {%
     include-markdown "**"
     exclude="./{index,LICENSE}.md"
+    order="name"
 %}
 ```
 
@@ -256,6 +283,13 @@ content to include.
 {% include-markdown '/escap\'ed/single-quotes/in/file\'/name.md' %}
 ```
 
+```jinja
+{%
+    include-markdown "**"
+    order="-natural-extension"
+%}
+```
+
 <!-- mdpo-disable-next-line -->
 
 #### **`include`**
@@ -282,6 +316,32 @@ Includes the content of a file or a group of files.
 - <a name="include_recursive" href="#include_recursive">#</a>
   **recursive** (_true_): When this option is disabled, included files are not
   processed for recursive includes. Possible values are `true` and `false`.
+- <a name="include_order" href="#include_order">#</a>
+  **order** (_'alpha-path'_): Define the order in which multiple files are included
+  when using globs. Possible values are:
+  - A combination of an optional order type and an optional order by separated
+    by a hyphen (`-`), and optionally prefixed by a hyphen (`-`) to indicate
+    ascending order. If an order type or an order by is not specified, the defaults
+    are used. It follows the form:
+    `[-]<order_type>-<order_by>` where:
+    - **Order type**:
+      - `'alpha'` (default): Alphabetical order.
+      - `'natural'`: Natural order, so that e.g. `file2.md` comes before `file10.md`.
+    - **Order by**:
+      - `'path'` (default): Order by full file path.
+      - `'name'`: Order by file name only.
+      - `'extension'`: Order by file extension.
+  - A combination of an optional prefix hyphen to denote ascending order and
+    one of the following values in the form `[-]<value>` where `<value>` is one of:
+    - `'size'`: Order by file size.
+    - `'mtime'`: Order by file modification time.
+    - `'ctime'`: Order by file creation time (or the last metadata change time
+      on Unix systems).
+    - `'atime'`: Order by file last access time.
+  - `'random'`: Random order.
+  - `'system'`: Order provided by the operating system. This is the same as not
+    specifying any order and relying on the default order of the filesystem. This
+    may be different between operating systems, so use it with care.
 - <a name="include_encoding" href="#include_encoding">#</a>
   **encoding** (_'utf-8'_): Specify the encoding of the included file.
   If not defined `'utf-8'` will be used.
@@ -306,6 +366,7 @@ Includes the content of a file or a group of files.
 {%
     include '**'
     exclude='./*.md'
+    order='random'
 %}
 ```
 

{mkdocs_include_markdown_plugin-7.1.8 → mkdocs_include_markdown_plugin-7.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs-include-markdown-plugin"
-version = "7.1.8"
+version = "7.2.0"
 description = "Mkdocs Markdown includer plugin."
 readme = "README.md"
 license = "Apache-2.0"
@@ -151,7 +151,7 @@ select = [
   "COM",
   "SLOT",
 ]
-ignore = ["G004"]
+ignore = ["G004", "E731"]
 
 [tool.ruff.lint.pydocstyle]
 convention = "google"

{mkdocs_include_markdown_plugin-7.1.8 → mkdocs_include_markdown_plugin-7.2.0}/src/mkdocs_include_markdown_plugin/config.py

@@ -20,6 +20,7 @@ class PluginConfig(Config):  # noqa: D101
     comments = MkType(bool, default=False)
     rewrite_relative_urls = MkType(bool, default=True)
     heading_offset = MkType(int, default=0)
+    order = MkType(str, default='alpha-path')
     start = Optional(MkType(str))
     end = Optional(MkType(str))
     exclude = ListOfItems(MkType(str), default=[])

{mkdocs_include_markdown_plugin-7.1.8 → mkdocs_include_markdown_plugin-7.2.0}/src/mkdocs_include_markdown_plugin/directive.py

@@ -13,8 +13,15 @@ from typing import TYPE_CHECKING
 from mkdocs.exceptions import PluginError
 from wcmatch import glob
 
-from mkdocs_include_markdown_plugin import process
 from mkdocs_include_markdown_plugin.logger import logger
+from mkdocs_include_markdown_plugin.process import (
+    file_lineno_message,
+    filter_paths,
+    is_absolute_path,
+    is_relative_path,
+    is_url,
+    sort_paths,
+)
 
 
 @dataclass
@@ -28,6 +35,7 @@ if TYPE_CHECKING:  # pragma: no cover
     from typing import Callable, Literal, TypedDict
 
     DirectiveBoolArgumentsDict = dict[str, DirectiveBoolArgument]
+    OrderOption = tuple[bool, str, str]
 
     DefaultValues = TypedDict(
         'DefaultValues', {
@@ -41,6 +49,7 @@ if TYPE_CHECKING:  # pragma: no cover
             'recursive': bool,
             'start': str | None,
             'end': str | None,
+            'order': str,
         },
     )
 
@@ -92,10 +101,12 @@ def str_arg(arg: str) -> re.Pattern[str]:
 
 
 ARGUMENT_REGEXES = {
+    # str
     'start': functools.partial(str_arg, 'start'),
     'end': functools.partial(str_arg, 'end'),
     'exclude': functools.partial(str_arg, 'exclude'),
     'encoding': functools.partial(str_arg, 'encoding'),
+    'order': functools.partial(str_arg, 'order'),
 
     # bool
     'comments': functools.partial(arg, 'comments'),
@@ -178,7 +189,7 @@ def warn_invalid_directive_arguments(
     )
     for maybe_arg in _maybe_arguments_iter(arguments_string):
         if maybe_arg not in valid_args:
-            location = process.file_lineno_message(
+            location = file_lineno_message(
                 page_src_path, docs_dir, directive_lineno(),
             )
             logger.warning(
@@ -283,12 +294,13 @@ def resolve_file_paths_to_include(  # noqa: PLR0912
     includer_page_src_path: str | None,
     docs_dir: str,
     ignore_paths: list[str],
+    order: str,
 ) -> tuple[list[str], bool]:
     """Resolve the file paths to include for a directive."""
-    if process.is_url(include_string):
+    if is_url(include_string):
         return [include_string], True
 
-    if process.is_absolute_path(include_string):
+    if is_absolute_path(include_string):
         if os.name == 'nt':  # pragma: no cover
             # Windows
             fpath = os.path.normpath(include_string)
@@ -299,21 +311,25 @@ def resolve_file_paths_to_include(  # noqa: PLR0912
             if not is_file:
                 return [], False
 
-            return process.filter_paths(
-                [fpath], ignore_paths,
-            ), False
+            paths = filter_paths([fpath], ignore_paths)
+            is_url_ = False
+            return sort_paths(paths, parse_order_option(order)), is_url_
 
         try:
             is_file = stat.S_ISREG(os.stat(include_string).st_mode)
         except (FileNotFoundError, OSError):
             is_file = False
-        return process.filter_paths(
+        paths = filter_paths(
             [include_string] if is_file else glob.iglob(
                 include_string, flags=GLOB_FLAGS,
             ),
-            ignore_paths), False
+            ignore_paths,
+        )
+        is_url_ = False
+        sort_paths(paths, parse_order_option(order))
+        return paths, is_url_
 
-    if process.is_relative_path(include_string):
+    if is_relative_path(include_string):
         if includer_page_src_path is None:  # pragma: no cover
             raise PluginError(
                 'Relative paths are not allowed when the includer page'
@@ -338,7 +354,10 @@ def resolve_file_paths_to_include(  # noqa: PLR0912
                 root_dir=root_dir,
             ):
                 paths.append(os.path.join(root_dir, fp))
-        return process.filter_paths(paths, ignore_paths), False
+        paths = filter_paths(paths, ignore_paths)
+        is_url_ = False
+        sort_paths(paths, parse_order_option(order))
+        return paths, is_url_
 
     # relative to docs_dir
     paths = []
@@ -357,7 +376,10 @@ def resolve_file_paths_to_include(  # noqa: PLR0912
             root_dir=root_dir,
         ):
             paths.append(os.path.join(root_dir, fp))
-    return process.filter_paths(paths, ignore_paths), False
+    paths = filter_paths(paths, ignore_paths)
+    is_url_ = False
+    sort_paths(paths, parse_order_option(order))
+    return paths, is_url_
 
 
 def resolve_file_paths_to_exclude(
@@ -366,10 +388,10 @@ def resolve_file_paths_to_exclude(
     docs_dir: str,
 ) -> list[str]:
     """Resolve the file paths to exclude for a directive."""
-    if process.is_absolute_path(exclude_string):
+    if is_absolute_path(exclude_string):
         return glob.glob(exclude_string, flags=GLOB_FLAGS)
 
-    if process.is_relative_path(exclude_string):
+    if is_relative_path(exclude_string):
         if includer_page_src_path is None:  # pragma: no cover
             raise PluginError(
                 'Relative paths are not allowed when the includer page'
@@ -394,3 +416,58 @@ def resolve_file_paths_to_exclude(
         flags=GLOB_FLAGS,
         root_dir=docs_dir,
     )
+
+
+def validate_order_option(
+        order: str,
+        page_src_path: str | None,
+        docs_dir: str,
+        directive_lineno: Callable[[], int],
+        directive: str,
+) -> None:
+    """Validate the 'order' option."""
+    regex = get_order_option_regex()
+    match = regex.match(order)
+    if not match:
+        location = file_lineno_message(
+            page_src_path, docs_dir, directive_lineno(),
+        )
+        raise PluginError(
+            f"Invalid value '{order}' for the 'order' argument in"
+            f" '{directive}' directive at {location}. The argument"
+            " 'order' must be a string that matches the regex"
+            f" '{regex.pattern}'.",
+        )
+
+
+@functools.cache
+def get_order_option_regex() -> re.Pattern[str]:
+    """Return the compiled regex to validate the 'order' option."""
+    return re.compile(
+        r'^-?'
+        r'(?:'
+        r'(?:alpha|natural)?(?:-?(?:path|name|extension))?'
+        r'|system|random|size|mtime|ctime|atime'
+        r')?$',
+    )
+
+
+def parse_order_option(order: str) -> OrderOption:
+    """Parse the 'order' option into a tuple."""
+    ascending = False
+    order_type = 'alpha'
+    order_by = 'path'
+    if order.startswith('-'):
+        ascending = True
+        order = order[1:]
+    order_split = order.split('-', 1)
+    if len(order_split) == 2:  # noqa: PLR2004
+        order_type, order_by = order_split
+    elif order_split[0] in (
+        'alpha', 'random', 'natural', 'system',
+        'size', 'mtime', 'ctime', 'atime',
+    ):
+        order_type = order_split[0]
+    elif order_split[0] in ('name', 'path', 'extension'):
+        order_by = order_split[0]
+    return ascending, order_type, order_by

{mkdocs_include_markdown_plugin-7.1.8 → mkdocs_include_markdown_plugin-7.2.0}/src/mkdocs_include_markdown_plugin/event.py

@@ -24,6 +24,7 @@ from mkdocs_include_markdown_plugin.directive import (
     parse_string_argument,
     resolve_file_paths_to_exclude,
     resolve_file_paths_to_include,
+    validate_order_option,
     warn_invalid_directive_arguments,
 )
 from mkdocs_include_markdown_plugin.files_watcher import FilesWatcher
@@ -141,13 +142,42 @@ def get_file_content(  # noqa: PLR0913, PLR0915
             ):
                 ignore_paths.append(path)
 
+        order = defaults['order']
+        if 'order' in used_arguments:
+            order_match = ARGUMENT_REGEXES['order']().search(
+                arguments_string,
+            )
+            order_ = parse_string_argument(order_match)
+            if order_ is None:
+                location = process.file_lineno_message(
+                    page_src_path, docs_dir, directive_lineno(),
+                )
+                raise PluginError(
+                    "Invalid empty 'order' argument in 'include'"
+                    f' directive at {location}',
+                )
+            validate_order_option(
+                order_, page_src_path, docs_dir, directive_lineno, 'include',
+            )
+            order = order_
+
         file_paths_to_include, is_url = resolve_file_paths_to_include(
             filename,
             page_src_path,
             docs_dir,
             ignore_paths,
+            order,
         )
 
+        if is_url and 'order' in used_arguments:  # pragma: no cover
+            location = process.file_lineno_message(
+                page_src_path, docs_dir, directive_lineno(),
+            )
+            logger.warning(
+                f"Ignoring 'order' argument of 'include' directive"
+                f" at {location} because the included path is a URL",
+            )
+
         if not file_paths_to_include:
             location = process.file_lineno_message(
                 page_src_path, docs_dir, directive_lineno(),
@@ -353,13 +383,46 @@ def get_file_content(  # noqa: PLR0913, PLR0915
             ):
                 ignore_paths.append(path)
 
+        order = defaults['order']
+        if 'order' in used_arguments:
+            order_match = ARGUMENT_REGEXES['order']().search(
+                arguments_string,
+            )
+            order_ = parse_string_argument(order_match)
+            if order_ is None:
+                location = process.file_lineno_message(
+                    page_src_path, docs_dir, directive_lineno(),
+                )
+                raise PluginError(
+                    "Invalid empty 'order' argument in 'include-markdown'"
+                    f' directive at {location}',
+                )
+            validate_order_option(
+                order_,
+                page_src_path,
+                docs_dir,
+                directive_lineno,
+                'include-markdown',
+            )
+            order = order_
+
         file_paths_to_include, is_url = resolve_file_paths_to_include(
             filename,
             page_src_path,
             docs_dir,
             ignore_paths,
+            order,
         )
 
+        if is_url and 'order' in used_arguments:  # pragma: no cover
+            location = process.file_lineno_message(
+                page_src_path, docs_dir, directive_lineno(),
+            )
+            logger.warning(
+                f"Ignoring 'order' argument of 'include-markdown' directive"
+                f" at {location} because the included path is a URL",
+            )
+
         if not file_paths_to_include:
             location = process.file_lineno_message(
                 page_src_path, docs_dir, directive_lineno(),
@@ -645,6 +708,7 @@ def on_page_markdown(
             'recursive': config.recursive,
             'start': config.start,
             'end': config.end,
+            'order': config.order,
         },
         Settings(
             exclude=config.exclude,

{mkdocs_include_markdown_plugin-7.1.8 → mkdocs_include_markdown_plugin-7.2.0}/src/mkdocs_include_markdown_plugin/plugin.py

@@ -11,7 +11,6 @@ from mkdocs.plugins import BasePlugin, event_priority
 
 
 if TYPE_CHECKING:  # pragma: no cover
-
     from mkdocs.config.defaults import MkDocsConfig
     from mkdocs.livereload import LiveReloadServer
     from mkdocs.structure.files import Files
@@ -19,6 +18,9 @@ if TYPE_CHECKING:  # pragma: no cover
 
 from mkdocs_include_markdown_plugin.cache import Cache, initialize_cache
 from mkdocs_include_markdown_plugin.config import PluginConfig
+from mkdocs_include_markdown_plugin.directive import (
+    get_order_option_regex,
+)
 from mkdocs_include_markdown_plugin.event import (
     on_page_markdown as _on_page_markdown,
 )
@@ -50,6 +52,15 @@ class IncludeMarkdownPlugin(BasePlugin[PluginConfig]):
                         ' "include-markdown".',
                     )
 
+        if self.config.order != 'alpha-path':
+            regex = get_order_option_regex()
+            if not regex.match(self.config.order):
+                raise PluginError(
+                    f"Invalid value '{self.config.order}' for the 'order'"
+                    ' global setting. Order must be a string'
+                    f" that matches the regex '{regex.pattern}'.",
+                )
+
         return config
 
     @cached_property

{mkdocs_include_markdown_plugin-7.1.8 → mkdocs_include_markdown_plugin-7.2.0}/src/mkdocs_include_markdown_plugin/process.py

@@ -15,6 +15,7 @@ if TYPE_CHECKING:  # pragma: no cover
     from typing import Any
 
     from mkdocs_include_markdown_plugin.cache import Cache
+    from mkdocs_include_markdown_plugin.directive import OrderOption
 
 
 # Markdown regular expressions. Taken from the original Markdown.pl by John
@@ -494,12 +495,12 @@ def filter_paths(
 
     Args:
         filepaths (list): Set of source paths to filter.
-        ignore_paths (list): Paths that must not be included in the response.
+        ignore_paths (list): Paths that are ignored.
 
     Returns:
         list: Non filtered paths ordered alphabetically.
     """
-    response = []
+    result = []
     for filepath in filepaths:
         # ignore by filepath
         if filepath in ignore_paths:
@@ -514,11 +515,60 @@ def filter_paths(
         # ignore if is a directory
         try:
             if not stat.S_ISDIR(os.stat(filepath).st_mode):
-                response.append(filepath)
+                result.append(filepath)
         except (FileNotFoundError, OSError):  # pragma: no cover
             continue
-    response.sort()
-    return response
+    return result
+
+
+def natural_sort_key(s: str) -> list[Any]:
+    """Key function for natural sorting of strings."""
+    return [int(text) if text.isdigit() else text.lower()
+            for text in re.split(r'(\d+)', s)]
+
+
+def sort_paths(paths: list[str], order: OrderOption) -> list[str]:
+    """Sort a list of paths in-place according to an order option."""
+    ascending, order_type, order_by = order
+
+    if order_type == 'random':
+        import random  # noqa: PLC0415
+
+        random.shuffle(paths)
+        return paths
+
+    key = None
+    if order_type == 'alpha':
+        if order_by == 'name':
+            def key(p: str) -> str:
+                return os.path.basename(p)
+        elif order_by == 'extension':
+            def key(p: str) -> str:
+                return os.path.splitext(p)[1]
+    elif order_type == 'natural':
+        if order_by == 'extension':
+            def key(p: str) -> str:
+                return natural_sort_key(os.path.splitext(p)[1])  # type: ignore
+        elif order_by == 'name':
+            def key(p: str) -> str:
+                return natural_sort_key(os.path.basename(p))  # type: ignore
+        else:
+            key = natural_sort_key  # type: ignore
+    elif order_type == 'size':
+        def key(p: str) -> int:  # type: ignore
+            return os.path.getsize(p)
+        ascending = not ascending  # larger files first
+    elif order_type == 'mtime':
+        def key(p: str) -> float:  # type: ignore
+            return os.path.getmtime(p)
+    elif order_type == 'ctime':
+        def key(p: str) -> float:  # type: ignore
+            return os.path.getctime(p)
+    elif order_type == 'atime':
+        def key(p: str) -> float:  # type: ignore
+            return os.path.getatime(p)
+    paths.sort(key=key, reverse=ascending)
+    return paths
 
 
 def _is_valid_url_scheme_char(c: str) -> bool: