makefiles-cli 1.0.0__py3-none-any.whl

makefiles/_version.py

@@ -0,0 +1,21 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '1.0.0'
+__version_tuple__ = version_tuple = (1, 0, 0)

makefiles/cli_parser.py

@@ -0,0 +1,80 @@
+import argparse
+
+import makefiles.types as custom_types
+
+
+def get_parser() -> argparse.ArgumentParser:
+    parser: argparse.ArgumentParser = argparse.ArgumentParser(
+        prog="mkfile",
+        description="A lightweight Python utility for file creation and template generation from XDG_TEMPLATES_DIR",
+    )
+
+    parser.add_argument(
+        "files",
+        nargs="*",
+        action="store",
+        help="paths to files to create",
+    )
+
+    parser.add_argument(
+        "--version",
+        action="store_true",
+        help="print version and exit",
+    )
+
+    parser.add_argument(
+        "-t",
+        "--template",
+        nargs="?",
+        action="store",
+        type=str,
+        const=object(),
+        default=None,
+        help="template to generate. If no template is provided, it will prompt for template",
+    )
+
+    parser.add_argument(
+        "-p",
+        "--parents",
+        action="store_true",
+        help="make parents directories as needed",
+    )
+
+    parser.add_argument(
+        "-P",
+        "--picker",
+        nargs=1,
+        action="store",
+        type=str,
+        choices=["fzf", "manual"],
+        default=["manual"],
+        help="which template picker to use. If picker is `fzf`, fzf must be present in PATH. Default is `manual`",
+    )
+
+    parser.add_argument(
+        "-H",
+        "--height",
+        nargs=1,
+        action="store",
+        type=custom_types.NaturalNumber,
+        default=[custom_types.NaturalNumber(10)],
+        help="height of fzf window if fzf is used as template picker",
+    )
+
+    parser.add_argument(
+        "-l",
+        "--list",
+        action="store_true",
+        help="list available templates and exit",
+    )
+
+    return parser
+
+
+def get_cli_args(argparser: argparse.ArgumentParser) -> argparse.Namespace:
+    cli_arguments: argparse.Namespace = argparser.parse_args()
+
+    if not cli_arguments.files and not (cli_arguments.version or cli_arguments.list):
+        argparser.error("the following arguments are required: files")
+
+    return cli_arguments

makefiles/exceptions.py

@@ -0,0 +1,82 @@
+class MKFileException(Exception):
+    """Base exception for this project"""
+
+    def __init__(self, *args) -> None:
+        Exception.__init__(self, *args)
+
+
+class InvalidPathError(MKFileException):
+    """Path is invalid"""
+
+    def __init__(self, *args) -> None:
+        MKFileException.__init__(self, *args)
+
+
+class PathNotFoundError(MKFileException, FileNotFoundError):
+    """Path does not exists"""
+
+    def __init__(self, *args) -> None:
+        FileNotFoundError.__init__(self, *args)
+
+
+class TemplateCreationError(MKFileException):
+    """Failed to create template"""
+
+    def __init__(self, *args) -> None:
+        MKFileException.__init__(self, *args)
+
+
+class NoTemplatesAvailableError(MKFileException, FileNotFoundError):
+    """No template found"""
+
+    def __init__(self, *args) -> None:
+        FileNotFoundError.__init__(self, *args)
+
+
+class TemplateNotFoundError(MKFileException, FileNotFoundError):
+    """Given template not found"""
+
+    def __init__(self, *args) -> None:
+        FileNotFoundError.__init__(self, *args)
+
+
+class CopyError(MKFileException):
+    """Failed to copy file"""
+
+    def __init__(self, *args) -> None:
+        MKFileException.__init__(self, *args)
+
+
+class InvalidSourceError(CopyError, InvalidPathError):
+    """Copy source is invalid"""
+
+    def __init__(self, *args) -> None:
+        CopyError.__init__(self, *args)
+
+
+class SourceNotFoundError(CopyError, FileNotFoundError):
+    """Copy source does not exists"""
+
+    def __init__(self, *args) -> None:
+        FileNotFoundError.__init__(self, *args)
+
+
+class DestinationExistsError(CopyError, FileExistsError):
+    """Copy destination already exists"""
+
+    def __init__(self, *args) -> None:
+        FileExistsError.__init__(self, *args)
+
+
+class FZFError(MKFileException):
+    """Failed to run fzf"""
+
+    def __init__(self, *args) -> None:
+        MKFileException.__init__(self, *args)
+
+
+class FZFNotFoundError(FZFError):
+    """fzf executable not found"""
+
+    def __init__(self, *args) -> None:
+        FZFError.__init__(self, *args)

