Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
janluke opened this issue Jan 4, 2019 · 0 comments
Open

Comments

@janluke
Copy link

janluke commented Jan 4, 2019

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant