Move code samples to master branch (#3271)

Move the code samples used for documentation into the master branch,
so they sit next to the code they document.

CHANGES

@@ -1,3 +1,4 @@
+    * Move doctests (doc code examples) to main branch
     * Update `ResponseT` type hint
     * Allow to control the minimum SSL version
     * Add an optional lock_name attribute to LockError.

doctests/README.md

@@ -0,0 +1,32 @@
+# Command examples for redis.io
+
+## How to add an example
+
+Create regular python file in the current folder with meaningful name. It makes sense prefix example files with
+command category (e.g. string, set, list, hash, etc) to make navigation in the folder easier. Files ending in *.py*
+are automatically run by the test suite.
+
+### Special markup
+
+See https://github.com/redis-stack/redis-stack-website#readme for more details.
+
+## How to test examples
+
+Examples are standalone python scripts, committed to the *doctests* directory. These scripts assume that the
+```requirements.txt``` and ```dev_requirements.txt``` from this repository have been installed, as per below.
+
+```bash
+pip install -r requirements.txt
+pip install -r dev_requirements.txt
+pip install -r doctests/requirements.txt
+```
+
+Note - the CI process, runs the basic ```black``` and ```isort``` linters against the examples. Assuming
+the requirements above have been installed you can run ```black yourfile.py``` and ```isort yourfile.py```
+locally to validate the linting, prior to CI.
+
+Just include necessary assertions in the example file and run
+```bash
+sh doctests/run_examples.sh
+```
+to test all examples in the current folder.

doctests/dt_bitfield.py

@@ -0,0 +1,34 @@
+# EXAMPLE: bitfield_tutorial
+# HIDE_START
+"""
+Code samples for Bitfield doc pages:
+    https://redis.io/docs/latest/develop/data-types/bitfields/
+"""
+import redis
+
+r = redis.Redis(decode_responses=True)
+# HIDE_END
+
+# REMOVE_START
+r.delete("bike:1:stats")
+# REMOVE_END
+
+# STEP_START bf
+bf = r.bitfield("bike:1:stats")
+res1 = bf.set("u32", "#0", 1000).execute()
+print(res1)  # >>> [0]
+
+res2 = bf.incrby("u32", "#0", -50).incrby("u32", "#1", 1).execute()
+print(res2)  # >>> [950, 1]
+
+res3 = bf.incrby("u32", "#0", 500).incrby("u32", "#1", 1).execute()
+print(res3)  # >>> [1450, 2]
+
+res4 = bf.get("u32", "#0").get("u32", "#1").execute()
+print(res4)  # >>> [1450, 2]
+# STEP_END
+
+# REMOVE_START
+assert res1 == [0]
+assert res4 == [1450, 2]
+# REMOVE_END

doctests/dt_bitmap.py

@@ -0,0 +1,40 @@
+# EXAMPLE: bitmap_tutorial
+# HIDE_START
+"""
+Code samples for Bitmap doc pages:
+    https://redis.io/docs/latest/develop/data-types/bitmaps/
+"""
+import redis
+
+r = redis.Redis(decode_responses=True)
+# HIDE_END
+
+# REMOVE_START
+r.delete("pings:2024-01-01-00:00")
+# REMOVE_END
+
+# STEP_START ping
+res1 = r.setbit("pings:2024-01-01-00:00", 123, 1)
+print(res1)  # >>> 0
+
+res2 = r.getbit("pings:2024-01-01-00:00", 123)
+print(res2)  # >>> 1
+
+res3 = r.getbit("pings:2024-01-01-00:00", 456)
+print(res3)  # >>> 0
+# STEP_END
+
+# REMOVE_START
+assert res1 == 0
+# REMOVE_END
+
+# STEP_START bitcount
+# HIDE_START
+r.setbit("pings:2024-01-01-00:00", 123, 1)
+# HIDE_END
+res4 = r.bitcount("pings:2024-01-01-00:00")
+print(res4)  # >>> 1
+# STEP_END
+# REMOVE_START
+assert res4 == 1
+# REMOVE_END

doctests/dt_bloom.py

@@ -0,0 +1,41 @@
+# EXAMPLE: bf_tutorial
+# HIDE_START
+"""
+Code samples for Bloom filter doc pages:
+    https://redis.io/docs/latest/develop/data-types/probabilistic/bloom-filter/
+"""
+import redis
+
+r = redis.Redis(decode_responses=True)
+# HIDE_END
+
+# STEP_START bloom
+res1 = r.bf().reserve("bikes:models", 0.01, 1000)
+print(res1)  # >>> True
+
+res2 = r.bf().add("bikes:models", "Smoky Mountain Striker")
+print(res2)  # >>> True
+
+res3 = r.bf().exists("bikes:models", "Smoky Mountain Striker")
+print(res3)  # >>> True
+
+res4 = r.bf().madd(
+    "bikes:models",
+    "Rocky Mountain Racer",
+    "Cloudy City Cruiser",
+    "Windy City Wippet",
+)
+print(res4)  # >>> [True, True, True]
+
+res5 = r.bf().mexists(
+    "bikes:models",
+    "Rocky Mountain Racer",
+    "Cloudy City Cruiser",
+    "Windy City Wippet",
+)
+print(res5)  # >>> [True, True, True]
+# STEP_END
+
+# REMOVE_START
+assert res1 is True
+# REMOVE_END

doctests/dt_cms.py

@@ -0,0 +1,32 @@
+# EXAMPLE: cms_tutorial
+# HIDE_START
+"""
+Code samples for Count-min sketch doc pages:
+    https://redis.io/docs/latest/develop/data-types/probabilistic/count-min-sketch/
+"""
+import redis
+
+r = redis.Redis(decode_responses=True)
+# HIDE_END
+# REMOVE_START
+r.delete("bikes:profit")
+# REMOVE_END
+
+# STEP_START cms
+res1 = r.cms().initbyprob("bikes:profit", 0.001, 0.002)
+print(res1)  # >>> True
+
+res2 = r.cms().incrby("bikes:profit", ["Smoky Mountain Striker"], [100])
+print(res2)  # >>> [100]
+
+res3 = r.cms().incrby(
+    "bikes:profit", ["Rocky Mountain Racer", "Cloudy City Cruiser"], [200, 150]
+)
+print(res3)  # >>> [200, 150]
+
+res4 = r.cms().query("bikes:profit", "Smoky Mountain Striker")
+print(res4)  # >>> [100]
+
+res5 = r.cms().info("bikes:profit")
+print(res5.width, res5.depth, res5.count)  # >>> 2000 9 450
+# STEP_END

doctests/dt_cuckoo.py

@@ -0,0 +1,36 @@
+# EXAMPLE: cuckoo_tutorial
+# HIDE_START
+"""
+Code samples for Cuckoo filter doc pages:
+    https://redis.io/docs/latest/develop/data-types/probabilistic/cuckoo-filter/
+"""
+import redis
+
+r = redis.Redis(decode_responses=True)
+# HIDE_END
+
+# REMOVE_START
+r.delete("bikes:models")
+# REMOVE_END
+
+# STEP_START cuckoo
+res1 = r.cf().reserve("bikes:models", 1000000)
+print(res1)  # >>> True
+
+res2 = r.cf().add("bikes:models", "Smoky Mountain Striker")
+print(res2)  # >>> 1
+
+res3 = r.cf().exists("bikes:models", "Smoky Mountain Striker")
+print(res3)  # >>> 1
+
+res4 = r.cf().exists("bikes:models", "Terrible Bike Name")
+print(res4)  # >>> 0
+
+res5 = r.cf().delete("bikes:models", "Smoky Mountain Striker")
+print(res5)  # >>> 1
+# STEP_END
+
+# REMOVE_START
+assert res1 is True
+assert res5 == 1
+# REMOVE_END

doctests/dt_geo.py

@@ -0,0 +1,45 @@
+# EXAMPLE: geo_tutorial
+# HIDE_START
+"""
+Code samples for Geospatial doc pages:
+    https://redis.io/docs/latest/develop/data-types/geospatial/
+"""
+import redis
+
+r = redis.Redis(decode_responses=True)
+# HIDE_END
+# REMOVE_START
+r.delete("bikes:rentable")
+# REMOVE_END
+
+# STEP_START geoadd
+res1 = r.geoadd("bikes:rentable", [-122.27652, 37.805186, "station:1"])
+print(res1)  # >>> 1
+
+res2 = r.geoadd("bikes:rentable", [-122.2674626, 37.8062344, "station:2"])
+print(res2)  # >>> 1
+
+res3 = r.geoadd("bikes:rentable", [-122.2469854, 37.8104049, "station:3"])
+print(res3)  # >>> 1
+# STEP_END
+
+# REMOVE_START
+assert res1 == 1
+assert res2 == 1
+assert res3 == 1
+# REMOVE_END
+
+# STEP_START geosearch
+res4 = r.geosearch(
+    "bikes:rentable",
+    longitude=-122.27652,
+    latitude=37.805186,
+    radius=5,
+    unit="km",
+)
+print(res4)  # >>> ['station:1', 'station:2', 'station:3']
+# STEP_END
+
+# REMOVE_START
+assert res4 == ["station:1", "station:2", "station:3"]
+# REMOVE_END

doctests/dt_hash.py

@@ -0,0 +1,107 @@
+# EXAMPLE: hash_tutorial
+# HIDE_START
+"""
+Code samples for Hash doc pages:
+    https://redis.io/docs/latest/develop/data-types/hashes/
+"""
+import redis
+
+r = redis.Redis(decode_responses=True)
+# HIDE_END
+# STEP_START set_get_all
+res1 = r.hset(
+    "bike:1",
+    mapping={
+        "model": "Deimos",
+        "brand": "Ergonom",
+        "type": "Enduro bikes",
+        "price": 4972,
+    },
+)
+print(res1)
+# >>> 4
+
+res2 = r.hget("bike:1", "model")
+print(res2)
+# >>> 'Deimos'
+
+res3 = r.hget("bike:1", "price")
+print(res3)
+# >>> '4972'
+
+res4 = r.hgetall("bike:1")
+print(res4)
+# >>> {'model': 'Deimos', 'brand': 'Ergonom', 'type': 'Enduro bikes', 'price': '4972'}
+
+# STEP_END
+
+# REMOVE_START
+assert res1 == 4
+assert res2 == "Deimos"
+assert res3 == "4972"
+assert res4 == {
+    "model": "Deimos",
+    "brand": "Ergonom",
+    "type": "Enduro bikes",
+    "price": "4972",
+}
+# REMOVE_END
+
+# STEP_START hmget
+res5 = r.hmget("bike:1", ["model", "price"])
+print(res5)
+# >>> ['Deimos', '4972']
+# STEP_END
+
+# REMOVE_START
+assert res5 == ["Deimos", "4972"]
+# REMOVE_END
+
+# STEP_START hincrby
+res6 = r.hincrby("bike:1", "price", 100)
+print(res6)
+# >>> 5072
+res7 = r.hincrby("bike:1", "price", -100)
+print(res7)
+# >>> 4972
+# STEP_END
+
+# REMOVE_START
+assert res6 == 5072
+assert res7 == 4972
+# REMOVE_END
+
+
+# STEP_START incrby_get_mget
+res11 = r.hincrby("bike:1:stats", "rides", 1)
+print(res11)
+# >>> 1
+res12 = r.hincrby("bike:1:stats", "rides", 1)
+print(res12)
+# >>> 2
+res13 = r.hincrby("bike:1:stats", "rides", 1)
+print(res13)
+# >>> 3
+res14 = r.hincrby("bike:1:stats", "crashes", 1)
+print(res14)
+# >>> 1
+res15 = r.hincrby("bike:1:stats", "owners", 1)
+print(res15)
+# >>> 1
+res16 = r.hget("bike:1:stats", "rides")
+print(res16)
+# >>> 3
+res17 = r.hmget("bike:1:stats", ["crashes", "owners"])
+print(res17)
+# >>> ['1', '1']
+# STEP_END
+
+# REMOVE_START
+assert res11 == 1
+assert res12 == 2
+assert res13 == 3
+assert res14 == 1
+assert res15 == 1
+assert res16 == "3"
+assert res17 == ["1", "1"]
+# REMOVE_END