makefiles/mkfile.py

@@ -0,0 +1,121 @@
+import argparse
+import os
+import pathlib
+import typing
+
+import makefiles.cli_parser as cli_parser
+import makefiles.exceptions as exceptions
+import makefiles.types as custom_types
+import makefiles.utils as utils
+import makefiles.utils.cli_io as cli_io
+import makefiles.utils.dirwalker as dirwalker
+import makefiles.utils.fileutils as fileutils
+import makefiles.utils.picker as picker
+
+TEMPLATES_DIR: str = os.environ.get("XDG_TEMPLATES_DIR", f"{os.environ["HOME"]}/Templates")
+
+
+def _get_available_templates(templates_dir: pathlib.Path) -> list[str]:
+    try:
+        available_templates: list[str] = dirwalker.listf(templates_dir)
+        if not available_templates:
+            raise exceptions.NoTemplatesAvailableError("no templates found")
+    except exceptions.InvalidPathError:
+        raise exceptions.NoTemplatesAvailableError("could not find template directory") from None
+
+    return available_templates
+
+
+def _create_template(
+    template: str,
+    *destinations: pathlib.Path,
+    templates_dir: pathlib.Path,
+    overwrite: bool,
+    parents: bool,
+) -> custom_types.ExitCode:
+    exitcode: custom_types.ExitCode = custom_types.ExitCode(0)
+
+    template_path: pathlib.Path = templates_dir.joinpath(template)
+    try:
+        exitcode = fileutils.copy(template_path, *destinations, overwrite=overwrite, parents=parents) or exitcode
+    except exceptions.SourceNotFoundError:
+        raise exceptions.TemplateNotFoundError(f"template {template} not found") from None
+
+    return exitcode
+
+
+def _get_template_from_prompt(
+    *,
+    t_picker: typing.Literal["fzf"] | typing.Literal["manual"],
+    fzf_height: custom_types.NaturalNumber = custom_types.NaturalNumber(10),
+    templates_dir: pathlib.Path,
+) -> str:
+    available_templates: list[str] = _get_available_templates(templates_dir)
+
+    if t_picker == "fzf":
+        return picker.fzf(available_templates, height=fzf_height)
+    elif t_picker == "manual":
+        return picker.manual(available_templates)
+
+
+def runner(cli_arguments: argparse.Namespace, templates_dir: pathlib.Path) -> custom_types.ExitCode:
+    exitcode: custom_types.ExitCode = custom_types.ExitCode(0)
+
+    files: list[str] = cli_arguments.files
+    template: str | object | None = cli_arguments.template
+    t_picker: typing.Literal["fzf"] | typing.Literal["manual"] = cli_arguments.picker[0]
+    fzf_height: custom_types.NaturalNumber = cli_arguments.height[0]
+
+    if cli_arguments.version:
+        cli_io.print(f"{utils.get_version()}\n")
+        exitcode = custom_types.ExitCode(1)
+        return exitcode
+
+    if cli_arguments.list:
+        cli_io.print(f"{"\n".join(_get_available_templates(templates_dir))}\n")
+        return exitcode
+
+    files_paths: list[pathlib.Path] = list(map(pathlib.Path, files))
+
+    if not template:
+        exitcode = (
+            fileutils.create_empty_files(*files_paths, overwrite=False, parents=cli_arguments.parents) or exitcode
+        )
+        return exitcode
+
+    if not isinstance(template, str):
+        template = _get_template_from_prompt(
+            t_picker=t_picker,
+            fzf_height=fzf_height,
+            templates_dir=templates_dir,
+        )
+
+    # fmt:off
+    exitcode = _create_template(
+        template,
+        *files_paths,
+        templates_dir=templates_dir,
+        overwrite=False,
+        parents=cli_arguments.parents,
+    ) or exitcode 
+    # fmt:on
+
+    return exitcode
+
+
+def main() -> custom_types.ExitCode:
+    templates_dir_path: pathlib.Path = pathlib.Path(TEMPLATES_DIR)
+    exitcode: custom_types.ExitCode = custom_types.ExitCode(0)
+
+    argument_parser: argparse.ArgumentParser = cli_parser.get_parser()
+    cli_arguments: argparse.Namespace = cli_parser.get_cli_args(argument_parser)
+
+    try:
+        exitcode = runner(cli_arguments, templates_dir_path) or exitcode
+    except exceptions.MKFileException as ex:
+        cli_io.eprint(f"{argument_parser.prog}: {str(ex)}\n")
+        exitcode = custom_types.ExitCode(1)
+    except KeyboardInterrupt:
+        exitcode = custom_types.ExitCode(130)
+
+    return exitcode

