tweep 0.1.0

data/CHANGELOG.markdown

@@ -0,0 +1,3 @@
+= 0.1.0 =
+
+* 2011-12-11 - Initial version

data/MIT-LICENSE.txt

@@ -0,0 +1,16 @@
+Copyright (c) 2011 Christophe Porteneuve
+
+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 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.markdown

@@ -0,0 +1,129 @@
+Tweep - Automatic Twitter Peeping.  Lets you rotate through tweets in a scheduled manner, with multiple accounts, and auto-retweet such tweets on other accounts yet.  For instance, think recent accounts for product launches versus their more established company accounts.
+
+# Installing
+
+Tweep is in Ruby, so you need Ruby and RubyGems installed.  It’s probably already there on your OSX or Linux box, and on Windows you can use the nifty [Ruby Installer](http://rubyinstaller.org/downloads/).  Then just install the gem to get the `tweep` command:
+
+```
+$ gem install tweep
+```
+
+# Configuring your accounts
+
+Accounts are detected by inspecting YAML files in the `accounts` subdirectory in the current working path.  The base name of the file can be anything, as the actual account is identified by the authentication information inside.
+
+To tweet on behalf of an account, Tweep needs this account’s **consumer key and secret**, along with **OAuth token and secret** for an app you setup on that account with Read/Write access (no DM access is necessary).
+
+## Creating custom applications for your accounts for Tweep to use
+
+Tweep is no central application that could prompt Twitter to authorize it, otherwise open-sourcing it with its OAuth tokens would be quite problematic: any user would be able to tweet as any other!
+
+You will need to create a custom app on your account for Tweep to use on your behalf. Here’s how:
+
+1. Sign in to [Twitter Developers](http://dev.twitter.com) using your regular Twitter account. This should get you to the "My Applications" screen.
+2. Click the "Create an app" link
+3. Give it a name (say, "Tweep").  This is the name that will show up as "the source" (the app you use to tweet) in your Tweep-sent tweets.
+4. description (anything) and website (your own perhaps).
+5. If you're brave and have some spare time, read the terms of use, cheekily renamed "Developer Rules of the Road."  Then check the "Yes, I agree" box.
+6. Type the CAPTCHA.  If it's unreadable, use the circular arrow icon on the right-hand side until you can manage it.
+7. Finally, click the "Create your Twitter application" button.
+
+OK, almost there.  Your app starts out as read-only: it won't let you *send tweets* to Twitter.  You're now on the app's screen.
+
+8. Click the Settings tab
+9. In Application Type, choose Read and Write
+10. At the bottom of the form, click "Update this Twitter application’s settings"
+11. Get back to the Details tab, and at the bottom, click "Create my access token"
+
+Yay, you’re done!  Click the OAuth tool tab and you’ll see the 4 pieces of authentication configuration you’ll need to put in your account’s YAML file.  Use the `your_account_1.yml` file as a template and copy-paste the 4 values in the proper places.  Make sure you keep the values wrapped in the quotes originally placed in the YAML file.
+
+## Why can't I just put in my login and password?
+
+First, because that's quite unsafe.  Your password is likely one you use in a number of other places;  having it lie around in some script somewhere isn't the best idea.
+
+Second, because login and password are primarily meant for direct human use.  A growing number of APIs do not allow them for program-based authentication, and Twitter's API is certainly headed that way.  So OAuth it is!  I realize this requires a bit of extra work on your part when setting up your access, but security and privacy are worth it.
+
+# Scheduling your tweets
+
+Your tweets are just a series of items in the `tweets` part of your YAML file.  Use one tweet per line, surrounded by double quotes (see examples in `your_account_1.yml`).  If you do need a double-quote in there, escape it by putting a backslash (`\`) before it, as you’ll see in the demo YAML file.
+
+Then your tweet schedule uses the `schedule` key.  You can provide one sub-key per day of the week, using their English lowercase name (e.g. `tuesday`).  Every such key lists hours of the day when to tweet.  These hours use the time zone of the machine you’ll run Tweep on.  You can use 24-hour or 12-hour format for times, and Tweep uses the hour and the (optional) minute part.  Seconds are overkill, so we don't want them.
+
+In 12-hour format, you can use 'am' or 'a', 'pm' or 'p' indifferently, using whatever case (upper or lower) you like best.  Also, stick to US format: `12am` is midnight, `12pm` is noon, and there is no such thing as `0am` or `0pm`…
+
+You can use multiple hours on the same day by separating hours with commas.
+
+If you want to schedule tweets on specific dates besides (or instead of) recurring weekdays, you can use specific dates as schedule keys, in the form `YYYY-MM-DD`, for instance `2011-12-25` for December 25, 2011.
+
+All this is nice and well, but the way you'll schedule the running of Tweep may end up launching it a few minutes late (perhaps because other, long tasks are run before it).  So you can allow a maximum delay for running Tweep, using the `allowed_delay` key in `schedule`, expressed in minutes.  For instance, setting `allowed_delay: 15` will let a task scheduled as `1p` be run until 01:15pm.
+
+# Controlling automatic retweets
+
+To define accounts that auto-retweet your tweets, you need two things:
+
+1. Setup these accounts in their own files, with at minimum their authentication info so Tweep can make them retweet stuff.
+2. List these accounts as retweeters in the "source" accounts’ YAML files.
+
+The listing part is done through the `retweeters` key, which contains one subkey per retweeter.  Subkeys are named **exactly** like the YAML files for these accounts (without the `.yml` extension).
+
+## Retweeting every tweet
+
+For an account to retweet *every single tweet* you write, you would use `always` as its definition.  For instance, to make `mygroupie` retweet everything your `me` account tweets through Tweep, you would need the following in your `me.yml` file:
+
+```yaml
+retweeters:
+  mygroupie: always
+```
+
+This can be a bit extreme, so you may want to have such accounts retweet only every other tweet, or one tweet in three, or one in four…  Just say so:
+
+```yaml
+retweeters:
+  mygroupie: every 3 tweets
+  mysupergroupe: every other tweet
+```
+
+We don't care about whether you actually say "tweet" or "tweets" at the end, and provide `other` as a nice-reading synonym for `2`.  Should you say "every one," it'll be treated as a synonym to
+"always".
+
+# Executing your tweeting campaign
+
+To run Tweep, just run the `tweep` command that is provided by the gem, in a directory that has the proper `accounts` subdirectory.
+
+In order to keep track of where it stands in rotating your accounts’ tweets and observing the
+"every so many tweets" policies, Tweep needs to be able to write to a `tweeping.idx` file in
+the directory it’s running at.
+
+You should then take steps to run the `tweep` command in the proper directory at regular intervals, frequently enough to honor your `schedule` settings.  Linux and OSX have Crontab for this, and Windows has Scheduled Tasks.
+
+## Logging
+
+By default, the `tweep` executable logs its activity (tweets and retweets) to the standard output.  You can redirect this manually to a file, forsake it to `/dev/null`, or ask it to log automatically to a `tweep.log` file in the current directory by using the `--log` command-line option.
+
+# Contributing
+
+Tweep intends to serve a rather simple need: doing basic Twitter campaigns and making sure
+your tweets get added visibility from retweets by more prominent accounts of yours until
+your originally-tweeting accounts get enough followers on their own.  It's more of a
+product- or service-launch thing, and for the relatively short term (a few months, perhaps
+up to a year?).
+
+If you have massively complex social media needs, you’re probably better off using an online
+service such as [SocialOomph](https://www.socialoomph.com/) or
+[CoTweet](http://cotweet.com/).
+
+Still, if you discover a bug, or feel you can improve the user experience in a way
+consistent with the initial design goals of Tweep, just fork the project on
+[Github](https://github.com/tdd/tweep), patch it, test it, and submit a pull request.
+I'll be happy to check these out and merge them in if I like them!
+
+## Tests
+
+I haven't written tests for this yet.  I sure intend to.  So stick around!  And of course, contributing tests is most welcome.  In order to reduce dependencies to a minimum, I will go with Test::Unit instead of fancier stuff like RSpec or Steak.
+
+# License
+
+Tweep is made available under the MIT license.  Check the [MIT-LICENSE.txt](MIT-LICENSE.txt)
+file in the soure code for details.  TL;DR: as long as you keep the license in there with
+due author and copyright info, you’re free to do whatever you want with Tweep, including
+commercial uses.  Just Don't Be Evil™.

data/accounts/your_account_1.yml

@@ -0,0 +1,31 @@
+# Auth -- this is the only required part
+consumer_key: ""
+consumer_secret: ""
+oauth_token: ""
+oauth_token_secret: ""
+
+# Schedule -- when to chomp through the tweets.txt file in the
+# same directory, tweet the top of the list, rotate and update
+# the file.  Optional if this is just a retweeter account.
+schedule:
+  monday: 1pm
+  thursday: 1pm
+  2011-12-25: 12am,12pm
+
+tweets:
+  - "Blah blah blah o'blah"
+  - "Bleh bleh bleh bleh bleh"
+  - "Blih blah o'blah blouh\" bleh bleh"
+
+# Retweets -- who retweets our tweets?  You can either provide
+# a single name as 'retweeter' or use the YAML array syntax inside
+# a "retweeters" key.  Tweep uses both if you do, "retweeter" being
+# considered set to 'always'.
+#
+# Optional if this is just a retweeter account, that doesn't tweet on
+# its own.
+retweeter: porteneuve
+
+retweeters:
+  porteneuve: always # Retweet every tweet.
+  rails: every 3 tweets

data/bin/tweep

@@ -0,0 +1,6 @@
+#! /usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path('../../lib', __FILE__))
+
+require 'tweep'
+Tweep.run!

data/lib/tweep.rb

@@ -0,0 +1,27 @@
+#! /usr/bin/env ruby
+# encoding: utf-8
+
+# Tweep - Automatic Twitter Peeping
+# Lets you rotate through tweets in a scheduled manner,
+# with multiple accounts, and auto-retweet such tweets on other accounts yet.
+#
+# (c) 2011 Christophe Porteneuve
+
+require 'tweep/account'
+require 'tweep/index'
+require 'tweep/logging'
+
+module Tweep
+  @@index = Index.new
+  
+  def self.run!
+    info 'Running…'
+    Account.each &:run!
+  ensure
+    @@index.save!
+  end
+
+  Dir['accounts/*.yml'].each do |defn|
+    Account.new(defn, @@index)
+  end
+end

data/lib/tweep/account.rb

@@ -0,0 +1,67 @@
+#! /usr/bin/env ruby
+# encoding: utf-8
+#
+# (c) 2011 Christophe Porteneuve
+
+require 'tweep/config'
+require 'rubygems'
+require 'twitter'
+
+module Tweep
+  class Account
+    @@registry = {}
+
+    def self.each(&block)
+      @@registry.values.each(&block)
+    end
+
+    def self.find(nick)
+      @@registry[nick]
+    end
+  
+    def initialize(yml, index)
+      return unless load_config(yml, index)
+      @index = index
+      @@registry[@config.nick] = self
+    end
+  
+    def retweet!(status_id)
+      Tweep.info "#{@config.nick} retweets #{status_id.inspect}"
+      execute :retweet, status_id
+    end
+  
+    def run!
+      return unless @config.has_tweets? && @config.now_is_a_good_time?
+      tweet!
+    end
+  
+  private
+    def execute(call, *args)
+      Twitter.configure do |config|
+        @config.auth.each do |k, v|
+          config.send("#{k}=", v)
+        end
+      end
+      Twitter.send(call, *args)
+    end
+
+    def load_config(file, index)
+      return unless File.file?(file) && File.readable_real?(file)
+      @config = Config.new(file, index)
+      @config.has_auth?
+    end
+    
+    def tweet!
+      status, idx = @config.next_tweet
+      return if status.blank?
+      Tweep.info "#{@config.nick} tweets: #{status}"
+      st = execute(:update, status)
+      @index.tweeted! @config.nick, idx
+      @config.retweeters.each do |retweeter, _|
+        if @config.should_get_retweeted_by?(retweeter)
+          self.class.find(retweeter).try(:retweet!, st.id)
+        end
+      end
+    end
+  end
+end

data/lib/tweep/config.rb

@@ -0,0 +1,120 @@
+#! /usr/bin/env ruby
+# encoding: utf-8
+#
+# (c) 2011 Christophe Porteneuve
+
+require 'tweep/core_exts'
+
+module Tweep
+  class Config
+    attr_reader :auth, :nick, :schedule, :retweeters, :tweets
+    
+    def initialize(file, index)
+      config = YAML::load(File.read(file))
+
+      @nick = File.basename(file, '.*')
+      @index = index
+      
+      load_auth config
+      load_schedule config
+      load_retweeters config
+
+      @tweets = (config['tweets'] || []).map(&:strip)
+    end
+    
+    def has_auth?
+      4 == @auth.values.reject(&:blank?).size
+    end
+    
+    def has_tweets?
+      @tweets.any?
+    end
+
+    def next_tweet
+      idx = @index.next_tweet_index(@nick)
+      idx = 0 if idx.to_i >= @tweets.size
+      [@tweets[idx], idx]
+    end
+
+    def now_is_a_good_time?
+      now = Time.now
+      (0..@allowed_delay.to_i).any? do |offset|
+        time = now - offset * 60
+        (@schedule[time.wday] || []).include?(time.strftime('%H:%M'))
+      end
+    end
+  
+    def should_get_retweeted_by?(retweeter)
+      if (result = @index.retweet_timely?(@nick, retweeter))
+        @index.next_retweet_in! @nick, retweeter, @retweeters[retweeter]
+      else
+        @index.retweet_will_wait! @nick, retweeter
+      end
+      result
+    end
+  
+  private
+    DOWS = %w(sunday monday tuesday wednesday thursday friday saturday)
+
+    TIME_REGEX = %r(
+      (?:
+      # 12-hour format - groups 1 and 2
+      ((?:0?[1-9]|1[012])(?::[0-5][0-9])?)
+      ([ap]m?)
+      |
+      # 24-hour format - group 3
+      ((?:[01]?[0-9]|2[0-3])(?:[0-5][0-9]?))
+      )
+    )ix
+    
+    def load_auth(config)
+      @auth = config.slice('consumer_key', 'consumer_secret', 'oauth_token', 'oauth_token_secret')
+    end
+    
+    def load_retweeters(config)
+      @retweeters = {}
+      if (shortcut = config['retweeter'])
+        @retweeters[shortcut.to_s] = 0
+      end
+      (config['retweeters'] || {}).each do |nick, pattern|
+        wait = 0
+        if pattern[/^\s*every\s+(\d+|other)(?:\s+tweets?)\s*$/i]
+          wait = 'other' == $1 ? 1 : [$1.to_i - 1, 0].max
+        end
+        @retweeters[nick] = wait
+      end
+    end
+
+    def load_schedule(config)
+      @schedule = (config['schedule'] || {}).inject({}) do |acc, (dow, hours)|
+        key = DOWS.index(dow.to_s.downcase)
+        if !key && dow.to_s[/^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$/]
+          key = Date.civil($1.to_i, $2.to_i, $3.to_i) rescue nil
+        end
+        if !key && 'allowed_delay' == dow
+          @allowed_delay = hours.to_i
+        elsif key
+          hours = hours.split(',').map(&:strip).reject(&:empty?)
+          hours = hours.map { |hour| self.class.read_hour(hour) }.compact
+          acc[key] = hours if hours
+        end
+        acc
+      end
+      
+    end
+
+    def self.read_hour(hour)
+      return unless hour =~ TIME_REGEX
+      h, m = if $1 && $2
+        h, m = $1.split(':').map(&:to_i)
+        h = 0 if 12 == h
+        h += 12 if 'P' == $2.upcase[0, 1]
+        [h, m]
+      else
+        $3.split(':').map(&:to_i)
+      end
+      m ||= 0
+      "%02d:%02d" % [h, m]
+    end
+  end
+end

data/lib/tweep/core_exts.rb

@@ -0,0 +1,48 @@
+#! /usr/bin/env ruby
+# encoding: utf-8
+
+# Tweep - Automatic Twitter Peeping
+# Lets me rotate through tweets in a scheduled manner,
+# with multiple accounts, and auto-retweet such tweets on other accounts yet.
+#
+# (c) 2011 Christophe Porteneuve
+
+class Hash
+  # :nodoc:
+  # Inspired by ActiveSupport
+  def slice(*keys)
+    inject({}) do |acc, (k, v)|
+      acc[k] = v if keys.include?(k)
+      acc
+    end
+  end
+end
+
+class Object
+  alias_method :try, :__send__
+end
+
+class NilClass
+  # :nodoc:
+  # Inspired by ActiveSupport
+  def blank?; true; end
+  
+  def try(*args); nil; end
+end
+
+class String
+  # :nodoc:
+  # Inspired by ActiveSupport
+  def blank?
+    strip.empty?
+  end
+end
+
+class Symbol
+  # :nodoc:
+  # For Ruby 1.8 compat, inspired by ActiveSupport
+  def to_proc
+    lambda { |o| o.send(self) }
+  end
+end
+

data/lib/tweep/index.rb

@@ -0,0 +1,42 @@
+#! /usr/bin/env ruby
+# encoding: utf-8
+#
+# (c) 2011 Christophe Porteneuve
+
+module Tweep
+  class Index
+    FILE_NAME = 'tweeping.idx'
+    
+    def initialize
+      @states = {}
+      @states = YAML::load(File.read(FILE_NAME)) if File.exists?(FILE_NAME)
+    end
+    
+    def next_retweet_in!(nick, retweeter, wait)
+      ((@states[nick] ||= {})[:waits] ||= {})[retweeter] = wait
+    end
+    
+    def next_tweet_index(nick)
+      (@states[nick] ||= {})[:next].to_i
+    end
+    
+    def retweet_timely?(nick, retweeter)
+      ((@states[nick] ||= {})[:waits] ||= {})[retweeter].to_i.zero?
+    end
+    
+    def retweet_will_wait!(nick, retweeter)
+      wait = ((@states[nick] ||= {})[:waits] ||= {})[retweeter].to_i
+      @states[nick][:waits][retweeter] = [wait - 1, 0].max
+    end
+    
+    def save!
+      File.open(FILE_NAME, 'w') { |f| f.write(YAML::dump(@states)) }
+    rescue Exception => e
+      Tweep.error "Could not save index to #{FILE_NAME} (#{e.class.name}: #{e.message})"
+    end
+    
+    def tweeted!(nick, idx)
+      (@states[nick] ||= {})[:next] = idx + 1
+    end
+  end
+end

data/lib/tweep/logging.rb

@@ -0,0 +1,33 @@
+#! /usr/bin/env ruby
+# encoding: utf-8
+
+# Tweep - Automatic Twitter Peeping
+# Lets me rotate through tweets in a scheduled manner,
+# with multiple accounts, and auto-retweet such tweets on other accounts yet.
+#
+# (c) 2011 Christophe Porteneuve
+
+require 'logger'
+
+module Tweep
+  %w(error warn info).each do |level|
+    module_eval <<-EOC
+      def self.#{level}(*args)
+        logger.#{level}(*args)
+      end
+    EOC
+  end
+  
+  def self.logger
+    return @logger if @logger
+    @logger = ARGV.include?('--log') ?
+      Logger.new('tweep.log', 5, 1_024 ** 2) :
+      Logger.new(STDOUT)
+    @logger.formatter = proc { |sev, datetime, progname, msg|
+      "[Tweep #{datetime} #{sev.to_s.upcase}] #{msg}\n"
+    }
+    @logger
+  end
+  
+  private_class_method :logger
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification 
+name: tweep
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Christophe Porteneuve
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-12-13 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: twitter
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 2.0.2
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: twitter
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 2.0.2
+  type: :runtime
+  version_requirements: *id002
+description: Tweep lets you rotate through tweets in a scheduled manner, with multiple accounts, and auto-retweet such tweets on other accounts yet.  For instance, think recent accounts for product launches versus their more established company accounts.
+email: tdd@tddsworld.com
+executables: 
+- tweep
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/tweep/account.rb
+- lib/tweep/config.rb
+- lib/tweep/core_exts.rb
+- lib/tweep/index.rb
+- lib/tweep/logging.rb
+- lib/tweep.rb
+- MIT-LICENSE.txt
+- CHANGELOG.markdown
+- README.markdown
+- accounts/your_account_1.yml
+- bin/tweep
+homepage: http://github.com/tdd/tweep
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Automatic Twitter Peeping
+test_files: []
+