{"id":4878,"library":"apeye","title":"apeye","description":"apeye is a Python library providing handy tools for working with URLs and APIs. It offers `pathlib.Path`-like objects for robust URL manipulation, a JSON-backed cache decorator for functions, and a `CacheControl` adapter for rate limiting HTTP requests. The library is currently at version 1.4.1 and maintains a sporadic but active release cadence.","status":"active","version":"1.4.1","language":"en","source_language":"en","source_url":"https://github.com/domdfcoding/apeye","tags":["url","api","utility","cache","rate-limiting"],"install":[{"cmd":"pip install apeye","lang":"bash","label":"Base installation"},{"cmd":"pip install apeye[limiter]","lang":"bash","label":"With rate limiting support"}],"dependencies":[{"reason":"Required for the `apeye.rate_limiter` module functionality.","package":"cachecontrol","optional":true}],"imports":[{"symbol":"URL","correct":"from apeye.url import URL"},{"symbol":"RequestsURL","correct":"from apeye.requests_url import RequestsURL"},{"symbol":"Cache","correct":"from apeye.cache import Cache"},{"symbol":"RateLimitAdapter","correct":"from apeye.rate_limiter import RateLimitAdapter"}],"quickstart":{"code":"from apeye.url import URL\nfrom apeye.requests_url import RequestsURL\nimport requests\n\n# Using URL for path-like URL manipulation\nbase_url = URL('https://api.example.com')\nendpoint = base_url / 'v1' / 'users'\nprint(f\"Constructed URL: {endpoint}\")\n\n# Using RequestsURL for integration with the requests library\napi_url = RequestsURL('https://httpbin.org/get')\n\ntry:\n    # This part requires network access\n    response = requests.get(api_url.get_url())\n    response.raise_for_status()\n    print(f\"API response (first 100 chars): {response.text[:100]}...\")\nexcept requests.exceptions.RequestException as e:\n    print(f\"Could not fetch URL: {e}. Check your network connection.\")\n\n# Example of using the cache (requires `apeye[limiter]` for CacheControl related features if used with requests adapter, \n# but the basic Cache decorator works standalone)\nfrom apeye.cache import Cache\nimport os\n\n@Cache(cache_dir='./apeye_cache')\ndef get_data(param: str) -> dict:\n    print(f\"Fetching data for: {param}\")\n    # Simulate a network request or heavy computation\n    import time\n    time.sleep(0.1)\n    return {'param': param, 'value': len(param)}\n\n# Clear cache directory for a fresh run if it exists\nimport shutil\nif os.path.exists('./apeye_cache'):\n    shutil.rmtree('./apeye_cache')\n\nprint(get_data('hello')) # First call, fetches data\nprint(get_data('hello')) # Second call, uses cache\nprint(get_data('world')) # New call, fetches data\n","lang":"python","description":"This quickstart demonstrates key features of apeye: using `apeye.url.URL` for constructing URLs with a `pathlib.Path`-like interface, and `apeye.requests_url.RequestsURL` for integrating with the `requests` library. It also shows a basic example of the `apeye.cache.Cache` decorator for memoizing function results."},"warnings":[{"fix":"Install `apeye` using `pip install apeye[limiter]` to include the necessary dependencies for rate limiting.","message":"When using the `rate_limiter` module, specifically `RateLimitAdapter`, ensure you install `apeye` with the `[limiter]` extra. As of v0.9.0, this functionality was moved to an optional dependency.","severity":"breaking","affected_versions":">=0.9.0"},{"fix":"If you intend to use `apeye` URLs with `requests`, import and use `RequestsURL` (e.g., `RequestsURL('your_url').get_url()`) or convert a `URL` object to a string explicitly: `requests.get(str(my_url))`.","message":"The primary `apeye.url.URL` class provides `pathlib.Path`-like functionality for URL manipulation but does not directly integrate with the `requests` library. For `requests` integration, use `apeye.requests_url.RequestsURL` or explicitly convert the `URL` object to a string before passing it to `requests`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}