makefiles/types.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+
+class NaturalNumber(int):
+    """
+    A strict subclass of `int` that represents natural numbers (positive integers > 0).
+
+    This class enforces validation at instantiation time. Any attempt to create a
+    `NaturalNumber` with a non-integer, zero, or negative value will raise an error.
+
+    Examples:
+        >>> NaturalNumber(5)
+        5
+        >>> NaturalNumber("3")
+        3
+        >>> NaturalNumber(-1)
+        ValueError: NaturalNumber must be greater than 0, got -1
+        >>> NaturalNumber("abc")
+        TypeError: Invalid literal for NaturalNumber: 'abc'
+
+    Raises:
+        TypeError: If the input cannot be converted to an integer.
+        ValueError: If the integer is not greater than 0.
+    """
+
+    def __new__(cls, x, /) -> NaturalNumber:
+        if not isinstance(x, int):
+            try:
+                x = int(x)
+            except (TypeError, ValueError):
+                raise TypeError(f"Invalid literal for NaturalNumber: {x!r}") from None
+
+        if x <= 0:
+            raise ValueError(f"NaturalNumber must be greater than 0, got {x}")
+
+        return super().__new__(cls, x)
+
+
+class ExitCode(int):
+    """
+    A strongly-typed representation of a POSIX-compliant process exit code.
+
+    This class ensures that only valid exit codes (unsigned 8-bit integers, 0–255)
+    can be instantiated. It inherits from `int`, so it can be used anywhere a regular
+    integer is accepted, such as in `sys.exit()` or `subprocess` interfaces.
+
+    Parameters:
+        x (int | str): The value to be validated and converted into a valid exit code.
+                       Non-integer inputs are attempted to be cast to `int`.
+
+    Raises:
+        TypeError: If the input is not convertible to an integer.
+        ValueError: If the resulting integer is outside the range [0, 255].
+
+    Example:
+        >>> code = ExitCode(0)
+        >>> sys.exit(code)
+
+        >>> code = ExitCode("42")
+        >>> print(code)  # 42
+
+        >>> ExitCode(999)
+        ValueError: ExitCode must be in range of [0,255], got 999
+    """
+
+    def __new__(cls, x, /) -> ExitCode:
+        if not isinstance(x, int):
+            try:
+                x = int(x)
+            except (TypeError, ValueError):
+                raise TypeError(f"Invalid literal for ExitCode: {x!r}") from None
+
+        if not (0 <= x <= 255):
+            raise ValueError(f"ExitCode must be in range of [0,255], got {x}")
+
+        return super().__new__(cls, x)

