#562 - Remove the requirement for about_resource

 * `about_resource` is now not a mandatory field
 * Updated docs (spec, references, changelog etc...)
 * Updated version and spec version

 Signed-off-by: Chin Yeung Li <[email protected]>

Author: chinyeungli

CHANGELOG.rst

@@ -1,14 +1,16 @@
 ==============================
 Changelog
 
-20xx-xx-xx
-    Release 10.2.0
+2024-xx-xx
+    Release 11.0.0
 
     * Add character support (at most 2 characters) for `attribute` field
     * Strip empty newline characters when loading an inventory
     * Catch invalid license_expression
     * Update the specification to 3.3.2
     * Support declared_license_expression" and "other_license_expression"
+    * Updated "about_resource" to be an optional field
+    * Updated spec to v4.0.0 as moving `about_resource` from mandatory to optional
 
 
 2023-09-25

about.ABOUT

@@ -1,6 +1,6 @@
 about_resource: .
 name: AboutCode-toolkit
-version: 10.1.0
+version: 11.0.0
 author: Jillian Daguil, Chin Yeung Li, Philippe Ombredanne, Thomas Druez
 copyright: Copyright (c) nexB Inc.
 description: |

docs/source/general.rst

@@ -79,12 +79,12 @@ it will copy and store next to the .ABOUT files.
     * - Standard Field Name
       - Description
       - Notes
-    * - about_resource
-      - Name/path of the component resource
-      - Mandatory
     * - name
       - Component name
       - Mandatory
+    * - about_resource
+      - Name/path of the component resource
+      - Optional
     * - ignored_resources
       - List of paths ignored from the ``about_resource``
       - Optional

docs/source/reference.rst

@@ -824,7 +824,7 @@ output.csv
 Special Notes
 -------------
 When using the field_filters configuration, all the standard required
-columns (about_resource and name) and the user defined required_fields
+columns (name) and the user defined required_fields
 need to be included.
 
 Notes

docs/source/specification.rst

@@ -1,7 +1,7 @@
 .. _specification:
 
 ===============================
-ABOUT File Specification v3.3.2
+ABOUT File Specification v4.0.0
 ===============================
 
 Purpose
@@ -228,15 +228,12 @@ in any case combination.
 Referencing the file or directory documented by an ABOUT file
 -------------------------------------------------------------
 
-An ABOUT file documents one file or directory. The mandatory ``about_resource``
+An ABOUT file documents one file or directory. The ``about_resource``
 field reference the documented file or directory. The value of the ``about_resource``
 field is the name or path of the referenced file or directory. There is also a
 ``ignored_resources`` field which can be used to ignore a set of subpaths inside the
 directory which is being documented in the ABOUT file.
 
-A tool processing an ABOUT file must report an error if the ``about_resource``
-field is missing.
-
 By convention, an ABOUT file is often stored in the same directory side-by-side
 to the file or directory that it documents, but this is not mandatory.
 
@@ -267,18 +264,18 @@ In this example, the ABOUT file documents the current directory, using a "." per
 
                 about_resource: .
 
-Other Mandatory fields
+Mandatory fields
 ----------------------
 
-When a tool processes an ABOUT file, it must issue an error if these
-mandatory field are missing.
+When a tool processes an ABOUT file, it must issue an error if the
+mandatory field is missing.
 
--   about_resource: The resource this file referencing to.
 -   name: Component name.
 
 Optional Information fields
 ---------------------------
 
+-   about_resource: The resource this file referencing to.
 -   ignored_resources: A list of paths under the ``about_resource`` path, which are
     not documented in the ABOUT file, and the information in the ABOUT file does not
     apply to these subpaths.

src/attributecode/__init__.py

@@ -20,9 +20,9 @@
 
 import saneyaml
 
-__version__ = '10.1.0'
+__version__ = '11.0.0'
 
