{"id":9818,"library":"httsleep","title":"HTTSleep","description":"HTTSleep is a Python library designed for polling HTTP endpoints with built-in features like exponential backoff and retries. It leverages `requests` for HTTP operations and `backoff` for robust retry logic. The current version is 0.3.1. Development appears to be in maintenance mode, with no new releases or significant commits since early 2021.","status":"maintenance","version":"0.3.1","language":"en","source_language":"en","source_url":"https://github.com/kopf/httsleep","tags":["http","polling","retry","backoff","client","network"],"install":[{"cmd":"pip install httsleep","lang":"bash","label":"Install httsleep"}],"dependencies":[{"reason":"Provides the underlying HTTP client functionality for polling.","package":"requests"},{"reason":"Powers the exponential backoff and retry mechanisms within the poller.","package":"backoff"},{"reason":"Used for structured JSON logging within the library.","package":"python-json-logger"}],"imports":[{"symbol":"HTTSleep","correct":"from httsleep import HTTSleep"}],"quickstart":{"code":"import time\nfrom httsleep import HTTSleep\nimport requests # To create a mock response for the example\nimport json\n\n# Simulate a remote service that eventually returns 'completed'\n# In a real scenario, this would be your actual API endpoint.\nmock_response_count = 0\ndef simulate_api_call(url=None, **kwargs):\n    nonlocal mock_response_count\n    mock_response_count += 1\n\n    mock_resp = requests.Response()\n    if mock_response_count < 3:\n        mock_resp.status_code = 202 # Accepted (still processing)\n        mock_resp._content = b'{\"status\": \"pending\", \"detail\": \"processing...\"}'\n        mock_resp.request = requests.Request('GET', url or 'http://mock.api/status').prepare()\n    else:\n        mock_resp.status_code = 200 # OK\n        mock_resp._content = b'{\"status\": \"completed\", \"result\": \"success!\"}'\n        mock_resp.request = requests.Request('GET', url or 'http://mock.api/status').prepare()\n    \n    # Monkey-patch json method for simplicity\n    def json_method():\n        return json.loads(mock_resp._content.decode('utf-8'))\n    mock_resp.json = json_method\n    return mock_resp\n\n# Create an HTTSleep instance\npoller = HTTSleep(\n    http_get_func=simulate_api_call, # Pass the mock function that makes HTTP calls\n    check_func=lambda resp: resp.json().get(\"status\") == \"completed\",\n    timeout=20, # Total timeout for polling in seconds\n    interval=1, # Initial interval in seconds\n    max_interval=5, # Max interval between retries\n    factor=2, # Exponential backoff factor\n    logger=None # Suppress default logging for clean quickstart output\n)\n\nprint(\"Starting polling for a 'completed' status...\")\ntry:\n    final_response = poller.poll()\n    print(f\"Polling successful! Final status: {final_response.json().get('status')}\")\n    print(f\"Total attempts: {mock_response_count}\")\nexcept Exception as e:\n    print(f\"Polling failed after timeout: {e}\")\n\n# Reset count for potential re-runs in an interactive environment\nmock_response_count = 0","lang":"python","description":"This quickstart demonstrates how to use `HTTSleep` to poll an endpoint until a specific condition is met. The `simulate_api_call` function acts as a mock HTTP service, returning 'pending' status a few times before eventually returning 'completed'. The `check_func` defines the condition for successful polling. The poller will retry with exponential backoff until the condition is met or the `timeout` is reached."},"warnings":[{"fix":"Thoroughly test `httsleep` in your target Python environment. Consider forking the project or choosing a more actively maintained alternative if long-term support and up-to-date dependencies are critical.","message":"HTTSleep has not been actively maintained or updated since January 2021. This means it may not be compatible with newer Python versions (beyond 3.8/3.9, which were current at the time of its last update), or its dependencies might become outdated, potentially leading to security vulnerabilities or runtime errors.","severity":"gotcha","affected_versions":"<=0.3.1"},{"fix":"Ensure your custom `http_get_func` uses `requests.get` (or similar `requests` methods) or constructs a `requests.Response`-compatible object. If you're mocking, ensure the mock object has the expected attributes and methods like `.json()` and `status_code`.","message":"The `http_get_func` passed to `HTTSleep` must return an object that mimics `requests.Response`, specifically having a `.json()` method and a `status_code` attribute, if these are used by your `check_func` or the default status checkers. Returning a non-compatible object (e.g., `None` or a plain dictionary) will lead to `AttributeError` or `TypeError`.","severity":"gotcha","affected_versions":"<=0.3.1"},{"fix":"To control logging, either pass `logger=None` to the `HTTSleep` constructor to disable it, or provide a pre-configured `logging.Logger` instance: `logger=logging.getLogger('my_logger')`.","message":"HTTSleep uses `python-json-logger` for its internal logging. If you don't configure the logger, it may log to the console with JSON formatting by default, which might be unexpected in non-JSON logging setups. You can explicitly pass `logger=None` or configure a custom logger.","severity":"gotcha","affected_versions":"<=0.3.1"},{"fix":"If you need both custom logic and default HTTP status checks, incorporate the default logic into your `check_func`, or chain it. Alternatively, consider using `status_checker` argument if applicable, but be aware of how they interact.","message":"HTTSleep provides default status checking logic based on HTTP status codes (e.g., 200 for success, 2xx for continuation). If you define a `check_func`, it completely overrides these defaults. Ensure your `check_func` handles all conditions, including what constitutes a success and what should trigger a retry or failure.","severity":"gotcha","affected_versions":"<=0.3.1"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Verify that your `http_get_func` always returns a `requests.Response`-like object, even in error scenarios (e.g., by catching exceptions and returning a `requests.Response` with an error status code and empty content), or ensure your mock is complete.","cause":"The `http_get_func` provided to `HTTSleep` returned `None` or an object that does not have a `.json()` method (or other expected `requests.Response` attributes), typically when the underlying HTTP request failed or was improperly mocked.","error":"AttributeError: 'NoneType' object has no attribute 'json'"},{"fix":"Increase the `timeout` value, adjust `interval`, `max_interval`, and `factor` to allow for longer and more frequent retries, or thoroughly debug your `check_func` and the target service to ensure the success condition is eventually reachable and correctly identified.","cause":"The `check_func` never returned `True` within the total `timeout` period specified. This can be due to the target service taking too long, the success condition never being met, or the `check_func` having a bug.","error":"httsleep.exceptions.HTTSleepTimeout: Polling timed out after X seconds."},{"fix":"Ensure `httsleep` is installed by running `pip install httsleep`. If you are using a virtual environment, activate it before running the installation and your script.","cause":"The `httsleep` library is not installed in the current Python environment, or the environment where the code is being run is different from where `pip install httsleep` was executed.","error":"ModuleNotFoundError: No module named 'httsleep'"}]}