Make it clear that CacheControl is a function that mounts an adapter
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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