makefiles/utils/__init__.py

@@ -0,0 +1,137 @@
+import os.path
+import pathlib
+
+
+def exists(path: pathlib.Path) -> bool:
+    """
+    Checks whether the specified path exists, including broken symlinks.
+
+    Args:
+        path (pathlib.Path): The path to check.
+
+    Returns:
+        bool: True if the path exists or is a broken symlink, False otherwise.
+    """
+    return os.path.lexists(path)
+
+
+def isfile(path: pathlib.Path) -> bool:
+    """
+    Checks whether the given path is a regular file and not a symbolic link.
+
+    Args:
+        path (pathlib.Path): The path to evaluate.
+
+    Returns:
+        bool: True if the path exists, is a regular file, and is not a symlink; False otherwise.
+    """
+    return path.is_file() and not path.is_symlink()
+
+
+def isdir(path: pathlib.Path) -> bool:
+    """
+    Checks whether the given path is a directory and not a symbolic link.
+
+    Args:
+        path (pathlib.Path): The path to evaluate.
+
+    Returns:
+        bool: True if the path exists, is a directory, and is not a symlink; False otherwise.
+    """
+    return path.is_dir() and not path.is_symlink()
+
+
+def isbrokenlink(path: pathlib.Path) -> bool:
+    """
+    Checks whether the given path is a broken symbolic link.
+
+    Args:
+        path (pathlib.Path): The path to evaluate.
+
+    Returns:
+        bool: True if the path is a symlink and its target does not exist; False otherwise.
+
+    Note:
+        This relies on the fact that `path.exists()` returns False for broken symlinks.
+    """
+    # if path is a broken link, pathlib.Path.exists will return False. We will use this feature
+    return path.is_symlink() and not path.exists()
+
+
+def islink(path: pathlib.Path) -> bool:
+    """
+    Checks whether the given path is a valid (non-broken) symbolic link.
+
+    Args:
+        path (pathlib.Path): The path to evaluate.
+
+    Returns:
+        bool: True if the path is a symlink and its target exists; False otherwise.
+    """
+    return path.is_symlink() and not isbrokenlink(path)
+
+
+def islinkf(path: pathlib.Path) -> bool:
+    """
+    Checks whether the given path is a symbolic link that points to a regular file.
+
+    Args:
+        path (pathlib.Path): The path to evaluate.
+
+    Returns:
+        bool: True if the path is a symlink and its target is a regular file; False otherwise.
+    """
+    return path.is_symlink() and path.is_file()
+
+
+def islinkd(path: pathlib.Path) -> bool:
+    """
+    Checks whether the given path is a symbolic link that points to a directory.
+
+    Args:
+        path (pathlib.Path): The path to evaluate.
+
+    Returns:
+        bool: True if the path is a symlink and its target is a directory; False otherwise.
+    """
+    return path.is_symlink() and path.is_dir()
+
+
+def get_version() -> str:
+    """
+    Returns the current version of the tool using `setuptools_scm`.
+
+    Attempts to import the version from the auto-generated `_version.py` module.
+    Falls back to "unknown" if the version cannot be imported.
+
+    Returns:
+        str: The current version string, or "unknown" if unavailable.
+    """
+    try:
+        import makefiles._version as v
+
+        return v.version
+    except ImportError:
+        return "unknown"
+
+
+def get_hinder(path: pathlib.Path) -> str | None:
+    """
+    Recursively identifies the nearest path component that would prevent file or directory creation.
+
+    This function checks if any part of the given path is a broken symlink or a non-directory
+    (excluding valid directory symlinks). It traverses up the path hierarchy until it either
+    finds such a hindrance or reaches the root.
+
+    Args:
+        path (pathlib.Path): The path to evaluate.
+
+    Returns:
+        str | None: The problematic path component as a string, or None if no hindrance is found.
+    """
+    if isbrokenlink(path) or not (isdir(path) or islinkd(path)):
+        return str(path)
+    if str(path) == "/":
+        return
+
+    return get_hinder(path.parent)

