micawber

Common errors

• No provider found for URL: http://example.com/some-unsupported-url

  cause The URL provided does not match any of `micawber`'s configured OEmbed providers, or the provider's endpoint has changed since `micawber`'s last update.
  fix Verify if the URL's service supports OEmbed. If it does, check the official OEmbed endpoint and consider manually adding a custom provider pattern to your `micawber.Micawber` instance.

• KeyError: 'title' (or 'html', 'thumbnail_url', etc.)

  cause The OEmbed response received from the provider was missing the expected key, indicating an incomplete or malformed response, or the content could not be retrieved by the provider.
  fix Access dictionary keys using `.get('key', None)` or `.get('key', 'Default Value')` to prevent `KeyError`. Print the full `response` dictionary to debug what data was actually received.

• requests.exceptions.ConnectionError: ('Connection aborted.', ConnectionResetError(104, 'Connection reset by peer'))

  cause A network issue (e.g., DNS resolution failure, firewall, server unavailability, or client-side connection reset) occurred while `micawber` was attempting to fetch content from an OEmbed provider.
  fix Verify your internet connectivity and the status of the OEmbed provider's server. Implement retry logic with exponential backoff for network requests to handle transient connection issues.

Warnings

• gotcha The built-in OEmbed provider list has not been updated since the library's last release in 2017. New services or changes to existing service endpoints may cause `micawber` to fail to retrieve content or retrieve incorrect data for certain URLs.
  Fix: Manually update providers by extending `micawber.providers.bootstrap_basic()` with custom patterns or using `micawber.Micawber` with an updated list of `Provider` objects.
• gotcha `micawber` does not configure a cache by default when using `micawber.bootstrap_basic()` or `micawber.Micawber()` without a `cache` argument. This can lead to repeated network requests for the same URL, impacting performance and potentially causing rate-limiting issues with external APIs.
  Fix: Initialize `micawber.Micawber` with a cache backend, e.g., `micawber.bootstrap_basic(cache=micawber.cache.Cache())` for an in-memory cache or integrate a custom cache system.
• gotcha If an OEmbed provider returns an error, an incomplete response, or malformed data, `micawber` might raise a `KeyError` when accessing expected fields (e.g., 'title', 'html') or return an incomplete dictionary without explicit error status.
  Fix: Implement robust `try-except KeyError` blocks and always use `.get()` with default values when accessing dictionary keys from the OEmbed response to handle missing data gracefully. Validate the presence of critical keys before use.

Install

• pip install micawber Install micawber

Imports

• bootstrap_basic

  from micawber import bootstrap_basic

  The simplest way to get a pre-configured Micawber instance with default providers.
• Micawber

  from micawber import Micawber

  For more granular control over providers and caching.
• bootstrap_basic
  wrong:

  from micawber import bootstrap_basic (not strictly wrong, but the top-level import is more common for convenience)

  correct:

  from micawber.providers import bootstrap_basic

  Direct import from the providers submodule. The top-level 'from micawber import bootstrap_basic' is a convenient alias.

Quickstart

Initialize micawber with default OEmbed providers and an in-memory cache. Then, use `m.request()` to fetch OEmbed data for a specific URL or `m.parse_text()` to automatically find URLs within text and replace them with embedded content.

import micawber
from micawber.cache import Cache

# Configure Micawber with default providers and an in-memory cache
m = micawber.bootstrap_basic(cache=Cache())

# Example URL (using a real OEmbed example, this is usually a video)
youtube_url = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'

# Request OEmbed data for a URL
try:
    response = m.request(youtube_url)
    print(f"Title: {response.get('title')}")
    print(f"Type: {response.get('type')}")
    print(f"HTML: {response.get('html', 'No HTML provided')[:50]}...")
except Exception as e:
    print(f"Error requesting OEmbed data: {e}")

# Alternatively, parse text containing URLs and replace them with rich content
text_with_url = f'Check out this video: {youtube_url} and some other stuff.'
html_output = m.parse_text(text_with_url)
print("\n--- Parsed Text HTML Output ---")
print(html_output[:200] + '...') # Print first 200 chars for brevity