Seedr API

An unofficial API wrapper for seedr.cc. This library provides a simple and convenient way to interact with the Seedr API from your Python applications with modern features like automatic token refresh, device authentication, and typed response models.

Installation

You can install the package using pip:

pip install seedr

Features

• 🔐 Multiple authentication methods (email/password, token, device code)
• 🔄 Automatic token refresh on expiration
• 📦 Typed response models for better code completion
• 🎯 Clean, modern Python API
• ✅ Full backward compatibility with existing code

Usage

Basic Authentication

Create an instance of the SeedrAPI class using your email and password, or an existing access token:

from seedr import SeedrAPI

# Authenticate with email and password
seedr = SeedrAPI(email='your_email@example.com', password='your_password')

# Or, authenticate with an access token
seedr = SeedrAPI(token='your_access_token')

# With both access and refresh tokens for auto-refresh
seedr = SeedrAPI(token='access_token', refresh_token='refresh_token')

Device Authentication

For device-based authentication (useful for apps running on limited input devices):

from seedr import SeedrAPI

# Initialize without credentials
seedr = SeedrAPI.__new__(SeedrAPI)
seedr.__init__.__defaults__ = (None, None, None, None)

# Get device code
user_code = seedr.get_device_code()
print(f"Go to seedr.cc and enter code: {user_code}")

# Wait for user to authorize, then get token
token = seedr.get_token(seedr.devc)
print(f"Access token: {token}")

Token Refresh

Set up automatic token refresh callback:

def on_token_refreshed(access_token, refresh_token):
    print(f"Token refreshed! Save these tokens:")
    print(f"Access: {access_token}")
    print(f"Refresh: {refresh_token}")
    # Save tokens to database/file

seedr = SeedrAPI(email='email@example.com', password='password')
seedr.on_token_refresh = on_token_refreshed

Get Drive Information

Get information about your account with typed response:

# Get root folder contents as typed object
folder = seedr.get_folder_contents()
print(f"Space used: {folder.space_used} / {folder.space_max}")
print(f"Folders: {len(folder.folders)}")
print(f"Files: {len(folder.files)}")
print(f"Active torrents: {len(folder.torrents)}")

# Access nested objects
for file in folder.files:
    print(f"File: {file.name}, Size: {file.size}, Video: {file.play_video}")

# Legacy method (returns dict)
drive_info = seedr.get_drive()
print(drive_info)

Get Folder Contents

Get the contents of a specific folder:

# Modern method with typed response
folder = seedr.get_folder_contents(folder_id=123)
for subfolder in folder.folders:
    print(f"Folder: {subfolder.name} ({subfolder.size} bytes)")

# Legacy method (returns dict)
folder_dict = seedr.get_folder(folder_id=123)

Get File Information

Get information about a specific file, including download URL:

# Modern method with typed response
file_details = seedr.get_file_details(folder_file_id=456)
print(f"Download URL: {file_details.url}")
print(f"File name: {file_details.name}")

# Legacy method (returns dict)
file_info = seedr.get_file(folder_file_id=456)
print(file_info['url'])

Add a Torrent

Add a torrent using a magnet link or direct .torrent file URL:

# Add magnet link
result = seedr.add_torrent('magnet:?xt=urn:btih:...')
print(result)

# Or use the new method name
result = seedr.add_magnet('magnet:?xt=urn:btih:...')

Delete Operations

Delete files, folders, or torrents:

# Delete a file
seedr.delete_file(file_id=123)

# Delete a folder
seedr.delete_folder(folder_id=456)

# Delete a torrent
seedr.delete_torrent(torrent_id=789)

Create Archive

Create a downloadable archive from a folder:

archive = seedr.create_archive(folder_id=123)
print(f"Archive URL: {archive.archive_url}")
print(f"Archive ID: {archive.archive_id}")

Response Models

The library provides typed response models for better code completion and type safety:

• SeedrFolderResponse - Complete folder information with nested objects
• SeedrTorrent - Torrent metadata (id, name, size, hash, progress)
• SeedrFolder - Folder metadata (id, name, fullname, size)
• SeedrFile - File metadata (name, size, hash, folder_id, play_video)
• SeedrFileDetails - File details with download URL
• SeedrArchiveResponse - Archive creation result with URL

# Example: Iterate through all content
folder = seedr.get_folder_contents()

# Access torrents
for torrent in folder.torrents:
    print(f"Torrent: {torrent.name}, Progress: {torrent.progress}")

# Access folders
for subfolder in folder.folders:
    print(f"Folder: {subfolder.name}, ID: {subfolder.id}")

# Access files
for file in folder.files:
    print(f"File: {file.name}, Size: {file.size}")

Error Handling

The library raises specific exceptions for different types of errors:

• InvalidLogin: Raised for incorrect username or password.
• InvalidToken: Raised for an invalid or expired access token.
• LoginRequired: Raised when no authentication credentials are provided.
• TokenExpired: Raised when the access token has expired.

You can handle these exceptions using a try...except block:

from seedr import SeedrAPI
from seedr.errors import InvalidLogin, InvalidToken

try:
    seedr = SeedrAPI(email='wrong@example.com', password='wrong_password')
except InvalidLogin as e:
    print(f"Invalid login credentials: {e}")

try:
    folder = seedr.get_folder_contents()
except InvalidToken:
    print("Token expired, please re-authenticate")

Migration Guide

If you're using the old API, your code will continue to work without changes. However, you can take advantage of new features:

Old way (still works):

seedr = SeedrAPI(email='email', password='pass')
drive = seedr.get_drive()  # Returns dict
print(drive['space_used'])

New way (recommended):

seedr = SeedrAPI(email='email', password='pass')
folder = seedr.get_folder_contents()  # Returns typed object
print(folder.space_used)  # Better code completion

New features available:

# Token refresh callback
seedr.on_token_refresh = lambda access, refresh: save_tokens(access, refresh)

# Device authentication
user_code = seedr.get_device_code()
token = seedr.get_token(seedr.devc)

# Create archives
archive = seedr.create_archive(folder_id=123)

# Delete torrents
seedr.delete_torrent(torrent_id=456)

Error Handling

The library raises specific exceptions for different types of errors:

• InvalidLogin: Raised for incorrect username or password.
• InvalidToken: Raised for an invalid or expired access token.
• LoginRequired: Raised when no authentication credentials are provided.

You can handle these exceptions using a try...except block:

from seedr.errors import InvalidLogin

try:
    seedr = SeedrAPI(email='wrong@example.com', password='wrong_password')
except InvalidLogin:
    print("Invalid login credentials.")

Contributing

Contributions are welcome! If you find a bug or have a feature request, please open an issue on the GitHub repository.

If you'd like to contribute code, please follow these steps:

1. Fork the repository.
2. Create a new branch for your feature or bug fix.
3. Make your changes and commit them with a descriptive message.
4. Push your changes to your fork.
5. Open a pull request to the main repository.

Credits

• Inspired by theabbie's seedr-api.