pyclean.modern.detect_debris_in_directory() - Code Metrics - Inspection of "[WIP] Suggest --debris option for PyClean usage" - bittner/pyclean - Measure and Improve Code Quality continuously with Scrutinizer

Passed

Pull Request — main (#95)

unknown

created 2025-10-15 16:04 UTC

pyclean.modern.detect_debris_in_directory() A

↳ Parent: pyclean.modern

Complexity

Conditions

Size

Total Lines	18
Code Lines	11

Duplication

Lines	0
Ratio	0 %

Importance

Changes

Metric	Value
eloc	11
dl	0
loc	18
rs	9.3333
c	0
b	0
f	0
cc	5
nop	1

# SPDX-FileCopyrightText: 2020 Peter Bittner <[email protected]>
#
# SPDX-License-Identifier: GPL-3.0-or-later

"""
Modern, cross-platform, pure-Python pyclean implementation.
"""

import logging
import os
from pathlib import Path

BYTECODE_FILES = ['.pyc', '.pyo']
BYTECODE_DIRS = ['__pycache__']
DEBRIS_TOPICS = {
    'cache': [
        '.cache/**/*',
        '.cache/',
    ],
    'coverage': [
        '.coverage',
        'coverage.json',
        'coverage.lcov',
        'coverage.xml',
        'htmlcov/**/*',
        'htmlcov/',
    ],
    'jupyter': [
        '.ipynb_checkpoints/**/*',
        '.ipynb_checkpoints/',
    ],
    'mypy': [
        '.mypy_cache/**/*',
        '.mypy_cache/',
    ],
    'package': [
        'build/bdist.*/**/*',
        'build/bdist.*/',
        'build/lib/**/*',
        'build/lib/',
        'build/',
        'dist/**/*',
        'dist/',
        'sdist/**/*',
        'sdist/',
        '*.egg-info/**/*',
        '*.egg-info/',
    ],
    'pytest': [
        '.pytest_cache/**/*',
        '.pytest_cache/',
        'pytestdebug.log',
    ],
    'ruff': [
        '.ruff_cache/**/*',
        '.ruff_cache/',
    ],
    'tox': [
        '.tox/**/*',
        '.tox/',
    ],
}


class CleanupRunner:
    """Module-level configuration and value store."""

    def __init__(self):
        """Cleanup runner with optional dry-run behavior."""
        self.unlink = None
        self.rmdir = None
        self.ignore = None
        self.unlink_count = None
        self.unlink_failed = None
        self.rmdir_count = None
        self.rmdir_failed = None

    def configure(self, args):
        """Set up runner according to command line options."""
        self.unlink = print_filename if args.dry_run else remove_file
        self.rmdir = print_dirname if args.dry_run else remove_directory
        self.ignore = args.ignore
        self.unlink_count = 0
        self.unlink_failed = 0
        self.rmdir_count = 0
        self.rmdir_failed = 0


log = logging.getLogger(__name__)
Runner = CleanupRunner()


def remove_file(fileobj):
    """Attempt to delete a file object for real."""
    log.debug('Deleting file: %s', fileobj)
    try:
        fileobj.unlink()
        Runner.unlink_count += 1
    except OSError as err:
        log.debug('File not deleted. %s', err)
        Runner.unlink_failed += 1


def remove_directory(dirobj):
    """Attempt to remove a directory object for real."""
    log.debug('Removing directory: %s', dirobj)
    try:
        dirobj.rmdir()
        Runner.rmdir_count += 1
    except OSError as err:
        log.debug('Directory not removed. %s', err)
        Runner.rmdir_failed += 1


def print_filename(fileobj):
    """Only display the file name, used with --dry-run."""
    log.debug('Would delete file: %s', fileobj)
    Runner.unlink_count += 1


def print_dirname(dirobj):
    """Only display the directory name, used with --dry-run."""
    log.debug('Would delete directory: %s', dirobj)
    Runner.rmdir_count += 1


def pyclean(args):
    """Cross-platform cleaning of Python bytecode."""
    Runner.configure(args)

    for dir_name in args.directory:
        dir_path = Path(dir_name)

        log.info('Cleaning directory %s', dir_path)
        descend_and_clean(dir_path, BYTECODE_FILES, BYTECODE_DIRS)

        for topic in args.debris:
            remove_debris_for(topic, dir_path)

        remove_freeform_targets(args.erase, args.yes, dir_path)

    log.info(
        'Total %d files, %d directories %s.',
        Runner.unlink_count,
        Runner.rmdir_count,
        'would be removed' if args.dry_run else 'removed',
    )

    if Runner.unlink_failed or Runner.rmdir_failed:
        log.debug(
            '%d files, %d directories %s not be removed.',
            Runner.unlink_failed,
            Runner.rmdir_failed,
            'would' if args.dry_run else 'could',
        )

    # Suggest --debris option if it wasn't used
    if not args.debris:
        suggest_debris_option(args)


def descend_and_clean(directory, file_types, dir_names):
    """
    Walk and descend a directory tree, cleaning up files of a certain type
    along the way. Only delete directories if they are empty, in the end.
    """
    for child in sorted(directory.iterdir()):
        if child.is_file():
            if child.suffix in file_types:
                Runner.unlink(child)
        elif child.is_dir():
            if child.name in Runner.ignore:
                log.debug('Skipping %s', child)
            else:
                descend_and_clean(child, file_types, dir_names)

            if child.name in dir_names:
                Runner.rmdir(child)
        else:
            log.debug('Ignoring %s (neither a file nor a folder)', child)


def remove_debris_for(topic, directory):
    """
    Clean up debris for a specific topic.
    """
    log.debug('Scanning for debris of %s ...', topic.title())

    for path_glob in DEBRIS_TOPICS[topic]:
        delete_filesystem_objects(directory, path_glob, recursive=True)


def remove_freeform_targets(glob_patterns, yes, directory):
    """
    Remove free-form targets using globbing.

    This is **potentially dangerous** since users can delete everything
    anywhere in their file system, including the entire project they're
    working on. For this reason, the implementation imposes the following
    (user experience-related) restrictions:

    - Deleting (directories) is not recursive, directory contents must be
      explicitly specified using globbing (e.g. ``dirname/**/*``).
    - The user is responsible for the deletion order, so that a directory
      is empty when it is attempted to be deleted.
    - A confirmation prompt for the deletion of every single file system
      object is shown (unless the ``--yes`` option is used, in addition).
    """
    for path_glob in glob_patterns:
        log.debug('Erase file system objects matching: %s', path_glob)
        delete_filesystem_objects(directory, path_glob, prompt=not yes)


def delete_filesystem_objects(directory, path_glob, prompt=False, recursive=False):
    """
    Identifies all pathnames matching a specific glob pattern, and attempts
    to delete them in the proper order, optionally asking for confirmation.

    Implementation Note: We sort the file system objects in *reverse order*
    and first delete *all files* before removing directories. This way we
    make sure that the directories that are deepest down in the hierarchy
    are empty (for both files & directories) when we attempt to remove them.
    """
    all_names = sorted(directory.glob(path_glob), reverse=True)
    dirs = (name for name in all_names if name.is_dir() and not name.is_symlink())

    files = (name for name in all_names if not name.is_dir() or name.is_symlink())

    for file_object in files:
        file_type = 'symlink' if file_object.is_symlink() else 'file'
        if prompt and not confirm('Delete %s %s' % (file_type, file_object)):
            Runner.unlink_failed += 1
            continue
        Runner.unlink(file_object)

    for dir_object in dirs:
        if prompt and not confirm('Remove empty directory %s' % dir_object):
            Runner.rmdir_failed += 1
            continue
        Runner.rmdir(dir_object)

    if recursive:
        subdirs = (Path(name.path) for name in os.scandir(directory) if name.is_dir())
        for subdir in subdirs:
            if subdir.name in Runner.ignore:
                log.debug('Skipping %s', subdir)
            else:
                delete_filesystem_objects(subdir, path_glob, prompt, recursive)


def confirm(message):
    """An interactive confirmation prompt."""
    try:
        answer = input('%s? ' % message)
        return answer.strip().lower() in ['y', 'yes']
    except KeyboardInterrupt:
        msg = 'Aborted by user.'
        raise SystemExit(msg)


def detect_debris_in_directory(directory):
    """
    Scan a directory for debris artifacts and return a list of detected topics.
    """
    detected_topics = []

    for topic, patterns in DEBRIS_TOPICS.items():
        for pattern in patterns:
            # Skip patterns that are for recursive cleanup (contain **)
            if '**' in pattern:
                continue
            # Check if the pattern matches anything in the directory
            matches = list(directory.glob(pattern))
            if matches:
                detected_topics.append(topic)
                break  # Found at least one match for this topic, move to next

    return detected_topics


def suggest_debris_option(args):
    """
    Suggest using the --debris option when it wasn't used.
    Optionally provide targeted suggestions based on detected artifacts.
    """
    # Collect all detected debris topics across all directories
    all_detected = set()
    for dir_name in args.directory:
        dir_path = Path(dir_name)
        if dir_path.exists():
            detected = detect_debris_in_directory(dir_path)
            all_detected.update(detected)

    if all_detected:
        # Provide targeted suggestion
        topics_str = ' '.join(sorted(all_detected))
        log.info(
            'Hint: Use --debris to also clean up build artifacts. Detected: %s',
            topics_str,
        )
    else:
        # Provide general suggestion
        log.info(
            'Hint: Use --debris to also clean up build artifacts '
            'from common Python development tools.',
        )


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 remove_file(fileobj):
94			"""Attempt to delete a file object for real."""
95			log.debug('Deleting file: %s', fileobj)
96			try:
97			fileobj.unlink()
98			Runner.unlink_count += 1
99			except OSError as err:
100			log.debug('File not deleted. %s', err)
101			Runner.unlink_failed += 1
102
103
104			def remove_directory(dirobj):
105			"""Attempt to remove a directory object for real."""
106			log.debug('Removing directory: %s', dirobj)
107			try:
108			dirobj.rmdir()
109			Runner.rmdir_count += 1
110			except OSError as err:
111			log.debug('Directory not removed. %s', err)
112			Runner.rmdir_failed += 1
113
114
115			def print_filename(fileobj):
116			"""Only display the file name, used with --dry-run."""
117			log.debug('Would delete file: %s', fileobj)
118			Runner.unlink_count += 1
119
120
121			def print_dirname(dirobj):
122			"""Only display the directory name, used with --dry-run."""
123			log.debug('Would delete directory: %s', dirobj)
124			Runner.rmdir_count += 1
125
126
127			def pyclean(args):
128			"""Cross-platform cleaning of Python bytecode."""
129			Runner.configure(args)
130
131			for dir_name in args.directory:
132			dir_path = Path(dir_name)
133
134			log.info('Cleaning directory %s', dir_path)
135			descend_and_clean(dir_path, BYTECODE_FILES, BYTECODE_DIRS)
136
137			for topic in args.debris:
138			remove_debris_for(topic, dir_path)
139
140			remove_freeform_targets(args.erase, args.yes, dir_path)
141
142			log.info(
143			'Total %d files, %d directories %s.',
144			Runner.unlink_count,
145			Runner.rmdir_count,
146			'would be removed' if args.dry_run else 'removed',
147			)
148
149			if Runner.unlink_failed or Runner.rmdir_failed:
150			log.debug(
151			'%d files, %d directories %s not be removed.',
152			Runner.unlink_failed,
153			Runner.rmdir_failed,
154			'would' if args.dry_run else 'could',
155			)
156
157			# Suggest --debris option if it wasn't used
158			if not args.debris:
159			suggest_debris_option(args)
160
161
162			def descend_and_clean(directory, file_types, dir_names):
163			"""
164			Walk and descend a directory tree, cleaning up files of a certain type
165			along the way. Only delete directories if they are empty, in the end.
166			"""
167			for child in sorted(directory.iterdir()):
168			if child.is_file():
169			if child.suffix in file_types:
170			Runner.unlink(child)
171			elif child.is_dir():
172			if child.name in Runner.ignore:
173			log.debug('Skipping %s', child)
174			else:
175			descend_and_clean(child, file_types, dir_names)
176
177			if child.name in dir_names:
178			Runner.rmdir(child)
179			else:
180			log.debug('Ignoring %s (neither a file nor a folder)', child)
181
182
183			def remove_debris_for(topic, directory):
184			"""
185			Clean up debris for a specific topic.
186			"""
187			log.debug('Scanning for debris of %s ...', topic.title())
188
189			for path_glob in DEBRIS_TOPICS[topic]:
190			delete_filesystem_objects(directory, path_glob, recursive=True)
191
192
193			def remove_freeform_targets(glob_patterns, yes, directory):
194			"""
195			Remove free-form targets using globbing.
196
197			This is potentially dangerous since users can delete everything
198			anywhere in their file system, including the entire project they're
199			working on. For this reason, the implementation imposes the following
200			(user experience-related) restrictions:
201
202			- Deleting (directories) is not recursive, directory contents must be
203			explicitly specified using globbing (e.g. ``dirname/*/``).
204			- The user is responsible for the deletion order, so that a directory
205			is empty when it is attempted to be deleted.
206			- A confirmation prompt for the deletion of every single file system
207			object is shown (unless the ``--yes`` option is used, in addition).
208			"""
209			for path_glob in glob_patterns:
210			log.debug('Erase file system objects matching: %s', path_glob)
211			delete_filesystem_objects(directory, path_glob, prompt=not yes)
212
213
214			def delete_filesystem_objects(directory, path_glob, prompt=False, recursive=False):
215			"""
216			Identifies all pathnames matching a specific glob pattern, and attempts
217			to delete them in the proper order, optionally asking for confirmation.
218
219			Implementation Note: We sort the file system objects in reverse order
220			and first delete all files before removing directories. This way we
221			make sure that the directories that are deepest down in the hierarchy
222			are empty (for both files & directories) when we attempt to remove them.
223			"""
224			all_names = sorted(directory.glob(path_glob), reverse=True)
225			dirs = (name for name in all_names if name.is_dir() and not name.is_symlink())
			0 ignored issues – show Comprehensibility Best Practice introduced 2023-01-27 09:22 UTC by Report Bug Copy Issue Report The variable `name` does not seem to be defined. Loading history...
226			files = (name for name in all_names if not name.is_dir() or name.is_symlink())
227
228			for file_object in files:
229			file_type = 'symlink' if file_object.is_symlink() else 'file'
230			if prompt and not confirm('Delete %s %s' % (file_type, file_object)):
231			Runner.unlink_failed += 1
232			continue
233			Runner.unlink(file_object)
234
235			for dir_object in dirs:
236			if prompt and not confirm('Remove empty directory %s' % dir_object):
237			Runner.rmdir_failed += 1
238			continue
239			Runner.rmdir(dir_object)
240
241			if recursive:
242			subdirs = (Path(name.path) for name in os.scandir(directory) if name.is_dir())
243			for subdir in subdirs:
244			if subdir.name in Runner.ignore:
245			log.debug('Skipping %s', subdir)
246			else:
247			delete_filesystem_objects(subdir, path_glob, prompt, recursive)
248
249
250			def confirm(message):
251			"""An interactive confirmation prompt."""
252			try:
253			answer = input('%s? ' % message)
254			return answer.strip().lower() in ['y', 'yes']
255			except KeyboardInterrupt:
256			msg = 'Aborted by user.'
257			raise SystemExit(msg)
258
259
260			def detect_debris_in_directory(directory):
261			"""
262			Scan a directory for debris artifacts and return a list of detected topics.
263			"""
264			detected_topics = []
265
266			for topic, patterns in DEBRIS_TOPICS.items():
267			for pattern in patterns:
268			# Skip patterns that are for recursive cleanup (contain **)
269			if '**' in pattern:
270			continue
271			# Check if the pattern matches anything in the directory
272			matches = list(directory.glob(pattern))
273			if matches:
274			detected_topics.append(topic)
275			break # Found at least one match for this topic, move to next
276
277			return detected_topics
278
279
280			def suggest_debris_option(args):
281			"""
282			Suggest using the --debris option when it wasn't used.
283			Optionally provide targeted suggestions based on detected artifacts.
284			"""
285			# Collect all detected debris topics across all directories
286			all_detected = set()
287			for dir_name in args.directory:
288			dir_path = Path(dir_name)
289			if dir_path.exists():
290			detected = detect_debris_in_directory(dir_path)
291			all_detected.update(detected)
292
293			if all_detected:
294			# Provide targeted suggestion
295			topics_str = ' '.join(sorted(all_detected))
296			log.info(
297			'Hint: Use --debris to also clean up build artifacts. Detected: %s',
298			topics_str,
299			)
300			else:
301			# Provide general suggestion
302			log.info(
303			'Hint: Use --debris to also clean up build artifacts '
304			'from common Python development tools.',
305			)
306

bittner / pyclean

Pull Request — main (#95)

pyclean.modern.detect_debris_in_directory() A

Complexity

Size

Duplication

Importance

Duplication Side-by-Side

Filter issues like