CacheControl 0.14.3__tar.gz → 0.15.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/PKG-INFO +10 -25
  2. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/cachecontrol/__init__.py +5 -3
  3. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/cachecontrol/adapter.py +4 -1
  4. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/cachecontrol/caches/redis_cache.py +9 -4
  5. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/cachecontrol/controller.py +92 -80
  6. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/cachecontrol/filewrapper.py +9 -4
  7. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/cachecontrol/serialize.py +5 -0
  8. cachecontrol-0.15.0/pyproject.toml +100 -0
  9. cachecontrol-0.14.3/pyproject.toml → cachecontrol-0.15.0/pyproject.toml.orig +20 -17
  10. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/tests/conftest.py +42 -26
  11. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/tests/test_adapter.py +1 -1
  12. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/tests/test_cache_control.py +182 -2
  13. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/tests/test_chunked_response.py +19 -1
  14. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/LICENSE.txt +0 -0
  15. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/README.rst +0 -0
  16. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/cachecontrol/_cmd.py +0 -0
  17. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/cachecontrol/cache.py +0 -0
  18. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/cachecontrol/caches/__init__.py +0 -0
  19. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/cachecontrol/caches/file_cache.py +0 -0
  20. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/cachecontrol/heuristics.py +0 -0
  21. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/cachecontrol/py.typed +0 -0
  22. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/cachecontrol/wrapper.py +0 -0
  23. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/tests/__init__.py +0 -0
  24. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/tests/issue_263.py +0 -0
  25. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/tests/test_etag.py +0 -0
  26. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/tests/test_expires_heuristics.py +0 -0
  27. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/tests/test_max_age.py +0 -0
  28. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/tests/test_redirects.py +0 -0
  29. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/tests/test_regressions.py +0 -0
  30. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/tests/test_serialization.py +0 -0
  31. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/tests/test_server_http_version.py +0 -0
  32. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/tests/test_storage_filecache.py +0 -0
  33. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/tests/test_storage_redis.py +0 -0
  34. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/tests/test_vary.py +0 -0
  35. {cachecontrol-0.14.3 → cachecontrol-0.15.0}/tests/utils.py +0 -0
@@ -1,46 +1,32 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: CacheControl
3
- Version: 0.14.3
3
+ Version: 0.15.0
4
4
  Summary: httplib2 caching for requests
5
5
  Keywords: requests,http,caching,web
6
+ Author: Eric Larson, Frost Ming, William Woodruff
6
7
  Author-email: Eric Larson <ericlarson@ionrock.com>, Frost Ming <me@frostming.com>, William Woodruff <william@yossarian.net>
7
- Requires-Python: >=3.9
8
- Description-Content-Type: text/x-rst
9
8
  License-Expression: Apache-2.0
9
+ License-File: LICENSE.txt
10
10
  Classifier: Development Status :: 4 - Beta
11
11
  Classifier: Environment :: Web Environment
12
12
  Classifier: Operating System :: OS Independent
13
- Classifier: Programming Language :: Python :: 3.9
14
13
  Classifier: Programming Language :: Python :: 3.10
15
14
  Classifier: Programming Language :: Python :: 3.11
16
15
  Classifier: Programming Language :: Python :: 3.12
17
16
  Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Programming Language :: Python :: 3.14
18
18
  Classifier: Topic :: Internet :: WWW/HTTP
19
- License-File: LICENSE.txt
20
- Requires-Dist: requests >= 2.16.0
21
- Requires-Dist: msgpack >= 0.5.2, < 2.0.0
22
- Requires-Dist: CacheControl[filecache, redis] ; extra == "dev"
23
- Requires-Dist: build ; extra == "dev"
24
- Requires-Dist: cherrypy ; extra == "dev"
25
- Requires-Dist: codespell[tomli] ; extra == "dev"
26
- Requires-Dist: furo ; extra == "dev"
27
- Requires-Dist: mypy ; extra == "dev"
28
- Requires-Dist: pytest ; extra == "dev"
29
- Requires-Dist: pytest-cov ; extra == "dev"
30
- Requires-Dist: ruff ; extra == "dev"
31
- Requires-Dist: sphinx ; extra == "dev"
32
- Requires-Dist: sphinx-copybutton ; extra == "dev"
33
- Requires-Dist: tox ; extra == "dev"
34
- Requires-Dist: types-redis ; extra == "dev"
35
- Requires-Dist: types-requests ; extra == "dev"
36
- Requires-Dist: filelock >= 3.8.0 ; extra == "filecache"
37
- Requires-Dist: redis>=2.10.5 ; extra == "redis"
19
+ Requires-Dist: requests>=2.16.0
20
+ Requires-Dist: msgpack>=0.5.2,<2.0.0
21
+ Requires-Dist: filelock>=3.8.0 ; extra == 'filecache'
22
+ Requires-Dist: redis>=2.10.5 ; extra == 'redis'
23
+ Requires-Python: >=3.10
38
24
  Project-URL: Homepage, https://pypi.org/project/CacheControl/
39
25
  Project-URL: Issues, https://github.com/psf/cachecontrol/issues
40
26
  Project-URL: Source, https://github.com/psf/cachecontrol
41
- Provides-Extra: dev
42
27
  Provides-Extra: filecache
43
28
  Provides-Extra: redis
29
+ Description-Content-Type: text/x-rst
44
30
 
45
31
  ..
46
32
  SPDX-FileCopyrightText: SPDX-FileCopyrightText: 2015 Eric Larson
@@ -89,4 +75,3 @@ For more info, check out the docs_
89
75
  .. _docs: http://cachecontrol.readthedocs.org/en/latest/
90
76
  .. _httplib2: https://github.com/httplib2/httplib2
91
77
  .. _requests: http://docs.python-requests.org/
