Passed
Push — main ( 809f25...c1ae8e )
by Peter
01:20
created

pyclean.modern.remove_freeform_targets()   A

Complexity

Conditions 2

Size

Total Lines 19
Code Lines 4

Duplication

Lines 0
Ratio 0 %

Importance

Changes 0
Metric Value
eloc 4
dl 0
loc 19
rs 10
c 0
b 0
f 0
cc 2
nop 4
1
# SPDX-FileCopyrightText: 2020 Peter Bittner <[email protected]>
2
#
3
# SPDX-License-Identifier: GPL-3.0-or-later
4
5
"""
6
Modern, cross-platform, pure-Python pyclean implementation.
7
"""
8
9
import logging
10
import os
11
from pathlib import Path
12
13
BYTECODE_FILES = ['.pyc', '.pyo']
14
BYTECODE_DIRS = ['__pycache__']
15
DEBRIS_TOPICS = {
16
    'cache': [
17
        '.cache/**/*',
18
        '.cache/',
19
    ],
20
    'coverage': [
21
        '.coverage',
22
        'coverage.json',
23
        'coverage.lcov',
24
        'coverage.xml',
25
        'htmlcov/**/*',
26
        'htmlcov/',
27
    ],
28
    'jupyter': [
29
        '.ipynb_checkpoints/**/*',
30
        '.ipynb_checkpoints/',
31
    ],
32
    'mypy': [
33
        '.mypy_cache/**/*',
34
        '.mypy_cache/',
35
    ],
36
    'package': [
37
        'build/bdist.*/**/*',
38
        'build/bdist.*/',
39
        'build/lib/**/*',
40
        'build/lib/',
41
        'build/',
42
        'dist/**/*',
43
        'dist/',
44
        'sdist/**/*',
45
        'sdist/',
46
        '*.egg-info/**/*',
47
        '*.egg-info/',
48
    ],
49
    'pytest': [
50
        '.pytest_cache/**/*',
51
        '.pytest_cache/',
52
        'pytestdebug.log',
53
    ],
54
    'ruff': [
55
        '.ruff_cache/**/*',
56
        '.ruff_cache/',
57
    ],
58
    'tox': [
59
        '.tox/**/*',
60
        '.tox/',
61
    ],
62
}
63
64
65
class CleanupRunner:
66
    """Module-level configuration and value store."""
67
68
    def __init__(self):
69
        """Cleanup runner with optional dry-run behavior."""
70
        self.unlink = None
71
        self.rmdir = None
72
        self.ignore = None
73
        self.unlink_count = None
74
        self.unlink_failed = None
75
        self.rmdir_count = None
76
        self.rmdir_failed = None
77
78
    def configure(self, args):
79
        """Set up runner according to command line options."""
80
        self.unlink = print_filename if args.dry_run else remove_file
81
        self.rmdir = print_dirname if args.dry_run else remove_directory
82
        self.ignore = args.ignore
83
        self.unlink_count = 0
84
        self.unlink_failed = 0
85
        self.rmdir_count = 0
86
        self.rmdir_failed = 0
87
88
89
log = logging.getLogger(__name__)
90
Runner = CleanupRunner()
91
92
93
def normalize(path_pattern: str) -> str:
94
    """
95
    Normalize path separators in a pattern for cross-platform support.
96
97
    On Windows, both forward slash and backslash are valid path separators.
98
    On Unix/Posix, only forward slash is valid (backslash can be part of filename).
99
    """
100
    return path_pattern.replace(os.sep, os.altsep or os.sep)
101
102
103
def should_ignore(path: Path, ignore_patterns: list[str]) -> bool:
104
    """
105
    Check if a path should be ignored based on ignore patterns.
106
107
    Patterns can be:
108
    - Simple names like 'bar': matches any directory with that name
109
    - Paths like 'foo/bar': matches 'bar' directory inside 'foo' directory
110
      and also ignores everything inside that directory
111
    """
112
    if not ignore_patterns:
113
        return False
114
115
    for pattern in ignore_patterns:
116
        # Check if pattern has multiple components (is a path with separators)
117
        pattern_parts = Path(normalize(pattern)).parts
118
        if len(pattern_parts) > 1:
119
            # Pattern contains path separator - match relative path
120
            # Path must have at least as many parts as the pattern
121
            if len(path.parts) < len(pattern_parts):
122
                continue
123
            # Check if pattern matches anywhere in the path hierarchy
124
            for i in range(len(path.parts) - len(pattern_parts) + 1):
125
                path_slice = path.parts[i : i + len(pattern_parts)]
126
                if path_slice == pattern_parts:
127
                    return True
128
        # Simple name - match the directory name anywhere
129
        elif path.name == pattern:
130
            return True
131
    return False
132
133
134
def remove_file(fileobj):
135
    """Attempt to delete a file object for real."""
