Merge branch 'master' into rs-connect-refcount-cycle

Author: petyaslavova

.github/actions/run-tests/action.yml

@@ -315,7 +315,7 @@ runs:
       with:
         name: pytest-results-redis_${{inputs.redis-version}}-python_${{inputs.python-version}}-parser_${{env.PARSER_BACKEND}}-el_${{inputs.event-loop}}-config_${{inputs.test-config}}
         path: |
-          *-results.xml
+          junit-results/*-results.xml
           prof/**
           profile_output*
         if-no-files-found: error

.github/wordlist.txt

@@ -122,11 +122,14 @@ docstrings
 eg
 enums
 exc
+fieldset
+fieldsets
 firsttimersonly
 fo
 formatter
 genindex
 gmail
+himport
 hiredis
 http
 idx
@@ -162,6 +165,7 @@ parsers
 performant
 pmessage
 png
+positionally
 pre
 psubscribe
 pubsub

.github/workflows/integration.yaml

@@ -31,7 +31,7 @@ env:
   # for example after 8.2.1 is published, 8.2 image contains 8.2.1 content
   CURRENT_REDIS_VERSION: '8.8.0'
   REDIS_VERSION_CUSTOM_MAP: >-
-    8.10:unstable-29211243717-debian
+    8.10:8.10.0
 
 jobs:
   dependency-audit:

.github/workflows/nightly-metrics.yaml

@@ -0,0 +1,82 @@
+name: Nightly test metrics
+
+# Once a day, run the redis-py standalone test suite (master, default
+# client configuration, modules included) against a Redis server built
+# from redis' unstable branch, and report per-test durations to Grafana
+# for performance regression tracking.
+
+on:
+  schedule:
+    - cron: '30 3 * * *' # nightly, staggered from the 01:00 CI run
+  workflow_dispatch:
+
+concurrency:
+  group: nightly-metrics
+  cancel-in-progress: false
+
+permissions:
+  contents: read # to fetch code (actions/checkout)
+
+jobs:
+  nightly-metrics:
+    name: Redis unstable; test metrics
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      # Secrets can't be used in `if:` conditions, so a first step checks
+      # the token and later steps are gated on its output. Without the
+      # secret the job prints a warning and skips everything.
+      - name: Check for the metrics token
+        id: gate
+        env:
+          OTEL_TOKEN: ${{ secrets.OTEL_CI_VISIBILITY_TOKEN }}
+        run: |
+          if [ -z "$OTEL_TOKEN" ]; then
+            echo "::warning::The OTEL_CI_VISIBILITY_TOKEN secret is not set; skipping the nightly metrics run."
+            echo "run=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "run=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - uses: actions/checkout@v7
+        if: steps.gate.outputs.run == 'true'
+
+      - name: Resolve latest unstable Redis image
+        id: unstable-image
+        if: steps.gate.outputs.run == 'true'
+        run: |
+          set -euo pipefail
+          # Pick the newest tag client-side instead of relying on the API's
+          # ordering parameter.
+          tag=$(curl -sf "https://hub.docker.com/v2/repositories/redislabs/client-libs-test/tags?page_size=100&name=unstable-" \
+            | jq -r '.results | max_by(.last_updated) | .name // empty')
+          if [ -z "$tag" ]; then
+            echo "::error::Could not resolve an unstable client-libs-test image tag from Docker Hub"
+            exit 1
+          fi
+          echo "Using image tag: $tag"
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+
+      - name: Run tests
+        if: steps.gate.outputs.run == 'true'
+        uses: ./.github/actions/run-tests
+        with:
+          python-version: '3.12'
+          parser-backend: 'plain'
+          # The server under test is the unstable image resolved above;
+          # redis-version only drives run-tests' setup branching and the
+          # artifact name, and it must be numeric.
+          redis-version: '8.10'
+          client-libs-test-image: ${{ steps.unstable-image.outputs.tag }}
+          # One config, so each test reports exactly one duration per night.
+          test-config: 'default-legacy_responses-standalone'
+
+      - name: Report test metrics
+        # Report even when tests fail, but not when the run was cancelled.
+        if: ${{ !cancelled() && steps.gate.outputs.run == 'true' }}
+        uses: redis-developer/cae-otel-ci-visibility@v4
+        with:
+          junit-xml-folder: 'junit-results'
+          otlp-endpoint: 'https://otlp-gateway-prod-us-central-0.grafana.net/otlp/v1/metrics'
+          otlp-headers: 'Authorization=Basic ${{ secrets.OTEL_CI_VISIBILITY_TOKEN }}'
+          server-version: 'unstable'

.gitignore

@@ -19,6 +19,7 @@ coverage.xml
 .coverage*
 prof
 profile_output*
+junit-results/
 docker/stunnel/keys
 /dockers/*/node-*/*
 /dockers/*/tls/*

README.md

@@ -221,6 +221,66 @@ This is useful when:
 
 For the complete failover configuration options and examples, see the [Multi-database client docs](https://redis.readthedocs.io/en/latest/multi_database.html).
 
+### Bulk hash ingestion (HIMPORT)
+
+Redis 8.10 adds the `HIMPORT` command family for loading many hashes that share
+the same set of field names: register the field names once with `himport_prepare`,
+then create each hash by sending only its values. Keys written this way are regular
+hashes — every hash command works on them.
+
+``` python
+r.himport_prepare("users", ["name", "email", "age"])
+r.himport_set("user:1", "users", ["alice", "alice@example.com", "25"])
+r.himport_set("user:2", "users", ["bob", "bob@example.com", "30"])
+r.himport_discard("users")  # => 1
+```
+
+Values pair positionally with the prepared fields. Hash enumeration order
+(`HGETALL`, `HKEYS`) is not guaranteed to match the prepare order.
+
+**Fieldsets are connection state.** A prepared fieldset lives in the server-side
+session of the physical connection that prepared it: it is invisible to other
+connections and destroyed by a disconnect or `RESET`. redis-py handles this for you —
+`himport_prepare` records the fieldset in a client-level registry, and the `PREPARE`
+is applied lazily on whatever pooled connection serves each `himport_set` (and
+re-applied automatically after a reconnect, `RESET`, or Sentinel/cluster failover).
+You declare each fieldset once per client with `himport_prepare`; there is no
+constructor argument for it.
+
+For the highest ingestion throughput, send the `PREPARE` and its `SET`s in one
+pipeline — a single batch always executes on one connection:
+
+``` python
+with r.pipeline(transaction=False) as pipe:
+    pipe.himport_prepare("users", ["name", "email", "age"])
+    for uid, row in rows:
+        pipe.himport_set(f"user:{uid}", "users", row)
+    pipe.execute()
+```
+
+The automatic re-prepare applies to direct calls only, not to commands inside
+`pipeline`/`transaction` blocks: a batched `himport_set` relies on the single
+pre-flight `PREPARE` in that batch.
+
+With `RedisCluster`, `himport_prepare` / `himport_discard` / `himport_discard_all`
+update the client's shared, cluster-wide registry and return immediately — like the
+standalone API, they perform no server I/O of their own. The server-side `PREPARE`
+(and, after a discard, `DISCARD`) is applied lazily on each node's connection the
+next time it serves an `himport_set`, and re-applied after reconnects or failover;
+`himport_set` itself routes by the key's hash slot. A discard is therefore not
+removed from every server session at once: each connection drops the fieldset on its
+next `himport_set` (or on disconnect). With Sentinel, call
+`himport_prepare` on the long-lived client returned by `master_for(...)`; the fieldset
+survives failover automatically. HIMPORT is not supported on the multi-database
+(Active-Active) client.
+
+The async client mirrors this exactly:
+
+``` python
+await r.himport_prepare("users", ["name", "email", "age"])
+await r.himport_set("user:1", "users", ["alice", "alice@example.com", "25"])
+```
+
 ---------------------------------------------
 
 ### Author

docs/examples.rst

@@ -15,3 +15,4 @@ Examples
    examples/timeseries_examples
    examples/redis-stream-example
    examples/opentelemetry_api_examples
+   examples/hash_examples