Add New Module file_remove #11032

shahargolshani · 2025-11-05T11:17:55Z

SUMMARY

This PR introduces a new module, `file_remove`, designed to idempotently delete a single file from a target host.

Rationale: This module serves as an enhancement for many file deletion cases not currently supported by ansible.builtin.file with state=absent.

Pattern-based deletion: It allows using regular expressions to remove multiple files that match a specific pattern (e.g., all .log or .tmp files) in a single task.

Design: This avoids the common workaround of using ansible.builtin.find, registering the results, and then looping over them with ansible.builtin.file. This module performs that entire operation idempotently in one step.

This new module provides a more powerful and intuitive interface for these common "clean-up" style operations.

changelog: New Module

ISSUE TYPE

New Module/Plugin Pull Request

COMPONENT NAME

file_remove

ADDITIONAL INFORMATION

(New module)

felixfontein · 2025-11-05T21:47:57Z

The typing errors are unrelated and have been fixed in another PR.

kginonredhat

Looks good

russoz

hi @shahargolshani Thanks for your contribution!

Overall it looks good, just a few adjustments. I have not checked the logic of the tests, but the use case for this is not very complex, I am trusting they are covering what's needed.

plugins/modules/file_remove.py

tests/integration/targets/file_remove/aliases

felixfontein

Thanks for your contribution!

plugins/modules/file_remove.py

russoz

Hi @shahargolshani thanks for the updates. Still a couple of dangling bits, but much closer to complete

tests/integration/targets/file_remove/tasks/main.yml

plugins/modules/file_remove.py

russoz

LGTM! Thanks!

felixfontein

How about adding type hints? Now that we have type checking and no longer support Python before 3.7, this would improve the module code's quality :)

I've added some suggestions below, I think this should do it (I haven't tested it though).

felixfontein · 2025-11-10T20:52:43Z

plugins/modules/file_remove.py

+files_count:
+  description: Number of files removed.
+  type: int
+  returned: always


Suggested change

returned: always

returned: success

felixfontein · 2025-11-10T20:52:50Z

plugins/modules/file_remove.py

+path:
+  description: The directory path that was searched.
+  type: str
+  returned: always


This return value is only returned when exit_json() is called.

Suggested change

returned: always

returned: success

felixfontein · 2025-11-10T20:53:51Z

plugins/modules/file_remove.py

+    path = module.params["path"]
+    pattern = module.params["pattern"]
+    use_regex = module.params["use_regex"]
+    recursive = module.params["recursive"]
+    file_type = module.params["file_type"]


Suggested change

path = module.params["path"]

pattern = module.params["pattern"]

use_regex = module.params["use_regex"]

recursive = module.params["recursive"]

file_type = module.params["file_type"]

path: str = module.params["path"]

pattern: str = module.params["pattern"]

use_regex: bool = module.params["use_regex"]

recursive: bool = module.params["recursive"]

file_type: t.Literal["file", "link", "any"] = module.params["file_type"]

felixfontein · 2025-11-10T20:54:04Z

plugins/modules/file_remove.py

+
+import os
+import re
+import glob


Suggested change

import glob

import glob

import typing as t

felixfontein · 2025-11-10T20:54:48Z

plugins/modules/file_remove.py

+from ansible.module_utils.basic import AnsibleModule
+
+
+def find_matching_files(path, pattern, use_regex, recursive, file_type):


Suggested change

def find_matching_files(path, pattern, use_regex, recursive, file_type):

def find_matching_files(path: str, pattern: str, use_regex: bool, recursive: bool, file_type: t.Literal["file", "link", "any"]) -> list[str]:

felixfontein · 2025-11-10T20:55:03Z

plugins/modules/file_remove.py

+    return sorted(matching_files)
+
+
+def should_include_file(file_path, file_type):


Suggested change

def should_include_file(file_path, file_type):

def should_include_file(file_path: str, file_type: t.Literal["file", "link", "any"]) -> bool:

felixfontein · 2025-11-10T20:55:20Z

plugins/modules/file_remove.py

+    return False
+
+
+def remove_files(module, files):


Suggested change

def remove_files(module, files):

def remove_files(module: AnsibleModule, files: list[str]) -> tuple[list[str], list[str]]:

felixfontein · 2025-11-10T20:55:26Z

plugins/modules/file_remove.py

+    return removed_files, failed_files
+
+
+def main():


Suggested change

def main():

def main() -> None:

ansibullbot added integration tests/integration module module plugins plugin (any type) tests tests labels Nov 5, 2025

This comment was marked as resolved.

Sign in to view

ansibullbot added ci_verified Push fixes to PR branch to re-run CI needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR labels Nov 5, 2025

shahargolshani force-pushed the dev/file_remove branch from 5b8e67c to fc19d13 Compare November 5, 2025 11:39

ansibullbot removed ci_verified Push fixes to PR branch to re-run CI needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR labels Nov 5, 2025

shahargolshani force-pushed the dev/file_remove branch from fc19d13 to c2250a8 Compare November 5, 2025 12:08

felixfontein added check-before-release PR will be looked at again shortly before release and merged if possible. backport-12 Automatically create a backport for the stable-12 branch labels Nov 5, 2025

shahargolshani force-pushed the dev/file_remove branch 2 times, most recently from 482a0e2 to cdb95e8 Compare November 6, 2025 10:28

kginonredhat approved these changes Nov 6, 2025

View reviewed changes

shahargolshani added 5 commits November 6, 2025 20:01

Add New Module file_remove

2f79422

Add fixes from code review

31765e4

Change file_type documentation

e1154a4

Remove python to_native from the module

296de23

Remove redundant block/always cleanup

49c8e5b

russoz reviewed Nov 7, 2025

View reviewed changes

plugins/modules/file_remove.py Outdated Show resolved Hide resolved

tests/integration/targets/file_remove/aliases Outdated Show resolved Hide resolved

felixfontein reviewed Nov 7, 2025

View reviewed changes

shahargolshani force-pushed the dev/file_remove branch 2 times, most recently from 41e7806 to 31765e4 Compare November 9, 2025 15:41

shahargolshani requested review from felixfontein and russoz November 9, 2025 15:51

russoz reviewed Nov 9, 2025

View reviewed changes

tests/integration/targets/file_remove/tasks/main.yml Outdated Show resolved Hide resolved

plugins/modules/file_remove.py Outdated Show resolved Hide resolved

plugins/modules/file_remove.py Outdated Show resolved Hide resolved

shahargolshani requested a review from russoz November 10, 2025 12:43

russoz approved these changes Nov 10, 2025

View reviewed changes

felixfontein reviewed Nov 10, 2025

View reviewed changes

		from ansible.module_utils.basic import AnsibleModule


		def find_matching_files(path, pattern, use_regex, recursive, file_type):

	def find_matching_files(path, pattern, use_regex, recursive, file_type):
	def find_matching_files(path: str, pattern: str, use_regex: bool, recursive: bool, file_type: t.Literal["file", "link", "any"]) -> list[str]:

		return sorted(matching_files)


		def should_include_file(file_path, file_type):

	def should_include_file(file_path, file_type):
	def should_include_file(file_path: str, file_type: t.Literal["file", "link", "any"]) -> bool:

	def remove_files(module, files):
	def remove_files(module: AnsibleModule, files: list[str]) -> tuple[list[str], list[str]]:

Add New Module file_remove #11032

Are you sure you want to change the base?

Add New Module file_remove #11032

Conversation

shahargolshani commented Nov 5, 2025

SUMMARY

This PR introduces a new module, file_remove, designed to idempotently delete a single file from a target host.

Rationale: This module serves as an enhancement for many file deletion cases not currently supported by ansible.builtin.file with state=absent.

Pattern-based deletion: It allows using regular expressions to remove multiple files that match a specific pattern (e.g., all *.log or *.tmp files) in a single task.

Design: This avoids the common workaround of using ansible.builtin.find, registering the results, and then looping over them with ansible.builtin.file. This module performs that entire operation idempotently in one step.

This new module provides a more powerful and intuitive interface for these common "clean-up" style operations.

changelog: New Module

ISSUE TYPE

COMPONENT NAME

ADDITIONAL INFORMATION

Uh oh!

This comment was marked as resolved.

felixfontein commented Nov 5, 2025

Uh oh!

kginonredhat left a comment

Choose a reason for hiding this comment

Uh oh!

russoz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

felixfontein left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

russoz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

russoz left a comment

Choose a reason for hiding this comment

Uh oh!

felixfontein left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

This PR introduces a new module, `file_remove`, designed to idempotently delete a single file from a target host.

Pattern-based deletion: It allows using regular expressions to remove multiple files that match a specific pattern (e.g., all .log or .tmp files) in a single task.