136
    log.debug('Deleting file: %s', fileobj)
137
    try:
138
        fileobj.unlink()
139
        Runner.unlink_count += 1
140
    except OSError as err:
141
        log.debug('File not deleted. %s', err)
142
        Runner.unlink_failed += 1
143
144
145
def remove_directory(dirobj):
146
    """Attempt to remove a directory object for real."""
147
    log.debug('Removing directory: %s', dirobj)
148
    try:
149
        dirobj.rmdir()
150
        Runner.rmdir_count += 1
151
    except OSError as err:
152
        log.debug('Directory not removed. %s', err)
153
        Runner.rmdir_failed += 1
154
155
156
def print_filename(fileobj):
157
    """Only display the file name, used with --dry-run."""
158
    log.debug('Would delete file: %s', fileobj)
159
    Runner.unlink_count += 1
160
161
162
def print_dirname(dirobj):
163
    """Only display the directory name, used with --dry-run."""
164
    log.debug('Would delete directory: %s', dirobj)
165
    Runner.rmdir_count += 1
166
167
168
def pyclean(args):
169
    """Cross-platform cleaning of Python bytecode."""
170
    Runner.configure(args)
171
172
    for dir_name in args.directory:
173
        dir_path = Path(dir_name)
174
175
        log.info('Cleaning directory %s', dir_path)
176
        descend_and_clean(dir_path, BYTECODE_FILES, BYTECODE_DIRS)
177
178
        for topic in args.debris:
179
            remove_debris_for(topic, dir_path)
180
181
        remove_freeform_targets(dir_path, args.erase, args.yes, args.dry_run)
182
183
        if args.folders:
184
            log.debug('Removing empty directories...')
185
            remove_empty_directories(dir_path)
186
187
    log.info(
188
        'Total %d files, %d directories %s.',
189
        Runner.unlink_count,
190
        Runner.rmdir_count,
191
        'would be removed' if args.dry_run else 'removed',
192
    )
193
194
    if Runner.unlink_failed or Runner.rmdir_failed:
195
        log.debug(
196
            '%d files, %d directories %s not be removed.',
197
            Runner.unlink_failed,
198
            Runner.rmdir_failed,
199
            'would' if args.dry_run else 'could',
200
        )
201
202
    # Suggest --debris option if it wasn't used
203
    if not args.debris:
204
        suggest_debris_option(args)
205
206
207
def descend_and_clean(directory, file_types, dir_names):
208
    """
209
    Walk and descend a directory tree, cleaning up files of a certain type
210
    along the way. Only delete directories if they are empty, in the end.
211
    """
212
    for child in sorted(directory.iterdir()):
213
        if child.is_file():
214
            if child.suffix in file_types:
215
                Runner.unlink(child)
216
        elif child.is_dir():
217
            if should_ignore(child, Runner.ignore):
218
                log.debug('Skipping %s', child)
219
            else:
220
                descend_and_clean(child, file_types, dir_names)
221
222
            if child.name in dir_names:
223
                Runner.rmdir(child)
224
        else:
225
            log.debug('Ignoring %s (neither a file nor a folder)', child)
226
227
228
def remove_debris_for(topic, directory):
229
    """
230
    Clean up debris for a specific topic.
231
    """
232
    log.debug('Scanning for debris of %s ...', topic.title())
233
234
    patterns = DEBRIS_TOPICS[topic]
235
    recursive_delete_debris(directory, patterns)
236
237
238
def remove_empty_directories(directory):
239
    """
240
    Recursively remove empty directories in the given directory tree.
241
242
    This walks the directory tree in post-order (bottom-up), attempting to
243
    remove directories that are empty.
244
    """
245
    try:
246
        subdirs = [
247
            Path(entry.path) for entry in os.scandir(directory) if entry.is_dir()
248
        ]
249
    except (OSError, PermissionError) as err:
250
        log.warning('Cannot access directory %s: %s', directory, err)
251
        return
252
253
    for subdir in subdirs:
254
        if should_ignore(subdir, Runner.ignore):
255
            log.debug('Skipping %s', subdir)
256
        else:
257
            remove_empty_directories(subdir)  # recurse down the hierarchy
258
            try:
259
                if next(subdir.iterdir(), None) is None:
260
                    Runner.rmdir(subdir)
261
            except (OSError, PermissionError) as err:
262
                log.debug('Cannot check or remove directory %s: %s', subdir, err)
263
264
265
def remove_freeform_targets(directory, glob_patterns, yes, dry_run=False):
266
    """
267
    Remove free-form targets using globbing.
268
269
    This is **potentially dangerous** since users can delete everything
270
    anywhere in their file system, including the entire project they're
271
    working on. For this reason, the implementation imposes the following
272
    (user experience-related) restrictions:
273
274
    - Deleting (directories) is not recursive, directory contents must be
275
      explicitly specified using globbing (e.g. ``dirname/**/*``).
276
    - The user is responsible for the deletion order, so that a directory
277
      is empty when it is attempted to be deleted.
278
    - A confirmation prompt for the deletion of every single file system
279
      object is shown (unless the ``--yes`` option is used, in addition).
280
    """