-__about_spec_version__ = '3.3.2'
+__about_spec_version__ = '4.0.0'
 
 __copyright__ = """
 Copyright (c) nexB Inc. All rights reserved. http://dejacode.org

src/attributecode/gen.py

@@ -152,18 +152,18 @@ def load_inventory(location, from_attrib=False, base_dir=None, scancode=False, r
         else:
             inventory = load_json(location)
 
-    try:
-        arp_list = []
-        errors = []
+    arp_list = []
+    errors = []
 
-        if is_spreadsheet:
-            # Only the .csv and .xlsx may have newline issue
-            stripped_inv = strip_inventory_value(inventory)
-        else:
-            stripped_inv = inventory
+    if is_spreadsheet:
+        # Only the .csv and .xlsx may have newline issue
+        stripped_inv = strip_inventory_value(inventory)
+    else:
+        stripped_inv = inventory
 
-        for component in stripped_inv:
-            if not from_attrib:
+    for component in stripped_inv:
+        if not from_attrib:
+            if 'about_resource' in component:
                 arp = component['about_resource']
                 dup_err = check_duplicated_about_resource(arp, arp_list)
                 if dup_err:
@@ -176,16 +176,11 @@ def load_inventory(location, from_attrib=False, base_dir=None, scancode=False, r
                 if invalid_about_filename and not invalid_about_filename in errors:
                     errors.append(invalid_about_filename)
 
-            newline_in_file_err = check_newline_in_file_field(component)
-            if newline_in_file_err:
-                errors.extend(newline_in_file_err)
+        newline_in_file_err = check_newline_in_file_field(component)
+        if newline_in_file_err:
+            errors.extend(newline_in_file_err)
 
-        if errors:
-            return errors, abouts
-    except Exception as e:
-        # TODO: why catch ALL Exception
-        msg = "The essential field 'about_resource' is not found in the <input>"
-        errors.append(Error(CRITICAL, msg))
+    if errors:
         return errors, abouts
 
     custom_fields_list = []
@@ -203,8 +198,8 @@ def load_inventory(location, from_attrib=False, base_dir=None, scancode=False, r
                     errors.append(Error(CRITICAL, msg))
                     return errors, abouts
         # Set about file path to '' if no 'about_resource' is provided from
-        # the input for `attrib`
-        if not 'about_resource' in fields:
+        # the input
+        if 'about_resource' not in fields:
             afp = ''
         else:
             afp = fields.get(model.About.ABOUT_RESOURCE_ATTR)
@@ -228,11 +223,6 @@ def load_inventory(location, from_attrib=False, base_dir=None, scancode=False, r
                 updated_resource_value = basename(resource_path)
             fields['about_resource'] = updated_resource_value
 
-        # Set 'about_resource' to '.' if no 'about_resource' is provided from
-        # the input for `attrib`
-        elif not 'about_resource' in fields and from_attrib:
-            fields['about_resource'] = u'.'
-
         ld_errors = about.load_dict(
             fields,
             base_dir,
@@ -268,7 +258,6 @@ def generate(location, base_dir, android=None, reference_dir=None, fetch_license
     Load ABOUT data from a CSV inventory at `location`. Write ABOUT files to
     base_dir. Return errors and about objects.
     """
-    not_exist_errors = []
     notice_dict = {}
     api_url = ''
     api_key = ''
@@ -294,7 +283,6 @@ def generate(location, base_dir, android=None, reference_dir=None, fetch_license
         scancode=scancode,
         worksheet=worksheet
     )
-
     if gen_license:
         license_dict, err = model.pre_process_and_fetch_license_dict(
             abouts, api_url=api_url, api_key=api_key)