92
-
@@ -7,14 +7,16 @@
7
7
  Make it easy to import from cachecontrol without long namespaces.
8
8
  """
9
9
 
10
- __author__ = "Eric Larson"
11
- __email__ = "eric@ionrock.org"
12
- __version__ = "0.14.3"
10
+ import importlib.metadata
13
11
 
14
12
  from cachecontrol.adapter import CacheControlAdapter
15
13
  from cachecontrol.controller import CacheController
16
14
  from cachecontrol.wrapper import CacheControl
17
15
 
16
+ __author__ = "Eric Larson"
17
+ __email__ = "eric@ionrock.org"
18
+ __version__ = importlib.metadata.version("cachecontrol")
19
+
18
20
  __all__ = [
19
21
  "__author__",
20
22
  "__email__",
@@ -4,7 +4,6 @@
4
4
  from __future__ import annotations
5
5
 
6
6
  import functools
7
- import types
8
7
  import weakref
9
8
  import zlib
10
9
  from typing import TYPE_CHECKING, Any, Collection, Mapping
@@ -145,6 +144,10 @@ class CacheControlAdapter(HTTPAdapter):
145
144
  super_update_chunk_length(self)
146
145
  if self.chunk_left == 0:
147
146
  self._fp._close() # type: ignore[union-attr]
147
+ elif self.chunk_left is not None:
148
+ self._fp._set_chunk_bytes_remaining( # type: ignore[union-attr]
149
+ self.chunk_left
150
+ )
148
151
 
149
152
  response._update_chunk_length = functools.partial( # type: ignore[method-assign]
150
153
  _update_chunk_length, weakref.ref(response)
@@ -23,16 +23,21 @@ class RedisCache(BaseCache):
23
23
  def set(
24
24
  self, key: str, value: bytes, expires: int | datetime | None = None
25
25
  ) -> None:
26
+ """Store ``value``, optionally expiring it after ``expires``.
27
+ """
26
28
  if not expires:
27
29
  self.conn.set(key, value)
28
- elif isinstance(expires, datetime):
30
+ return
31
+
32
+ if isinstance(expires, datetime):
29
33
  now_utc = datetime.now(timezone.utc)
30
34
  if expires.tzinfo is None:
31
35
  now_utc = now_utc.replace(tzinfo=None)
32
- delta = expires - now_utc
33
- self.conn.setex(key, int(delta.total_seconds()), value)
36
+ ttl = int((expires - now_utc).total_seconds())
34
37
  else:
35
- self.conn.setex(key, expires, value)
38
+ ttl = expires
39
+
40
+ self.conn.setex(key, ttl, value)
36
41
 
37
42
  def delete(self, key: str) -> None:
38
43
  self.conn.delete(key)
@@ -13,6 +13,7 @@ import logging
13
13
  import re
14
14
  import time
15
15
  import weakref
16
+ from contextlib import closing
16
17
  from email.utils import parsedate_tz
17
18
  from typing import TYPE_CHECKING, Collection, Mapping
18
19
 
@@ -70,7 +71,8 @@ class CacheController:
70
71
  raise Exception("Only absolute URIs are allowed. uri = %s" % uri)
71
72
 
72
73
  scheme = scheme.lower()
73
- authority = authority.lower()
74
+ userinfo, separator, host = authority.rpartition("@")
75
+ authority = f"{userinfo}{separator}{host.lower()}"
74
76
 
75
77
  if not path:
76
78
  path = "/"
@@ -112,7 +114,7 @@ class CacheController:
112
114
  continue
113
115
 
114
116
  parts = cc_directive.split("=", 1)
115
- directive = parts[0].strip()
117
+ directive = parts[0].strip().lower()
116
118
 
117
119
  try:
118
120
  typ, required = known_directives[directive]
@@ -128,12 +130,12 @@ class CacheController:
128
130
  except IndexError:
129
131
  if required:
130
132
  logger.debug(
131
- "Missing value for cache-control " "directive: %s",
133
+ "Missing value for cache-control directive: %s",
132
134
  directive,
133
135
  )
134
136
  except ValueError:
135
137
  logger.debug(
136
- "Invalid value for cache-control directive " "%s, must be %s",
138
+ "Invalid value for cache-control directive %s, must be %s",
137
139
  directive,
138
140
  typ.__name__,
139
141
  )
@@ -161,9 +163,14 @@ class CacheController:
161
163
  else:
162
164
  body_file = None
163
165
 
164
- result = self.serializer.loads(request, cache_data, body_file)
166
+ result: HTTPResponse | None = None
167
+ try:
168
+ result = self.serializer.loads(request, cache_data, body_file)
169
+ finally:
170
+ if result is None and body_file is not None:
171
+ body_file.close()
165
172
  if result is None:
166
- logger.warning("Cache entry deserialization failed, entry ignored")
173
+ logger.debug("Cache entry deserialization failed, entry ignored")
167
174
  return result
168
175
 
169
176
  def cached_request(self, request: PreparedRequest) -> HTTPResponse | Literal[False]:
@@ -190,44 +197,47 @@ class CacheController:
190
197
  if not resp:
191
198
  return False
192
199
 
193
- # If we have a cached permanent redirect, return it immediately. We
194
- # don't need to test our response for other headers b/c it is
195
- # intrinsically "cacheable" as it is Permanent.
196
- #
197
- # See:
198
- # https://tools.ietf.org/html/rfc7231#section-6.4.2
199
- #
200
- # Client can try to refresh the value by repeating the request
201
- # with cache busting headers as usual (ie no-cache).
202
- if int(resp.status) in PERMANENT_REDIRECT_STATUSES:
203
- msg = (
204
- "Returning cached permanent redirect response "
205
- "(ignoring date and etag information)"
200
+ keep_response = False
201
+ try:
202
+ headers: CaseInsensitiveDict[str] = CaseInsensitiveDict(resp.headers)
203
+ date_tuple = parsedate_tz(headers.get("date", ""))
204
+ keep_response = date_tuple is not None and self._is_fresh(
205
+ resp, headers, cc, calendar.timegm(date_tuple[:6])
206
206
  )
207
- logger.debug(msg)
207
+ finally:
208
+ if not keep_response:
209
+ resp.close()
210
+
211
+ if keep_response:
208
212
  return resp
209
213
 
210
- headers: CaseInsensitiveDict[str] = CaseInsensitiveDict(resp.headers)
211
- if not headers or "date" not in headers:
212
- if "etag" not in headers:
213
- # Without date or etag, the cached response can never be used
214
- # and should be deleted.
215
- logger.debug("Purging cached response: no date or etag")
216
- self.cache.delete(cache_url)
214
+ if date_tuple is None:
215
+ if "date" in headers:
216
+ # Keep entries with unparseable dates available for revalidation.
217
+ logger.debug("Ignoring cached response: invalid date")
218
+ return False
217
219
  logger.debug("Ignoring cached response: no date")
218
- return False
219
220
 
220
- now = time.time()
221
- time_tuple = parsedate_tz(headers["date"])
222
- assert time_tuple is not None
223
- date = calendar.timegm(time_tuple[:6])
224
- current_age = max(0, now - date)
221
+ if "etag" not in headers:
222
+ logger.debug("Purging cached response: stale or missing date, with no ETag")
223
+ self.cache.delete(cache_url)
224
+ return False
225
+
226
+ def _is_fresh(
227
+ self,
228
+ resp: HTTPResponse,
229
+ headers: Mapping[str, str],
230
+ request_cc: Mapping[str, int | None],
231
+ date: int,
232
+ ) -> bool:
233
+ current_age = max(0, time.time() - date)
225
234
  logger.debug("Current age based on date: %i", current_age)
226
235
 
227
- # TODO: There is an assumption that the result will be a
228
- # urllib3 response object. This may not be best since we
229
- # could probably avoid instantiating or constructing the
230
- # response until we know we need it.
236
+ # Apply normal freshness checks to every cached response. In the case
237
+ # of permanent redirects, RFC 9110 sections 15.4.2 and 15.4.9 permit
238
+ # heuristic caching, but RFC 9111 section 4.2.2 requires explicit
239
+ # expiration to take precedence. The redirect fallback below is used
240
+ # only when neither max-age nor Expires provides an expiration.
231
241
  resp_cc = self.parse_cache_control(headers)
232
242
 
233
243
  # determine freshness
@@ -247,16 +257,22 @@ class CacheController:
247
257
  freshness_lifetime = max(0, expire_time)
248
258
  logger.debug("Freshness lifetime from expires: %i", freshness_lifetime)
249
259
 
260
+ # Permanent redirects are heuristically cacheable when the response
261
+ # does not provide an explicit freshness lifetime.
262
+ elif int(resp.status) in PERMANENT_REDIRECT_STATUSES:
263
+ logger.debug("Returning cached permanent redirect response")
264
+ return True
265
+
250
266
  # Determine if we are setting freshness limit in the
251
267
  # request. Note, this overrides what was in the response.
252
- max_age = cc.get("max-age")
268
+ max_age = request_cc.get("max-age")
253
269
  if max_age is not None:
254
270
  freshness_lifetime = max_age
255
271
  logger.debug(
256
272
  "Freshness lifetime from request max-age: %i", freshness_lifetime
257
273
  )
258
274
 
259
- min_fresh = cc.get("min-fresh")
275
+ min_fresh = request_cc.get("min-fresh")
260
276
  if min_fresh is not None:
261
277
  # adjust our current age by our min fresh
262
278
  current_age += min_fresh
@@ -266,21 +282,16 @@ class CacheController:
266
282
  if freshness_lifetime > current_age:
267
283
  logger.debug('The response is "fresh", returning cached response')
268
284
  logger.debug("%i > %i", freshness_lifetime, current_age)
269
- return resp
285
+ return True
270
286
 
271
- # we're not fresh. If we don't have an Etag, clear it out
272
- if "etag" not in headers:
273
- logger.debug('The cached response is "stale" with no etag, purging')
274
- self.cache.delete(cache_url)
275
-
276
- # return the original handler
277
287
  return False
278
288
 
279
289
  def conditional_headers(self, request: PreparedRequest) -> dict[str, str]:
280
290
  resp = self._load_from_cache(request)
281
- new_headers = {}
282
-
283
- if resp:
291
+ if not resp:
292
+ return {}
293
+ with closing(resp):
294
+ new_headers = {}
284
295
  headers: CaseInsensitiveDict[str] = CaseInsensitiveDict(resp.headers)
285
296
 
286
297
  if "etag" in headers:
@@ -289,7 +300,7 @@ class CacheController:
289
300
  if "last-modified" in headers:
290
301
  new_headers["If-Modified-Since"] = headers["Last-Modified"]
291
302
 
292
- return new_headers
303
+ return new_headers
293
304
 
294
305
  def _cache_set(
295
306
  self,
@@ -299,9 +310,14 @@ class CacheController:
299
310
  body: bytes | None = None,
300
311
  expires_time: int | None = None,
301
312
  ) -> None:
313
+ """Store the data in the cache.
302
314
  """
303
- Store the data in the cache.
304
- """
315
+ if expires_time is not None and expires_time <= 0:
316
+ # Already stale on arrival
317
+ logger.debug("Purging cached response: expires in the past")
318
+ self.cache.delete(cache_url)
319
+ return
320
+
305
321
  if isinstance(self.cache, SeparateBodyBaseCache):
