cta_redux 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 69b3ea9908066bc8bdbf52865df0885b2c7bc5a3
-  data.tar.gz: 60ec4638cb25ad8a65e1282252bc630972c9fa8f
+  metadata.gz: 9e3939dcf2d580a8ef7487ea5f9ef1a3b1464737
+  data.tar.gz: d148cd49ce17813bec6bed9b33fd3a0f4fe9393f
 SHA512:
-  metadata.gz: f77382a34fb99fce097142a98c22c3bed8a25992e31279ea18887c3a0398c97346717138019486d5cfdebbefe67a0f3173a517383d8021d516faa8366e8efcbd
-  data.tar.gz: 513d7dca04757788ebc544f1437b852094f9ab1e13c1331380395cc7a369c5d82f97022879052fbfb4bcd6842433fe6c8d15f57e1a66d49597fde5cfd2085200
+  metadata.gz: 1633690c5355c45aa87daafaf17fa261f25d495bd6b022b09394e9e067e5071c00e4b1293405ab015c9d88488b3ff1d272821c10a337bedd6f3ac2cc06742454
+  data.tar.gz: 82df0c408f08a8c45def1be764730302620a9bfd70309d8ba4cd12617e72926c34b6f5b494a050639d25afa1d4aac739af078dd9c55ce3872de640df725f7437

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.5
+  - 2.2.0
+script: bundle exec rspec spec

data/README.md

@@ -1,16 +1,40 @@
 # cta_redux
 
