cachecontrol icon indicating copy to clipboard operation
cachecontrol copied to clipboard

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

Open janluke opened this issue 7 years ago • 0 comments

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.

janluke avatar Jan 04 '19 20:01 janluke