apeye

1.4.1 · active · verified Sun Apr 12

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.

Warnings

breaking 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.
Fix: Install `apeye` using `pip install apeye[limiter]` to include the necessary dependencies for rate limiting.
gotcha 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`.
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))`.

Install

pip install apeye Base installation
pip install apeye[limiter] With rate limiting support

Imports

URL
```
from apeye.url import URL
```

RequestsURL

from apeye.requests_url import RequestsURL

Cache
```
from apeye.cache import Cache
```

RateLimitAdapter

from apeye.rate_limiter import RateLimitAdapter

Quickstart

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.

from apeye.url import URL
from apeye.requests_url import RequestsURL
import requests

# Using URL for path-like URL manipulation
base_url = URL('https://api.example.com')
endpoint = base_url / 'v1' / 'users'
print(f"Constructed URL: {endpoint}")

# Using RequestsURL for integration with the requests library
api_url = RequestsURL('https://httpbin.org/get')

try:
    # This part requires network access
    response = requests.get(api_url.get_url())
    response.raise_for_status()
    print(f"API response (first 100 chars): {response.text[:100]}...")
except requests.exceptions.RequestException as e:
    print(f"Could not fetch URL: {e}. Check your network connection.")

# Example of using the cache (requires `apeye[limiter]` for CacheControl related features if used with requests adapter, 
# but the basic Cache decorator works standalone)
from apeye.cache import Cache
import os

@Cache(cache_dir='./apeye_cache')
def get_data(param: str) -> dict:
    print(f"Fetching data for: {param}")
    # Simulate a network request or heavy computation
    import time
    time.sleep(0.1)
    return {'param': param, 'value': len(param)}

# Clear cache directory for a fresh run if it exists
import shutil
if os.path.exists('./apeye_cache'):
    shutil.rmtree('./apeye_cache')

print(get_data('hello')) # First call, fetches data
print(get_data('hello')) # Second call, uses cache
print(get_data('world')) # New call, fetches data

view raw JSON →