@@ -309,6 +297,9 @@ def generate(location, base_dir, android=None, reference_dir=None, fetch_license
         about.about_file_path = about.about_file_path.strip()
         if about.about_file_path.startswith('/'):
             about.about_file_path = about.about_file_path.lstrip('/')
+        # Use the name as the ABOUT file name if about_resource is empty
+        if not about.about_file_path:
+            about.about_file_path = about.name.value
         dump_loc = join(bdir, about.about_file_path.lstrip('/'))
 
         # The following code is to check if there is any directory ends with spaces
@@ -328,30 +319,6 @@ def generate(location, base_dir, android=None, reference_dir=None, fetch_license
             continue
 
         try:
-            # Generate value for 'about_resource' if it does not exist
-            if not about.about_resource.value:
-                about.about_resource.value = dict()
-                about_resource_value = ''
-                if about.about_file_path.endswith('/'):
-                    about_resource_value = u'.'
-                else:
-                    about_resource_value = basename(about.about_file_path)
-                about.about_resource.value[about_resource_value] = None
-                about.about_resource.present = True
-                # Check for the existence of the 'about_resource'
-                # If the input already have the 'about_resource' field, it will
-                # be validated when creating the about object
-                loc = util.to_posix(dump_loc)
-                about_file_loc = loc
-                path = join(dirname(util.to_posix(about_file_loc)),
-                            about_resource_value)
-                if not exists(path):
-                    path = util.to_posix(path.strip(UNC_PREFIX_POSIX))
-                    path = normpath(path)
-                    msg = (u'Field about_resource: '
-                           u'%(path)s '
-                           u'does not exist' % locals())
-                errors.append(Error(INFO, msg))
 
             licenses_dict = {}
             if gen_license:

src/attributecode/model.py

@@ -874,7 +874,7 @@ class About(object):
     ABOUT_RESOURCE_ATTR = 'about_resource'
 
     # Required fields
-    required_fields = ['name', ABOUT_RESOURCE_ATTR]
+    required_fields = ['name']
 
     def get_required_fields(self):
         return [f for f in self.fields if f.required]
@@ -886,7 +886,7 @@ def set_standard_fields(self):
         is simpler.
         """
         self.fields = dict([
-            ('about_resource', AboutResourceField(required=True)),
+            ('about_resource', AboutResourceField()),
             ('ignored_resources', AboutResourceField()),
             ('name', SingleLineField(required=True)),
             ('version', SingleLineField()),

tests/test_gen.py

@@ -109,11 +109,19 @@ def test_load_inventory_without_about_resource(self):
         from_attrib = False
         errors, abouts = gen.load_inventory(
             location, base_dir=base_dir, from_attrib=from_attrib)
-        expected_error = [Error(
-            CRITICAL,  "The essential field 'about_resource' is not found in the <input>")]
+        expected = (
+            '''name: AboutCode
+version: 0.11.0
+license_expression: apache-2.0
+licenses:
+  - key: apache-2.0
+    name: apache-2.0
+'''
+        )
 
-        assert errors == expected_error
-        assert abouts == []
+        assert errors == []
+        result = [a.dumps() for a in abouts]
+        assert expected == result[0]
 
     def test_load_inventory_without_about_resource_from_attrib(self):
         location = get_test_loc('test_gen/inv_no_about_resource.csv')
@@ -126,8 +134,7 @@ def test_load_inventory_without_about_resource_from_attrib(self):
         assert len(errors) == expected_num_errors
 
         expected = (
-            '''about_resource: .
-name: AboutCode
+            '''name: AboutCode
 version: 0.11.0
 license_expression: apache-2.0
 licenses:

tests/test_model.py

@@ -478,12 +478,10 @@ def test_About_loads_ignored_resources_field(self):
         result = [f.name for f in a.all_fields() if f.present]
         assert expected == result
 
-    def test_About_has_errors_when_about_resource_is_missing(self):
+    def test_About_has_no_errors_when_about_resource_is_missing(self):
         test_file = get_test_loc('test_gen/parser_tests/.ABOUT')
         a = model.About(test_file)
-        expected = [Error(CRITICAL, 'Field about_resource is required')]
-        result = a.errors
-        assert expected == result
+        assert a.errors == []
 
     def test_About_has_errors_when_about_resource_does_not_exist(self):
         test_file = get_test_loc(
@@ -500,7 +498,6 @@ def test_About_has_errors_when_missing_required_fields_are_missing(self):
         test_file = get_test_loc('test_model/parse/missing_required.ABOUT')
         a = model.About(test_file)
         expected = [
-            Error(CRITICAL, 'Field about_resource is required'),
             Error(CRITICAL, 'Field name is required'),
         ]
         result = a.errors
@@ -510,7 +507,6 @@ def test_About_has_errors_when_required_fields_are_empty(self):
         test_file = get_test_loc('test_model/parse/empty_required.ABOUT')
         a = model.About(test_file)
         expected = [
-            Error(CRITICAL, 'Field about_resource is required and empty'),
             Error(CRITICAL, 'Field name is required and empty'),
         ]
         result = a.errors
@@ -728,9 +724,7 @@ def test_get_field_names_only_returns_non_empties(self):
         abouts = [a, b]
         # ensure all fields (including custom fields) and
         # about_resource are collected in the correct order
-        expected = [
-            model.About.ABOUT_RESOURCE_ATTR, 'name', 'f', 'g'
-        ]
+        expected = ['name', 'f', 'g']
         result = model.get_field_names(abouts)
         assert expected == result
 
@@ -749,7 +743,6 @@ def test_get_field_names_does_not_return_duplicates_custom_fields(self):
         # ensure all fields (including custom fields) and
         # about_resource are collected in the correct order
         expected = [
-            'about_resource',
             'name',
             'cf',
             'f',
@@ -1281,14 +1274,8 @@ def test_collect_inventory_with_about_resource_path_from_directory(self):
 
     def test_collect_inventory_with_no_about_resource_from_directory(self):
         location = get_test_loc('test_model/inventory/no_about_resource_key')
-        result = get_temp_file()
         errors, abouts = model.collect_inventory(location)
-
-        model.write_output(abouts, result, format='csv')
-
-        expected_errors = [
-            Error(CRITICAL, 'about/about.ABOUT: Field about_resource is required')]
-        assert expected_errors == errors
+        assert errors == []
 
     def test_collect_inventory_complex_from_directory(self):
         location = get_test_loc('test_model/inventory/complex')