Adds enum, revises some docstrings, and attribute names

Author: chalmerlowe

google/cloud/bigquery/enums.py

@@ -462,3 +462,22 @@ class JobCreationMode(object):
     The conditions under which BigQuery can decide to not create a Job are
     subject to change.
     """
+
+
+class SourceColumnMatch(str, enum.Enum):
+    """Uses sensible defaults based on how the schema is provided.
+
+    If autodetect is used, then columns are matched by name. Otherwise, columns
+    are matched by position. This is done to keep the behavior backward-compatible.
+    """
+
+    SOURCE_COLUMN_MATCH_UNSPECIFIED = "SOURCE_COLUMN_MATCH_UNSPECIFIED"
+    """Unspecified column name match option."""
+
+    POSITION = "POSITION"
+    """Matches by position. This assumes that the columns are ordered the same
+    way as the schema."""
+
+    NAME = "NAME"
+    """Matches by name. This reads the header row as column names and reorders
+    columns to match the field names in the schema."""

google/cloud/bigquery/external_config.py

@@ -476,11 +476,19 @@ def skip_leading_rows(self, value):
 
     @property
     def null_markers(self) -> Optional[List[str]]:
-        """Optional[List[str]]: A list of strings represented as SQL NULL value.
+        """Optional[List[str]]: A list of strings represented as SQL NULL value in a CSV file.
+
+        null_marker and null_markers can't be set at the same time.
+        If null_marker is set, null_markers has to be not set.
+        If null_markers is set, null_marker has to be not set.
+        If both null_marker and null_markers are set at the same time, a user
+        error would be thrown.
+        Any strings listed in null_markers, including
+        empty string would be interpreted as SQL NULL. This applies to all column
+        types.
 
         See
-        https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#CsvOptions.FIELDS.null_marker
-        (Note: API doc refers to null_marker singular, but proto is null_markers plural and a list)
+        https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#CsvOptions.FIELDS.null_markers
         """
         return self._properties.get("nullMarkers")
 
@@ -490,13 +498,19 @@ def null_markers(self, value: Optional[List[str]]):
 
     @property
     def source_column_name_match_option(self) -> Optional[str]:
-        """Optional[str]: Controls the strategy used to match loaded columns to the schema.
-        Acceptable values are: "POSITION", "NAME".
+        """Optional[str]: Controls the strategy used to match loaded columns to the schema. If not
+        set, a sensible default is chosen based on how the schema is provided. If
+        autodetect is used, then columns are matched by name. Otherwise, columns
+        are matched by position. This is done to keep the behavior
+        backward-compatible.
+        Acceptable values are:
+          POSITION - matches by position. This assumes that the columns are ordered
+              the same way as the schema.
+          NAME - matches by name. This reads the header row as column names and
+              reorders columns to match the field names in the schema.
 
         See
         https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#ExternalDataConfiguration.FIELDS.source_column_match
-        (Note: This field is documented under ExternalDataConfiguration in the REST API docs but seems
-         more appropriate here for CSVOptions, matching the proto structure for external tables)
         """
         return self._properties.get("sourceColumnMatch")
 

tests/unit/job/test_load.py

@@ -42,7 +42,7 @@ def _setUpConstants(self):
         self.DATETIME_FORMAT = "%Y-%m-%dT%H:%M:%S"
         self.TIME_FORMAT = "%H:%M:%S"
         self.TIMESTAMP_FORMAT = "YYYY-MM-DD HH:MM:SS.SSSSSSZ"
-        self.NULL_MARKERS = ["N/A", "\\N"]
+        self.NULL_MARKERS = ["N/A", "NA"]
         self.SOURCE_COLUMN_NAME_MATCH_OPTION = "MATCH_BY_NAME"
 
     def _make_resource(self, started=False, ended=False):