trans-api 0.0.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    OWZiMWExZjAyYjVmNDFiZDY1NTFiMzdlMDM1OGQyNGZkZjQyNTdmYQ==
+  data.tar.gz: !binary |-
+    YmIyZjRkNTM3MWQ3Y2U1MDNjZTQ5Y2I5NWQ0ZTBkZDAyMDk0NjE5Yg==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    MmRkYTc1ODczMDFlYzJiMGY1ODBlYTk1NjI1MzUwMmRlMGJmNmY5MDQwMzM1
+    ZDI3ZGEwYzg5MjgzMTVlZWQxYWUzNTQ0ZmZjNzg3N2MwOTE1MzE3NTQ0YTA4
+    MzU3NzQ2ZGE1YzQ0ZTkzNDM4NjYzZjk3YWZjY2FiZGIxNWVkZTg=
+  data.tar.gz: !binary |-
+    OTJhZTgyZTIwZjBkZGEzZjBkNjc0NzRmYzAzYmEyMWE2ZTQxY2JiMjVjN2Ex
+    OTk1NjRkMzY1YmFiZjJiNmJlMmJmODRiNGVjMmVhZDNmZTg5ODk2ZGEyOTg1
+    ZjE3N2ZlMzRmNDgxM2QwZGRiN2ZiZWNiNzllZGVjMmIwZGM1NDM=

data/.gitignore