281
    for path_glob in glob_patterns:
282
        log.debug('Erase file system objects matching: %s', path_glob)
283
        delete_filesystem_objects(directory, path_glob, prompt=not yes, dry_run=dry_run)
284
285
286
def recursive_delete_debris(directory, patterns):
287
    """
288
    Recursively delete debris matching any of the given patterns.
289
290
    This function walks the directory tree once and applies all patterns
291
    at each level, avoiding redundant directory scans.
292
    """
293
    for pattern in patterns:
294
        delete_filesystem_objects(directory, pattern)
295
296
    try:
297
        subdirs = (
298
            Path(entry.path) for entry in os.scandir(directory) if entry.is_dir()
0 ignored issues
show
Comprehensibility Best Practice introduced by
The variable entry does not seem to be defined.
Loading history...
299
        )
300
    except (OSError, PermissionError) as err:
301
        log.warning('Cannot access directory %s: %s', directory, err)
302
        return
303
304
    for subdir in subdirs:
305
        if should_ignore(subdir, Runner.ignore):
306
            log.debug('Skipping %s', subdir)
307
        else:
308
            recursive_delete_debris(subdir, patterns)
309
310
311
def delete_filesystem_objects(directory, path_glob, prompt=False, dry_run=False):
312
    """
313
    Identifies all pathnames matching a specific glob pattern, and attempts
314
    to delete them in the proper order, optionally asking for confirmation.
315
316
    Implementation Note: We sort the file system objects in *reverse order*
317
    and first delete *all files* before removing directories. This way we
318
    make sure that the directories that are deepest down in the hierarchy
319
    are empty (for both files & directories) when we attempt to remove them.
320
    """
321
    all_names = sorted(directory.glob(path_glob), reverse=True)
322
    dirs = (name for name in all_names if name.is_dir() and not name.is_symlink())
0 ignored issues
show
Comprehensibility Best Practice introduced by
The variable name does not seem to be defined.
Loading history...
323
    files = (name for name in all_names if not name.is_dir() or name.is_symlink())
324
325
    for file_object in files:
326
        file_type = 'symlink' if file_object.is_symlink() else 'file'
327
        if (
328
            not dry_run
329
            and prompt
330
            and not confirm('Delete %s %s' % (file_type, file_object))
331
        ):
332
            Runner.unlink_failed += 1
333
            continue
334
        Runner.unlink(file_object)
335
336
    for dir_object in dirs:
337
        if (
338
            not dry_run
339
            and prompt
340
            and not confirm('Remove empty directory %s' % dir_object)
341
        ):
342
            Runner.rmdir_failed += 1
343
            continue
344
        Runner.rmdir(dir_object)
345
346
347
def confirm(message):
348
    """An interactive confirmation prompt."""
349
    try:
350
        answer = input('%s? ' % message)
351
        return answer.strip().lower() in ['y', 'yes']
352
    except KeyboardInterrupt:
353
        msg = 'Aborted by user.'
354
        raise SystemExit(msg)
355
356
357
def detect_debris_in_directory(directory):
358
    """
359
    Scan a directory for debris artifacts and return a list of detected topics.
360
    """
361
    detected_topics = []
362
363
    for topic, patterns in DEBRIS_TOPICS.items():
364
        for pattern in patterns:
365
            # Skip patterns that are for recursive cleanup (contain **)
366
            if '**' in pattern:
367
                continue
368
            # Check if the pattern matches anything in the directory
369
            matches = list(directory.glob(pattern))
370
            if matches:
371
                detected_topics.append(topic)
372
                break  # Found at least one match for this topic, move to next
373
374
    return detected_topics
375
376
377
def suggest_debris_option(args):
378
    """
379
    Suggest using the --debris option when it wasn't used.
380
    Optionally provide targeted suggestions based on detected artifacts.
381
    """
382
    # Collect all detected debris topics across all directories
383
    all_detected = set()
384
    for dir_name in args.directory:
385
        dir_path = Path(dir_name)
386
        if dir_path.exists():
387
            detected = detect_debris_in_directory(dir_path)
388
            all_detected.update(detected)
389
390
    if all_detected:
391
        # Provide targeted suggestion
392
        topics_str = ' '.join(sorted(all_detected))
393
        log.info(
394
            'Hint: Use --debris to also clean up build artifacts. Detected: %s',
395
            topics_str,
396
        )
397
    else:
398
        # Provide general suggestion
399
        log.info(
400
            'Hint: Use --debris to also clean up build artifacts '
401
            'from common Python development tools.',
402
        )
403