#20 - Provide more clarity on the content class

Author: patkyn

README.md

@@ -96,13 +96,13 @@ DwcaHandler.list_class_rowtypes()
 * In creating a dwca with multimedia extension, provide format and type values in the Simple Multimedia extension, otherwise, dwcahandler will attempt to fill these info by guessing the mimetype from url.
 
 ```python
-from dwcahandler import CsvFileType
+from dwcahandler import ContentData
 from dwcahandler import DwcaHandler
 from dwcahandler import MetaElementTypes
 from dwcahandler import Eml
 
-core_csv = CsvFileType(files=['/tmp/occurrence.csv'], type=MetaElementTypes.OCCURRENCE, keys=['occurrenceID'])
-ext_csvs = [CsvFileType(files=['/tmp/multimedia.csv'], type=MetaElementTypes.MULTIMEDIA)]
+core_csv = ContentData(data=['/tmp/occurrence.csv'], type=MetaElementTypes.OCCURRENCE, keys=['occurrenceID'])
+ext_csvs = [ContentData(data=['/tmp/multimedia.csv'], type=MetaElementTypes.MULTIMEDIA)]
 
 eml = Eml(dataset_name='Test Dataset',
           description='Dataset description',
@@ -118,16 +118,16 @@ DwcaHandler.create_dwca(core_csv=core_csv, ext_csv_list=ext_csvs, eml_content=em
 
 ```python
 from dwcahandler import DwcaHandler
-from dwcahandler.dwca import CsvFileType
+from dwcahandler.dwca import ContentData
 from dwcahandler import MetaElementTypes
 from dwcahandler import Eml
 import pandas as pd
 
 core_df = pd.read_csv("/tmp/occurrence.csv")
-core_frame = CsvFileType(files=core_df, type=MetaElementTypes.OCCURRENCE, keys=['occurrenceID'])
+core_frame = ContentData(data=core_df, type=MetaElementTypes.OCCURRENCE, keys=['occurrenceID'])
 
 ext_df = pd.read_csv("/tmp/multimedia.csv")