@@ -0,0 +1,19 @@
+*.rbc
+*.sassc
+*.swp
+*.DS_Store
+.sass-cache
+capybara-*.html
+.rspec
+/.bundle
+/vendor/bundle
+/log/*
+/tmp/*
+/db/*.sqlite3
+/public/system/*
+/coverage/
+/spec/tmp/*
+**.orig
+rerun.txt
+pickle-email-*.html
+/pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in trans-api.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,20 @@
+PATH
+  remote: .
+  specs:
+    trans-api (0.0.1)
+      json
+      nokogiri
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    json (1.7.5)
+    nokogiri (1.5.5)
+    test-unit (2.5.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  test-unit
+  trans-api!

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Dennis Blommesteijn
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,334 @@
+# Trans::Api
+
+Trans::Api is an ruby implementation for Transmission RPC. Based on RPC spec 13328
+https://trac.transmissionbt.com/browser/trunk/extras/rpc-spec.txt
+
+It required for the Transmission RPC to run the 'remote access':
+
+OSX:
+
+  Transmission > Preferences > Remote (tab) > Enable remote access
+
+
+### Platforms
+
+This gem is (build and) tested with:
+
+  OSX Lion, Mountain Lion
+
+  Ruby 1.9.3
+
+  Rails: 3.2.8, 3.2.9
+
+  Transmission 2.73 (13589)
+
+
+### Roadmap
+
+* Version (0.0.1) (current)
+
+  Initial project import.
+
+* Version (0.0.2)
+
+  Session object include: 'blocklist', 'port-test'
+
+  Torrent object include 'torrent-start-now', 'queue-move-top/up/down/bottom'
+
+  Torrent object 'delete_all!' explicit torrent references
+
+  Torrent object 'waitfor' helper to check for lambda after/before calling it's chained cousin
+
+
+### Known Issues
+
+The Transmission RPC call 'torrent-remove' (implemented as torrent.delete! and Torrent::delete_all!) will crash the daemon! This is NOT a known Transmission issue.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'trans-api', git: "git://github.com/dblommesteijn/trans-api.git"
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install trans-api
+
+
+## Setup
+
+Define a configuration for your connection (initialize script)
+
+```ruby
+CONFIG = { host: "localhost", port: 9091, user: "admin", pass: "admin", path: "/transmission/rpc" }
+```
+
+Setup default configuration (initialize script)
+
+```ruby
+Trans::Api::Client.config = CONFIG
+```
+
+Define default torrent fields (bulk requests)
+NOTE: connection is slow when running many torrents with a large amount of fields (transmission rpc issue).
+On requesting an additional info field from the torrent object, a new call is made to the RPC (and stored
+withing the object).
+
+```ruby
+Trans::Api::Torrent.default_fields = [ :id, :status, :name ]
+```
+
+Example
+
+```ruby
+Trans::Api::Torrent.default_fields = [ :id, :status, :name ]
+# loads the torrent object of id 1 with fields: :id, :status, :name
+id = 1
+torrent = Trans::Api::Torrent.find id
+# calls the rpc to receive files from the defined torrent
+torrent.files
+```
+
+## Examples
+
+  Check the examples/ folder or Unit tests: test/unit/trans_ (session/torrent) _object.rb
+
+
+## Usage
+
+Trans api can be used in two ways:
+
+
+1. Connect (raw class)
+
+```ruby
+tc = Trans::Api::Connect.new CONFIG
+torrents = tc.torrent_get([:id, :name, :status])
+```
+
+2. Mapped objects (torrent, file, session classes)
+
+	examples below.
+
+
+### Requesting Torrent Info
+
+Get all registered torrents
+
+```ruby
+Trans::Api::Torrent.all
+```
+
+Get a specific torrent by transmission id
+NOTE: transmission assigns random ids to torrents on daemon start
+
+```ruby
+id = 1
+Trans::Api::Torrent.find id
+```
+
+### Torrent static calls
+
+Start all (start all transfers)
+
+```ruby
+Trans::Api::Torrent.start_all
+```
+
+Stop all (stop all transfers)
+
+```ruby
+Trans::Api::Torrent.stop_all
+```
+
+Delete all (tranmission daemon will crash on rapid call)
+
+```ruby
+torrents = Trans::Api::Torrent.all
+# assign explicit torrent objects for removal
+Trans::Api::Torrent.delete_all torrents
+```
+
+Add torrent file
+
+```ruby
+options = {paused: true}
+Trans::Api::Torrent.add_file filename, options
+```
+
+Get all fields
+```ruby
+Trans::Api::Torrent.ACCESSOR_FIELDS
+```
+
+Get all Mutable fields
+```ruby
+Trans::Api::Torrent.MUTATOR_FIELDS
+```
+
+
+### Torrent instance actions
+
+Get a torrent object
+
+```ruby
+id = 1
+torrent = Trans::Api::Torrent.find id
+```
+
+Save (store changed values)
+
+```ruby
+torrent.save!
+```
+
+Start (activate torrent for transfer)
+
+```ruby
+torrent.start!
+```
+
+Start Now (not sure what's the difference to start!, it's a different API call)
+
+```ruby
+torrent.start_now!
+```
+
+Reset (reload all torrent fields, including later requested ones)
+
+```ruby
+torrent.reset!
+```
+
+Stop (stop torrent transfer)
+
+```ruby
+torrent.stop!
+```
+
+File Objects (returns a list of Trans::Api::File objects)
+
+```ruby
+torrent.files_objects
+```
+
+Status names (get the status name of the torrent)
+
+```ruby
+torrent.status_name
+```
+
+Verify (recheck downloaded files)
+
+```ruby
+torrent.verify!
+```
+
+Reannounce Torrent
+
+```ruby
+torrent.reannounce!
+```
+
+Delete (tranmission daemon will crash on rapid call)
+
+```ruby
+options = {delete_local_data: true}
+torrent.delete! options
+```
+
+Waitfor (automatic delayed responce after/before chained method is called)
+
+  Blocking busy waiting for lambda to return true
+
+```ruby
+# waitfor status name not equals stopped after calling start!
+optional = :after
+torrent.waitfor( lambda{|t| t.status_name != :stopped}, optional ).start!
+# waitfor status name equals stopped after calling stop!
+torrent.waitfor( lambda{|t| t.status_name == :stopped}, optional ).stop!
+# NOTE: waitfor can be used for blocking without a chained method (optional = :before only)
+```
+
+NOTE: defined torrent accessor fields are defined as instance methods to the Torrent object
+
+
+### Session Info
+
+Get session object (singleton)
+
+```ruby
+session = Trans::Api::Session.instance
+```
+
+Get available fields (returns symbols of get/set fields)
+
+```ruby
+session.fields
+```
+
+Get all fields and values
+
+```ruby
+session.fields_and_values
+```
+
+Reset (reload object, request information and not saving changes)
+
+```ruby
+session.reset!
+```
+
+NOTE: defined session fields are defined as instance methods to the Session object
+
+
+### File Info
+
+Getting files from a torrent (file cannot be used standalone, it's an helper class)
+
+```ruby
+id = 1
+torrent = Trans::Api::Torrent.find id
+files = torrent.files_objects
+files.each do |file|
+	# manipulate file here!
+end
+```
+
+File name
+
+```ruby
+file.name
+```
+
+File mark unwant (mark for ignore, not download)
+
+```ruby
+file.unwant
+```
+
+File mark want (mark for download)
+
+```ruby
+file.want
+```
+
+File wanted? (marked for download)
+
+```ruby
+file.wanted?
+```
+
+File stats
+
+```ruby
+file.stat
+```
+
+NOTE: changed preferences (want, unwant) set options on the linked Torrent object, after saving torrent (torrent.save!) file mutations are stored.
+

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/examples/basic_setup.rb

@@ -0,0 +1,78 @@
+#!/usr/bin/env ruby
+
+# setup
+require 'rubygems'
+require "bundler/setup"
+require 'trans-api'
+
+
+class BasicSetup
+
+  include Trans::Api
+
+  CONFIG = { host: "localhost", port: 9091, user: "admin", pass: "admin", path: "/transmission/rpc" }
+  FIELDS = [ :id, :status, :name ]
+
+  def initialize
+
+    # connection information (rpc location)
+    Client.config = CONFIG
+
+    # default loading torrent fields
+    Torrent.default_fields = FIELDS
+
+    #TODO: add a section for session here!!
+
+  end
+
+
+  def add_torrent
+
+    # selecting a file to add (debian demo file)
+    file = ::File.expand_path(::File.dirname(__FILE__) + "/torrents/debian-6.0.6-amd64-CD-10.iso.torrent")
+
+    # adding a torrent using static call on Torrent object (paused transfer)
+    @torrent = Torrent.add_file file, paused: true
+    # return variable is an instance of the torrent file
+    # an exception can be raised on invalid request
+
+    # NOTE: we will store it for later use (removing this torrent, not the whole list)
+
+  end
+
+  def remove_torrent
+
+    #TODO: remove torrent here!
+
+  end
+
+  def iterating_torrents
+
+    torrents = Torrent.all
+
+    torrents.each do |torrent|
+
+      puts "#{torrent.name} -> #{torrent.status_name}"
+
+    end
+
+  end
+
+end
+
+
+
+# initiate BasicSetup object, and run its methods
+begin
+
+  bs = BasicSetup.new
+  bs.add_torrent
+  bs.iterating_torrents
+
+rescue Exception => e
+  puts e
+end
+
+
+
+

data/lib/trans-api/client.rb

@@ -0,0 +1,30 @@
+module Trans
+  module Api
+
+    class Client
+      DEFAULT = {scheme: "http", host: "localhost", port: 9091, path: "/transmission/rpc", user: "admin", pass: "admin"}
+
+      # construct
+
+      def initialize(options={})
+        args = @@config
+        args.merge!(options)
+        @conn = Connect.new args
+      end
+
+      def connect
+        @conn
+      end
+
+      class << self
+        def config=(config = {})
+          @@config = config
+        end
+      end
+
+
+    end
+
+
+  end
+end