new module: filesize - create or resize a file, given its size (#2232)

* new module: filesize

* description: create or resize a file, given its size
* with integration tests

* Update plugins/modules/files/filesize.py (version_added)

Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>

* Update filesize.py (extends_documentation_fragment: use fqcn)

Co-authored-by: Amin Vakil <info@aminvakil.com>

* doc: use strict lowercase booleans (true/false) rather than other variants

* use *raw* type to manage size values

* drop 'miB' unit family

* Apply suggestions from code review

Co-authored-by: Felix Fontein <felix@fontein.de>

* add more details

Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>
Co-authored-by: Amin Vakil <info@aminvakil.com>
Co-authored-by: Felix Fontein <felix@fontein.de>

tests/integration/targets/filesize/tasks/symlinks.yml

@@ -0,0 +1,93 @@
+---
+# Check that the module works with symlinks, as expected, i.e. as dd does:
+# follow symlinks.
+
+- name: Ensure the test file is absent
+  ansible.builtin.file:
+    path: "{{ filesize_testfile }}"
+    state: absent
+
+- name: Create a broken symlink in the same directory
+  ansible.builtin.file:
+    src:  "{{ filesize_testfile | basename }}"
+    dest: "{{ filesize_testlink }}"
+    state: link
+    force: yes
+    follow: no
+
+
+
+- name: Create a file with a size of 512 kB (512000 bytes) (check mode)
+  community.general.filesize:
+    path: "{{ filesize_testlink }}"
+    size: "512 kB"
+  register: filesize_test_symlink_01
+  check_mode: yes
+
+- name: Create a file with a size of 512 kB (512000 bytes)
+  community.general.filesize:
+    path: "{{ filesize_testlink }}"
+    size: "512 kB"
+  register: filesize_test_symlink_02
+
+- name: Stat the resulting file (not the symlink)
+  ansible.builtin.stat:
+    path: "{{ filesize_test_symlink_02.path }}"
+  register: filesize_stat_symlink_02
+
+
+- name: Create a file with a size of 500 KiB (512000 bytes) (check mode, idempotency)
+  community.general.filesize:
+    path: "{{ filesize_testlink }}"
+    size: "500 KiB"
+  register: filesize_test_symlink_03
+  check_mode: yes
+
+- name: Create a file with a size of 500 KiB (512000 bytes) (idempotency)
+  community.general.filesize:
+    path: "{{ filesize_testlink }}"
+    size: "500 KiB"
+  register: filesize_test_symlink_04
+
+- name: Stat the file again (should remain the same)
+  ansible.builtin.stat:
+    path: "{{ filesize_test_symlink_04.path }}"
+  register: filesize_stat_symlink_04
+
+
+- name: Assert that results are as expected
+  ansible.builtin.assert:
+    that:
+      - filesize_test_symlink_01 is changed
+      - filesize_test_symlink_02 is changed
+      - filesize_test_symlink_03 is not changed
+      - filesize_test_symlink_04 is not changed
+
+      - filesize_test_symlink_02.cmd == filesize_test_symlink_01.cmd
+      - filesize_test_symlink_03.cmd is undefined
+      - filesize_test_symlink_04.cmd is undefined
+
+      - filesize_test_symlink_01.state is undefined
+      - filesize_test_symlink_02.state in ["file"]
+      - filesize_test_symlink_01.size is undefined
+      - filesize_test_symlink_02.size == 512000
+      - filesize_test_symlink_03.size == 512000
+      - filesize_test_symlink_04.size == 512000
+
+      - filesize_stat_symlink_02.stat.size == 512000
+      - filesize_stat_symlink_04.stat.size == 512000
+
+      - filesize_test_symlink_04.path == filesize_test_symlink_02.path
+      - filesize_test_symlink_04.path != filesize_testlink
+
+
+
+- name: Remove test file
+  ansible.builtin.file:
+    path: "{{ filesize_testfile }}"
+    state: absent
+
+- name: Remove test link
+  ansible.builtin.file:
+    path: "{{ filesize_testlink }}"
+    state: absent