fix: CSVImport bugs (AUTH column, case-insensitive validation, username case) + QuerysetEndpoint.find_by_name

.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: Build and publish docs
+
+on:
+  push:
+    branches: [master]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  build-and-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install docs dependencies
+        run: pip install -e ".[docs]"
+
+      - name: Build Sphinx docs
+        run: sphinx-build -b html docs sphinx_build
+
+      - name: Checkout gh-pages
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+          path: gh-pages
+
+      - name: Copy Sphinx output into gh-pages/sphinx
+        run: |
+          rm -rf gh-pages/sphinx
+          cp -r sphinx_build gh-pages/sphinx
+
+      - name: Create PR to gh-pages
+        uses: peter-evans/create-pull-request@v6
+        with:
+          path: gh-pages
+          branch: docs-update
+          base: gh-pages
+          title: "docs: update generated API reference"
+          body: "Automated update of Sphinx-generated API reference from master."
+          commit-message: "docs: regenerate Sphinx API reference"

.readthedocs.yaml

@@ -0,0 +1,25 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally, but recommended,
+# declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+   - method: pip
+     path: .
+     extra_requirements:
+     - docs

docs/conf.py

@@ -0,0 +1,68 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+
+# -- Project information -----------------------------------------------------
+# Source - https://stackoverflow.com/a/75396624
+# Posted by Jan, modified by community. See post 'Timeline' for change history
+# Retrieved 2026-06-19, License - CC BY-SA 4.0
+
+# conf.py
+
+try:
+    import tomllib
+except ImportError:
+    import tomli as tomllib
+
+from pathlib import Path
+import importlib.metadata
+
+with open(Path(__file__).parent.parent / "pyproject.toml", "rb") as f:
+    toml = tomllib.load(f)
+
+# -- Project information -----------------------------------------------------
+
+project = toml["project"]["name"]
+release = importlib.metadata.version(project)
+version = ".".join(release.split(".")[:2])
+
+# -- General configuration ---------------------------------------------------
+# -- General configuration
+
+extensions = [
+    "sphinx.ext.duration",
+    "sphinx.ext.doctest",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+]
+
+intersphinx_mapping = {
+    "rtd": ("https://docs.readthedocs.io/en/stable/", None),
+    "python": ("https://docs.python.org/3/", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
+}
+intersphinx_disabled_domains = ["std"]
+
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "furo"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = []

docs/index.rst

@@ -0,0 +1,9 @@
+tableauserverclient
+===================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+.. automodule:: tableauserverclient
+   :members:

pyproject.toml

@@ -35,6 +35,7 @@ repository = "https://github.com/tableau/server-client-python"
 [project.optional-dependencies]
 test = ["black==26.3.1", "build", "mypy==1.4", "pytest>=7.0", "pytest-cov", "pytest-subtests",
     "pytest-xdist", "requests-mock>=1.0,<2.0", "types-requests>=2.32.4.20250913"]
+docs = ["sphinx", "tomli", "furo"]
 
 [tool.setuptools.package-data]
 # Only include data for tableauserverclient, not for samples, test, docs

tableauserverclient/models/connection_item.py

@@ -150,16 +150,7 @@ def from_response(cls, resp, ns) -> list["ConnectionItem"]:
 
     @classmethod
     def from_xml_element(cls, parsed_response, ns) -> list["ConnectionItem"]:
-        """
-        <connections>
-            <connection serverAddress="mysql.test.com">
-                <connectionCredentials embed="true" name="test" password="secret" />
-            </connection>
-            <connection serverAddress="pgsql.test.com">
-                <connectionCredentials embed="true" name="test" password="secret" />
-                </connection>
-        </connections>
-        """
+        """Parse connection items from an XML ``<connections>`` element."""
         all_connection_items: list["ConnectionItem"] = list()
         all_connection_xml = parsed_response.findall(".//t:connection", namespaces=ns)
 

tableauserverclient/models/job_item.py

@@ -27,7 +27,7 @@ class JobItem:
 
     Parameters
     ----------
-    id_ : str
+    id : str
         The identifier of the job.
 
     job_type : str

tableauserverclient/models/site_item.py

@@ -52,10 +52,13 @@ class SiteItem:
         cause an error.
 
     tier_explorer_capacity: int
+        (Optional) The maximum number of licenses for users with the Explorer role allowed on a site.
+
     tier_creator_capacity: int
+        (Optional) The maximum number of licenses for users with the Creator role allowed on a site.
+
     tier_viewer_capacity: int
-        (Optional) The maximum number of licenses for users with the Creator,
-        Explorer, or Viewer role, respectively, allowed on a site.
+        (Optional) The maximum number of licenses for users with the Viewer role allowed on a site.
 
     storage_quota: int
         (Optional) Specifies the maximum amount of space for the new site, in

tableauserverclient/models/task_item.py

@@ -13,7 +13,7 @@ class TaskItem:
 
     Parameters
     ----------
-    id_ : str
+    id : str
         The ID of the task.
 
     task_type : str

tableauserverclient/models/user_item.py

@@ -432,36 +432,37 @@ class ColumnType(IntEnum):
             EMAIL = 6
             AUTH = 7
 
-            MAX = 7
+            MAX = 8  # total number of columns (not last index)
 
         # Read a csv line and create a user item populated by the given attributes
         @staticmethod
         def create_user_from_line(line: str):
             if line is None or line is False or line == "\n" or line == "":
                 return None
-            line = line.strip().lower()
-            values: list[str] = list(map(str.strip, line.split(",")))
-            user = UserItem(values[UserItem.CSVImport.ColumnType.USERNAME])
+            values: list[str] = list(map(str.strip, line.strip().split(",")))
+            if len(values) > UserItem.CSVImport.ColumnType.MAX:
+                raise ValueError("Too many attributes for user import")
+            username = values[UserItem.CSVImport.ColumnType.USERNAME]
+            user = UserItem(username)
             if len(values) > 1:
-                if len(values) > UserItem.CSVImport.ColumnType.MAX:
-                    raise ValueError("Too many attributes for user import")
-                while len(values) <= UserItem.CSVImport.ColumnType.MAX:
+                while len(values) < UserItem.CSVImport.ColumnType.MAX:
                     values.append("")
                 site_role = UserItem.CSVImport._evaluate_site_role(
                     values[UserItem.CSVImport.ColumnType.LICENSE],
                     values[UserItem.CSVImport.ColumnType.ADMIN],
                     values[UserItem.CSVImport.ColumnType.PUBLISHER],
                 )
-
+                raw_auth = values[UserItem.CSVImport.ColumnType.AUTH]
+                auth = UserItem.CSVImport._auth_canonical().get(raw_auth.lower()) if raw_auth else None
                 user._set_values(
                     None,
-                    values[UserItem.CSVImport.ColumnType.USERNAME],
+                    username,
                     site_role,
                     None,
                     None,
                     values[UserItem.CSVImport.ColumnType.DISPLAY_NAME],
                     values[UserItem.CSVImport.ColumnType.EMAIL],
-                    values[UserItem.CSVImport.ColumnType.AUTH],
+                    auth,
                     None,
                     None,
                     None,
@@ -491,6 +492,16 @@ def validate_file_for_import(csv_file: io.TextIOWrapper, logger) -> tuple[int, l
 
         # Some fields in the import file are restricted to specific values
         # Iterate through each field and validate the given value against hardcoded constraints
+        @staticmethod
+        def _auth_canonical() -> dict[str, str]:
+            """Lowercase → canonical form mapping for Auth values."""
+            return {
+                "saml": "SAML",
+                "openid": "OpenID",
+                "serverdefault": "ServerDefault",
+                "tableauidwithmfa": "TableauIDWithMFA",
+            }
+
         @staticmethod
         def _validate_import_line_or_throw(incoming, logger) -> None:
             _valid_attributes: list[list[str]] = [
@@ -501,7 +512,12 @@ def _validate_import_line_or_throw(incoming, logger) -> None:
                 ["system", "site", "none", "no"],  # admin
                 ["yes", "true", "1", "no", "false", "0"],  # publisher
                 [],
-                [UserItem.Auth.SAML, UserItem.Auth.OpenID, UserItem.Auth.ServerDefault],  # auth
+                [
+                    "SAML",
+                    "OpenID",
+                    "ServerDefault",
+                    "TableauIDWithMFA",
+                ],  # auth — normalized by _auth_canonical before comparison
             ]
 
             line = list(map(str.strip, incoming.split(",")))
@@ -511,10 +527,16 @@ def _validate_import_line_or_throw(incoming, logger) -> None:
             logger.debug(f"> details - {username}")
             UserItem.validate_username_or_throw(username)
             for i in range(1, len(line)):
-                logger.debug(f"column {UserItem.CSVImport.ColumnType(i).name}: {line[i]}")
-                UserItem.CSVImport._validate_attribute_value(
-                    line[i], _valid_attributes[i], UserItem.CSVImport.ColumnType(i)
-                )
+                value = line[i]
+                valid = _valid_attributes[i]
+                # normalize case for fields with a restricted value set
+                if valid:
+                    if i == UserItem.CSVImport.ColumnType.AUTH:
+                        value = UserItem.CSVImport._auth_canonical().get(value.lower(), value)
+                    else:
+                        value = value.lower()
+                logger.debug(f"column {UserItem.CSVImport.ColumnType(i).name}: {value}")
+                UserItem.CSVImport._validate_attribute_value(value, valid, UserItem.CSVImport.ColumnType(i))
 
         # Given a restricted set of possible values, confirm the item is in that set
         @staticmethod

tableauserverclient/server/endpoint/endpoint.py

@@ -374,6 +374,9 @@ def fields(self: Self, *fields: str) -> QuerySet:
         queryset.request_options.fields |= set(fields) | set(("_default_",))
         return queryset
 
+    def find_by_name(self, name: str) -> list[T]:
+        return list(self.filter(name=name))
+
     def only_fields(self: Self, *fields: str) -> QuerySet:
         """
         Add fields to the request options. If no fields are provided, the

test/test_user_model.py

@@ -136,3 +136,36 @@ def test_validate_usernames_file() -> None:
     test_data = _mock_file_content(usernames)
     valid, invalid = TSC.UserItem.CSVImport.validate_file_for_import(test_data, logger)
     assert valid == 5, f"Exactly 5 of the lines were valid, counted {valid + len(invalid)}"
+
+
+def test_validate_mixed_case_license() -> None:
+    # Regression: issue #1809 — 'Viewer' (capital V) was rejected by case-sensitive check
+    TSC.UserItem.CSVImport._validate_import_line_or_throw("username, pword, fname, Viewer, None, no, email", logger)
+    TSC.UserItem.CSVImport._validate_import_line_or_throw("username, pword, fname, Creator, Site, yes, email", logger)
+    TSC.UserItem.CSVImport._validate_import_line_or_throw("username, pword, fname, EXPLORER, NONE, YES, email", logger)
+
+
+def test_validate_tableauid_with_mfa_auth() -> None:
+    # TableauIDWithMFA is a valid auth value and must not be rejected
+    TSC.UserItem.CSVImport._validate_import_line_or_throw(
+        "username, pword, fname, creator, none, yes, email, TableauIDWithMFA", logger
+    )
+
+
+def test_create_user_preserves_username_case() -> None:
+    # Username must not be lowercased — case matters for LDAP and email-format usernames
+    user = TSC.UserItem.CSVImport.create_user_from_line("JSmith, pword, John Smith, creator, none, yes, j@example.com")
+    assert user is not None
+    assert user.name == "JSmith", f"Username was lowercased: {user.name}"
+
+
+def test_create_user_with_auth_column() -> None:
+    # AUTH column (position 7) must be parsed — was broken by MAX=7 off-by-one
+    user = TSC.UserItem.CSVImport.create_user_from_line("username, pword, fname, creator, none, yes, email, SAML")
+    assert user is not None
+    assert user.auth_setting == "SAML", f"Expected SAML, got {user.auth_setting}"
+
+
+def test_too_many_columns_raises() -> None:
+    with pytest.raises((ValueError, AttributeError)):
+        TSC.UserItem.CSVImport.create_user_from_line("u, p, n, creator, none, yes, email, SAML, extra")