edq.net.settings

  1# pylint: disable=global-statement,invalid-name
  2
  3"""
  4This module holds options that persist the lifetime of the program.
  5Most options can be overwritten in specific calls, e.g., in edq.net.request.make_request().
  6"""
  7
  8import typing
  9
 10ANCHOR_HEADER_KEY: str = 'edq-anchor'
 11"""
 12By default, requests made via make_request() will send a header with this key that includes the anchor component of the URL.
 13Anchors are not traditionally sent in requests, but this will allow exchanges to capture this extra piece of information.
 14"""
 15
 16DEFAULT_HTTPS_VERIFICATION: bool = True
 17
 18DEFAULT_CONNECTION_TIMEOUT_SECS: float = 30.0
 19
 20DEFAULT_READ_TIMEOUT_SECS: float = 60.0 * 30
 21
 22DEFAULT_EXCHANGES_IGNORE_HEADERS: typing.List[str] = [
 23    'accept',
 24    'accept-encoding',
 25    'accept-language',
 26    'access-control-allow-origin',
 27    'access-control-allow-credentials',
 28    'access-control-allow-methods',
 29    'access-control-request-method',
 30    'access-control-allow-headers',
 31    'cache-control',
 32    'connection',
 33    'content-length',
 34    'content-security-policy',
 35    'content-type',
 36    'cookie',
 37    'date',
 38    'dnt',
 39    'etag',
 40    'host',
 41    'link',
 42    'location',  # Will be specially kept on allowed redirects.
 43    'pragma',
 44    'priority',
 45    'referrer-policy',
 46    'sec-fetch-dest',
 47    'sec-fetch-mode',
 48    'sec-fetch-site',
 49    'sec-fetch-user',
 50    'sec-gpc',
 51    'server',
 52    'server-timing',
 53    'set-cookie',
 54    'upgrade-insecure-requests',
 55    'user-agent',
 56    'x-content-type-options',
 57    'x-download-options',
 58    'x-permitted-cross-domain-policies',
 59    'x-rate-limit-remaining',
 60    'x-request-context-id',
 61    'x-request-cost',
 62    'x-runtime',
 63    'x-session-id',
 64    'x-xss-protection',
 65    ANCHOR_HEADER_KEY,
 66]
 67
 68_exchanges_ignore_headers: typing.List[str] = DEFAULT_EXCHANGES_IGNORE_HEADERS.copy()
 69"""
 70By default, ignore these headers during exchange matching.
 71Some are sent automatically and we don't need to record (like content-length),
 72and some are additional information we don't need.
 73"""
 74
 75_exchanges_out_dir: typing.Union[str, None] = None
 76""" If not None, all requests made via make_request() will be saved as an HTTPExchange in this directory. """
 77
 78_exchanges_clean_response_func: typing.Union[str, None] = None
 79"""
 80If not None, this function reference will be used to clean responses (and bodies)
 81before creating an exchange with edq.net.exchange.HTTPExchange.from_response().
 82
 83This reference must be importable via edq.util.pyimport.fetch().
 84String references are used instead of actual function references because these values will be stored inside the exchange.
 85The referenced function should follow the edq.net.exchange.HTTPExchangeResponseCleanFunc protocol.
 86"""
 87
 88_exchanges_finalize_func: typing.Union[str, None] = None
 89"""
 90If not None, all exchanges created with edq.net.exchange.HTTPExchange.from_response()
 91will have this function reference called before returning the created exchange.
 92
 93This reference must be importable via edq.util.pyimport.fetch().
 94String references are used instead of actual function references because these values will be stored inside the exchange.
 95The referenced function should follow the edq.net.exchange.HTTPExchangeFinalizeFunc protocol.
 96"""
 97
 98_http_verification: bool = DEFAULT_HTTPS_VERIFICATION
 99"""
100Whether to verify HTTPS requests.
101Should be set to false when using fake/testing certificates.
102"""
103
104_connection_timeout_secs: float = DEFAULT_CONNECTION_TIMEOUT_SECS
105""" The timeout for establishing a connection. """
106
107_read_timeout_secs: float = DEFAULT_READ_TIMEOUT_SECS
108""" The timeout for reading from a connection. """
109
110_request_complete_callback: typing.Union[typing.Callable, None] = None  # pylint: disable=invalid-name
111"""
112If not None, call this func when make_request() is about to end.
113This function should follow the edq.net.exchange.HTTPExchangeComplete protocol.
114"""
115
116def get_exchanges_clean_response_func() -> typing.Union[str, None]:
117    """ Get the clean response func for exchanges. """
118
119    return _exchanges_clean_response_func
120
121def set_exchanges_clean_response_func(value: typing.Union[str, None] = None) -> None:
122    """ Set the clean response func for exchanges. """
123
124    global _exchanges_clean_response_func
125    _exchanges_clean_response_func = value
126
127def get_exchanges_finalize_func() -> typing.Union[str, None]:
128    """ Get the finalize func for exchanges. """
129
130    return _exchanges_finalize_func
131
132def set_exchanges_finalize_func(value: typing.Union[str, None] = None) -> None:
133    """ Set the finalize func for exchanges. """
134
135    global _exchanges_finalize_func
136    _exchanges_finalize_func = value
137
138def get_exchanges_ignore_headers() -> typing.List[str]:
139    """ Get the exchange headers to ignore. """
140
141    return _exchanges_ignore_headers
142
143def set_exchanges_ignore_headers(value: typing.Union[typing.List[str], None] = None) -> None:
144    """ Set the exchange headers to ignore. """
145
146    global _exchanges_ignore_headers
147
148    if (value is None):
149        value = DEFAULT_EXCHANGES_IGNORE_HEADERS.copy()
150
151    _exchanges_ignore_headers = value
152
153def get_exchanges_out_dir() -> typing.Union[str, None]:
154    """ Get the directory to write HTTP exchanges (if any). """
155
156    return _exchanges_out_dir
157
158def set_exchanges_out_dir(value: typing.Union[str, None] = None) -> None:
159    """ Set the directory to write HTTP exchanges. """
160
161    global _exchanges_out_dir
162    _exchanges_out_dir = value
163
164def get_https_verification() -> bool:
165    """ Get whether to check the SSL certificate for HTTPS requests. """
166
167    return _http_verification
168
169def set_https_verification(value: typing.Union[bool, None] = None) -> None:
170    """ Set whether to check the SSL certificate for HTTPS requests. """
171
172    global _http_verification
173
174    if (value is None):
175        value = DEFAULT_HTTPS_VERIFICATION
176
177    _http_verification = value
178
179def get_connection_timeout_secs() -> float:
180    """ Get the timeout for establishing a connection. """
181
182    return _connection_timeout_secs
183
184def set_connection_timeout_secs(value: typing.Union[float, None] = None) -> None:
185    """ Set the timeout for establishing a connection. """
186
187    global _connection_timeout_secs
188
189    if (value is None):
190        value = DEFAULT_CONNECTION_TIMEOUT_SECS
191
192    _connection_timeout_secs = value
193
194def get_read_timeout_secs() -> float:
195    """ Get the timeout for reading from a connection. """
196
197    return _read_timeout_secs
198
199def set_read_timeout_secs(value: typing.Union[float, None] = None) -> None:
200    """ Set the timeout for reading from a connection. """
201
202    global _read_timeout_secs
203
204    if (value is None):
205        value = DEFAULT_READ_TIMEOUT_SECS
206
207    _read_timeout_secs = value
208
209def get_request_complete_callback() -> typing.Union[typing.Callable, None]:
210    """ Get the make_request() callback. """
211
212    return _request_complete_callback
213
214def set_request_complete_callback(value: typing.Union[typing.Callable, None] = None) -> None:
215    """ Set the make_request() callback. """
216
217    global _request_complete_callback
218    _request_complete_callback = value