-ext_frame = [CsvFileType(files=ext_df, type=MetaElementTypes.MULTIMEDIA)]
+ext_frame = [ContentData(data=ext_df, type=MetaElementTypes.MULTIMEDIA)]
 
 eml = Eml(dataset_name='Test Dataset',
           description='Dataset description',
@@ -138,7 +138,9 @@ eml = Eml(dataset_name='Test Dataset',
 DwcaHandler.create_dwca(core_csv=core_frame, ext_csv_list=ext_frame, eml_content=eml, output_dwca='/tmp/dwca.zip')
 ```
  
-* Create Darwin Core Archive from csv files in a zip files.
+* Convenient helper function to build Darwin Core Archive from a list of csv files.
+* Build event core DwCA if event.txt file is supplied, otherwise, occurrence DwCA if occurrence.txt is supplied. 
+* Raises error if neither event.txt not occurrence.txt is in the list
 * Class row types are determined by file names of the csvs.
 * If no content keys provided, the default keys are eventID for event content and occurrenceID for occurrence content
 * Delimiter for txt files are comma delimiter by default. For tab delimiter, supply CsvEncoding
@@ -152,10 +154,12 @@ eml = Eml(dataset_name='Test Dataset',
           citation="test citation",
           rights="test rights")
 
-DwcaHandler.create_dwca_from_zip_content(zip_file="/tmp/txt_files.zip",  eml_content=eml, output_dwca='/tmp/dwca.zip')
+DwcaHandler.create_dwca_from_file_list(files=["/tmp/event.csv", "/tmp/occurrence.csv"],  eml_content=eml, output_dwca='/tmp/dwca.zip')
 ```
  
 * Convenient helper function to create Darwin Core Archive from csv files in a zip files.
+* Build event core DwCA if event.txt file is supplied, otherwise, occurrence DwCA if occurrence.txt is supplied in the zip file
+* Raises error if neither event.txt not occurrence.txt is in the list
 * Class row types are determined by file names of the csvs.
 * If no content keys provided, the default keys are eventID for event content and occurrenceID for occurrence content
 * Delimiter for txt files are comma delimiter by default. For tab delimiter, supply CsvEncoding
@@ -201,13 +205,13 @@ DwcaHandler.merge_dwca(dwca_file='/tmp/dwca.zip', delta_dwca_file='/tmp/delta-dw
  
 * Delete Rows from core file in Darwin Core Archive
 ```python
-from dwcahandler import CsvFileType
+from dwcahandler import ContentData
 from dwcahandler import DwcaHandler, MetaElementTypes
 
-delete_csv = CsvFileType(files=['/tmp/old-records.csv'], type=MetaElementTypes.OCCURRENCE, keys=['occurrenceID'])
+delete_csv = ContentData(data=['/tmp/old-records.csv'], type=MetaElementTypes.OCCURRENCE, keys=['occurrenceID'])
 
 DwcaHandler.delete_records(dwca_file='/tmp/dwca.zip',
-                           records_to_delete=delete_csv, 
+                           records_to_delete=delete_csv,
                            output_dwca='/tmp/new-dwca.zip')
 ```
  

src/dwcahandler/dwca/__init__.py

@@ -1,6 +1,6 @@
 # flake8: noqa
 """
-Tools to convert data frames into Darwin Core Archive (DwCA) files.
+Tools to convert data frame or text files into Darwin Core Archive (DwCA) file.
 
 See https://ipt.gbif.org/manual/en/ipt/2.6/dwca-guide for a guide to DwCAs.
 
@@ -185,36 +185,36 @@ class Defaults:
 from dwcahandler.dwca.dwca_meta import (MetaElementTypes, MetaElementInfo, MetaDwCA,
                                         MetaElementAttributes, get_meta_class_row_type)
 @dataclass
-class CsvFileType:
-    """A description of a CSV file in a DwCA
+class ContentData:
+    """A class describing the content data used for core and extension.
+       Use this class to define the core content and extension content to build a DwCA (see README on usage)
     """
-    files: Union[list[str], pd.DataFrame, io.TextIOWrapper]  # can accept more than one file or a dataframe
-    type: MetaElementTypes # 'occurrence', 'taxon', 'event', multimedia,...
-    keys: Optional[list] = None  # must be supplied for csv extensions to link extension records to core record
-    # when creating dwca. for core other than occurrence, this neeeds to be supplied as key.
-    # column keys lookup in core or extension for delete records
-    associated_files_loc: Optional[str] = None  # in case there are associated media that need to be packaged in dwca
+    data: Union[list[str], pd.DataFrame, io.TextIOWrapper]  # can accept more than one files, dataframe or file pointer
+    type: MetaElementTypes # Enumerated types from the class row type.
+    keys: Optional[list] = None # keys that uniquely identify a record in the content
+    associated_files_loc: Optional[str] = None  # provide a folder path containing the embedded images.
+                                # Embedded images file name must be supplied as associatedMedia in the content
     csv_encoding: CSVEncoding = field(
         default_factory=lambda: CSVEncoding(csv_delimiter=",", csv_eol="\n", csv_text_enclosure='"',
                                             csv_escape_char='"'))
 
     def check_for_empty(self, include_keys = True):
-        if self.files and len(self.files) > 0 and \
+        if self.data and len(self.data) > 0 and \
                 self.type and isinstance(self.type, MetaElementTypes) and \
                 (not include_keys or include_keys and self.keys and len(self.keys) > 0):
             return True
         return False
 
-    def add_data(self, other_csv_file_type: CsvFileType):
+    def add_data(self, other_csv_file_type: ContentData):
         if self.type and self.type == other_csv_file_type.type:
-            if isinstance(self.files, pd.DataFrame) and isinstance(other_csv_file_type.files, pd.DataFrame):
-                self.files = pd.concat([self.files, other_csv_file_type.files], ignore_index=False)
+            if isinstance(self.data, pd.DataFrame) and isinstance(other_csv_file_type.data, pd.DataFrame):
+                self.data = pd.concat([self.data, other_csv_file_type.data], ignore_index=False)
                 return True
-            elif isinstance(self.files, list) and isinstance(other_csv_file_type.files, list):
-                self.files.append(other_csv_file_type.files)
+            elif isinstance(self.data, list) and isinstance(other_csv_file_type.data, list):
+                self.data.append(other_csv_file_type.data)
                 return True
         elif not self.type:
-            self.files = other_csv_file_type.files
+            self.data = other_csv_file_type.data
             self.type = other_csv_file_type.type
         return False
 

src/dwcahandler/dwca/base_dwca.py

@@ -7,15 +7,15 @@
 from abc import ABCMeta, abstractmethod
 from typing import Union
 from io import BytesIO
-from dwcahandler.dwca import CoreOrExtType, CsvFileType, MetaElementTypes
+from dwcahandler.dwca import CoreOrExtType, ContentData, MetaElementTypes
 from dwcahandler.dwca.eml import Eml
 
 
 class BaseDwca(metaclass=ABCMeta):
     """An abstract DwCA that provides basic operations"""
 
     @abstractmethod
-    def extract_csv_content(self, csv_info: CsvFileType, core_ext_type: CoreOrExtType,
+    def extract_csv_content(self, csv_info: ContentData, core_ext_type: CoreOrExtType,
                             build_coreid_for_ext: bool = False):
         """Get the content from a single file in the DwCA
 
@@ -48,11 +48,11 @@ def generate_meta(self):
 
     @abstractmethod
     def write_dwca(self, output_dwca: Union[str, BytesIO]):
-        """Write the content of the DwCA to a directory.
+        """Write the content of the DwCA to a file path (supplied as string) or to BytesIO in memory.
 
-        Writes all CSV files, as well as a meta-file and EML file for the archive.
+        Writes all CSV data, as well as a meta-file and EML file for the archive.
 
-        :param output_dwca: The path to write to or dwca in memory
+        :param output_dwca: The file path or BytesIO
         """
         pass
 
@@ -85,7 +85,7 @@ def convert_associated_media_to_extension(self):
         pass
 
     @abstractmethod
-    def delete_records(self, records_to_delete: CsvFileType):
+    def delete_records(self, records_to_delete: ContentData):
         pass
 
     @abstractmethod
@@ -111,10 +111,10 @@ def fill_additional_info(self):
         for multimedia_content, _ in contents:
             self.add_multimedia_info_to_content(multimedia_content)
 
-    def delete_records_in_dwca(self, records_to_delete: CsvFileType, output_dwca: Union[str, BytesIO]):
-        """Delete records in dwca if the key records are defined in CsvFileType
+    def delete_records_in_dwca(self, records_to_delete: ContentData, output_dwca: Union[str, BytesIO]):
+        """Delete records in dwca if the key records are defined in ContentData
 
-        :param records_to_delete: A CsvFileType that containing the text file of the record keys,
+        :param records_to_delete: A ContentData that containing the text file of the record keys,
                                   the key names of the records and MetaElementType type class of the dwca
                                   where the records need to be removed
         :param output_dwca: output dwca path where the result of the dwca is writen to or the output dwca in memory
@@ -125,14 +125,14 @@ def delete_records_in_dwca(self, records_to_delete: CsvFileType, output_dwca: Un
         self.generate_meta()
         self.write_dwca(output_dwca)
 
-    def create_dwca(self, core_csv: CsvFileType, output_dwca: Union[str, BytesIO],
-                    ext_csv_list: list[CsvFileType] = None, validate_content: bool = True,
+    def create_dwca(self, core_csv: ContentData, output_dwca: Union[str, BytesIO],
+                    ext_csv_list: list[ContentData] = None, validate_content: bool = True,
                     eml_content: Union[str, Eml] = ''):
         """Create a dwca given the contents of core and extensions and eml content
 
-        :param core_csv: CsvFileType containing the files, class types and keys to form the core of the dwca
+        :param core_csv: ContentData containing the data, class type and keys to form the core of the dwca
         :param output_dwca: the resulting path of the dwca or the dwca in memory
-        :param ext_csv_list: list of CsvFileTypes containing the files, class types and keys to form the
+        :param ext_csv_list: list of ContentData containing the data, class type and keys to form the
                               extensions of the dwca if supplied
         :param validate_content: whether to validate the contents
         :param eml_content: eml content in string or a filled Eml object
@@ -143,7 +143,7 @@ def create_dwca(self, core_csv: CsvFileType, output_dwca: Union[str, BytesIO],
         self.extract_csv_content(csv_info=core_csv, core_ext_type=CoreOrExtType.CORE,
                                  build_coreid_for_ext=True if len(ext_csv_list) > 0 else False)
 
-        # if multimedia files is supplied, do not attempt to convert associated media to multimedia
+        # if multimedia data is supplied, do not attempt to convert associated media to multimedia
         if not any(ext.type == MetaElementTypes.MULTIMEDIA for ext in ext_csv_list):
             image_ext = self.convert_associated_media_to_extension()
             if image_ext:
@@ -200,10 +200,10 @@ def validate_dwca(self, content_keys: dict, error_file: str):
         set_keys = self.set_keys(content_keys)
         return self.validate_content(content_to_validate=set_keys, error_file=error_file)
 
-    def validate_file(self, csv: CsvFileType, error_file: str):
+    def validate_file(self, csv: ContentData, error_file: str):
         """Validate the text file
 
-        :param csv: CsvFileType to pass the csv, key and type
+        :param csv: ContentData to pass the csv, key and type
         :param error_file: optional error_file for the errored data
         """
         self.extract_csv_content(csv_info=csv, core_ext_type=CoreOrExtType.CORE)

src/dwcahandler/dwca/core_dwca.py

@@ -22,7 +22,7 @@
 from pandas.errors import EmptyDataError
 from pandas.io import parsers
 from dwcahandler.dwca import (BaseDwca, CoreOrExtType, CSVEncoding,
-                              CsvFileType, Defaults, Eml, Terms, get_keys,
+                              ContentData, Defaults, Eml, Terms, get_keys,
                               MetaDwCA, MetaElementInfo, MetaElementTypes,
                               MetaElementAttributes, Stat, record_diff_stat)
 
@@ -488,16 +488,16 @@ def _delete_content(self, content, delete_content):
         content = self._filter_content(delete_content, content.df_content)
         return content
 
-    def delete_records(self, records_to_delete: CsvFileType):
+    def delete_records(self, records_to_delete: ContentData):
         """Delete records from either a core or extension content frame
 
         :param records_to_delete: A CSV file of records to delete, keyed to the DwCA file
          """
         delete_content = pd.DataFrame()
-        if isinstance(records_to_delete.files, pd.DataFrame):
-            delete_content = records_to_delete.files.copy(deep=True)
+        if isinstance(records_to_delete.data, pd.DataFrame):
+            delete_content = records_to_delete.data.copy(deep=True)
         else:
-            delete_content = self._combine_contents(records_to_delete.files, records_to_delete.csv_encoding,
+            delete_content = self._combine_contents(records_to_delete.data, records_to_delete.csv_encoding,
                                                     use_chunking=False)
         valid_delete_file = (all(col in delete_content.columns for col in records_to_delete.keys)
                              or len(delete_content) > 0)
@@ -735,7 +735,7 @@ def convert_associated_media_to_extension(self):
             if len(image_df) > 0:
                 self._update_meta_fields(content=self.core_content, key_field=self.core_content.keys[0])
                 log.info("%s associated media extracted", str(len(image_df)))
-                return CsvFileType(files=image_df, type=MetaElementTypes.MULTIMEDIA,
+                return ContentData(data=image_df, type=MetaElementTypes.MULTIMEDIA,
                                    keys=self.core_content.keys)
 
             log.info("Nothing to extract from associated media")
@@ -886,20 +886,20 @@ def validate_content(self, content_to_validate: dict = None, error_file: str = N
 
         return True if validation_success else False
 
-    def extract_csv_content(self, csv_info: CsvFileType,
+    def extract_csv_content(self, csv_info: ContentData,
                             core_ext_type: CoreOrExtType, build_coreid_for_ext: bool = False):
-        """Read the files from a CSV description into a content frame and include it in the Dwca.
+        """Read the data from a CSV description into a content frame and include it in the Dwca.
 
         :param csv_info: The CSV file(s)
         :param core_ext_type: Whether this is a core or extension content frame
         :param build_coreid_for_ext: indicator to build id and core id to support dwca with extension
         """
-        if isinstance(csv_info.files, pd.DataFrame) :
-            csv_content = csv_info.files
-        elif isinstance(csv_info.files, io.TextIOWrapper):
-            csv_content = self._read_csv(csv_info.files)
+        if isinstance(csv_info.data, pd.DataFrame) :
+            csv_content = csv_info.data
+        elif isinstance(csv_info.data, io.TextIOWrapper):
+            csv_content = self._read_csv(csv_info.data)
         else:
-            csv_content = self._combine_contents(csv_info.files, csv_info.csv_encoding)
+            csv_content = self._combine_contents(csv_info.data, csv_info.csv_encoding)
 
         # Use default keys if not provided
         if core_ext_type == CoreOrExtType.CORE: