Merge branch 'main' into 1046-feat-faster-json-dumps-with-msgspec

.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

.pre-commit-config.yaml

@@ -50,7 +50,7 @@ repos:
   - id: check-readthedocs
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.5.1
+  rev: v0.5.2
   hooks:
   - id: ruff
     args: [--fix, --exit-non-zero-on-fix, --show-fixes]

docs/conf.py

@@ -14,6 +14,7 @@
 #
 from __future__ import annotations
 
+import os
 import sys
 from datetime import datetime
 from pathlib import Path
@@ -60,10 +61,19 @@
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 # -- Options for HTML output -----------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-#
+
+# Define the canonical URL for sdk.meltano.com
+html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")
+html_context = {}
+
+# Tell Jinja2 templates the build is running on Read the Docs
+if os.environ.get("READTHEDOCS", "") == "True":
+    html_context["READTHEDOCS"] = True
+
 html_logo = "_static/img/logo.svg"
 html_theme = "furo"
 html_theme_options = {
@@ -155,6 +165,7 @@
 intersphinx_mapping = {
     "requests": ("https://requests.readthedocs.io/en/latest/", None),
     "python": ("https://docs.python.org/3/", None),
+    "faker": ("https://faker.readthedocs.io/en/master/", None),
 }
 
 # -- Options for linkcode --------------------------------------------------------------

docs/stream_maps.md

@@ -228,12 +228,16 @@ can be referenced directly by mapping expressions.
 
 #### Built-In Functions
 
-- `md5()` - returns an inline MD5 hash of any string, outputting the string representation
-    of the hash's hex digest.
+- [`md5()`](inv:python:py:module:#hashlib) - returns an inline MD5 hash of any string, outputting
+    the string representation of the hash's hex digest.
   - This is defined by the SDK internally with native python:
-    `hashlib.md5(<input>.encode("utf-8")).hexdigest()`.
-- `datetime` - This is the datetime module object from the Python standard library. You can access
-    datetime.datetime, datetime.timedelta, etc.
+    [`hashlib.md5(<input>.encode("utf-8")).hexdigest()`](inv:python:py:method:#hashlib.hash.hexdigest).
+- [`datetime`](inv:python:py:module:#datetime) - This is the datetime module object from the Python
+    standard library. You can access [`datetime.datetime`](inv:python:py:class:#datetime.datetime),
+    [`datetime.timedelta`](inv:python:py:class:#datetime.timedelta), etc.
+- [`json`](inv:python:py:module:#json) - This is the json module object from the Python standard
+    library. Primarily used for calling [`json.dumps()`](inv:python:py:function:#json.dumps)
+    and [`json.loads()`](inv:python:py:function:#json.loads).
 
 #### Built-in Variable Names
 
@@ -242,10 +246,12 @@ can be referenced directly by mapping expressions.
 - `record` - an alias for the record values dictionary in the current stream.
 - `_` - same as `record` but shorter to type
 - `self` - the existing property value if the property already exists
-- `fake` - a [`Faker`](https://faker.readthedocs.io/en/master/) instance, configurable via `faker_config` (see previous example) - see the built-in [standard providers](https://faker.readthedocs.io/en/master/providers.html) for available methods
+- `fake` - a [`Faker`](inv:faker:std:doc#index) instance, configurable via `faker_config`
+  (see previous example) - see the built-in [standard providers](inv:faker:std:doc#providers)
+  for available methods
 
   ```{tip}
-  The `fake` object is only available if the plugin specifies `faker` as an addtional dependency (through the `singer-sdk` `faker` extra, or directly).
+  The `fake` object is only available if the plugin specifies `faker` as an additional dependency (through the `singer-sdk` `faker` extra, or directly).
   ```
 
 #### Automatic Schema Detection

noxfile.py

@@ -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)