New Filter plugin from_csv (#2037)

* Added from_csv filter and integration tests

* Cleaning up whitespace

* Adding changelog fragment

* Updated changelog fragment name

* Removed temp fragment

* Refactoring csv functions Part 1

* Syncing refactored csv modules/filters

* Adding unit tests for csv Module_Util

* Updating changelog fragment

* Correcting whitespace in unit test

* Improving changelog fragment

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

* Update changelogs/fragments/2037-add-from-csv-filter.yml

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

tests/integration/targets/filter_from_csv/aliases

@@ -0,0 +1,2 @@
+shippable/posix/group2
+skip/python2.6  # filters are controller only, and we no longer support Python 2.6 on the controller

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

@@ -0,0 +1,49 @@
+####################################################################
+# WARNING: These are designed specifically for Ansible tests       #
+# and should not be used as examples of how to write Ansible roles #
+####################################################################
+
+- name: Parse valid csv input
+  assert:
+    that:
+      - "valid_comma_separated | community.general.from_csv  ==  expected_result"
+
+- name: Parse valid csv input containing spaces with/without skipinitialspace=True
+  assert:
+    that:
+      - "valid_comma_separated_spaces | community.general.from_csv(skipinitialspace=True)  ==  expected_result"
+      - "valid_comma_separated_spaces | community.general.from_csv  !=  expected_result"
+
+- name: Parse valid csv input with no headers with/without specifiying fieldnames
+  assert:
+    that:
+      - "valid_comma_separated_no_headers | community.general.from_csv(fieldnames=['id','name','role'])  ==  expected_result"
+      - "valid_comma_separated_no_headers | community.general.from_csv  !=  expected_result"
+
+- name: Parse valid pipe-delimited csv input with/without delimiter=|
+  assert:
+    that:
+      - "valid_pipe_separated | community.general.from_csv(delimiter='|')  ==  expected_result"
+      - "valid_pipe_separated | community.general.from_csv  !=  expected_result"
+
+- name: Register result of invalid csv input when strict=False
+  debug:
+    var: "invalid_comma_separated | community.general.from_csv"
+  register: _invalid_csv_strict_false
+
+- name: Test invalid csv input when strict=False is successful
+  assert:
+    that:
+      - _invalid_csv_strict_false is success
+
+- name: Register result of invalid csv input when strict=True
+  debug:
+    var: "invalid_comma_separated | community.general.from_csv(strict=True)"
+  register: _invalid_csv_strict_true
+  ignore_errors: True
+
+- name: Test invalid csv input when strict=True is failed
+  assert:
+    that:
+      - _invalid_csv_strict_true is failed
+      - _invalid_csv_strict_true.msg is match('Unable to process file:.*')

tests/integration/targets/filter_from_csv/vars/main.yml

@@ -0,0 +1,26 @@
+valid_comma_separated: |
+  id,name,role
+  1,foo,bar
+  2,bar,baz
+valid_comma_separated_spaces: |
+  id,name,role
+  1, foo, bar
+  2, bar, baz
+valid_comma_separated_no_headers: |
+  1,foo,bar
+  2,bar,baz
+valid_pipe_separated: |
+  id|name|role
+  1|foo|bar
+  2|bar|baz
+invalid_comma_separated: |
+  id,name,role
+  1,foo,bar
+  2,"b"ar",baz
+expected_result:
+  - id: '1'
+    name: foo
+    role: bar
+  - id: '2'
+    name: bar
+    role: baz

tests/unit/plugins/module_utils/test_csv.py

@@ -0,0 +1,164 @@
+# -*- coding: utf-8 -*-
+
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import pytest
+
+from ansible_collections.community.general.plugins.module_utils import csv
+
+
+VALID_CSV = [
+    (
+        'excel',
+        {},
+        None,
+        "id,name,role\n1,foo,bar\n2,bar,baz",
+        [
+            {
+                "id": "1",
+                "name": "foo",
+                "role": "bar",
+            },
+            {
+                "id": "2",
+                "name": "bar",
+                "role": "baz",
+            },
+        ]
+    ),
+    (
+        'excel',
+        {"skipinitialspace": True},
+        None,
+        "id,name,role\n1, foo, bar\n2, bar, baz",
+        [
+            {
+                "id": "1",
+                "name": "foo",
+                "role": "bar",
+            },
+            {
+                "id": "2",
+                "name": "bar",
+                "role": "baz",
+            },
+        ]
+    ),
+    (
+        'excel',
+        {"delimiter": '|'},
+        None,
+        "id|name|role\n1|foo|bar\n2|bar|baz",
+        [
+            {
+                "id": "1",
+                "name": "foo",
+                "role": "bar",
+            },
+            {
+                "id": "2",
+                "name": "bar",
+                "role": "baz",
+            },
+        ]
+    ),
+    (
+        'unix',
+        {},
+        None,
+        "id,name,role\n1,foo,bar\n2,bar,baz",
+        [
+            {
+                "id": "1",
+                "name": "foo",
+                "role": "bar",
+            },
+            {
+                "id": "2",
+                "name": "bar",
+                "role": "baz",
+            },
+        ]
+    ),
+    (
+        'excel',
+        {},
+        ['id', 'name', 'role'],
+        "1,foo,bar\n2,bar,baz",
+        [
+            {
+                "id": "1",
+                "name": "foo",
+                "role": "bar",
+            },
+            {
+                "id": "2",
+                "name": "bar",
+                "role": "baz",
+            },
+        ]
+    ),
+]
+
+INVALID_CSV = [
+    (
+        'excel',
+        {'strict': True},
+        None,
+        'id,name,role\n1,"f"oo",bar\n2,bar,baz',
+    ),
+]
+
+INVALID_DIALECT = [
+    (
+        'invalid',
+        {},
+        None,
+        "id,name,role\n1,foo,bar\n2,bar,baz",
+    ),
+]
+
+
+@pytest.mark.parametrize("dialect,dialect_params,fieldnames,data,expected", VALID_CSV)
+def test_valid_csv(data, dialect, dialect_params, fieldnames, expected):
+    dialect = csv.initialize_dialect(dialect, **dialect_params)
+    reader = csv.read_csv(data, dialect, fieldnames)
+    result = True
+
+    for idx, row in enumerate(reader):
+        for k, v in row.items():
+            if expected[idx][k] != v:
+                result = False
+                break
+
+    assert result
+
+
+@pytest.mark.parametrize("dialect,dialect_params,fieldnames,data", INVALID_CSV)
+def test_invalid_csv(data, dialect, dialect_params, fieldnames):
+    dialect = csv.initialize_dialect(dialect, **dialect_params)
+    reader = csv.read_csv(data, dialect, fieldnames)
+    result = False
+
+    try:
+        for row in reader:
+            continue
+    except csv.CSVError:
+        result = True
+
+    assert result
+
+
+@pytest.mark.parametrize("dialect,dialect_params,fieldnames,data", INVALID_DIALECT)
+def test_invalid_dialect(data, dialect, dialect_params, fieldnames):
+    result = False
+
+    try:
+        dialect = csv.initialize_dialect(dialect, **dialect_params)
+    except csv.DialectNotAvailableError:
+        result = True
+
+    assert result