limits 4.7.2__tar.gz → 4.7.3__tar.gz

{limits-4.7.2 → limits-4.7.3}/HISTORY.rst

@@ -3,6 +3,18 @@
 Changelog
 =========
 
+v4.7.3
+------
+Release Date: 2025-04-12
+
+* Documentation
+
+  * Expand benchmark results to included preseeded limits
+
+* Bug Fix
+
+  * Handle clearing missing key with memcache + async
+
 v4.7.2
 ------
 Release Date: 2025-04-09
@@ -873,5 +885,6 @@ Release Date: 2015-01-08
 
 
 
+
 
 

{limits-4.7.2 → limits-4.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: limits
-Version: 4.7.2
+Version: 4.7.3
 Summary: Rate limiting utilities
 Home-page: https://limits.readthedocs.org
 Author: Ali-Akber Saifee

{limits-4.7.2 → limits-4.7.3}/doc/source/conf.py

@@ -39,7 +39,15 @@ else:
         "branch": git_info.get("branch", ""),
         "sha": git_info.get("long", None)
     }
-
+benchmark_param_mapping = {
+    "percentage_full": {
+        "display": "Percentage Seeded",
+        "info": "Percentage of rate limit already filled before the benchmark is run",
+    },
+    "async": {"display": "Asyncio", "info": "Using asyncio storage implementation"},
+    "storage_type": {"display": "Storage", "info": "Storage Backend"},
+    "strategy": {"display": "Strategy", "info": "Rate Limiting Strategy"},
+}
 html_static_path = ["_static"]
 
 html_css_files = [
@@ -73,6 +81,7 @@ extensions = [
     "sphinxext.opengraph",
     "sphinxcontrib.programoutput",
     "sphinx_copybutton",
+    "sphinx_design",
     "sphinx_inline_tabs",
     "sphinx_paramlinks",
     "bench_chart",

{limits-4.7.2 → limits-4.7.3}/doc/source/ext/_static/benchmark-chart.css

@@ -1,3 +1,11 @@
+.plot-container {
+  filter: invert(100%);
+}
+
+body[data-theme="light"] .plot-container {
+  filter: invert(0);
+}
+
 .benchmark-chart {
   width: 100%;
 }
@@ -34,28 +42,56 @@
   0% {
     opacity: 0;
   }
-  ,
   25% {
-    opacity: 25%;
+    opacity: 0.25;
   }
-  ,
   50% {
-    opacity: 50%;
+    opacity: 0.5;
   }
-  ,
   90% {
-    opacity: 90%;
+    opacity: 0.9;
   }
-  ,
   100% {
-    opacity: 100%;
+    opacity: 1;
+  }
+}
+.benchmark-filters {
+  padding-top: 1em;
+  padding-bottom: 1em;
+  display: flex;
+  justify-content: flex-end;
+}
+.benchmark-filter-dropdowns {
+  display: flex;
+  align-items: flex-end;
+  justify-content: flex-end;
+  margin-top: 2em;
+  flex-direction: row;
+  @media only screen and (max-width: 800px) {
+    flex-basis: min-content;
+  }
+  @media only screen and (max-width: 400px) {
+    flex-basis: max-content;
+    flex-direction: column;
   }
 }
 
-.plot-container {
-  filter: invert(100%);
+.benchmark-filter {
+  display: flex;
+  flex-direction: row;
+  gap: 0.25em;
+  padding: 0.25em;
 }
 
-body[data-theme="light"] .plot-container {
-  filter: invert(0);
+.benchmark-filter label {
+  font-size: small;
+  font-weight: bold;
+}
+
+.benchmark-filter select {
+  font-size: small;
+  border: 1px solid;
+  border-radius: 0.4em;
+}
+.benchmark-filter input[type="checkbox"] {
 }

limits-4.7.3/doc/source/ext/_static/js/benchmark-chart.js

@@ -0,0 +1,343 @@
+import { render, html } from "https://unpkg.com/uhtml@3.2.1?module";
+import { fetchBenchmarkData } from "./benchmark-loader.js";
+const KNOWN_PARAMS = [
+  "storage_type",
+  "limit",
+  "strategy",
+  "async",
+  "percentage_full",
+];
+
+function getBenchmarkData(result, query) {
+  let benchmarks = result.benchmarks;
+  return benchmarks.filter(function (benchmark) {
+    let okay = true;
+    if (query) {
+      Object.entries(query).forEach((entry) => {
+        let key = entry[0];
+        let value = entry[1];
+        if (
+          key != "group" &&
+          !(value === "") && // i.e. any.
+          benchmark.params[key] != null &&
+          benchmark.params[key] != value
+        ) {
+          okay = false;
+        } else if (key == "group" && value != benchmark.group) {
+          okay = false;
+        }
+      });
+    }
+    return okay;
+  });
+}
+
+function formatParam(key, str) {
+  if (key === "limit") {
+    var m = str.match(/(\d+(?:\.\d+)?)\s+per\s+1\s+(\w+)/i);
+    if (!m) return str;
+    var n = parseFloat(m[1]),
+      u = m[2].toLowerCase(),
+      num =
+        n >= 1000
+          ? (n / 1000) % 1 === 0
+            ? n / 1000 + "K"
+            : (n / 1000).toFixed(1) + "K"
+          : n.toString(),
+      umap = {
+        second: "s",
+        seconds: "s",
+        minute: "min",
+        minutes: "mins",
+        hour: "hr",
+        hours: "hr",
+        day: "day",
+        days: "day",
+      };
+    return num + "/" + (umap[u] || u);
+  } else if (key === "percentage_full") {
+    return `${str}% Seeded`;
+  }
+  return str;
+}
+
+function nameTransform(benchmark, stripParams, query) {
+  let name = benchmark.name;
+  let params = benchmark.params;
+  name = name
+    .replace(/\[.*?\]/, "")
+    .replace("_async", "")
+    .replaceAll("_", "-");
+  name = name.replace(benchmark.group, "");
+  let queryParam = Object.entries(query).map((entry) => entry[0]);
+  let additional = getRemainingGroups(benchmark, query);
+  Object.entries(additional).forEach((param) => {
+    let value = formatParam(param[0], param[1]);
+    if (name) {
+      name += ` - ${value}`;
+    } else {
+      name = `${value}`;
+    }
+  });
+  return name;
+}
+
+function getRemainingGroups(benchmark, query) {
+  let queryParam = Object.entries(query).map((entry) => entry[0]);
+  let additional = {};
+  Object.entries(benchmark.params).forEach((param) => {
+    const key = param[0];
+    const value = param[1];
+    if (
+      (!queryParam.includes(key) || query?.[key] === "") &&
+      KNOWN_PARAMS.includes(key)
+    ) {
+      additional[key] = value;
+    }
+  });
+  return additional;
+}
+
+function getColorForStorage(storageType) {
+  const storageColorMap = {
+    memory: window
+      .getComputedStyle(document.body)
+      .getPropertyValue("--color-purple"),
+    mongodb: window
+      .getComputedStyle(document.body)
+      .getPropertyValue("--color-yellow"),
+    memcached: window
+      .getComputedStyle(document.body)
+      .getPropertyValue("--color-aqua"),
+    redis: window
+      .getComputedStyle(document.body)
+      .getPropertyValue("--color-red"),
+  };
+
+  // Fallback color if an unknown storageType appears
+  return storageColorMap[storageType] || "#7f7f7f"; // gray
+}
+
+function sortBenchmarksByParams(benchmarks, sortKeys) {
+  return benchmarks.sort(function (a, b) {
+    for (const key of sortKeys) {
+      let valA = (a.params?.[key] || "").toLowerCase();
+      let valB = (b.params?.[key] || "").toLowerCase();
+      if (key === "limit") {
+        valA = parseInt(valA.split(" ")[0], 10);
+        valB = parseInt(valB.split(" ")[0], 10);
+      }
+      if (valA < valB) return -1;
+      if (valA > valB) return 1;
+    }
+    return a.name.localeCompare(b.name);
+  });
+}
+
+let dispatched = new Set();
+
+document.addEventListener("DOMContentLoaded", function () {
+  const charts = document.querySelectorAll(".benchmark-chart");
+  charts.forEach((chart) => {
+    const source = chart.dataset.source;
+    const filters = JSON.parse(chart.dataset.filters);
+    const query = JSON.parse(chart.dataset.query);
+    const paramMapping = JSON.parse(chart.dataset.paramMapping);
+    const chartId = chart.dataset.chartId;
+    let sortBy = JSON.parse(
+      chart.dataset.sortBy || '["storage_type", "limit"]',
+    );
+    render(
+      chart,
+      html`
+        <div class="benchmark-chart-loading">
+          <span>Loading</span>
+        </div>
+      `,
+    );
+    if (!dispatched.has(source)) {
+      fetchBenchmarkData(`${source}.json`)
+        .then((result) => {
+          window.Benchmarks[source] = result;
+          let event = new Event(`${source}-loaded`);
+          window.dispatchEvent(event);
+        })
+        .catch((error) => {
+          let event = new Event(`${source}-failed`);
+          window.dispatchEvent(event);
+        });
+    }
+    dispatched.add(source);
+    window.addEventListener(`${chart.dataset.source}-failed`, function () {
+      chart.querySelector(".benchmark-chart-loading")?.remove();
+      render(
+        chart,
+        html`
+          <div class="benchmark-chart-error">Benchmark data not available.</div>
+        `,
+      );
+    });
+    window.addEventListener(`${chart.dataset.source}-loaded`, function () {
+      chart.innerHTML = "";
+      chart.querySelector(".benchmark-chart-loading")?.remove();
+      const results = Benchmarks[chart.dataset.source];
+      const allBenchmarks = getBenchmarkData(results, query);
+      const currentFilters = Object.fromEntries(
+        Object.entries(filters).map(([key, value]) => {
+          return typeof value.default === "boolean"
+            ? [key, value.default]
+            : [key, value.default != null ? value.default.toString() : ""];
+        }),
+      );
+      const queryFilter = { ...query, ...currentFilters };
+      const dropdownTarget = document.createElement("div");
+      dropdownTarget.classList.add("benchmark-filters");
+      const chartTarget = document.createElement("div");
+      chart.append(chartTarget);
+      chart.append(dropdownTarget);
+      function renderDropdowns() {
+        const dropdowns = Object.entries(filters).map(([key]) => {
+          const fullName = `${chartId}-${key}`;
+          const uniqueValues = [
+            ...new Set(allBenchmarks.map((b) => b.params?.[key])),
+          ].sort();
+          const isBoolean =
+            uniqueValues.length === 2 &&
+            uniqueValues.includes(true) &&
+            uniqueValues.includes(false);
+          if (isBoolean) {
+            return html`
+              <div class="benchmark-filter" title=${paramMapping[key]?.info}>
+                <input
+                  type="checkbox"
+                  id=${fullName}
+                  ?checked=${currentFilters[key] === true}
+                  onchange=${(e) => {
+                    currentFilters[key] = e.target.checked;
+                    renderChartWithFilters(currentFilters);
+                  }}
+                />
+                <label for=${fullName}>
+                  ${paramMapping[key]?.display || key}
+                </label>
+              </div>
+            `;
+          } else {
+            return html`
+              <div class="benchmark-filter" title=${paramMapping[key]?.info}>
+                <label for=${fullName}>
+                  ${paramMapping[key]?.display || key}
+                  <select
+                    id=${fullName}
+                    onchange=${(e) => {
+                      const value = e.target.value;
+                      if (value) {
+                        currentFilters[key] =
+                          value === "false"
+                            ? false
+                            : value === "true"
+                              ? true
+                              : value;
+                      } else {
+                        currentFilters[key] = "";
+                      }
+                      renderChartWithFilters(currentFilters);
+                    }}
+                  >
+                    <option value="" ?selected=${currentFilters[key] == ""}>
+                      All
+                    </option>
+                    ${uniqueValues.map(
+                      (val) => html`
+                        <option
+                          value=${val}
+                          ?selected=${currentFilters[key] == val.toString()}
+                        >
+                          ${val}
+                        </option>
+                      `,
+                    )}
+                  </select>
+                </label>
+              </div>
+            `;
+          }
+        });
+        render(
+          dropdownTarget,
+          html`<div class="benchmark-filter-dropdowns">${dropdowns}</div>`,
+        );
+      }
+      function legendKeyFunc(benchmark, key) {
+        return key === "group" ? benchmark.group : benchmark.params[key];
+      }
+      function renderChartWithFilters(currentFilters) {
+        const queryFilter = { ...query, ...currentFilters };
+        const data = sortBenchmarksByParams(
+          getBenchmarkData(results, queryFilter),
+          sortBy,
+        );
+        let legendGroupKey =
+          queryFilter?.storage_type == ""
+            ? "storage_type"
+            : Object.entries(queryFilter).find((entry) => entry[1] === "")?.[0];
+        Plotly.newPlot(
+          chartTarget,
+          data.map((benchmark) => ({
+            type: "box",
+            name: nameTransform(benchmark, true, queryFilter),
+            y: benchmark.stats.data || [
+              benchmark.stats.min * 1e3,
+              benchmark.stats.q1 * 1e3,
+              benchmark.stats.median * 1e3,
+              benchmark.stats.q3 * 1e3,
+              benchmark.stats.max * 1e3,
+            ],
+            boxmean: true,
+            boxpoints: false,
+            line: { width: 1 },
+            marker: {
+              color: getColorForStorage(benchmark.params.storage_type),
+            },
+            showlegend: true,
+            legendgroup: legendKeyFunc(benchmark, legendGroupKey),
+            legendgrouptitle: {
+              text: formatParam(
+                legendGroupKey,
+                legendKeyFunc(benchmark, legendGroupKey),
+              ),
+            },
+          })),
+          {
+            yaxis: {
+              title: { text: "Time (ms)" },
+              exponentformat: "none",
+              ticksuffix: " ms",
+              tickformat: ",.2f",
+            },
+          },
+          {
+            responsive: true,
+            displaylogo: false,
+          },
+        );
+      }
+
+      renderDropdowns();
+      renderChartWithFilters(currentFilters);
+      let initial = true;
+      chartTarget.on("plotly_afterplot", function () {
+        const { hash } = window.location;
+        if (hash && initial) {
+          initial = false;
+          const target = document.querySelector(hash);
+          if (target) {
+            setTimeout(function () {
+              target.scrollIntoView({ behavior: "instant" });
+            }, 10);
+          }
+        }
+      });
+    });
+  });
+});

{limits-4.7.2 → limits-4.7.3}/doc/source/ext/bench_chart.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import json
 import os
+import uuid
 from typing import TYPE_CHECKING
 
 from docutils import nodes
@@ -31,13 +32,14 @@ def query(argument):
 
 
 def filters(argument):
-    filters: dict[str, list | bool] = {}
+    filters: dict[str, dict[str, str | bool]] = {}
     for filter in argument.strip().split(","):
-        if ":" in filter:
-            source, value = filter.split(":")
-            filters.setdefault(source, []).append(value)
+        source, default = filter.split("=")
+        if ":" in source:
+            source, label = source.split(":")
         else:
-            filters[filter] = True
+            source, label = source, source
+        filters[source] = {"label": label, "default": check_bool(default)}
     return filters
 
 
@@ -66,7 +68,6 @@ class BenchmarkDetails(SphinxDirective):
 
 
 class BenchmarkChart(SphinxDirective):
-    required_arguments = 0
     final_argument_whitespace = False
     option_spec = {
         "source": str,
@@ -78,17 +79,18 @@ class BenchmarkChart(SphinxDirective):
 
     def run(self):
         source = self.options.get("source", "benchmark-summary")
-        filters = self.options.get("filters", ["group"])
+        filters = self.options.get("filters", {})
         query = self.options.get("query", {})
         sortBy = self.options.get("sort", [])
-
         html = f"""
                 <div
                     class='benchmark-chart'
                     data-source='{source}'
                     data-filters='{json.dumps(filters)}'
                     data-query='{json.dumps(query)}'
-                    data-sortBy='{json.dumps(sortBy)}'>
+                    data-sort-by='{json.dumps(sortBy)}'
+                    data-chart-id='{uuid.uuid4().hex}'
+                    data-param-mapping='{json.dumps(self.env.config.benchmark_param_mapping)}'>
                 </div>
                 """
 
@@ -117,6 +119,7 @@ def setup(app: Sphinx):
     app.add_directive("benchmark-chart", BenchmarkChart)
     app.add_directive("benchmark-details", BenchmarkDetails)
     app.add_config_value("benchmark_git_context", default={}, rebuild="env")
+    app.add_config_value("benchmark_param_mapping", default={}, rebuild="env")
 
     def add_assets(app, env) -> None:
         static_path = os.path.join(here, "_static")

limits-4.7.3/doc/source/performance.rst

@@ -0,0 +1,126 @@
+Performance
+===========
+
+The performance of each rate-limiting strategy and storage backend
+differs in both throughput and storage cost characteristics.
+
+Performance by storage and strategy
+-----------------------------------
+Below you will find benchmarks for each strategy and storage giving
+a high level overview of the performance.
+
+
+.. dropdown:: Benchmark parameters
+
+   - 100 unique virtual users (i.e. unique rate limit keys)
+   - A rate limit of ``500/minute``
+   - Each virtual user's limit was pre-seeded to be 50% full.
+
+   See :ref:`performance:benchmark run details` for information on the benchmarking
+   environment.
+
+.. tab-set::
+
+    .. tab-item:: Hit
+
+       Performance of :meth:`~limits.strategies.RateLimiter.hit`
+       by storage & strategy.
+
+       .. benchmark-chart::
+          :source: benchmark-summary
+          :query: limit=500 per 1 minute,group=hit,percentage_full=50
+          :sort: storage_type,strategy
+          :filters: storage_type=,strategy=,async=false
+
+
+    .. tab-item:: Test
+
+       Performance of :meth:`~limits.strategies.RateLimiter.test`
+       by storage & strategy.
+
+       .. benchmark-chart::
+          :source: benchmark-summary
+          :query: limit=500 per 1 minute,group=test,percentage_full=50
+          :sort: storage_type,strategy
+          :filters: storage_type=,strategy=,async=false
+
+    .. tab-item:: Get Window Stats
+
+       Performance of :meth:`~limits.strategies.RateLimiter.get_window_stats`
+       by storage & strategy.
+
+       .. benchmark-chart::
+          :source: benchmark-summary
+          :query: limit=500 per 1 minute,group=get-window-stats,percentage_full=50
+          :sort: storage_type,strategy
+          :filters: storage_type=,strategy=,async=false
+
+
+Performance implication of limit sizes
+--------------------------------------
+
+Though for :ref:`strategies:fixed window` and :ref:`strategies:sliding window counter` both the
+storage cost and performance of operations remains constant when the limit window and size varies,
+this is not true for :ref:`strategies:moving window` which maintains a complete log of successful
+requests within the window.
+
+The following benchmarks demonstrate the implications when using various limits.
+
+.. dropdown:: Benchmark parameters
+
+  - 100 unique virtual users
+  - Rate limits of
+
+    - ``500/minute``
+    - ``10000/day``
+    - ``100000/day``
+  - Each virtual user's limit was pre-seeded to be:
+
+    - 5% full.
+    - 50% full.
+    - 90% full.
+
+  See :ref:`performance:benchmark run details` for information on the benchmarking
+  environment.
+
+.. tab-set::
+
+   .. tab-item::  Hit
+
+      Performance of :meth:`~limits.strategies.RateLimiter.hit`
+      with various rate limits
+
+      .. benchmark-chart::
+         :source: benchmark-summary
+         :query: group=hit
+         :sort: storage_type,limit
+         :filters: strategy=,percentage_full=50,storage_type=,async=false
+
+   .. tab-item:: Test
+
+      Performance of :meth:`~limits.strategies.RateLimiter.test`
+      with various rate limits
+
+      .. benchmark-chart::
+         :source: benchmark-summary
+         :query: group=test
+         :sort: storage_type,limit
+         :filters: strategy=,percentage_full=50,storage_type=,async=false
+
+
+   .. tab-item:: Get Window Stats
+
+      Performance of :meth:`~limits.strategies.RateLimiter.get_window_stats`
+      with various rate limits
+
+      .. benchmark-chart::
+         :source: benchmark-summary
+         :query: group=get-window-stats
+         :sort: storage_type,limit
+         :filters: strategy=,percentage_full=50,storage_type=,async=false
+
+
+Benchmark run details
+---------------------
+.. benchmark-details::
+   :source: benchmark-summary

{limits-4.7.2 → limits-4.7.3}/limits/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2025-04-09T14:27:52-0700",
+ "date": "2025-04-12T18:43:47-0700",
  "dirty": false,
  "error": null,
- "full-revisionid": "451bd270b52aff6324de3ed6576a8fc87fbdaf9a",
- "version": "4.7.2"
+ "full-revisionid": "58af4445a2d0b1de9251cd60e847d25267b4830d",
+ "version": "4.7.3"
 }
 '''  # END VERSION_JSON
 

{limits-4.7.2 → limits-4.7.3}/limits/aio/storage/memcached.py

@@ -93,7 +93,10 @@ class MemcachedStorage(Storage, SlidingWindowCounterSupport, TimestampedSlidingW
         """
         :param key: the key to clear rate limits for
         """
-        await (await self.get_storage()).delete(key.encode("utf-8"))
+        try:
+            await (await self.get_storage()).delete(key.encode("utf-8"))
+        except self.dependency.NotFoundCommandError:
+            pass
 
     async def decr(self, key: str, amount: int = 1, noreply: bool = False) -> int:
         """