psf / psf/cachecontrol

Make it clear that CacheControl is a function that mounts an adapter

Open
#199 0 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
505
Forks
149
Avg merge
2d 13h
Merged PRs (30d)
7

Description

The camel-case notation suggests that CacheControl is a class. Given the docs terminology, according to which CacheControl is a "wrapper", I expect that CacheControl returns an object that wraps a session.

But CacheControl is neither a class nor it returns a wrapper object. It's a function which mounts an HTTPAdapter to the session and returns the session itself. It's a function with side-effects that could even return None.

My problem with it is that it's not even innocently misleading, because if the user has already mounted an HTTPAdapter for "http://" and "https://", CacheControl will overwrite that adapter without the user even realizing what happened because he/she was convinced by the naming convention and the docs that CacheControl is a wrapper.

Consider:

  • switching to a name that reflects what's actually happening, e.g. mount_cache_adapter;
  • warning the user that any eventual adapter for those prefixes will be overwritten.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at the CacheControl function and inspect how it mounts an HTTPAdapter on the session for the http:// and https:// prefixes. Decide whether the requested API naming change or an overwrite warning is intended, then verify that the chosen behavior makes the adapter replacement explicit.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
networking
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.