Feature Request: Global Configuration for `impersonate` Parameter

[DoiiarX]

📝 Feature Request: Global Configuration for impersonate Parameter

Is your feature request related to a problem? Please describe.

I am replacing the standard requests library with curl-cffi in a large, existing codebase. curl-cffi's ability to impersonate browsers (e.g., using the impersonate parameter) is the primary reason for this transition, especially for bypassing certain bot protection measures.

The problem is that there is no simple, native way to set the impersonate value globally for all functional calls (requests.get, requests.post, etc.) or for all instantiated Session objects without explicit parameter passing.

This forces me to:

1. Manually modify every single request call site across the project to add impersonate="chromeXX".
2. Implement a custom ImpersonateSession class and ensure all library code uses this custom session instead of the default requests (or curl_cffi.requests) module functions, which requires significant code refactoring.

This lack of a global configuration adds substantial overhead to projects migrating to curl-cffi that require a consistent browser fingerprint.

Describe the solution you'd like

I would like the library to support a mechanism for setting a default global impersonate target that applies automatically to all new request calls and newly created Session objects, unless explicitly overridden.

This could be implemented in one of the following ways:

A. Environment Variable Configuration (Preferred)

Allowing the user to set an environment variable, such as CURL_CFFI_IMPERSONATE_DEFAULT, which the library checks upon startup.

• Example Usage:

  export CURL_CFFI_IMPERSONATE_DEFAULT="chrome120"

• Library Behavior: Any call like requests.get(url) or a new Session() would default to impersonate="chrome120" unless the impersonate parameter is explicitly passed.

B. Global Configuration Function

Provide a simple function to set the global default at runtime.

• Example Usage:

  import curl_cffi.requests as requests
  requests.set_global_impersonate("chrome120") 
  # Subsequent calls (requests.get(), new Session()) will use chrome120

Describe alternatives you've considered

1. Custom Session Class: As discussed in our previous exchange, implementing a wrapper/subclass around curl_cffi.requests.Session to inject the parameter (ImpersonateSession).

   • Drawbacks: This is the most robust but requires intrusive code changes across the codebase to ensure all network logic uses the custom class.

2. Monkey Patching: Attempting to patch the underlying Session.request method.

   • Drawbacks: Highly discouraged due to potential instability and maintenance issues, making the code fragile.

Additional context

This feature would significantly lower the barrier to entry for large-scale projects looking to leverage $curl-cffi$ for consistent anti-bot bypass capabilities, allowing them to benefit from the library without massive refactoring efforts.

[lexiforest]

Actually, we do have an environment variable for that, see: https://github.com/lexiforest/curl-impersonate/blob/main/docs/04_libcurl.md#using-curl_impersonate-env-var