python-fragment

An unofficial Python library for interacting with Fragment (Python 3.9+). The library scrapes Fragment's HTML pages and exposes a clean, fully typed interface.

Features

• Both synchronous and asynchronous clients
• Fast HTML parsing powered by selectolax
• Fully typed - all returned data is described with TypedDict schemas
• Automatic retries on network failures with exponential back-off

Installation

pip install python-fragment

Quick Start

Async client

import asyncio
import fragment

async def main():
  async with fragment.AsyncClient() as client:
    # Search usernames currently on auction
    usernames = await client.search_usernames(
      query="crypto",
      filter="auction",
      sort="price_desc"
    )
    for u in usernames[:3]:
      print(u)
      # {
      #   'username': 'crypto',
      #   'status': 'auction',
      #   'value': 15000.0,
      #   'datetime': '2024-08-01T12:00:00+00:00',
      #   'is_resale': False
      # }

asyncio.run(main())

Sync client

import fragment

with fragment.Client() as client:
  # Detailed info for a specific username
  info = client.username_info("durov")
  print(info["status"])
  print(info["bid_history"])
  print(info["ownership_history"])

Proxy Usage

A proxy can be set for the entire client session or overridden per individual request. The interface is identical for both AsyncClient and Client.

Client-level proxy

import fragment

PROXY = "http://{user}:{password}@{host}:{port}"

# Async
async with fragment.AsyncClient(proxy=PROXY) as client:
  print(await client.username_info("crypto"))

# Sync
with fragment.Client(proxy=PROXY) as client:
  print(client.username_info("crypto"))

Per-request proxy

import fragment

PROXY = "http://{user}:{password}@{host}:{port}"

# Async
async with fragment.AsyncClient() as client:
  print(await client.username_info("crypto", proxy=PROXY))

# Sync
with fragment.Client() as client:
  print(client.username_info("crypto", proxy=PROXY))

Error Handling

import fragment
from fragment.errors import FragmentHTTPError, ParserError


async with fragment.AsyncClient() as client:
  try:
    info = await client.username_info("someusername")
  except FragmentHTTPError as e:
    print(f"HTTP error: {e}")
  except ParserError as e:
    print(f"Failed to parse Fragment HTML: {e}")

FragmentHTTPError - raised when the server returns a non-OK response.

ParserError - raised when the Fragment page structure has changed and data cannot be extracted.