306
322
  # We pass in the body separately; just put a placeholder empty
307
323
  # string in the metadata.
@@ -358,8 +374,7 @@ class CacheController:
358
374
 
359
375
  if "date" in response_headers:
360
376
  time_tuple = parsedate_tz(response_headers["date"])
361
- assert time_tuple is not None
362
- date = calendar.timegm(time_tuple[:6])
377
+ date = calendar.timegm(time_tuple[:6]) if time_tuple is not None else 0
363
378
  else:
364
379
  date = 0
365
380
 
@@ -430,7 +445,8 @@ class CacheController:
430
445
  # the cache.
431
446
  elif "date" in response_headers:
432
447
  time_tuple = parsedate_tz(response_headers["date"])
433
- assert time_tuple is not None
448
+ if time_tuple is None:
449
+ return
434
450
  date = calendar.timegm(time_tuple[:6])
435
451
  # cache when there is a max-age > 0
436
452
  max_age = cc.get("max-age")
@@ -450,11 +466,15 @@ class CacheController:
450
466
  elif "expires" in response_headers:
451
467
  if response_headers["expires"]:
452
468
  expires = parsedate_tz(response_headers["expires"])
453
- if expires is not None:
454
- expires_time = calendar.timegm(expires[:6]) - date
469
+ if expires is None:
470
+ # https://tools.ietf.org/html/rfc9111#section-5.3: an
471
+ # invalid Expires must be read as a time in the past.
472
+ expires_time = 0
455
473
  else:
