Passed
Pull Request — main (#103)
by Peter
01:14
created

pyclean.modern.pyclean()   C

Complexity

Conditions 9

Size

Total Lines 37
Code Lines 25

Duplication

Lines 0
Ratio 0 %

Importance

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