Repository navigation
Expand file tree
/
Copy pathutils.py
More file actions
152 lines (119 loc) · 5.08 KB
/
Copy pathutils.py
File metadata and controls
152 lines (119 loc) · 5.08 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
"""Shared helpers: logging setup, file discovery, and filename safety.
These utilities have no dependency on the xls/HTML conversion logic so they
can be unit tested in isolation and reused by both the CLI and the batch
converter.
"""
from __future__ import annotations
import logging
import re
import unicodedata
from pathlib import Path
from rich.logging import RichHandler
logger = logging.getLogger("xls2html")
_ILLEGAL_FILENAME_CHARS = re.compile(r'[<>:"/\\|?*\x00-\x1f]')
_XLS_SUFFIXES = {".xls"}
def setup_logging(*, verbose: bool = False, quiet: bool = False) -> None:
"""Configure the ``xls2html`` logger with a Rich console handler.
Args:
verbose: Emit DEBUG-level messages (open files, sheet/row/column
counts, output locations).
quiet: Emit only ERROR-level messages and above. Takes precedence
over ``verbose`` if both are set.
"""
if quiet:
level = logging.ERROR
elif verbose:
level = logging.DEBUG
else:
level = logging.INFO
handler = RichHandler(
show_time=False,
show_path=False,
markup=False,
rich_tracebacks=False,
)
handler.setLevel(level)
logger.handlers.clear()
logger.addHandler(handler)
logger.setLevel(level)
logger.propagate = False
def is_hidden(path: Path) -> bool:
"""Return True if ``path`` is a dotfile or an Excel lock file (``~$``)."""
return path.name.startswith(".") or path.name.startswith("~$")
def find_xls_files(inputs: list[Path], *, recursive: bool = False) -> list[Path]:
"""Resolve a mix of file and directory inputs into a sorted list of .xls files.
Directories are scanned for ``*.xls`` (case-insensitive). Hidden files
and Excel lock files (``~$name.xls``) are skipped. Plain files are
included as-is even if their suffix is not ``.xls``, so an explicit
mistake is reported later as a clear conversion error rather than
silently vanishing from the input list.
Args:
inputs: Paths supplied by the user (files and/or directories).
recursive: If True, descend into subdirectories of any directory
input.
Returns:
Sorted, de-duplicated list of resolved file paths.
"""
results: set[Path] = set()
for item in inputs:
if item.is_dir():
pattern = "**/*" if recursive else "*"
for candidate in item.glob(pattern):
if (
candidate.is_file()
and candidate.suffix.lower() == ".xls"
and not is_hidden(candidate)
):
results.add(candidate)
elif item.is_file():
if not is_hidden(item):
results.add(item)
else:
# Non-existent path: kept as-is so the caller can report a
# clear "file not found" error instead of it disappearing.
results.add(item)
return sorted(results)
def sanitize_filename(name: str, *, fallback: str = "sheet") -> str:
"""Turn an arbitrary worksheet or file name into a safe filename fragment.
Strips path separators and directory-traversal sequences, control
characters, and other filesystem-hostile characters, then normalises
unicode and whitespace. Never returns an empty string.
Args:
name: Raw name (e.g. a worksheet title) to sanitise.
fallback: Value to return if sanitisation would otherwise yield an
empty string.
Returns:
A filesystem-safe filename fragment (no extension).
"""
normalized = unicodedata.normalize("NFKD", name)
normalized = normalized.encode("ascii", "ignore").decode("ascii")
normalized = normalized.replace("..", "").replace("/", "_").replace("\\", "_")
normalized = _ILLEGAL_FILENAME_CHARS.sub("_", normalized)
normalized = re.sub(r"\s+", " ", normalized).strip(" ._")
return normalized or fallback
def resolve_within(base: Path, candidate: Path) -> Path:
"""Resolve ``candidate`` and verify it stays within ``base``.
Used to defend output-path construction against directory traversal
when a filename is derived from untrusted content (e.g. a worksheet
name embedded in the workbook).
Args:
base: Directory that the result must stay inside of.
candidate: Path to validate, expected to be a child of ``base``.
Returns:
The resolved absolute path.
Raises:
ValueError: If ``candidate`` resolves outside of ``base``.
"""
base_resolved = base.resolve()
candidate_resolved = candidate.resolve()
if base_resolved != candidate_resolved and base_resolved not in candidate_resolved.parents:
raise ValueError(f"Refusing to write outside of {base_resolved}: {candidate_resolved}")
return candidate_resolved
def format_bytes(size: int) -> str:
"""Format a byte count as a short human-readable string (e.g. ``12.3 KB``)."""
value = float(size)
for unit in ("B", "KB", "MB", "GB"):
if value < 1024 or unit == "GB":
return f"{value:.0f} {unit}" if unit == "B" else f"{value:.1f} {unit}"
value /= 1024
return f"{value:.1f} GB"