456
- expires_time = None
474
+ expires_time = calendar.timegm(expires[:6]) - date
457
475
 
476
+ # A non-positive lifetime here means the response arrived
477
+ # stale
458
478
  logger.debug(
459
479
  "Caching b/c of expires header. expires in {} seconds".format(
460
480
  expires_time
@@ -485,27 +505,19 @@ class CacheController:
485
505
  # we didn't have a cached response
486
506
  return response
487
507
 
488
- # Lets update our headers with the headers from the new request:
489
- # http://tools.ietf.org/html/draft-ietf-httpbis-p4-conditional-26#section-4.1
490
- #
491
- # The server isn't supposed to send headers that would make
492
- # the cached body invalid. But... just in case, we'll be sure
493
- # to strip out ones we know that might be problmatic due to
494
- # typical assumptions.
495
- excluded_headers = ["content-length"]
496
-
497
- cached_response.headers.update(
498
- {
499
- k: v
500
- for k, v in response.headers.items()
501
- if k.lower() not in excluded_headers
502
- }
503
- )
504
-
505
- # we want a 200 b/c we have content via the cache
506
- cached_response.status = 200
507
-
508
- # update our cache
509
- self._cache_set(cache_url, request, cached_response)
508
+ try:
509
+ # A 304 updates the headers while keeping the cached body and its length.
510
+ cached_response.headers.update(
511
+ {
512
+ k: v
513
+ for k, v in response.headers.items()
514
+ if k.lower() != "content-length"
515
+ }
516
+ )
517
+ cached_response.status = 200
518
+ self._cache_set(cache_url, request, cached_response)
519
+ except BaseException:
520
+ cached_response.close()
521
+ raise
510
522
 
511
523
  return cached_response
@@ -8,6 +8,7 @@ from tempfile import NamedTemporaryFile
8
8
  from typing import TYPE_CHECKING, Any, Callable
9
9
 
10
10
  if TYPE_CHECKING:
11
+ from collections.abc import Buffer
11
12
  from http.client import HTTPResponse
12
13
 
13
14
 
@@ -31,11 +32,12 @@ class CallbackFileWrapper:
31
32
  """
32
33
 
33
34
  def __init__(
34
- self, fp: HTTPResponse, callback: Callable[[bytes], None] | None
35
+ self, fp: HTTPResponse, callback: Callable[[Buffer], None] | None
35
36
  ) -> None:
36
37
  self.__buf = NamedTemporaryFile("rb+", delete=True)
37
38
  self.__fp = fp
38
39
  self.__callback = callback
40
+ self.__chunk_bytes_remaining = 0
39
41
 
40
42
  def __getattr__(self, name: str) -> Any:
41
43
  # The vagaries of garbage collection means that self.__fp is
@@ -68,6 +70,7 @@ class CallbackFileWrapper:
68
70
  return False
69
71
 
70
72
  def _close(self) -> None:
73
+ result: Buffer
71
74
  if self.__callback:
72
75
  if self.__buf.tell() == 0:
73
76
  # Empty file:
@@ -105,14 +108,16 @@ class CallbackFileWrapper:
105
108
 
106
109
  return data
107
110
 
111
+ def _set_chunk_bytes_remaining(self, chunk_bytes_remaining: int) -> None:
112
+ self.__chunk_bytes_remaining = chunk_bytes_remaining
113
+
108
114
  def _safe_read(self, amt: int) -> bytes:
109
115
  data: bytes = self.__fp._safe_read(amt) # type: ignore[attr-defined]
110
- if amt == 2 and data == b"\r\n":
111
- # urllib executes this read to toss the CRLF at the end
112
- # of the chunk.
116
+ if self.__chunk_bytes_remaining == 0 and amt == 2:
113
117
  return data
114
118
 
115
119
  self.__buf.write(data)
120
+ self.__chunk_bytes_remaining -= len(data)
116
121
  if self.__is_fp_closed():
117
122
  self._close()
118
123
 
@@ -68,6 +68,11 @@ class Serializer:
68
68
  data: bytes,
69
69
  body_file: IO[bytes] | None = None,
70
70
  ) -> HTTPResponse | None:
71
+ """Return a fresh response owned by the caller, or None for a cache miss.
72
+
73
+ A returned response owns the supplied body file. On a miss or an
74
+ exception, the caller retains ownership of the file.
75
+ """
71
76
  # Short circuit if we've been given an empty set of data
72
77
  if not data:
73
78
  return None
@@ -0,0 +1,100 @@
1
+ [build-system]
2
+ requires = ["uv_build>=0.9.6,<0.14.0"]
3
+ build-backend = "uv_build"
4
+
5
+ [tool.uv.build-backend]
6
+ source-include = ["tests/**"]
7
+ module-name = "cachecontrol"
8
+ module-root = ""
9
+
10
+ [tool.mypy]
11
+ show_error_codes = true
12
+ strict = true
13
+ enable_error_code = [
14
+ "ignore-without-code",
15
+ "redundant-expr",
16
+ "truthy-bool",
17
+ ]
18
+
19
+ [[tool.mypy.overrides]]
20
+ module = "msgpack"
21
+ ignore_missing_imports = true
22
+
23
+ [tool.pytest.ini_options]
24
+ norecursedirs = [
25
+ "bin",
26
+ "lib",
27
+ "include",
28
+ "build",
29
+ ]
30
+
31
+ [project]
32
+ name = "CacheControl"
33
+ version = "0.15.0"
34
+ description = "httplib2 caching for requests"
35
+ readme = "README.rst"
36
+ license = "Apache-2.0"
37
+ license-files = ["LICENSE.txt"]
38
+ classifiers = [
39
+ "Development Status :: 4 - Beta",
40
+ "Environment :: Web Environment",
41
+ "Operating System :: OS Independent",
42
+ "Programming Language :: Python :: 3.10",
43
+ "Programming Language :: Python :: 3.11",
44
+ "Programming Language :: Python :: 3.12",
45
+ "Programming Language :: Python :: 3.13",
46
+ "Programming Language :: Python :: 3.14",
47
+ "Topic :: Internet :: WWW/HTTP",
48
+ ]
49
+ keywords = [
50
+ "requests",
51
+ "http",
52
+ "caching",
53
+ "web",
54
+ ]
55
+ dependencies = [
56
+ "requests >= 2.16.0",
57
+ "msgpack >= 0.5.2, < 2.0.0",
58
+ ]
59
+ requires-python = ">=3.10"
60
+
61
+ [[project.authors]]
62
+ name = "Eric Larson"
63
+ email = "ericlarson@ionrock.com"
64
+
65
+ [[project.authors]]
66
+ name = "Frost Ming"
67
+ email = "me@frostming.com"
68
+
69
+ [[project.authors]]
70
+ name = "William Woodruff"
71
+ email = "william@yossarian.net"
72
+
73
+ [project.urls]
74
+ Homepage = "https://pypi.org/project/CacheControl/"
75
+ Issues = "https://github.com/psf/cachecontrol/issues"
76
+ Source = "https://github.com/psf/cachecontrol"
77
+
78
+ [project.optional-dependencies]
79
+ filecache = ["filelock >= 3.8.0"]
80
+ redis = ["redis>=2.10.5"]
81
+
82
+ [project.scripts]
83
+ doesitcache = "cachecontrol._cmd:main"
84
+
85
+ [dependency-groups]
86
+ dev = [
87
+ "CacheControl[filecache,redis]",
88
+ "cherrypy",
89
+ "cheroot >= 11.1.2",
90
+ "codespell",
91
+ "furo",
92
+ "mypy",
93
+ "pytest",
94
+ "pytest-cov",
95
+ "ruff",
96
+ "sphinx",
97
+ "sphinx-copybutton",
98
+ "types-redis",
99
+ "types-requests",
100
+ ]
@@ -1,16 +1,16 @@
1
1
  [build-system]
2
- requires = ["flit_core >=3.11,<4"]
3
- build-backend = "flit_core.buildapi"
2
+ requires = ["uv_build>=0.9.6,<0.14.0"]
3
+ build-backend = "uv_build"
4
4
 
5
- [tool.flit.module]
6
- name = "cachecontrol"
5
+ [tool.uv.build-backend]
6
+ source-include = ["tests/**"]
7
+ module-name = "cachecontrol"
8
+ module-root = ""
7
9
 
8
- [tool.flit.sdist]
9
- include = ["tests/"]
10
10
 
11
11
  [project]
12
12
  name = "CacheControl"
13
- dynamic = ["version"]
13
+ version = "0.15.0"
14
14
  description = "httplib2 caching for requests"
15
15
  readme = "README.rst"
16
16
  license = "Apache-2.0"
@@ -24,33 +24,31 @@ classifiers = [
24
24
  "Development Status :: 4 - Beta",
25
25
  "Environment :: Web Environment",
26
26
  "Operating System :: OS Independent",
27
- "Programming Language :: Python :: 3.9",
28
27
  "Programming Language :: Python :: 3.10",
29
28
  "Programming Language :: Python :: 3.11",
30
29
  "Programming Language :: Python :: 3.12",
31
30
  "Programming Language :: Python :: 3.13",
31
+ "Programming Language :: Python :: 3.14",
32
32
  "Topic :: Internet :: WWW/HTTP",
33
33
  ]
34
34
  keywords = ["requests", "http", "caching", "web"]
35
35
  dependencies = ["requests >= 2.16.0", "msgpack >= 0.5.2, < 2.0.0"]
36
- requires-python = ">=3.9"
36
+ requires-python = ">=3.10"
37
37
 
38
38
  [project.urls]
39
39
  Homepage = "https://pypi.org/project/CacheControl/"
40
40
  Issues = "https://github.com/psf/cachecontrol/issues"
41
41
  Source = "https://github.com/psf/cachecontrol"
42
42
 
43
- [project.optional-dependencies]
44
- # End-user extras.
45
- filecache = ["filelock >= 3.8.0"]
46
- redis = ["redis>=2.10.5"]
47
-
43
+ [dependency-groups]
48
44
  # Development extras.
49
45
  dev = [
50
46
  "CacheControl[filecache,redis]",
51
- "build",
52
47
  "cherrypy",
53
- "codespell[tomli]",
48
+ # See: https://github.com/cherrypy/cherrypy/issues/2070
49
+ # See: https://github.com/cherrypy/cheroot/issues/769
50
+ "cheroot >= 11.1.2",
51
+ "codespell",
54
52
  "furo",
55
53
  "mypy",
56
54
  "pytest",
@@ -58,11 +56,16 @@ dev = [
58
56
  "ruff",
59
57
  "sphinx",
60
58
  "sphinx-copybutton",
61
- "tox",
62
59
  "types-redis",
63
60
  "types-requests",
64
61
  ]
65
62
 
63
+ [project.optional-dependencies]
64
+ # End-user extras.
65
+ filecache = ["filelock >= 3.8.0"]
66
+ redis = ["redis>=2.10.5"]
67
+
68
+
66
69
  [project.scripts]
67
70
  doesitcache = "cachecontrol._cmd:main"
68
71
 
@@ -2,14 +2,13 @@
2
2
  #
3
3
  # SPDX-License-Identifier: Apache-2.0
4
4
 
5
- from pprint import pformat
6
-
7
5
  import os
8
6
  import socket
9
-
10
- import pytest
7
+ from pprint import pformat
11
8
 
12
9
  import cherrypy
10
+ import pytest
11
+ from cheroot.server import HTTPRequest
13
12
 
14
13
 
15
14
  class SimpleApp:
@@ -103,6 +102,14 @@ class SimpleApp:
103
102
  for i in range(10):
104
103
  yield pformat(i).encode("utf8")
105
104
 
105
+ def stream_with_crlf(self, env, start_response):
106
+ headers = [("Content-Type", "text/plain"), ("Cache-Control", "max-age=5000")]
107
+ start_response("200 OK", headers)
108
+
109
+ yield b"AA"
110
+ yield b"\r\n"
111
+ yield b"BB"
112
+
106
113
  def fixed_length(self, env, start_response):
107
114
  body = b"0123456789"
108
115
  headers = [
@@ -126,7 +133,22 @@ class SimpleApp:
126
133
 
127
134
  @pytest.fixture(scope="session")
128
135
  def server():
129
- return cherrypy.server
136
+ cherrypy.tree.graft(SimpleApp(), "/")
137
+
138
+ ip, port = get_free_port()
139
+
140
+ cherrypy.config.update({"server.socket_host": ip, "server.socket_port": port})
141
+
142
+ # turn off logging
143
+ logger = cherrypy.log.access_log
144
+ if logger:
145
+ logger.removeHandler(logger.handlers[0])
146
+
147
+ cherrypy.server.start()
148
+
149
+ yield cherrypy.server
150
+
151
+ cherrypy.server.stop()
130
152
 
131
153
 
132
154
  @pytest.fixture()
@@ -134,6 +156,21 @@ def url(server):
134
156
  return "http://%s:%s/" % server.bind_addr
135
157
 
136
158
 
159
+ @pytest.fixture()
160
+ def malformed_chunk_delimiters(monkeypatch):
161
+ """Make the test server send XX instead of each chunk's trailing CRLF."""
162
+ write = HTTPRequest.write
163
+
164
+ def write_malformed_chunk(request, chunk):
165
+ if request.chunked_write and chunk:
166
+ data = f"{len(chunk):x}\r\n".encode() + chunk + b"XX"
167
+ request.conn.wfile.write(data)
168
+ else:
169
+ write(request, chunk)
170
+
171
+ monkeypatch.setattr(HTTPRequest, "write", write_malformed_chunk)
172
+
173
+
137
174
  def get_free_port():
138
175
  s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
139
176
  s.bind(("", 0))
@@ -141,24 +178,3 @@ def get_free_port():
141
178
  s.close()
142
179
  ip = os.environ.get("WEBTEST_SERVER_BIND", "127.0.0.1")
143
180
  return ip, port
144
-
145
-
146
- def pytest_configure(config):
147
- cherrypy.tree.graft(SimpleApp(), "/")
148
-
149
- ip, port = get_free_port()
150
-
151
- cherrypy.config.update({"server.socket_host": ip, "server.socket_port": port})
152
-
153
- # turn off logging
154
- logger = cherrypy.log.access_log
155
- logger.removeHandler(logger.handlers[0])
156
-
157
- cherrypy.server.start()
158
-
159
-
160
- def pytest_unconfigure(config):
161
- try:
162
- cherrypy.server.stop()
163
- except: # noqa: E722
164
- pass
@@ -75,7 +75,7 @@ class TestSessionActions:
75
75
  resp.raise_for_status()
76
76
  r1_weak = weakref.ref(resp.raw)
77
77
 
78
- # This is a mis-use of requests, becase we should either consume
78
+ # This is a mis-use of requests, because we should either consume
79
79
  # the body, or call .close().
80
80
  # But requests without cachecontrol handle this anyway, because
81
81
  # urllib3.response.HTTPResponse has a __del__ finalizer on it that closes it
@@ -8,7 +8,8 @@ Unit tests that verify our caching methods work correctly.
8
8
 
9
9
  import os
10
10
  import time
11
- from unittest.mock import ANY, Mock
11
+ from io import BytesIO
12
+ from unittest.mock import ANY, Mock, patch
12
13
 
13
14
  import pytest
14
15
 
@@ -63,6 +64,13 @@ class TestCacheControllerResponse:
63
64
 
64
65
  assert not cc.cache.set.called
65
66
 
67
+ def test_no_cache_with_malformed_date(self, cc):
68
+ # An unparseable date must not crash; treat it like a missing date
69
+ resp = self.resp({"cache-control": "max-age=3600", "date": "garbage"})
70
+ cc.cache_response(self.req(), resp)
71
+
72
+ assert not cc.cache.set.called
73
+
66
74
  def test_no_cache_with_wrong_sized_body(self, cc):
67
75
  # When the body is the wrong size, then we don't want to cache it
68
76
  # because it is obviously broken.
@@ -106,12 +114,81 @@ class TestCacheControllerResponse:
106
114
  cc.cache_response(self.req(), resp)
107
115
  assert not cc.cache.get(cache_url)
108
116
 
117
+ def test_cache_control_directives_case_insensitive(self, cc):
118
+ now = time.strftime(TIME_FMT, time.gmtime())
119
+ resp = self.resp({"cache-control": "No-Store, max-age=3600", "date": now})
120
+
121
+ cc.cache_response(self.req(), resp)
122
+
123
+ assert not cc.cache.set.called
124
+
109
125
  def test_cache_response_no_store_with_etag(self, cc):
110
126
  resp = self.resp({"cache-control": "no-store", "ETag": "jfd9094r808"})
111
127
  cc.cache_response(self.req(), resp)
112
128
 
113
129
  assert not cc.cache.set.called
114
130
 
131
+ def test_cache_response_expires_in_future(self, cc):
132
+ now = time.time()
133
+ resp = self.resp(
134
+ {
135
+ "date": time.strftime(TIME_FMT, time.gmtime(now)),
136
+ "expires": time.strftime(TIME_FMT, time.gmtime(now + 3600)),
137
+ }
138
+ )
139
+ cc.cache_response(self.req(), resp)
140
+
141
+ cc.cache.set.assert_called_with(self.url, ANY, expires=3600)
142
+
143
+ @pytest.mark.parametrize(
144
+ "expires",
145
+ [
146
+ # RFC 9111 4.2.1: freshness lifetime is Expires - Date, which the
147
+ # origin is free to make negative to force revalidation.
148
+ "past",
149
+ # RFC 9111 5.3: an invalid Expires means "already expired".
150
+ "0",
151
+ "garbage",
152
+ ],
153
+ )
154
+ def test_cache_response_expires_in_past_not_cached(self, cc, expires):
155
+ now = time.time()
156
+ if expires == "past":
157
+ expires = time.strftime(TIME_FMT, time.gmtime(now - 3600))
158
+ resp = self.resp(
159
+ {"date": time.strftime(TIME_FMT, time.gmtime(now)), "expires": expires}
160
+ )
161
+ cc.cache_response(self.req(), resp)
162
+
163
+ assert not cc.cache.set.called
164
+
165
+ def test_cache_response_expires_in_past_purges_existing_entry(self):
166
+ now = time.time()
167
+ cache = DictCache({self.url: b"stale"})
168
+ cc = CacheController(cache, serializer=Mock())
169
+
170
+ resp = self.resp(
171
+ {
172
+ "date": time.strftime(TIME_FMT, time.gmtime(now)),
173
+ "expires": time.strftime(TIME_FMT, time.gmtime(now - 3600)),
174
+ }
175
+ )
176
+ cc.cache_response(self.req(), resp)
177
+
178
+ assert cc.cache.get(self.url) is None
179
+
180
+ @pytest.mark.parametrize("expires_time", [0, -1, -3600])
181
+ def test_cache_set_never_passes_non_positive_expires(self, cc, expires_time):
182
+ """``_cache_set`` is the only chokepoint into ``BaseCache.set``.
183
+
184
+ Backends may therefore assume ``expires`` is either None or strictly
185
+ positive; a non-positive deadline must purge instead of store.
186
+ """
187
+ cc._cache_set(self.url, self.req(), self.resp(), b"testing", expires_time)
188
+
189
+ assert not cc.cache.set.called
190
+ cc.cache.delete.assert_called_with(self.url)
191
+
115
192
  def test_no_cache_with_vary_star(self, cc):
116
193
  # Vary: * indicates that the response can never be served
117
194
  # from the cache, so storing it can be avoided.
@@ -120,6 +197,74 @@ class TestCacheControllerResponse:
120
197
 
121
198
  assert not cc.cache.set.called
122
199
 
200
+ def test_cache_response_preserves_userinfo_case(self):
201
+ cache = DictCache({})
202
+ cc = CacheController(cache)
203
+ url = "http://Alice:Secret@localhost/"
204
+ req = DummyRequest(url=url, headers={})
205
+ resp = DummyResponse(status=200, headers={"ETag": "xyz"})
206
+ cc.cache_response(req, resp, b"")
207
+
208
+ req = DummyRequest(
209
+ url="http://alice:secret@localhost/", headers={"if-match": "xyz"}
210
+ )
211
+ result = cc.conditional_headers(req)
212
+
213
+ assert not result
214
+
215
+ def test_conditional_headers_closes_response(self, cc):
216
+ resp = self.resp({"ETag": '"cached"'})
217
+ cc.serializer.loads.return_value = resp
218
+
219
+ assert cc.conditional_headers(self.req()) == {"If-None-Match": '"cached"'}
220
+ resp.close.assert_called_once_with()
221
+
222
+ @pytest.mark.parametrize("vary", [False, True], ids=["bad-metadata", "vary-miss"])
223
+ def test_cache_load_miss_closes_body(self, tmp_path, monkeypatch, vary):
224
+ cache = SeparateBodyFileCache(tmp_path)
225
+ cc = CacheController(cache)
226
+ data = b"invalid metadata"
227
+ if vary:
228
+ data = cc.serializer.dumps(
229
+ self.req({"Accept-Language": "en"}),
230
+ DummyResponse(200, {"Vary": "Accept-Language"}),
231
+ b"",
232
+ )
233
+ cache.set(self.url, data)
234
+ with BytesIO(b"body") as body:
235
+ monkeypatch.setattr(cache, "get_body", Mock(return_value=body))
236
+ assert cc._load_from_cache(self.req()) is None
237
+ assert body.closed
238
+
239
+ def test_purge_closes_separate_body_first(self, tmp_path, monkeypatch):
240
+ cache = SeparateBodyFileCache(tmp_path)
241
+ cc = CacheController(cache)
242
+ req = self.req()
243
+ resp = DummyResponse(200, {"Date": "Thu, 01 Jan 1970 00:00:00 GMT"})
244
+ cc._cache_set(self.url, req, resp, b"body")
245
+
246
+ cached = cc._load_from_cache(req)
247
+ assert cached is not None
248
+ delete = cache.delete
249
+
250
+ def delete_after_close(key):
251
+ assert cached.closed
252
+ delete(key)
253
+
254
+ monkeypatch.setattr(cache, "delete", delete_after_close)
255
+ with patch.object(cc, "_load_from_cache", return_value=cached):
256
+ assert cc.cached_request(req) is False
257
+ assert cache.get(self.url) is None
258
+
259
+ def test_update_cached_response_closes_on_write_error(self, cc):
260
+ cached = self.resp()
261
+ cc.serializer.loads.return_value = cached
262
+ cc.cache.set.side_effect = OSError("cache write failed")
263
+
264
+ with pytest.raises(OSError, match="cache write failed"):
265
+ cc.update_cached_response(self.req(), DummyResponse(304, {}))
266
+ cached.close.assert_called_once_with()
267
+
123
268
  def test_update_cached_response_no_local_cache(self):
124
269
  """
125
270
  If the local cache doesn't have the given URL, just reuse the response
@@ -239,6 +384,7 @@ class TestCacheControlRequest:
239
384
  self.c.cache = DictCache({self.url: cached_resp})
240
385
  resp = self.req({})
241
386
  assert not resp
387
+ cached_resp.close.assert_called_once_with()
242
388
 
243
389
  def test_cache_request_no_cache(self):
244
390
  resp = self.req({"cache-control": "no-cache"})
@@ -268,11 +414,25 @@ class TestCacheControlRequest:
268
414
  self.c.cache = cache
269
415
  r = self.req({})
270
416
  assert r == resp
417
+ resp.close.assert_not_called()
271
418
 
272
419
  def test_cache_request_unfresh_max_age(self):
273
420
  earlier = time.time() - 3700 # epoch - 1h01m40s
274
421
  now = time.strftime(TIME_FMT, time.gmtime(earlier))
275
- resp = Mock(headers={"cache-control": "max-age=3600", "date": now}, status=200)
422
+ resp = Mock(
423
+ headers={"cache-control": "max-age=3600", "date": now, "ETag": '"cached"'},
424
+ status=200,
425
+ )
426
+ self.c.cache = DictCache({self.url: resp})
427
+ r = self.req({})
428
+ assert not r
429
+ resp.close.assert_called_once_with()
430
+ assert self.c.cache.get(self.url) is resp
431
+
432
+ def test_cache_request_unfresh_permanent_redirect(self):
433
+ earlier = time.time() - 3600
434
+ date = time.strftime(TIME_FMT, time.gmtime(earlier))
435
+ resp = Mock(headers={"cache-control": "max-age=1", "date": date}, status=301)
276
436
  self.c.cache = DictCache({self.url: resp})
277
437
  r = self.req({})
278
438
  assert not r
@@ -305,3 +465,23 @@ class TestCacheControlRequest:
305
465
  self.c.cache = DictCache({self.url: resp})
306
466
 
307
467
  assert not self.req({})
468
+
469
+ def test_cached_request_with_malformed_date_not_returned(self):
470
+ # A cached entry with an unparseable date must not crash the lookup
471
+ resp = Mock(
472
+ headers={"cache-control": "max-age=3600", "date": "garbage"}, status=200
473
+ )
474
+
475
+ self.c.cache = DictCache({self.url: resp})
476
+
477
+ assert not self.req({})
478
+ resp.close.assert_called_once_with()
479
+ assert self.c.cache.get(self.url) is resp
480
+
481
+ def test_cached_request_closes_response_on_freshness_error(self):
482
+ resp = Mock(headers={"Date": "Sat, 01 Jan 10000 00:00:00 GMT"})
483
+ self.c.cache = DictCache({self.url: resp})
484
+
485
+ with pytest.raises(ValueError):
486
+ self.req({})
487
+ resp.close.assert_called_once_with()
@@ -43,14 +43,32 @@ class TestChunkedResponses:
43
43
  content_1 = resp_1.content
44
44
 
45
45
  resp_2 = sess.get(url + "stream")
46
- content_2 = resp_1.content
46
+ content_2 = resp_2.content
47
47
 
48
48
  assert not resp_1.from_cache
49
49
  assert resp_2.from_cache
50
50
  assert content_1 == content_2
51
51
 
52
+ def test_stream_with_crlf_chunk_is_cached_without_corruption(self, url, sess):
53
+ resp_1 = sess.get(url + "stream_with_crlf")
54
+ resp_2 = sess.get(url + "stream_with_crlf")
55
+
56
+ assert resp_1.content == b"AA\r\nBB"
57
+ assert resp_2.from_cache
58
+ assert resp_2.content == resp_1.content
59
+
52
60
  def test_stream_is_not_cached_when_content_is_not_read(self, url, sess):
53
61
  sess.get(url + "stream", stream=True)
54
62
  resp = sess.get(url + "stream", stream=True)
55
63
 
56
64
  assert not resp.from_cache
65
+
66
+ def test_stream_with_malformed_delimiters_is_cached_without_corruption(
67
+ self, url, sess, malformed_chunk_delimiters
68
+ ):
69
+ resp_1 = sess.get(url + "stream_with_crlf")
70
+ resp_2 = sess.get(url + "stream_with_crlf")
71
+
72
+ assert resp_1.content == b"AA\r\nBB"
73
+ assert resp_2.from_cache
74
+ assert resp_2.content == resp_1.content
File without changes
File without changes