#!/usr/bin/env python
# encoding: utf-8
# Created by Put.io.
# Copyright (c) 2010 Put.io.
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
"""
Basic Tutorial:
from putio import *
# connecting your put.io with your api key and api secret
api = Api("123456","abcdef")
# getting your items
items = api.get_items()
for it in items:
print "%5s %s" % (it.id, it.name)
# creating a folder
newitem = api.create_folder(name="blabla")
# getting one item
item = api.get_items(id=newitem.id)[0]
#item = api.get_items()[0]
# getting an item info
item = item.update_info()
print item.name, item.id, item.is_dir, item.__dict__
# renaming an item
print "old name: %s" % item.name
newitem = item.rename_item("renamed by api")
print "new name: %s" % newitem.name
# moving an item to a target folder
# 0 being root of your files
newitem.move_item(target=0)
# deleting an item
newitem.delete_item()
# searching items
sresults = api.search_items("avi from:me type:video")
See the site for more info.
Todos:
* oAuth support
* Creating and getting MP4 Files
* File Uploading
* User Methods
"""
import sys
import socket
import urllib
import urllib2
try:
import json
except ImportError:
import simplejson as json
# setup
RPC_URL = "http://api.put.io/v1"
# constants
UNITS = ['B', 'K', 'M', 'G', 'T', 'P', 'E']
TIMEOUT = 60 #seconds
VERSION = "0.91"
# 0.92 transfers/add change
# 0.91 tidying up for the release; unicode human_size, user_idi user info
# bugs; some user, friend and item methods
# 0.90 updated auth, "v1"
# 0.85 reformated input and output. big changes on the api server.
# 0.84b typos
# 0.84 item_search to search_items, get_items orderby, get_friends
# 0.83 new stream url
def human_size(size):
"""
Converts bytes to human readable strings
Takes : An Integer
Returns: A String
Example:
>>> print human_size(12.66) # 12.7B
>>> print human_size(12345) # 12.1K
>>> print human_size(12345678) # 11.8M
>>> print human_size(12345678910) # 11.5G
>>> print human_size(12345678910111) # 11.2T
"""
if isinstance(size, unicode): size = int(size)
s = float(size * 1.0)
i = 0
while size >= 1024.00 and i < len(UNITS):
i += 1
size /= 1024.00
return "%.1f%s" % (size, UNITS[i])
def _send(obj, path, post=None, **args):
"""
Chats with API Server.
Takes : A dict.
Returns: JSON
To format the output, call _result() method.
Request Format:
{
"user_id" : INTEGER,
"api_key" : STRING,
"api_secret" : STRING,
"params" : DICTIONARY
}
Response Format:
{
"user_id" : INTEGER,
"response" : {
"results" : [{
.... data ....
}]
},
"error" :null,
"error_message" :null
}
"""
post_request = dict()
if not obj:
raise PutioError("You need to login first")
else:
post_request['api_key'] = obj.api_key
post_request['api_secret'] = obj.api_secret
url = RPC_URL + path
if args: url += "?" + urllib.urlencode(args)
# print url
# print "0. REQUEST: %s: %s" % (type(post), post)
post_request['params'] = dict()
for k in post.keys():
#if k not in ("user_id", "api_key", "api_secret"):
if k not in ("api_key", "api_secret"):
post_request['params'][k] = post[k]
else:
post_request[k] = post[k]
# print "POSTREQUEST: %s" % post_request
pre_post = {}
pre_post['request'] = json.dumps(post_request)
error_data = ""
try:
# print "1. POST: %s: %s" % (type(pre_post), pre_post)
request = urllib2.Request(url, urllib.urlencode(pre_post))
# default timeout time is 60 seconds.
socket.setdefaulttimeout(TIMEOUT)
if (sys.version_info[0] == 2 and sys.version_info[1] > 5) \
or sys.version_info[0] > 2:
u = urllib2.urlopen(request, timeout=TIMEOUT)
else:
u = urllib2.urlopen(request)
data = u.read()
# print "2. RECEIVED DATA: %s" % data
return _result(obj, data)
except urllib2.HTTPError, e:
error_data = e.read()
if e.code == 500:
raise PutioError("An error occured. This may be a bug. Please \
report to the application provider.", e)
elif e.code == 404:
raise PutioError("Unknown method, service or parameters.", e)
else:
raise PutioError("Service unavailable. Please try again.", e)
except urllib2.URLError, e:
raise PutioError("Request failed. (%s)" % str(e), e)
except UnboundLocalError, e:
raise PutioError("Service unavailable. This may be a bug on the api \
server side. Please report following info: (%s)" % str(e), e)
def _result(obj, data):
"""
Takes : JSON
Returns: A Dict
Checks if the api server returned an error or not.
Returns the error message or the success message.
JSON Format that API Server returns:
{
"error": false,
"error_message": null,
"user_id": some_integer,
"user_name": "username"
"response": {
"results": [ ...Always an array of things... ]
}
}
"""
try:
result = json.loads(data)
# print "3. RESULT DATA: %s" % result
except ValueError, e:
#logger.error('Error: %s' % e)
#logger.error('Data: %s' % data)
#logger.error('Result: %s' % result)
raise PutioError("Json error.", e)
# It's now a python dictionary. Json.loads() makes necessary
# conversions like "false" to "False", "null" to "None", etc.
# print "3. JSON TO DICT: ", result
if result['error'] is False:
obj.user_name = result['user_name']
obj.user_id = result['id']
return result['response']['results']
else:
#raise PutioError(result['error_message'])
return None
def strip_tags(value):
"""
Return the given HTML with all tags stripped.
You may use this to strip the html tags from
Put.io Dashboard Messages. (Optional)
Usage:
print strip_tags(MessageInstance.title)
"""
import re
return re.sub(r'<[^>]*?>', '', value)
class BaseObj(object):
# Creates an object with given dictionary.
def __init__(self, dictionary=None, **args):
if dictionary:
self.__dict__ = dictionary
if len(args) > 0:
for k,v in args.iteritems():
self.__dict__[k] = v
# def __getattr__(self, k):
# return self.__dict__[k]
def _convert_to_string(self):
if self.__dict__.has_key('file_type'):
self.file_type = Item._int_to_filetype(self.file_type)
if self.__dict__.has_key('dl_handler'):
self.dl_handler = UrlBucket.dl_handler[str(self.dl_handler)]
if self.__dict__.has_key('dltype'):
self.dltype = UrlBucket.dltype[str(self.dltype)]
class PutioError(Exception):
"""
PutioError Exception Class
"""
def __init__(self, message='', original=None):
self.message = message
self.original = original
def __str__(self):
if self.original:
original_name = type(self.original).__name__
return '%s (Original Exception: %s, "%s")' % (self.message,
original_name,
self.original.args)
else:
return self.message
class User(BaseObj):
"""
Sample user:
u.name : 'aft'
u.friends_count : 497
u.bw_avail_last_month : '0'
u.bw_quota : '161061273600'
u.shared_items : 3
u.bw_quota_available : '35157040261'
u.disk_quota : '206115891200'
u.disk_quota_available : '158153510402'
u.shared_space : 0
"""
def __init__(self, api, dictionary=None, **args):
BaseObj.__init__(self, dictionary, **args)
self.api = api
class Friend(BaseObj):
"""
Sample friend
f.dir_id : '1407'
f.id : '2'
f.name : 'hasan'
"""
def __init__(self, api, dictionary=None, **args):
BaseObj.__init__(self, dictionary, **args)
self.api = api
def get_items(self, **args):
"""
Takes : A friend instance
Returns: A List of item objects.
Shortcut for listing a friends shared items.
"""
return self.api.get_items(parent_id = self.dir_id, **args)
class Message(BaseObj):
"""
Dashboard message objects.
Message Methods:
message.delete()
Message Attributes:
message.id (Integer)
message.user_id (Integer)
message.title (String)
message.description (None)
message.importance (Integer)
message.file_name (String)
message.file_type (String)
message.user_file_id (Integer)
message.from_user_id (Integer. If None, message is from Put.io)
message.channel (Integer)
message.hidden (Integer, 1 or 0)
Sample:
user_file_id = 4
user_id = 17
description = None
title = 'abcd.mp4
(89.86K)
downloaded'
importance = 0
file_name = 'abcd.mp4'
id = 3773
file_type = 'audio'
hidden = 0
from_user_id = None
channel = 2
"""
def __init__(self, api, dictionary=None, **args):
BaseObj.__init__(self, dictionary, *args)
self.file_type = Item._int_to_filetype(self.file_type)
self.api = api
def delete(self):
"""
Deletes messages. Returns none if unsuccessful.
"""
args = {"id":self.id}
result = _send(self.api, path="/messages", post=args, method="delete")
if not result: return None
class Api(object):
"""
A python interface into the Put.io API
Example usage:
To create an instance of the putio.Api class, with authentication:
>>> from putio import *
>>> api = api(YOUR_API_KEY, YOUR_API_SECRET)
To get the list of your files:
>>> items = api.get_items()
>>> for i in items: print i.id, i.name
To get the item list in a specified folder:
>>> items = api.get_items(id=123)
>>> for i in items: print i.id, i.name
Api Methods:
api.get_items()
api.get_transfers()
api.get_user()
api.is_ready()
api.create_folder()
api.search_items()
api.get_messages()
api.create_subscription()
api.get_subscription()
api.get_folder_list()
api.update_user_token()
api.get_user_info()
api.create_bucket()
"""
def __init__(self, api_key, api_secret):
self.user_id = None
self.user_name = None
self.access_token = None
self.api_key = api_key
self.api_secret = api_secret
# Token is required only for streaming links
self.access_token = self._get_user_token()
self.api = self
def update_user_token(self):
"""
Before streaming a video/audio file, its best to update the token.
This method doesn't return anything. It just updates the Api instance.
"""
self.access_token = self._get_user_token()
def get_user_name(self):
"""
Takes : Nothing
Returns: A String
Returns the name of the authenticated user. You can use this to
welcome your user.
"""
return self.user_name
def is_ready(self):
"""
Takes : Nothing.
Returns: True or False
Checks if the authentication is successful. Returns False if it isn't.
Probably, you won't be using this much.
Example:
>>> api = Api("key", "secret")
>>> if api.is_ready(): print "Vuhuu!"
"""
try:
return self.user_name
except:
return None
def get_items(self, limit=20, offset=0, parent_id=0, **arguments):
"""
Takes : Item attributes [Optional]
Returns: An Array of Item objects
Example:
>>> import putio
>>> api = putio.Api(YOUR_API_KEY, YOUR_API_SECRET)
>>> items = api.get_items() #without an argument
>>> items = api.get_items(type="video") #with an argument
>>> for i in items: print i.name, i.id, i.type
You can use these optional parameters while selecting item(s):
id = STRING or INTEGER
parent_id = STRING or INTEGER
offset = INTEGER (Default:0)
limit = INTEGER (Default: 20)
type = STRING (See Item class for available types)
orderby = STRING (Default: createdat_desc)
Orderby parameters:
id_asc
id_desc
type_asc
type_desc
name_asc
name_desc
extention_asc
extention_desc
createdat_asc
createdat_desc (Default)
See Item Class doc for the available attributes.
"""
items = []
args = {"limit":limit, "offset":offset, "parent_id":parent_id}
for k,v in arguments.iteritems(): args[k] = v
if "type" in arguments:
args['type'] = Item._filetype_to_int(arguments["type"])
result = _send(self.api, path="/files", post=args, method="list")
if result:
self.update_user_token()
for r in result:
items.append(Item(self.api, r))
return items
else:
raise PutioError("You have no items to show.")
def get_transfers(self):
"""
Takes : Nothing
Returns: An Array of Transfer objects
Example:
>>> trans = api.get_transfers()
>>> if newtransfers:
>>> for t in newtransfers:
>>> print t.name, t.status, t.percent_done
>>> else: print "you have no active transfers"
See Transfer Class doc for the available attributes.
"""
transfers = []
args = {}
transferlist = _send(self, path="/transfers", post=args, method="list")
if len(transferlist) > 0:
for k in transferlist:
transfers.append(Transfer(self.api, k))
return transfers
else:
return None
raise PutioError('You have no active transfers at the moment.')
def create_folder(self, name="New Folder", parent_id=0):
"""
Takes : A String [Optional], and
An Integer [Optional]
Returns: A Single Item object if successful.
Example:
>>> newfolder = api.create_folder(name="Created by Api")
>>> if newfolder: print "%s is created." % newfolder.name
"""
args = {"name":name, "parent_id":parent_id}
newfolder = _send(self.api,
path="/files",
post=args,
method="create_dir")
if newfolder and isinstance(newfolder, list):
newfolder = newfolder[0]
newfolder['id'] = int(newfolder['id'])
return Item(self.api, newfolder)
else:
#raise PutioError('Folder could not be created.')
return None
def search_items(self, query):
"""
Takes : A String
Returns: An Array of Item objects
Returns search results. You may add search parameters to the string
such as:
"from:'me'" (from:shares|jack|all|etc.)
"type:'video'" (audio|image|iphone|all|etc.)
"ext:'mp3'" (avi|jpg|mp4|all|etc.)
"time:'today'" (yesterday|thismonth|thisweek|all|etc.)
Example:
>>> searchresults = api.search_items("'jazz' from:'me' type:'audio'")
>>> if searchresults:
>>> for sr in searchresults: print sr.name
"""
search_results = []
args = {"query":query}
result = _send(self, path="/files", post=args, method="search")
if result:
self.update_user_token()
for r in result: search_results.append(Item(self.api, r))
return search_results
else:
return None
def get_messages(self):
"""
Takes : Nothing
Returns: An Array of Message objects
Returns your dashboard messages.
Example:
>>> msgs = api.get_messages()
>>> if msgs:
>>> for m in msgs: print m.title
"""
messages = []
args = {}
result = _send(self, path="/messages", post=args, method="list")
if result:
for r in result: messages.append(Message(self.api, r))
return messages
else:
return None
def create_subscription(self, name="My LegalTorrents Subscription",
url="http://www.legaltorrents.com/rss.xml",
**arguments):
"""
Takes : A String for name, a string for URL, and optional args.
Returns: A Single Subscription object
Creates a new subscription and returns it.
Example:
>>> newsub = api.create_subscription(name="Mininova",
url="http://www.mininova.org/rss.xml")
>>> if newsub: print "%s created." % newsub.name
See Subscription Class for available attributes
"""
args = {"title":name, "url":url}
for k in arguments.keys(): args[k] = arguments[k]
result = _send(self, path="/subscriptions", post=args, method="create")
if result:
return Subscription(self.api, result[0])
else:
return None
def get_subscriptions(self, **arguments):
"""
Takes: Nothing
Returns: An Array of Subscription objects
Returns a list of your subscriptions.
Example:
>>> subs = api.get_subscriptions()
>>> if newsub:
>>> for s in subs: print subs.name
See Subscription Class for available attributes
"""
subscriptions = []
args = {}
result = _send(self, path="/subscriptions", post=args, method="list")
if len(result) > 0:
for r in result:
if len(arguments) > 0:
for k,v in arguments.iteritems():
if r[k] == v:
subscriptions.append(Subscription(self.api, r))
else:
subscriptions.append(Subscription(self.api, r))
return subscriptions
else:
return None
def get_folder_list(self):
"""
Takes : Nothing
Returns: An Array of item objects.
Notice that this method returns a flat list of your folders. Create
your own method if you need a tree like list.
Parent_id is id of the container folder
Example:
>>> folderlist = api.get_folder_list()
>>> if folderlist:
>>> for f in folderlist: print f.name
Here is the returned item before being processed:
{
u'dirs': [...{sub folder 1}, {sub folder 2}...], # or []
u'shared': None,
u'id': u'4220',
u'name': u'renamed (4)',
u'default_shared': None
}
See Folder Class for available attributes
"""
folders = []
args = {}
result = _send(self, path="/files", post=args, method="dirmap")
# flattens the folder list
def recursive(folderarray):
if len(folderarray['dirs']) > 0:
for fa in folderarray['dirs']:
folders.append(Folder(self.api, fa))
recursive(fa)
else: folders.append(Folder(self.api, folderarray))
if result:
for r in result['dirs']:
if len(r['dirs']) > 0:
recursive(r)
else: folders.append(Folder(self.api, r))
return folders
else:
return None
def get_user_info(self):
"""
Takes : Nothing
Returns: A Single User object if successful.
Gives information about the authenticated user. Use this to inform
user about its quotas, sharing size, current available space, etc.
All sizes are in bytes. Use human_size(byte) to convert if necessary.
Returned Attributes:
info.bw_quota
info.disk_quota
info.bw_quota_available
info.disk_quota_available
info.name
info.shared_space
info.friends_count
info.shared_items
"""
args = {}
result = _send(self, path="/user", post=args, method="info")[0]
if result:
return User(self.api, result)
else:
return None
def _get_user_token(self):
"""
Internal method for getting the user token.
"""
args = {}
result = _send(self, path="/user", post=args, method="acctoken")
if result:
return result['token']
def get_friends(self):
"""
Takes : Nothing
Returns: An Array of Friend objects
Returns friends of the authenticated user.
Friend attributes:
friend.id
friend.name
friend.dir_id
Example:
>>> friends = api.get_friends()
>>> if friends:
>>> for f in friends: print f.name
To get a friend's files, use dir_id as a parent_id with get_items()
Option 1:
>>> for f in friends:
>>> items[f] = api.get_items(parent_id=f.dir_id)
>>> for i in items['jack']: print i.name
Option 2:
>>> for f in friends:
>>> f_items = f.get_items(limit=1)
>>> for fi in f_items: print fi.name
Returns None if the friend has no items.
"""
friends = []
args = {}
result = _send(self, path="/user", post=args, method="friends")
if result:
for r in result: friends.append(Friend(self.api, r))
return friends
else:
return None
def create_bucket(self):
"""
Takes : Nothing
Returns: An empty bucket object.
You'll need buckets to analyze and fetch URLs. Bucket is basicly a
container of one or more URLs, which then you can analyze and make
Put.io fetch the successfully analyzed URLs.
To fetch some URLs, you'll need to:
* Create a bucket (or use already existing one)
* Use Add method to add some URLs to the bucket
* Make Put.io analyze the bucket
* Add more or delete some of them
* And make Put.io fetch the URLs in the bucket.
After the analyzation, you can get a report about the bucket content
and the user quotas. For this, use get_report() method of UrlBucket
class.
"""
return UrlBucket(self.api)
class Item(BaseObj):
"""
An item can be a file or a folder.
Avaiable Item methods are:
item.rename_item()
item.move_item()
item.delete_item()
item.update_info()
item.get_download_url()
item.get_zip_url()
item.get_stream_url()
Available Item attributes:
Sizes are in bytes. Use human_size(byte) to convert if necessary.
item.id
item.name
item.type
item.size
item.is_dir
item.parent_id
item.screenshot_url
item.thumb_url
item.file_icon_url
item.download_url
Example Folder Item:
"id":"4394",
"name":"Billie Ray Martin The Crackdown Project - Vol 1",
"type":"folder",
"size":"23472048",
"is_dir":true,
"parent_id":"0",
"screenshot_url":"http://put.io/screenshot/b/dgRraFxlXmNl.jpg",
"thumb_url":"http://put.io/screenshot/dgRraFxlXmNl.jpg",
"file_icon_url":"http://put.io/images/file_types/folder.png",
"folder_icon_url":"",
"download_url":"http://node2.endlessdisk.com/download-file/17/4394",
"zip_url":"/stream-basket/17/4394"}
at the moment, type can be a:
folder
file
audio
movie
image
compressed
pdf
ms_doc
text
swf
unknown
"""
filetypes = {
"folder" : 0,
"file" : 1,
"audio" : 2,
"movie" : 3,
"image" : 4,
"compressed" : 5,
"pdf" : 6,
"ms_doc" : 7,
"text" : 8,
"swf" : 9
}
def __init__(self, api, dictionary=None, **args):
BaseObj.__init__(self, dictionary, **args)
self.api = api
@staticmethod
def _filetype_to_int(filetype):
if Item.filetypes.has_key(str(filetype.lower())):
return Item.filetypes[filetype]
else: raise PutioError("Unknown type. Please use one of these: " \
"folder, file, audio, movie, image," \
"compressed, pdf, ms_doc, text, swf")
@staticmethod
def _int_to_filetype(filetypeint):
"""
This method is not used because Api Server gives file types as string
"""
newfiletypes = dict()
# changes {"key":intvalue} to {"strvalue":"key"} first
for k,v in Item.filetypes.iteritems(): newfiletypes[str(v)] = k
# then finds value in keys
if newfiletypes.has_key(str(filetypeint)):
return newfiletypes[str(filetypeint)]
else:
return "unknown"
def rename_item(self, name):
"""
Takes : A String [Required]
Returns: A Single Item object
Example:
>>> print "Old Name: %s" % item.name
>>> item = item.rename_item("New Item Name")
>>> print "New Name: %s" % item.name
Renames the item.
"""
args = {"name":name, "id":self.id}
result = _send(self.api, path="/files", post=args, method="rename")
if result: return Item(self.api, result[0])
else: return None
def move_item(self, target=0):
"""
Takes : An Integer of target folder id. [Optional]
Returns: A Single Item object
Example:
>>> item = item.move_item(target=1221)
>>> if item:
>>> print "New Location: %s" % api.get_items(id=item.id).name
Moves the item to another folder. Parent_id = 0 is the root folder
of your disk space.
"""
args = {"id":self.id, "parent_id":target}
result = _send(self.api, path="/files", post=args, method="move")
if result: return Item(self.api, result[0])
else: return None
def delete_item(self):
"""
Takes : Nothing
Returns: Nothing if successful.
Example:
>>> item.delete_item()
Destroys the item permanently.
"""
args = {"id":self.id}
result = _send(self.api, path="/files", post=args, method="delete")
# fixme, check and return the result
return result
def update_info(self):
"""
Takes : Nothing
Returns: A Single Item object
Example:
>>> item = item.update_info()
>>> print item.__dict__
Refreshes the items attributes. Useful for folders, because folders
can be updated via subscriptions in the background.
Raises an exception if unsuccessful.
"""
args = {"id":self.id}
result = _send(self.api, path="/files", post=args, method="info")
if result:
return Item(self.api, result[0])
else:
raise PutioError("Update failed. Item may be unavailable.")
def get_download_url(self):
"""
Returns: A String
Example:
>>> item = item.update_info() #if necessary
>>> print item.get_download_url()
"""
if self.is_dir == False:
return self.download_url
else:
return None
def get_stream_url(self):
"""
Takes : Nothing
Returns: A String
Returns the stream url of files. If item is a folder, then download
url will be returned.
"""
result = self.update_info()
if result:
if self.is_dir == False:
sturl = str(self.stream_url) + "/atk/" \
+ self.api.access_token
return sturl
else:
return self.get_download_url()
else: raise PutioError("Error: Item not found.")
def create_mp4(self):
"""TODO"""
pass
def create_folder(self, name="New Folder", **args):
"""
Takes : Nothing
Returns: An Item object
Creates and returns a folder in another folder.
"""
return self.api.create_folder(name = name, parent_id = self.id,**args)
class Folder(Item):
"""
Folders are an Item object. Check Item class documentation for more info.
Sample:
folder.id = 4394
folder.name = "Billie Ray Martin The Crackdown Project"
folder.type = "folder"
folder.size = 23472048
folder.is_dir = True
folder.parent_id = 0
folder.screenshot_url = "/images/file_types/file.png"
folder.thumb_url = "/images/file_types/file.png"
folder.file_icon_url = "/images/file_types/folder.png"
folder.folder_icon_url = ""
folder.download_url = "http://XX.put.io/download-file/17/4394"
folder.zip_url = "http://XX.put.io/stream-basket/17/4394"
"""
def __init__(self, api, dictionary=None, **args):
Item.__init__(self, dictionary, **args)
self.api = api
def create_folder(self, name="New Folder", **args):
"""
Creates a folder in another folder. This method is not being used
at the moment.
"""
return self.api.create_folder(name = name, parent_id = self.id,**args)
class Subscription(BaseObj):
"""
Subscription Methods:
edit()
delete()
toggle_status()
undate_info()
add_do_filters()
add_dont_filters()
Subscription Attributes:
subsitem.id (integer)
subsitem.url (string)
subsitem.name (string)
subsitem.do_filters (strings, seperated by commas)
subsitem.dont_filters (strings, seperated by commas)
subsitem.parent_folder_id (integer)
subsitem.last_update_time (string)
subsitem.next_update_time (string)
subsitem.paused (boolean)
Example:
>>> subsitem = api.get_subscriptions()[0]
>>> if subsitem: print subsitem.name
Sample Values:
subsitem.id = 860
subsitem.url = "http://legaltorrents.com/music/rss.xml"
subsitem.name = "Jazz Radio"
subsitem.do_filters = "jazz, mp3"
subsitem.dont_filters = "smooth, wav"
subsitem.parent_folder_id = 234
subsitem.last_update_time = "2010-01-01 00:00"
subsitem.next_update_time = "2010-01-01 00:00"
subsitem.paused = False
"""
def __init__(self, api, dictionary=None, **args):
BaseObj.__init__(self, dictionary, **args)
self.api = api
def edit(self, **arguments):
"""
Takes : A Dictionary of attributes to change
Returns: A Single Subscription object
Example:
>>> newsub = subsitem.edit(name="newname", url="http://newurl", ...)
>>> if newsubs: print "Subscription updated."
Changes values of any given subscription attribute.
"""
args = {"id":self.id, "title":self.name, "url":self.url}
for k in arguments.keys(): args[k] = arguments[k]
result = _send(self.api,
path="/subscriptions",
post=args,
method="edit")
if result: return Subscription(self.api, result[0])
else: return None
def delete(self):
"""
Deletes the subscription item permanently.
Example:
>>> subsitem.delete()
>>> if newsubs: print "Subscription updated."
"""
args = {"id":self.id}
result = _send(self.api, path="/subscriptions", post=args, method="delete")
# fixme, better solution?
if not result: return None
def toggle_status(self):
"""
Toggles the activity status of a subscription item. You may also
change this value by editing the subscription item. This is just a
shortcut we use.
Example:
>>> print subsitem.paused # print True
>>> subsitem.toggle_status()
>>> print subsitem.paused # print False
"""
args = {"id":self.id}
result = _send(self.api, path="/subscriptions", post=args, method="pause")
if result:
self.paused = result[0]['paused']
return Subscription(self.api, result[0])
else:
return None
def update_info(self):
"""
Refreshes the subscription info. Use this to get the latest info
about the subscriptions.
Example:
>>> subs.update_info()
or
>>> subs = subs.update_info
"""
args = {"id":self.id}
result = _send(self.api, path="/subscriptions", post=args, method="info")
if result:
return Subscription(self.api, result[0])
else:
raise PutioError("Subscription update failed.")
def add_do_filters(self, *arguments):
"""
Takes : An Array of strings
Returns: Updated Subscription object
Adds keyword(s) to "do fetch" filter
"""
args = self._modify_filter("add", *arguments)
result = _send(self.api, path="/subscriptions", post=args, method="edit")
if result:
return Subscription(self.api, result[0])
else:
return False
def add_dont_filters(self, *arguments):
"""
Takes : An Array of strings
Returns: Updated Subscription object
Adds keyword(s) to "don't fetch" filter
"""
args = self._modify_filter("add", *arguments)
result = _send(self.api, path="/subscriptions", post=args, method="edit")
if result:
return Subscription(self.api, result[0])
else:
return False
def del_do_filters(self, *arguments):
"""
Takes : An Array of strings
Returns: Updated Subscription object
Deletes keyword(s) from "do fetch" filter
"""
args = self._modify_filter("remove", *arguments)
result = _send(self.api, path="/subscriptions", post=args, method="edit")
if result:
return Subscription(self.api, result[0])
else:
return False
def del_dont_filters(self, *arguments):
"""
Takes : An Array of strings
Returns: Updated Subscription object
Deletes keyword(s) from "dont fetch" filter
"""
args = self._modify_filter("remove", *arguments)
result = _send(self.api, path="/subscriptions", post=args, method="edit")
if result:
return Subscription(self.api, result[0])
else:
return False
def _modify_filter(self, task, *arguments):
if self.do_filters is None: self.do_filters = ""
if self.dont_filters is None: self.dont_filters = ""
if task == "remove":
self.do_filters = self._remove_filter(self.do_filters, *arguments)
self.dont_filters = self._remove_filter(self.dont_filters, *arguments)
else:
self.do_filters = self._add_filter(self.do_filters, *arguments)
self.dont_filters = self._add_filter(self.dont_filters, *arguments)
args = {
"id":self.id,
"title":self.name,
"url":self.url,
"do_filters":self.do_filters,
"dont_filters":self.dont_filters
}
return args
@staticmethod
def _add_filter(filt, *arguments):
filters = list(filt.split(','))
for a in arguments:filters.append(a)
for n in range(len(filters)): filters[n] = str(filters[n]).strip()
filters_str = ",".join(filters)
return filters_str
@staticmethod
def _remove_filter(filt, *arguments):
filters = list(filt.split(','))
for a in arguments:filters.append(a)
for n in range(len(filters)): filters[n] = str(filters[n]).strip()
filters_str = ",".join(filters)
return filters_str
class Transfer(BaseObj):
"""
Transfer Methods:
instance.destroy_transfer()
Transfer Attributes:
instance.id
instance.name
instance.status
instance.percent_done
human_size : 200.0M
name : The.Messenger.DVDRip.XviD-AMIABLE.part1.rar
url : http://rapidshare.com/files/3232/abc.part1.rar'
needs_pass : 0,
source : rapidshare.com',
paid_bw : 209715200',
error : None,
type : file',
size : 209715200'
Samples:
instance.status = 'Completed'
instance.percent_done = '100'
instance.id = '45'
instance.name = 'A video file.avi'
instance.status : 'Waiting'
instance.percent_done : '0'
instance.id : '47'
instance.name : 'abcde.mp4'
"""
def __init__(self, api, dictionary=None, **args):
BaseObj.__init__(self, dictionary, **args)
self.api = api
def destroy_transfer(self):
"""
Destroys an active transfer irreversibly.
Example:
>>> instance.destroy_transfer()
"""
args = {"id":self.id}
result = _send(self.api, path="/transfers", post=args, method="cancel")
if result: return True
else: return None
def send_password(self):
"""TODO"""
pass
class UrlBucket(object):
"""
Url bucket is a completion of urls ready to fetch.
UrlBucket Methods:
bucket.add()
bucket.analyze_and_add_urls()
bucket.get_report()
bucket.fetch()
Static Methods:
extract_urls()
crawl_webpage()
Abilities:
* Add urls to the bucket
* Get report of the bucket if you need to.
* Fetch the urls
You can also:
* Analyze urls and add
* Crawl a web page and extract URLs
* Extract URLs from a text block
"""
def __init__(self, api, singleurl=[], torrenturl=[], multiparturl=[], **info):
self.api = api
self.report = {}
self.last_analyzed_bw_avail = None
self.last_analyzed_disk_avail = None
self.req_space = None
self.paid_bw = None
self.links = {"multiparturl":[], "torrenturl":[], "singleurl":[], "error":[]}
self._add(singleurl=singleurl, torrenturl=torrenturl, multiparturl=multiparturl)
def _add(self, singleurl=[], torrenturl=[], multiparturl=[], error=[], **info):
"""
Internal method. Use add() instead, or better yet use analyze().
"""
for v in [singleurl, torrenturl, multiparturl, error]:
if not isinstance(v, list):
raise PutioError("Add method takes only arrays.")
if len(multiparturl) > 0:
for m in multiparturl:
self.links['multiparturl'].append(m)
if len(torrenturl) > 0:
for i in torrenturl:
self.links['torrenturl'].append(i)
if len(singleurl) > 0:
for i in singleurl:
self.links['singleurl'].append(i)
if len(error) > 0:
for i in error:
self.links['error'].append(i)
if len(info.keys()) > 0:
self.last_analyzed_bw_avail = info["last_analyzed_bw_avail"]
self.last_analyzed_disk_avail = info["last_analyzed_disk_avail"]
self.req_space = info["req_space"]
self.paid_bw = info["paid_bw"]
return self
def add(self, url):
"""
Takes: String or array
Returns: Dictionary of bucket items
Adds url(s) to the bucket to analyze or fetch. We recommend using
analyze_and_add_urls() method.
"""
if url and isinstance(url, str):
arg = {"url":url}
self.links['singleurl'].append(Url(self.api, arg))
elif url and isinstance(url, list):
for u in url:
arg = {"url":url}
self.links['singleurl'].append(Url(self.api, arg))
else:
raise PutioError("Add method takes a string or a list")
return self.links
def get_report(self):
"""
Returns the report of your bucket's last analyzation. Each UrlBucket
has its own report. After updating a bucket, remember to check its
new report.
Analyzed urls return like this one:
{
'dl_handler': 1,
'name': 'Itemname.ext',
'file_type': 1,
'error': None,
'url': 'http://torrent.a.b/file.torrent',
'paid_bw': 0,
'file_size': 244091464,
'type_name': 'file',
'dltype': 2, #fixme whats this?
'human_size': '232.78M'
}
"""
return {"Current Available Disk Space": self.last_analyzed_disk_avail,
"Current Available Bandwidth": self.last_analyzed_bw_avail,
"Required Space": self.req_space,
"Bandwidth to be deducted from quota": self.paid_bw,
"Urls":self.links}
def fetch(self):
"""
Takes : A bucket instance
Returns: Array of transfers. (All the active transfers, to be exact.)
Initiates fetching all the links of the given URL Bucket instance.
Returns newly added transfers. Erroneous transfers will have the word
"Error" in "status".
Also you may edit below to raise exceptions, if result.error is not
false.
"""
go_fetch = []
for k in self.links.keys():
for i in self.links[k]:
if k != "error": go_fetch.append(i.url)
self.links = {}
args = {"links":go_fetch}
result = _send(self.api, path="/transfers", post=args, method="add")
transfers = []
if result:
for r in result:
transfers.append(Transfer(self.api, r))
return transfers
else:
return None
def analyze(self, links=None):
"""
Takes : An Array of URLs.
Returns: An Array of Link objects.
Example:
Link objects can be fetched one by one by iterating the array.
>>> links = bucket.analyze(array)
>>> for l in links: l.fetch()
or
The whole bucket can be fetched with a single request.
>>> bucket.analyze(array)
>>> mytransfers = bucket.fetch()
"""
multipart_urls = []
single_urls = []
torrent_urls = []
error_urls = []
paid_bw = 0
req_space = 0
#args = {"links":urllib.quote(text)}
if links and isinstance(links, list):
args = {"links":links}
elif links and isinstance(links, str):
raise PutioError("Analyze method takes a list. Use " + \
"extract_urls() to convert string of urls to a list.")
else:
go_analyze = []
for k in self.links.keys():
for i in self.links[k]:
if k != "error": go_analyze.append(i.url)
args = {"links":go_analyze}
result = _send(self.api, path="/urls", post=args, method="analyze")
if result:
if len(result['items']['multiparturl']) > 0:
for r in result['items']['multiparturl']:
# unicode to int
paid_bw += int(r['paid_bw'])
req_space += int(r['size'])
for p in r["parts"]:
multipart_urls.append(Multipart(self.api, p))
if len(result['items']['torrent']) > 0:
for r in result['items']['torrent']:
torrent_urls.append(Torrent(self.api, r))
paid_bw += int(r['paid_bw'])
req_space += int(r['size'])
if len(result['items']['singleurl']) > 0:
for r in result['items']['singleurl']:
single_urls.append(Url(self.api, r))
paid_bw += int(r['paid_bw'])
req_space += int(r['size'])
if len(result['items']['error']) > 0:
for r in result['items']['error']:
error_urls.append(Url(self.api, r))
self.links = {"multiparturl":[], "torrenturl":[],
"singleurl":[], "error":[]}
self._add(multiparturl=multipart_urls,
singleurl=single_urls,
torrenturl=torrent_urls,
error=error_urls,
last_analyzed_disk_avail=result['disk_avail'],
last_analyzed_bw_avail=result['bw_avail'],
paid_bw=paid_bw,
req_space=req_space
)
return self.get_report()
else:
return None
def crawl_webpage(self, url):
"""
Takes : A String of a web page URL
Returns: A String of cleaned url list
Example:
>>> newbucket = api.create_bucket()
>>> cleaned_urls = newbucket.crawl_webpage("http://a.b.c/downloads")
"""
return self.extract_urls(url)
def extract_urls(self, text):
"""
Takes : A String
Returns: A list of cleaned urls
Example:
>>> txt = "Check these out: http://a.b/c.torrent and ftp://a.b/c.rar"
>>> urls = bucket.extract_urls(txt)
>>> print urls
["http://a.b/c.torrent", "ftp://a.b/c.rar"]
Extracts URLs from a block of text.
* Links in the text are recognized by the protocol names such as http,
ftp, etc.
* Torrent file links do have to have .torrent extention.
"""
extracted_urls = []
args = {"txt":text}
result = _send(self.api, path="/urls", post=args, method="extracturls")
if result:
for r in result: extracted_urls.append(r['url'])
#return " \n".join(extracted_urls)
return extracted_urls
else:
return []
class Url(BaseObj):
"""
For us, Url is a downloadable file link. These files can be any type.
Sources can be ftp, http, etc.
Url Attributes:
instance.dl_handler = 'Single Url'
instance.name = 'name_of_the_file.mp4'
instance.file_type = 'file'
instance.error = None
instance.url = 'ftp://a.b.c/name_of_the_file.mp4'
instance.paid_bw = 0
instance.file_size = '92014'
instance.type_name = 'file'
instance.dltype = 3
instance.human_size = '89.86K'
"""
def __init__(self, api, dictionary=None, **args):
BaseObj.__init__(self, dictionary, **args)
self.api = api
class Error(BaseObj):
"""
SingleRapid is a Rapidshare url, which is generally an archive file. If
the downloaded file have a multiple volume, it's a Multipart object.
Url Attributes:
instance.dl_handler = 'Rapid'
instance.name = 'ABCDE.rar'
instance.file_type = 'file'
instance.error = None
instance.url = 'http://rapidshare.com/files/abcde.rar'
instance.paid_bw = '104961263'
instance.file_size = '104961263'
instance.type_name = 'file'
instance.dltype = 1
instance.human_size = '100.10M'
"""
def __init__(self, api, dictionary=None, **args):
BaseObj.__init__(self, dictionary, **args)
self.api = api
class Torrent(BaseObj):
"""
Torrent objects are fetched via our Torrent clients. It can contain
single, multi part archive files, or any other file type. Send the
torrent URL, we figure out the rest.
Torrent Attributes:
instance.dl_handler = 'Torrent'
instance.name = 'ABCDE.avi'
instance.file_type = 'file'
instance.file_size = 244091464
instance.url = 'http://a.b/c.torrent'
instance.paid_bw = 0
instance.error = None
instance.type_name = 'file'
instance.dltype = 2
instance.human_size = '232.78M'
"""
def __init__(self, api, dictionary=None, url=None, **args):
BaseObj.__init__(self, dictionary, **args)
self.api = api
class Multipart(BaseObj):
"""
Multipart objects are files, which contains patterns like "part1",
"001", etc. These files are automatically extracted and saved to your
space.
Multipart Attributes:
instance.name = 'ABCDE'
instance.size = 366500388
instance.human_size = 350.0M
instance.paid_bw = 366500388
instance.parts = [
{
"url":"http:\/\/rapidshare.com\/files\/1\/M.part3.rar",
"size":"47711664",
"paid_bw":"47711664",
"source":"rapidshare.com",
"name":"Mdb35.part3.rar",
"human_size":"45.5M",
"type":"file",
"needs_pass":0,
"error":null
},
{
"url":"http:\/\/rapidshare.com\/files\/2\/M.part1.rar",
"size":"55000000",
"paid_bw":"55000000",
"source":"rapidshare.com",
"name":"Mdb35.part1.rar",
"human_size":"52.5M",
"type":"file",
"needs_pass":0,
"error":null
}
]
instance.error = None
"""
def __init__(self, api, dictionary=None, **args):
BaseObj.__init__(self, dictionary, **args)
self.api = api
if __name__ == '__main__':
print "This file should not be executed."