Merge branch 'main' into 1373-feature-allow-application-developers-to…

…-customize-logging-configuration

.flake8

@@ -1,7 +1,7 @@
 [flake8]
 max-line-length = 88
 exclude = cookiecutter
-ignore = E, W
+ignore = E, F, W
 per-file-ignores =
     # Don't require docstrings conventions in private modules
     singer_sdk/helpers/_*.py:DAR

.github/workflows/api-changes.yml

@@ -0,0 +1,53 @@
+name: API Changes
+
+on:
+  pull_request:
+    paths:
+    - singer_sdk/**
+    - .github/workflows/api-changes.yml
+    - CHANGELOG.md
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:  # added using https://github.com/step-security/secure-repo
+  contents: read
+
+jobs:
+  check-api-changes:
+    name: Check API Changes
+    runs-on: ubuntu-latest
+    env:
+      NOXSESSION: api
+    steps:
+    - name: Check out the repository
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Setup Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: 3.12
+
+    - name: Install tools
+      env:
+        PIP_CONSTRAINT: ${{ github.workspace }}/.github/workflows/constraints.txt
+      run: |
+        python -Im pip install -U pip
+        pipx install griffe nox
+        pipx inject nox nox-poetry
+        pipx list
+
+    - name: Set REF
+      id: set-ref
+      if: always() && !startsWith(github.head_ref, 'release/')
+      run: |
+        echo "ref=${{ github.event.pull_request.base.sha }}" >> $GITHUB_OUTPUT
+
+    # Check API against the latest commit on the base branch
+    - name: Run Nox
+      run: |
+        nox -- ${{ steps.set-ref.outputs.ref }}

.github/workflows/constraints.txt

@@ -1,3 +1,4 @@
+griffe==0.48.0
 pip==24.1.2
 poetry==1.8.3
 poetry-plugin-export==1.8.0

.readthedocs.yml

@@ -3,7 +3,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.11"
+    python: "3.12"
 
 sphinx:
   builder: html

noxfile.py

@@ -186,7 +186,7 @@ def docs_serve(session: Session) -> None:
         "build",
         "-W",
     ]
-    session.install(".[docs]")
+    session.install(".[docs]", "sphinx-autobuild")
 
     build_dir = Path("build")
     if build_dir.exists():
@@ -279,3 +279,18 @@ def version_bump(session: Session) -> None:
         "bump",
         *args,
     )
+
+
+@nox.session(name="api")
+def api_changes(session: nox.Session) -> None:
+    """Check for API changes."""
+    args = [
+        "griffe",
+        "check",
+        "singer_sdk",
+    ]
+
+    if session.posargs:
+        args.append(f"-a={session.posargs[0]}")
+
+    session.run(*args, external=True)

pyproject.toml

@@ -65,14 +65,13 @@ urllib3 = ">=1.26,<2"
 
 # Sphinx dependencies installed as optional 'docs' extras
 # https://github.com/readthedocs/readthedocs.org/issues/4912#issuecomment-664002569
-sphinx = {version = ">=4.5", optional = true}
-furo = {version = ">=2022.12.7", optional = true}
-sphinx-copybutton = {version = ">=0.3.1", optional = true}
-myst-parser = {version = ">=1", optional = true}
-sphinx-autobuild = {version = ">=2021.3.14", optional = true}
-sphinx-inline-tabs = {version = ">=2023.4.21", optional = true}
-sphinx-notfound-page = {version = ">=1.0.0", optional = true}
-sphinx-reredirects = {version = ">=0.1.1", optional = true}
+sphinx = {version = ">=7", python = ">=3.9", optional = true}
+furo = {version = ">=2024.5.6", python = ">=3.9", optional = true}
+sphinx-copybutton = {version = ">=0.5.2", python = ">=3.9", optional = true}
+myst-parser = {version = ">=3", python = ">=3.9", optional = true}
+sphinx-inline-tabs = {version = ">=2023.4.21", python = ">=3.9", optional = true}
+sphinx-notfound-page = {version = ">=1.0.0", python = ">=3.9", optional = true}
+sphinx-reredirects = {version = ">=0.1.5", python = ">=3.9", optional = true}
 
 # File storage dependencies installed as optional 'filesystem' extras
 fs-s3fs = {version = ">=1.1.1", optional = true}
@@ -106,7 +105,6 @@ docs = [
     "pytest",
     "sphinx",
     "sphinx-copybutton",
-    "sphinx-autobuild",
     "sphinx-inline-tabs",
     "sphinx-notfound-page",
     "sphinx-reredirects",
@@ -253,7 +251,6 @@ DEP002 = [
     "furo",
     "myst-parser",
     "sphinx",
-    "sphinx-autobuild",
     "sphinx-copybutton",
     "sphinx-inline-tabs",
     "sphinx-notfound-page",

singer_sdk/_singerlib/__init__.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from singer_sdk._singerlib import exceptions
 from singer_sdk._singerlib.catalog import (
     Catalog,
     CatalogEntry,
@@ -16,6 +17,7 @@
     SingerMessageType,
     StateMessage,
     exclude_null_dict,
+    format_message,
     write_message,
 )
 from singer_sdk._singerlib.schema import Schema, resolve_schema_references
@@ -35,7 +37,9 @@
     "SingerMessageType",
     "StateMessage",
     "StreamMetadata",
+    "exceptions",
     "exclude_null_dict",
+    "format_message",
     "resolve_schema_references",
     "strftime",
     "strptime_to_utc",

singer_sdk/_singerlib/encoding/__init__.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from ._base import GenericSingerReader, GenericSingerWriter, SingerMessageType
+from ._simple import SingerReader, SingerWriter
+
+__all__ = [
+    "GenericSingerReader",
+    "GenericSingerWriter",
+    "SingerMessageType",
+    "SingerReader",
+    "SingerWriter",
+]