Passed
Pull Request — main (#103)
by
unknown
01:16
created

pyclean.modern.CleanupRunner.configure()   A

Complexity

Conditions 3

Size

Total Lines 9
Code Lines 8

Duplication

Lines 0
Ratio 0 %

Importance

Changes 0
Metric Value
cc 3
eloc 8
nop 2
dl 0
loc 9
rs 10
c 0
b 0
f 0
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 after processing their contents.
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
            # Recursively process subdirectories first
258
            remove_empty_directories(subdir)
259
            # Try to remove the directory if it's empty
260
            try:
261
                # Check if directory is empty
262
                if not any(subdir.iterdir()):
263
                    Runner.rmdir(subdir)
264
            except (OSError, PermissionError) as err:
265
                log.debug('Cannot check or remove directory %s: %s', subdir, err)
266
267
268
def remove_freeform_targets(directory, glob_patterns, yes, dry_run=False):
269
    """
270
    Remove free-form targets using globbing.
271
272
    This is **potentially dangerous** since users can delete everything
273
    anywhere in their file system, including the entire project they're
274
    working on. For this reason, the implementation imposes the following
275
    (user experience-related) restrictions:
276
277
    - Deleting (directories) is not recursive, directory contents must be
278
      explicitly specified using globbing (e.g. ``dirname/**/*``).
279
    - The user is responsible for the deletion order, so that a directory
280
      is empty when it is attempted to be deleted.
281
    - A confirmation prompt for the deletion of every single file system
282
      object is shown (unless the ``--yes`` option is used, in addition).
283
    """
284
    for path_glob in glob_patterns:
285
        log.debug('Erase file system objects matching: %s', path_glob)
286
        delete_filesystem_objects(directory, path_glob, prompt=not yes, dry_run=dry_run)
287
288
289
def recursive_delete_debris(directory, patterns):
290
    """
291
    Recursively delete debris matching any of the given patterns.
292
293
    This function walks the directory tree once and applies all patterns
294
    at each level, avoiding redundant directory scans.
295
    """
296
    for pattern in patterns:
297
        delete_filesystem_objects(directory, pattern)
298
299
    try:
300
        subdirs = (
301
            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...
302
        )
303
    except (OSError, PermissionError) as err:
304
        log.warning('Cannot access directory %s: %s', directory, err)
305
        return
306
307
    for subdir in subdirs:
308
        if should_ignore(subdir, Runner.ignore):
309
            log.debug('Skipping %s', subdir)
310
        else:
311
            recursive_delete_debris(subdir, patterns)
312
313
314
def delete_filesystem_objects(directory, path_glob, prompt=False, dry_run=False):
315
    """
316
    Identifies all pathnames matching a specific glob pattern, and attempts
317
    to delete them in the proper order, optionally asking for confirmation.
318
319
    Implementation Note: We sort the file system objects in *reverse order*
320
    and first delete *all files* before removing directories. This way we
321
    make sure that the directories that are deepest down in the hierarchy
322
    are empty (for both files & directories) when we attempt to remove them.
323
    """
324
    all_names = sorted(directory.glob(path_glob), reverse=True)
325
    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...
326
    files = (name for name in all_names if not name.is_dir() or name.is_symlink())
327
328
    for file_object in files:
329
        file_type = 'symlink' if file_object.is_symlink() else 'file'
330
        if (
331
            not dry_run
332
            and prompt
333
            and not confirm('Delete %s %s' % (file_type, file_object))
334
        ):
335
            Runner.unlink_failed += 1
336
            continue
337
        Runner.unlink(file_object)
338
339
    for dir_object in dirs:
340
        if (
341
            not dry_run
342
            and prompt
343
            and not confirm('Remove empty directory %s' % dir_object)
344
        ):
345
            Runner.rmdir_failed += 1
346
            continue
347
        Runner.rmdir(dir_object)
348
349
350
def confirm(message):
351
    """An interactive confirmation prompt."""
352
    try:
353
        answer = input('%s? ' % message)
354
        return answer.strip().lower() in ['y', 'yes']
355
    except KeyboardInterrupt:
356
        msg = 'Aborted by user.'
357
        raise SystemExit(msg)
358
359
360
def detect_debris_in_directory(directory):
361
    """
362
    Scan a directory for debris artifacts and return a list of detected topics.
363
    """
364
    detected_topics = []
365
366
    for topic, patterns in DEBRIS_TOPICS.items():
367
        for pattern in patterns:
368
            # Skip patterns that are for recursive cleanup (contain **)
369
            if '**' in pattern:
370
                continue
371
            # Check if the pattern matches anything in the directory
372
            matches = list(directory.glob(pattern))
373
            if matches:
374
                detected_topics.append(topic)
375
                break  # Found at least one match for this topic, move to next
376
377
    return detected_topics
378
379
380
def suggest_debris_option(args):
381
    """
382
    Suggest using the --debris option when it wasn't used.
383
    Optionally provide targeted suggestions based on detected artifacts.
384
    """
385
    # Collect all detected debris topics across all directories
386
    all_detected = set()
387
    for dir_name in args.directory:
388
        dir_path = Path(dir_name)
389
        if dir_path.exists():
390
            detected = detect_debris_in_directory(dir_path)
391
            all_detected.update(detected)
392
393
    if all_detected:
394
        # Provide targeted suggestion
395
        topics_str = ' '.join(sorted(all_detected))
396
        log.info(
397
            'Hint: Use --debris to also clean up build artifacts. Detected: %s',
398
            topics_str,
399
        )
400
    else:
401
        # Provide general suggestion
402
        log.info(
403
            'Hint: Use --debris to also clean up build artifacts '
404
            'from common Python development tools.',
405
        )
406