makefiles/utils/cli_io.py

@@ -0,0 +1,81 @@
+"""
+This module provides functions and classes for handling terminal input and output
+in a consistent and controlled manner.
+
+The built-in `input` and `print` functions can exhibit inconsistent behavior.
+For example, the `input` function may write its prompt to `stderr` instead of
+`stdout` under certain conditions. To avoid such inconsistencies, this module
+uses the `sys` module to manage input and output manually.
+"""
+
+import io
+import sys
+
+
+def _write_to_stream(text: str, *, stream: io.TextIOWrapper) -> None:
+    try:
+        stream.write(text)
+    except UnicodeEncodeError:
+        # Fallback to safe encoding
+        encoded = text.encode(stream.encoding or "utf-8", "backslashreplace")
+
+        if hasattr(stream, "buffer"):
+            stream.buffer.write(encoded)
+        else:
+            # Decode back to text if binary buffer is unavailable
+            fallback_text = encoded.decode(stream.encoding or "utf-8", "strict")
+            stream.write(fallback_text)
+
+
+def print(text: str) -> None:
+    """
+    Writes the specified text to standard output (stdout) and flushes the stream.
+
+    Args:
+        text (str): The text string to be written to stdout.
+
+    Notes:
+        This function bypasses the built-in `print` to provide consistent
+        output behavior by directly writing to `sys.stdout`.
+
+    Side Effects:
+        Flushes the stdout buffer immediately after writing.
+    """
+    stream: io.TextIOWrapper = sys.stdout  # type:ignore
+    _write_to_stream(text, stream=stream)
+    stream.flush()
+
+
+def eprint(text: str) -> None:
+    """
+    Writes the specified text to standard error (stderr) and flushes the stream.
+
+    Args:
+        text (str): The text string to be written to stderr.
+
+    Notes:
+        This function directly writes to `sys.stderr`, providing consistent error
+        output behavior, bypassing the built-in `print`.
+
+    Side Effects:
+        Flushes the stderr buffer immediately after writing.
+    """
+    stream: io.TextIOWrapper = sys.stderr  # type:ignore
+    _write_to_stream(text, stream=stream)
+    stream.flush()
+
+
+def input() -> str:
+    """
+    Reads a line of input from standard input (stdin) and returns it as a string.
+
+    Returns:
+        str: The input string with the trailing newline character removed.
+
+    Notes:
+        This function reads directly from `sys.stdin` to avoid inconsistencies
+        sometimes observed with the built-in `input` function.
+    """
+    stream: io.TextIOWrapper = sys.stdin  # type:ignore
+    input: str = stream.readline().rstrip("\n")
+    return input

makefiles/utils/dirwalker.py

@@ -0,0 +1,37 @@
+import os
+import pathlib
+
+import makefiles.exceptions as exceptions
+import makefiles.utils as utils
+
+
+def listf(path: pathlib.Path) -> list[str]:
+    """
+    Recursively lists all non-hidden files within a directory, relative to the given path.
+
+    Args:
+        path (pathlib.Path): Path to a directory or a symbolic link to a directory.
+
+    Returns:
+        list[str]: A list of relative file paths (as strings) for all non-hidden files
+                   within the directory tree rooted at `path`.
+
+    Raises:
+        makefiles.exceptions.InvalidPathError: If the provided path is not a directory or a symlink to a directory.
+    """
+    path = path.absolute()
+    if not (utils.isdir(path) or utils.islinkd(path)):
+        raise exceptions.InvalidPathError("given path is not a directory or link to directory")
+
+    result: list[str] = []
+
+    for root, dirs, files in os.walk(path, topdown=True):
+        # Exclude hidden directories
+        dirs[:] = filter(lambda d: not d.startswith("."), dirs)
+
+        for file in files:
+            if not file.startswith("."):
+                relative_path: str = os.path.relpath(os.path.join(root, file), path)
+                result.append(relative_path)
+
+    return result