pip install altsportsleagues
# or
poetry add altsportsleagues
# or
pipenv install altsportsleagues

from altsportsleagues import AltSportsLeagues
import os

client = AltSportsLeagues(
    api_key=os.getenv('ASL_API_KEY'),
    timeout=30  # optional, in seconds
)

# List leagues
leagues = client.leagues.list(
    tier='tier-2',
    sport='Soccer',
    limit=10
)

for league in leagues.data:
    print(f"{league.name} ({league.country})")

from altsportsleagues import AltSportsLeagues

client = AltSportsLeagues(
    api_key='your_api_key',      # Required
    base_url=None,               # Optional: API base URL
    timeout=30,                  # Optional: Request timeout (seconds)
    retries=3,                   # Optional: Max retry attempts
    retry_delay=1.0,             # Optional: Delay between retries (seconds)
    headers=None,                # Optional: Custom headers dict
)

leagues = client.leagues.list(
    sport_type='Soccer',         # optional
    archetype='major_league',    # optional
    tier='tier-2',               # optional: tier-1, tier-2, tier-3, tier-4
    country='United States',     # optional
    limit=100,                   # optional, default: 100
    offset=0                     # optional, default: 0
)

# Access response
print(f"Total: {leagues.meta.total}")
print(f"Results: {len(leagues.data)}")
for league in leagues.data:
    print(league.name)

league = client.leagues.get('league_001')

print(f"Name: {league.data.name}")
print(f"Sport: {league.data.sport}")
print(f"Tier: {league.data.tier}")
print(f"Data Readiness: {league.data.data_readiness}%")

stats = client.leagues.stats()

print(f"Total Leagues: {stats['total_leagues']}")
print(f"Tier Breakdown: {stats['tier_breakdown']}")
print(f"Average Readiness: {stats['average_data_readiness']}%")

results = client.discovery.search(
    query='professional pickleball leagues in North America',
    min_confidence=0.7,  # optional, 0-1
    limit=10             # optional
)

for result in results.data:
    print(f"{result.name} - Confidence: {result.confidence_score}")

similar = client.discovery.similar(
    league_id='league_001',
    limit=10  # optional
)

for league in similar.data:
    print(f"{league.name} - Similarity: {league.similarity_score}")

valuation = client.valuation.evaluate(
    league_id='league_001',
    include_api_assessment=True,   # optional
    include_data_quality=True      # optional
)

print(f"Composite Score: {valuation.data.composite_score}/100")
print(f"Tier: {valuation.data.tier}")
print(f"Annual Value: ${valuation.data.estimated_annual_value:,.0f}")

# Dimensional breakdown
for dimension, score in valuation.data.dimensions.items():
    print(f"  {dimension}: {score}/100")

score = client.qualification.score(
    league_id='league_001',
    mappings=[
        {
            'source': 'match_id',
            'target': 'event.id',
            'confirmed': True
        }
    ],
    quality_metrics={
        'overallScore': 85,
        'mappedPercentage': 90,
        'confirmedPercentage': 80,
        'recommendation': 'accept'
    }
)

print(f"Qualified: {score.data.qualified}")
print(f"Score: {score.data.qualification_score}/100")
print(f"Tier: {score.data.estimated_tier}")
print(f"Effort: {score.data.engineering_effort}")

import asyncio
from altsportsleagues import AsyncAltSportsLeagues

async def main():
    client = AsyncAltSportsLeagues(api_key='your_api_key')
    
    # Concurrent requests
    leagues, stats = await asyncio.gather(
        client.leagues.list(tier='tier-2'),
        client.leagues.stats()
    )
    
    print(f"Found {len(leagues.data)} tier-2 leagues")
    print(f"Total leagues: {stats['total_leagues']}")
    
    await client.close()  # Clean up

asyncio.run(main())

from altsportsleagues import (
    AltSportsLeagues,
    APIError,
    AuthenticationError,
    RateLimitError,
    ValidationError
)

client = AltSportsLeagues(api_key='demo-0001')

try:
    league = client.leagues.get('invalid_id')
except AuthenticationError as e:
    print(f"Auth failed: {e.message}")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after} seconds")
except ValidationError as e:
    print(f"Validation error: {e.fields}")
except APIError as e:
    print(f"API Error [{e.code}]: {e.message}")
    print(f"Status: {e.status}")
except Exception as e:
    print(f"Unexpected error: {e}")

def paginate_leagues(client, **kwargs):
    """Generator that yields all leagues matching filters."""
    offset = 0
    limit = kwargs.get('limit', 100)
    
    while True:
        response = client.leagues.list(
            **{**kwargs, 'limit': limit, 'offset': offset}
        )
        
        yield from response.data
        
        if not response.meta.has_more:
            break
        
        offset += limit

# Usage
for league in paginate_leagues(client, tier='tier-2', sport='Soccer'):
    print(league.name)

from altsportsleagues import AltSportsLeagues
from altsportsleagues.types import (
    LeagueBasic,
    LeagueDetailed,
    LeagueListResponse,
    SearchResult,
    ValuationResult
)

client: AltSportsLeagues = AltSportsLeagues(api_key='demo-0001')
leagues: LeagueListResponse = client.leagues.list()
league: LeagueDetailed = leagues.data[0]

from altsportsleagues import AltSportsLeagues

with AltSportsLeagues(api_key='your_api_key') as client:
    leagues = client.leagues.list(tier='tier-2')
    for league in leagues.data:
        print(league.name)

# Client automatically closed

league_ids = ['league_001', 'league_002', 'league_003']

for league_id in league_ids:
    valuation = client.valuation.evaluate(league_id=league_id)
    print(f"{league_id}: {valuation.data.tier} (score: {valuation.data.composite_score})")

# Search for leagues
results = client.discovery.search(
    query='professional ultimate frisbee',
    min_confidence=0.7
)

# Get details for top 3 results
for result in results.data[:3]:
    league = client.leagues.get(result.id)
    valuation = client.valuation.evaluate(league_id=result.id)
    
    print(f"\n{league.data.name}:")
    print(f"  Country: {league.data.country}")
    print(f"  Tier: {valuation.data.tier}")
    print(f"  Score: {valuation.data.composite_score}/100")
    print(f"  Value: ${valuation.data.estimated_annual_value:,.0f}")

import json

# Get all tier-1 leagues
tier1 = client.leagues.list(tier='tier-1', limit=500)

# Export to JSON
with open('tier1_leagues.json', 'w') as f:
    data = [league.dict() for league in tier1.data]
    json.dump(data, f, indent=2, default=str)

print(f"Exported {len(tier1.data)} tier-1 leagues")