-# Reloading CTA GTFS data
+[![Build Status](https://travis-ci.org/ahayworth/cta_redux.svg?branch=master)](https://travis-ci.org/ahayworth/cta_redux)
 
-Note that this will take a long time - there are several million stop_time records.
+The CTA (http://www.transitchicago.com) provides a wealth of information for developers, but it's hard to access, inconsistent, and there are no official clients. CTA Redux is an easy to use, comprehensive client for that data.
 
-1. cd data && curl 'http://www.transitchicago.com/downloads/sch_data/<latest file>' > gtfs.zip && unzip gtfs.zip
+This gem combines GTFS data with live API responses to create a consistent view of CTA vehicles and status.
 
-2. cd ../script && for i in `ls ../data/*.txt`; do echo $i; ./gtfs_to_sqlite.rb $i ../data/cta-gtfs.db; done
+Examples:
 
-3. rm ../data/*{txt,htm,zip}
+```ruby
+require 'cta_redux'
 
-4. cd ../data && gzip cta-gtfs.db
+CTA::TrainTracker.key = 'foo'
+CTA::BusTracker.key   = 'bar'
 
-5. Commit / push / create release and gem
+# Pick a random stop on the brown line
+stop = CTA::Route[:brown].stops.all.sample
 
+routes = []
+stop.predictions!.predictions.sort_by(&:seconds).each do |prd|
+  routes << prd.route.route_id
+  puts "A #{prd.direction} #{prd.route.route_long_name} " +
+    "train will be arriving at #{stop.stop_name} in #{prd.minutes} minutes."
+end
+
+# Pick a random stop on the 8-Halsted route
+stop = CTA::Route["8"].stops.all.sample
+stop.predictions!.predictions.sort_by(&:seconds).each do |prd|
+  routes << prd.route.route_id
+  puts "A(n) #{prd.route.route_id}-#{prd.route.route_long_name} will be " +
+    "arriving at #{stop.stop_name} in #{prd.minutes} minutes."
+end
+
+CTA::CustomerAlerts.alerts!(:routes => routes.uniq).alerts.each do |alert|
+  puts "Alert: #{alert.short_description}"
+end
+```
+
+More information is available at (http://www.rubydoc.info/gems/cta_redux/0.1.0)

data/cta_redux.gemspec

@@ -18,12 +18,18 @@ Gem::Specification.new do |spec|
 
   spec.files         = `git ls-files -z`.split("\x0")
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.extensions    = ["ext/inflate_database/extconf.rb"]
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
+  # TODO - Support 1.8.7, I doubt it'll be that difficult.
+  spec.required_ruby_version = ">= 1.9.3"
+
   spec.add_development_dependency "bundler", "~> 1.7"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.2.0"
+  spec.add_development_dependency "yard", ">= 0.8.7.6"
+
   spec.add_dependency "sequel", ">= 4.19.0"
   spec.add_dependency "sqlite3", ">= 1.3.10"
   spec.add_dependency "faraday", ">= 0.9.1"

data/ext/inflate_database/extconf.rb

@@ -0,0 +1,14 @@
+require 'mkmf'
+require 'zlib'
+data_dir = File.join(File.expand_path("../../..", __FILE__), 'data')
+db_filename = File.join(data_dir, 'cta-gtfs.db')
+if !File.exists?(db_filename)
+  dbf = File.open(db_filename, 'wb')
+  Zlib::GzipReader.open("#{db_filename}.gz") do |gz|
+    dbf.puts gz.read
+  end
+  dbf.close
+  File.unlink("#{db_filename}.gz")
+end
+
+create_makefile "inflate_database/inflate_database"

data/lib/cta_redux.rb

@@ -4,40 +4,60 @@ require "sqlite3"
 require "faraday"
 require "faraday_middleware"
 require "multi_xml"
-require "zlib"
 
 module CTA
   base_path = File.expand_path("..", __FILE__)
-  data_dir = File.join(File.expand_path("../..", __FILE__), 'data')
-  Dir.glob("#{base_path}/cta_redux/faraday_middleware/*") { |lib| require lib }
-  Dir.glob("#{base_path}/cta_redux/api/*") { |lib| require lib }
+
+  require "#{base_path}/cta_redux/faraday_middleware/bus_tracker_parser.rb"
+  require "#{base_path}/cta_redux/faraday_middleware/train_tracker_parser.rb"
+  require "#{base_path}/cta_redux/faraday_middleware/customer_alerts_parser.rb"
+  require "#{base_path}/cta_redux/faraday_middleware/simple_cache.rb"
+
+  require "#{base_path}/cta_redux/api/api_response.rb"
+  require "#{base_path}/cta_redux/api/bus_tracker.rb"
+  require "#{base_path}/cta_redux/api/train_tracker.rb"
+  require "#{base_path}/cta_redux/api/customer_alerts.rb"
+
   require "#{base_path}/cta_redux/train_tracker.rb"
   require "#{base_path}/cta_redux/bus_tracker.rb"
   require "#{base_path}/cta_redux/customer_alerts.rb"
+  require "#{base_path}/cta_redux/version.rb"
+
 
+  data_dir = File.join(File.expand_path("../..", __FILE__), 'data')
   db_filename = File.join(data_dir, 'cta-gtfs.db')
 
-  # First run
-  if !File.exists?(db_filename)
-    dbf = File.open(db_filename, 'wb')
-    Zlib::GzipReader.open("#{db_filename}.gz") do |gz|
-      dbf.puts gz.read
+  # travis-ci needs to manually unzip things
+  if ENV['TRAVIS'] == 'true'
+    if !File.exists?(db_filename)
+      dbf = File.open(db_filename, 'wb')
+      Zlib::GzipReader.open("#{db_filename}.gz") do |gz|
+        dbf.puts gz.read
+      end
+      dbf.close
+      File.unlink("#{db_filename}.gz")
     end
-    dbf.close
   end
-
   DB = Sequel.sqlite(:database => db_filename, :readonly => true)
 
-  Dir.glob("#{base_path}/cta_redux/models/*") do |lib|
-    next if lib =~ /train/ || lib =~ /bus/
-    require lib
-  end
+  require "#{base_path}/cta_redux/models/agency.rb"
+  require "#{base_path}/cta_redux/models/calendar.rb"
+  require "#{base_path}/cta_redux/models/route.rb"
+  require "#{base_path}/cta_redux/models/shape.rb"
+  require "#{base_path}/cta_redux/models/stop.rb"
+  require "#{base_path}/cta_redux/models/stop_time.rb"
+  require "#{base_path}/cta_redux/models/transfer.rb"
+  require "#{base_path}/cta_redux/models/trip.rb"
 
   require "#{base_path}/cta_redux/models/train.rb"
   require "#{base_path}/cta_redux/models/bus.rb"
+
 end
 
 class Array
+  # Encloses the object with an array, if it is not already
+  # @param object [Object] the object to enclose
+  # @return [Array<Object>] the object, enclosed in an array
   def self.wrap(object)
     if object.nil?
       []

data/lib/cta_redux/bus_tracker.rb

@@ -1,5 +1,6 @@
 module CTA
   class BusTracker
+    # Returns the connection object we use to talk to the BusTracker API
     def self.connection
       raise "You need to set a developer key first. Try CTA::BusTracker.key = 'foo'." unless @key
 
@@ -13,10 +14,22 @@ module CTA
       end
     end
 
+    # Returns the current time according to the BusTime servers that power the BusTracker API.
+    # @return [CTA::BusTracker::TimeResponse]
     def self.time!
       connection.get('gettime')
     end
 
+    # Returns status of vehicles out on the road.
+    # @param [Hash] options
+    # @option options [Array<String>, Array<Integer>, String, Integer] :vehicles A list or single vehicle IDs to query.
+    #   Not available with :routes.
+    # @option options [Array<String>, Array<Integer>, String, Integer] :routes A list or single route IDs to query.
+    #   Not available with :vehicles.
+    # @return [CTA::BusTracker::VehiclesResponse]
+    # @example
+    #   CTA::BusTracker.vehicles!(:routes => [22,36])
+    #   CTA::BusTracker.vehicles!(:vehicles => 4240)
     def self.vehicles!(options={})
       allowed_keys = [:vehicles, :routes]
       if options.keys.any? { |k| !allowed_keys.include?(k) }
@@ -36,10 +49,18 @@ module CTA
       connection.get('getvehicles', { :rt => routes, :vid => vehicles })
     end
 
+    # Returns a list of all routes the BusTracker API knows about - whether or not they are active.
+    # @return [CTA::BusTracker::RoutesResponse]
     def self.routes!
       connection.get('getroutes')
     end
 
+    # Returns the directions in which a route operates (eg Eastbound, Westbound)
+    # @param [Hash] options
+    # @option options [String, Integer] :route The route to query for available directions
+    # @return [CTA::BusTracker::DirectionsResponse]
+    # @example
+    #   CTA::BusTracker.directions!(:route => 37)
     def self.directions!(options={})
       allowed_keys = [:route]
       if options.keys.any? { |k| !allowed_keys.include?(k) }
@@ -58,6 +79,13 @@ module CTA
       connection.get('getdirections', { :rt => routes.first })
     end
 
+    # Returns the stops along a route and direction
+    # @params [Hash] options
+    # @option options [String, Integer] :route The route to query for stops
+    # @option options [String, Integer] :direction The direction to query for stops
+    # @return [CTA::BusTracker::StopsResponse]
+    # @example
+    #   CTA::BusTracker.stops!(:route => 22, :direction => :northbound)
     def self.stops!(options={})
       allowed_keys = [:route, :direction]
       if options.keys.any? { |k| !allowed_keys.include?(k) }
@@ -84,6 +112,14 @@ module CTA
       connection.get('getstops', { :rt => routes.first, :dir => directions.first.to_s.capitalize })
     end
 
+    # Returns available patterns for a route
+    # @params [Hash] options
+    # @option options [String, Integer] :route The route to query for patterns. Not available with :patterns
+    # @option options [Array<String>, Array<Integer>, String, Integer] :patterns Patterns to return. Not available with :route
+    # @return [CTA::BusTracker::PatternsResponse]
+    # @example
+    #   CTA::BusTracker.patterns!(:route => 22)
+    #   CTA::BusTracker.patterns!(:patterns => [3936, 3932])
     def self.patterns!(options={})
       allowed_keys = [:route, :patterns]
       if options.keys.any? { |k| !allowed_keys.include?(k) }
@@ -106,6 +142,16 @@ module CTA
       connection.get('getpatterns', { :pid => patterns, :rt => routes.first })
     end
 
+    # Returns a set of arrival/departure predictions.
+    # @params [Hash] options
+    # @option options [Array<String>, Array<Integer>, String, Integer] :vehicles Vehicles to predict. Not available with :routes
+    # @option options [Array<String>, Array<Integer>, String, Integer] :routes Routes to predict. Not available with :vehicles
+    # @option options [Array<String>, Array<Integer>, String, Integer] :stops Stops along a route to predict. Required with :routes
+    # @option options [String, Integer] :limit Maximum number of predictions to return.
+    # @return [CTA::BusTracker::PredictionsResponse]
+    # @example
+    #   CTA::BusTracker.predictions!(:routes => 22, :stops => 15895)
+    #   CTA::BusTracker.predictions!(:vehicles => [2172, 1860], :limit => 1)
     def self.predictions!(options={})
       allowed_keys = [:vehicles, :stops, :routes, :limit]
       if options.keys.any? { |k| !allowed_keys.include?(k) }
@@ -127,6 +173,16 @@ module CTA
       connection.get('getpredictions', { :rt => routes, :vid => vehicles, :stpid => stops, :top => limit })
     end
 
+    # Returns active bulletins.
+    # @note Consider using {CTA::CustomerAlerts.alerts!} or {CTA::CustomerAlerts.status!}, as those are not rate-limited.
+    # @params [Hash] options
+    # @option options [Array<String>, Array<Integer>, String, Integer] :routes Routes for which to retrieve bulletins.
+    #   When combined with :direction or :stops, may only specify one :route.
+    # @option options [String, Integer] :direction Direction of a route for which to retrieve bulletins.
+    # @option options [String, Integer] :stop Stop along a route for which to retrieve bulletins.
+    # @return [CTA::BusTracker::ServiceBulletinsResponse]
+    # @example
+    #   CTA::BusTracker.bulletins!(:routes => [8, 22])
     def self.bulletins!(options={})
       allowed_keys = [:routes, :directions, :stop]
       if options.keys.any? { |k| !allowed_keys.include?(k) }
@@ -162,19 +218,29 @@ module CTA
       connection.get('getservicebulletins', { :rt => routes, :stpid => stops, :dir => directions.first })
     end
 
+    # Returns the current API key used to talk to BusTracker
+    # @return [String] the api key
     def self.key
       @key
     end
 
+    # Sets the API key used to talk to BusTracker
+    # @note If using SimpleCache as a caching strategy, this resets the cache.
+    # @param key [String] The key to use
     def self.key=(key)
       @key = key
       @connection = nil
     end
 
+    # Returns the debug status of the API. When in debug mode, all API responses will additionally return
+    # the parsed XML tree, and the original XML for inspection
     def self.debug
       !!@debug
     end
 
+    # Sets the debug status of the API. When in debug mode, all API responses will additionally return
+    # the parsed XML tree, and the original XML for inspection
+    # @param debug [true, false]
     def self.debug=(debug)
       @debug = debug
       @connection = nil

data/lib/cta_redux/customer_alerts.rb

@@ -1,6 +1,7 @@
 module CTA
   class CustomerAlerts
 
+    # Returns the connection object we use to talk to the CustomerAlerts API
     def self.connection
       @connection ||= Faraday.new do |faraday|
         faraday.url_prefix = 'http://www.transitchicago.com/api/1.0/'
@@ -10,14 +11,21 @@ module CTA
       end
     end
 
+    # Returns an overview of system status.
+    # @param [Hash] options
+    # @option options [Array<Integer> Array<String>, Integer, String] :routes Routes to query for status
+    # @option options [String, Integer] :stations Station to query for status
+    # @return [CTA::CustomerAlerts::RouteStatusResponse]
+    # @example
+    #    CTA::CustomerAlerts.status!(:routes => [8,22])
     def self.status!(options = {})
-      allowed_keys = [:routes, :stations]
+      allowed_keys = [:routes, :station]
       if options.keys.any? { |k| !allowed_keys.include?(k) }
         raise "Illegal argument!"
       end
 
       routes   = Array.wrap(options[:routes]).flatten.compact.uniq.join(',')
-      stations = Array.wrap(options[:stations]).flatten.compact.uniq
+      stations = Array.wrap(options[:station]).flatten.compact.uniq
 
       if stations.size > 1
         raise "Can only specify one station!"
@@ -26,6 +34,18 @@ module CTA
       connection.get('routes.aspx', { :type => options[:type], :routeid => routes, :stationid => stations.first })
     end
 
+    # Returns alerts for given routes or stations
+    # @param [Hash] options
+    # @option options [Array<Integer> Array<String>, Integer, String] :routes Routes to query for alerts. Not available with :station
+    # @option options [Integer, String] :station Station to query for alerts. Not available with :route
+    # @option options [true, false] :active Only return active alerts
+    # @option options [true, false] :accessibility Include alerts related to accessibility (elevators, etc)
+    # @option options [true, false] :planned Only return planned alerts
+    # @option options [Integer] :recent_days Only return alerts within the specified number of days
+    # @option options [Integer] :before Only return alerts starting prior to the specified number of days
+    # @return [CTA::CustomerAlerts::AlertsResponse]
+    # @example
+    #    CTA::CustomerAlerts.alerts!(:route => 8)
     def self.alerts!(options = {})
       allowed_keys = [:active, :accessibility, :planned, :routes, :station, :recent_days, :before]
       if options.keys.any? { |k| !allowed_keys.include?(k) }
@@ -60,10 +80,15 @@ module CTA
       connection.get('alerts.aspx', params)
     end
 
+    # Returns the debug status of the API. When in debug mode, all API responses will additionally return
+    # the parsed XML tree, and the original XML for inspection
     def self.debug
       !!@debug
     end
 
+    # Sets the debug status of the API. When in debug mode, all API responses will additionally return
+    # the parsed XML tree, and the original XML for inspection
+    # @param debug [true, false]
     def self.debug=(debug)
       @debug = debug
       @connection = nil

data/lib/cta_redux/train_tracker.rb

@@ -1,5 +1,6 @@
 module CTA
   class TrainTracker
+    # Returns the connection object we use to talk to the TrainTracker API
     def self.connection
       raise "You need to set a developer key first. Try CTA::TrainTracker.key = 'foo'." unless @key
 
@@ -13,6 +14,15 @@ module CTA
       end
     end
 
+    # Returns the arrivals for a route, or station
+    # @param [Hash] options
+    # @option options [String, Integer] :route The route to query
+    # @option options [String, Integer] :station The station to query for arrivals
+    # @option options [String, Integer] :parent_station The parent station to query for arrivals.
+    # @option options [String, Integer] :limit Maximum number of results to return
+    # @return [CTA::TrainTracker::ArrivalsResponse]
+    # @example
+    #    CTA::TrainTracker.arrivals!(:route => :red)
     def self.arrivals!(options={})
       allowed_keys = [:route, :parent_station, :station, :limit]
       if options.keys.any? { |k| !allowed_keys.include?(k) }
@@ -48,10 +58,25 @@ module CTA
       connection.get('ttarrivals.aspx', params)
     end
 
+    # Returns the arrivals for a route, or station
+    # @param [Hash] options
+    # @option options [String, Integer] :route The route to query
+    # @option options [String, Integer] :station The station to query for arrivals
+    # @option options [String, Integer] :parent_station The parent station to query for arrivals.
+    # @option options [String, Integer] :limit Maximum number of results to return
+    # @return [CTA::TrainTracker::ArrivalsResponse]
+    # @example
+    #    CTA::TrainTracker.predicitons!(:route => :red)
     def self.predictions!(options={})
       self.arrivals!(options)
     end
 
+    # Returns a set of upcoming positions for a train/run
+    # @param [Hash] options
+    # @option options [String, Integer] :run The run number of the train to follow
+    # @return [CTA::TrainTracker::FollowResponse]
+    # @example
+    #    CTA::TrainTracker.follow!(:run => 914)
     def self.follow!(options={})
       raise "Must specify a run! Try follow(:run => 914)..." unless options.has_key?(:run)
 
@@ -64,6 +89,12 @@ module CTA
       connection.get('ttfollow.aspx', { :runnumber => runs.first })
     end
 
+    # Returns the position and next station of all trains in service.
+    # @param [Hash] options
+    # @option options [Array<String>, Array<Integer>, String, Integer] :routes Routes for which to return positions
+    # @return [CTA::TrainTracker::LocationsResponse]
+    # @example
+    #    CTA::TrainTracker.locations!(:route => [:red, :blue])
     def self.locations!(options={})
       unless options.has_key?(:routes)
         raise "Must specify at least one route! (Try locations(:routes => [:red, :blue]) )"
@@ -78,23 +109,39 @@ module CTA
       connection.get('ttpositions.aspx', { :rt => rt.join(',') })
     end
 
+    # Returns the position and next station of all trains in service.
+    # @param [Hash] options
+    # @option options [Array<String>, Array<Integer>, String, Integer] :routes Routes for which to return positions
+    # @return [CTA::TrainTracker::LocationsResponse]
+    # @example
+    #    CTA::TrainTracker.positions!(:route => [:red, :blue])
     def self.positions!(options={})
       self.locations!(options)
     end
 
+    # Returns the current API key used to talk to TrainTracker
+    # @return [String] the api key
     def self.key
       @key
     end
 
+    # Sets the API key used to talk to TrainTracker
+    # @note If using SimpleCache as a caching strategy, this resets the cache.
+    # @param key [String] The key to use
     def self.key=(key)
       @key = key
       @connection = nil
     end
 
+    # Returns the debug status of the API. When in debug mode, all API responses will additionally return
+    # the parsed XML tree, and the original XML for inspection
     def self.debug
       !!@debug
     end
 
+    # Sets the debug status of the API. When in debug mode, all API responses will additionally return
+    # the parsed XML tree, and the original XML for inspection
+    # @param debug [true, false]
     def self.debug=(debug)
       @debug = debug
       @connection = nil

data/lib/cta_redux/version.rb

@@ -1,3 +1,3 @@
 module CTA
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cta_redux
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Andrew Hayworth
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-14 00:00:00.000000000 Z
+date: 2015-02-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 3.2.0
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.8.7.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.8.7.6
 - !ruby/object:Gem::Dependency
   name: sequel
   requirement: !ruby/object:Gem::Requirement
@@ -130,11 +144,13 @@ description: |-
 email:
 - ahayworth@gmail.com
 executables: []
-extensions: []
+extensions:
+- ext/inflate_database/extconf.rb
 extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".rspec"
+- ".travis.yml"
 - Gemfile
 - LICENSE
 - README.md
@@ -142,6 +158,7 @@ files:
 - cta_redux.gemspec
 - data/.gitkeep
 - data/cta-gtfs.db.gz
+- ext/inflate_database/extconf.rb
 - lib/cta_redux.rb
 - lib/cta_redux/api/api_response.rb
 - lib/cta_redux/api/bus_tracker.rb
@@ -198,7 +215,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -232,3 +249,4 @@ test_files:
 - spec/stubs/ttfollow_run217_response.xml
 - spec/stubs/ttpositions_response.xml
 - spec/train_tracker_spec.rb
+has_rdoc: