cta_redux 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9e3939dcf2d580a8ef7487ea5f9ef1a3b1464737
-  data.tar.gz: d148cd49ce17813bec6bed9b33fd3a0f4fe9393f
+  metadata.gz: f83f5bf3b8bfc681998bdaa39b19c45a77a8c388
+  data.tar.gz: 371f9733b0decd55ea6858f9e39b7cd8337a0ebe
 SHA512:
-  metadata.gz: 1633690c5355c45aa87daafaf17fa261f25d495bd6b022b09394e9e067e5071c00e4b1293405ab015c9d88488b3ff1d272821c10a337bedd6f3ac2cc06742454
-  data.tar.gz: 82df0c408f08a8c45def1be764730302620a9bfd70309d8ba4cd12617e72926c34b6f5b494a050639d25afa1d4aac739af078dd9c55ce3872de640df725f7437
+  metadata.gz: 996e04cc55d7f1d65aaa9703676aac5c818d1096b152f48a7d2aea9e2edc24a6aa8fed1c64cc4d2ceb6ca84de870c614ffa3b659707fd2533064f9deb5bcc016
+  data.tar.gz: 33b0201a8c53886c123e5ce98b22b0f3254b7af914044da8160821ce9f095162b632fce2c68ea377613d00452e150a5c89d31b2885b4a64ee4190e8a021248c9

data/CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Notes
+
+When running the gem from a git checkout, you'll need to unzip the CTA database yourself.
+
+````cd data && gunzip cta-gtfs.db.gz````
+
+# How to reload CTA GTFS data
+
+Note that this will take a long time - there are several million stop_time records.
+
+1. cd data && curl 'http://www.transitchicago.com/downloads/sch_data/<latest file>' > gtfs.zip && unzip gtfs.zip
+
+2. cd ../script && for i in `ls ../data/*.txt`; do echo $i; ./gtfs_to_sqlite.rb $i ../data/cta-gtfs.db; done
+
+3. rm ../data/*{txt,htm,zip}
+
+4. cd ../data && sqlite3 ./cta-gtfs.db
+
+5. ANALYZE
+
+6. VACUUM
+
+7. gzip cta-gtfs.db
+
+8. Commit / push / create release and gem
+

data/README.md

@@ -37,4 +37,4 @@ CTA::CustomerAlerts.alerts!(:routes => routes.uniq).alerts.each do |alert|
 end
 ```
 
-More information is available at (http://www.rubydoc.info/gems/cta_redux/0.1.0)
+More information is available at (http://www.rubydoc.info/github/ahayworth/cta_redux)

data/lib/cta_redux/api/api_response.rb

@@ -1,7 +1,10 @@
 module CTA
   class API
     class Error
+      # @return [Integer] Error code from the API. Normalized across different CTA APIs, and 0 indicates success.
       attr_reader :code
+
+      # @return [String] Detailed error message, if any, from the API.
       attr_reader :message
 
       def initialize(options = {})
@@ -11,9 +14,16 @@ module CTA
     end
 
     class Response
+      # @return [DateTime] Timestamp from the API server, if available. Defaults to DateTime.now if unavailable.
       attr_reader :timestamp
+
+      # @return [CTA::API::Error] Error information from the API
       attr_reader :error
+
+      # @return [String, nil] Raw XML from the API. Only set when {CTA::BusTracker.debug} or {CTA::TrainTracker.debug} is true.
       attr_reader :raw_body
+
+      # @return [Hash, nil] Parsed XML from the API. Only set when {CTA::BusTracker.debug} or {CTA::TrainTracker.debug} is true.
       attr_reader :parsed_body
 
       def initialize(parsed_body, raw_body, debug)

data/lib/cta_redux/api/bus_tracker.rb

@@ -6,13 +6,15 @@ module CTA
   class BusTracker
 
     class VehiclesResponse < CTA::API::Response
+      # @return [Array<CTA::Bus>] An array with a full {CTA::Bus} object for each vehicle returned in the API, augmented
+      #  with live details
       attr_reader :vehicles
 
       def initialize(parsed_body, raw_body, debug)
         super(parsed_body, raw_body, debug)
         @vehicles = Array.wrap(parsed_body["bustime_response"]["vehicle"]).map do |v|
           bus = CTA::Bus.find_active_run(v["rt"], v["tmstmp"], (v["dly"] == "true")).first
-          bus.live!(v)
+          bus.live = CTA::Bus::Live.new(v)
 
           bus
         end
@@ -20,6 +22,7 @@ module CTA
     end
 
     class TimeResponse < CTA::API::Response
+      # @return [DateTime] Current time according to the BusTime servers which power the BusTracker API
       attr_reader :timestamp
 
       def initialize(parsed_body, raw_body, debug)
@@ -29,6 +32,8 @@ module CTA
     end
 
     class RoutesResponse < CTA::API::Response
+      # @return [Array<CTA::Route>] An array with a full {CTA::Route} object for each route returned by the API,
+      #  augmented with the color that the API thinks you should be using (which is not always found in the GTFS data).
       attr_reader :routes
 
       def initialize(parsed_body, raw_body, debug)
@@ -43,6 +48,7 @@ module CTA
     end
 
     class DirectionsResponse < CTA::API::Response
+      # @return [Array<Direction>] An array of {Direction} that the requested route operates.
       attr_reader :directions
 
       def initialize(parsed_body, raw_body, debug)
@@ -52,6 +58,9 @@ module CTA
     end
 
     class StopsResponse < CTA::API::Response
+      # @return [Array<CTA::Stop>] An array with full {CTA::Stop} objects that correspond to the stops returned from the API.
+      # @note Some stops returned from BusTracker are not found in GTFS data, so cta_redux creates them on the fly. These
+      #  stops are for seasonal routes. An email has been sent to the CTA asking why they're not included in the GTFS data (they should be).
       attr_reader :stops
 
       def initialize(parsed_body, raw_body, debug)
@@ -63,6 +72,7 @@ module CTA
     end
 
     class PatternsResponse < CTA::API::Response
+      # @return [Array<Pattern>] An array of {Pattern} objects for the requested query.
       attr_reader :patterns
 
       def initialize(parsed_body, raw_body, debug)
@@ -72,22 +82,28 @@ module CTA
     end
 
     class PredictionsResponse < CTA::API::Response
+      # @return [Array<CTA::Bus>] An array of {CTA::Bus} objects that correspond to the predictions requested.
       attr_reader :vehicles
+      # @return [Array<CTA::Bus::Prediction>] An array of {CTA::Bus::Prediction} objects that correspond to the predictions requested.
+      #  This is equivalent to calling +vehicles.map { |b| b.live.predictions }.flatten+
       attr_reader :predictions
 
       def initialize(parsed_body, raw_body, debug)
         super(parsed_body, raw_body, debug)
         @vehicles = Array.wrap(parsed_body["bustime_response"]["prd"]).map do |p|
           bus = CTA::Bus.find_active_run(p["rt"], p["tmstmp"], (p["dly"] == "true")).first
-          bus.live!(p, p)
+          bus.live = CTA::Bus::Live.new(p, p)
 
           bus
         end
-        @predictions = @vehicles.map(&:predictions).flatten
+        @predictions = @vehicles.map { |b| b.live.predictions }.flatten
       end
     end
 
     class ServiceBulletinsResponse < CTA::API::Response
+      # @return [Array<ServiceBulletin>] An array of {ServiceBulletin} objects that correspond to the query requested.
+      # @note Consider using the {CTA::CustomerAlerts} methods to search for alerts, as theoretically they should have the same
+      #  data and it is not a rate-limited API.
       attr_reader :bulletins
 
       def initialize(parsed_body, raw_body, debug)
@@ -97,7 +113,19 @@ module CTA
     end
 
     class ServiceBulletin
-      attr_reader :name, :subject, :details, :brief, :priority, :affected_services
+      # @return [String] The name of the bulletin.
+      attr_reader :name
+      # @return [String] A short description of the bulletin.
+      attr_reader :subject
+      # @return [String] More details about the bulletin
+      attr_reader :details
+      # @return [String] Another short description of the bulletin
+      # @note This seems to usually be unset by the CTA.
+      attr_reader :brief
+      # @return [Symbol] Priority of the alert. One of +[:low, :medium, :high]+
+      attr_reader :priority
+      # @return [Array<Service>] An array of {Service} objects that encapsulate information (if any) about which routes and stops are affected by this bulletin.
+      attr_reader :affected_services
 
       def initialize(sb)
         @name = sb["nm"]
@@ -111,9 +139,16 @@ module CTA
     end
 
     class Service
+      # @return [CTA::Route] A {CTA::Route}, if any, affected by a {ServiceBulletin}
       attr_reader :route
+      # @return [Direction] A {Direction} object for the direction, if any, affected by a {ServiceBulletin}
       attr_reader :direction
+      # @return [CTA::Stop] A specific {CTA::Stop} object for the stop affected by a {ServiceBulletin}
       attr_reader :stop
+
+      # @return [String] The name of the {CTA::Stop} affected.
+      # @note Usually this is equivalent to calling +stop.name+, but sometimes the CTA returns a {ServiceBulletin} with a stop name,
+      #  but no stop id set - and the stop name may not exactly correspond to a {CTA::Stop} object in the GTFS feed.
       attr_reader :stop_name
 
       def initialize(s)
@@ -134,11 +169,22 @@ module CTA
       end
     end
 
+    # @note {Pattern} objects enclose {Point} objects that describe a bus route. Conceptually it is similar to how a {CTA::Trip} contains
+    #  many {CTA::StopTime} objects that describe the route a vehicle takes. However, it is specific to busses and contains better information
+    #  for drawing turns and side-streets that the bus may take on its route. This bit of the API is mostly unnecessary unless you're drawing
+    #  maps.
     class Pattern
+      # @return [Integer] The ID of the pattern
       attr_reader :id
+      # @return [Integer] The ID of the pattern
       attr_reader :pattern_id
+      # @return [Integer] The total length of the pattern
       attr_reader :length
+      # @return [Direction] A {Direction} object that describes to which direction of a route this pattern applies.
+      # @note This logically means that any given bus route (so long as it's not a circulator or one-way express) will have
+      #  two associated {Pattern} objects
       attr_reader :direction
+      # @return [Array<Point>] An array of {Point} objects that describe stops and waypoints along the {Pattern}
       attr_reader :points
 
       def initialize(p)
@@ -151,7 +197,22 @@ module CTA
     end
 
     class Point
-      attr_reader :sequence, :lat, :lon, :latitude, :longitude, :type, :stop, :distance
+      # @return [Integer] The order that this {Point} appears along a {Pattern}
+      attr_reader :sequence
+      # @return [Float] The latitude of this {Point}
+      attr_reader :lat
+      # @return [Float] The longitude of this {Point}
+      attr_reader :lon
+      # @return [Float] The latitude of this {Point}
+      attr_reader :latitude
+      # @return [Float] The longitude of this {Point}
+      attr_reader :longitude
+      # @return [Symbol] The type of this {Point}. One of +[:stop, :waypoint]+
+      attr_reader :type
+      # @return [CTA::Stop] The {CTA::Stop} associated with this point.
+      attr_reader :stop
+      # @return [Float] The physical distance into a {Pattern} that corresponds to this {Point}
+      attr_reader :distance
 
       def initialize(p)
         @sequence = p["seq"].to_i
@@ -168,6 +229,9 @@ module CTA
     end
 
     class Direction
+      # @return [String] A direction for a service.
+      # @note The raw BusTracker API expects directions in the exact format this object returns. This is mostly an implementation detail, but
+      #  explains a bit about why this object even exists.
       attr_reader :direction
 
       def initialize(d)

data/lib/cta_redux/api/customer_alerts.rb

@@ -5,7 +5,16 @@ require 'multi_xml'
 module CTA
   class CustomerAlerts
     class RouteStatus
-      attr_reader :route, :route_color, :route_text_color, :service_id, :route_url, :status, :status_color
+      # @return [CTA::Route] The {CTA::Route} that corresponds to this {RouteStatus}
+      attr_reader :route
+      # @return [String] The color the CTA suggests when displaying information about this alert.
+      attr_reader :route_color
+      # @return [String] The color of text the CTA suggests when displaying information about this alert.
+      attr_reader :route_text_color
+      # @return [String] A text description of the status of this route.
+      attr_reader :status
+      # @return [String] A color suggestion from the CTA when displaying information about the route status.
+      attr_reader :status_color
 
       def initialize(s)
         @route = CTA::Route.where(:route_id => s["Route"].split(" ").first).or(:route_id => s["ServiceId"]).first
@@ -17,9 +26,40 @@ module CTA
     end
 
     class Alert
-      attr_reader :id, :alert_id, :headline, :short_description, :full_description, :score,
-                  :severity_color, :category, :impact, :start, :end, :tbd, :major_alert, :is_major_alert,
-                  :url, :services
+      # @return [Integer] The internal ID of this alert
+      attr_reader :id
+      # @return [Integer] The internal ID of this alert
+      attr_reader :alert_id
+      # @return [String] A descriptive one-line summary for this alert
+      attr_reader :headline
+      # @return [String] A descriptive short summary for this alert
+      attr_reader :short_description
+      # @return [String] A long-form summary for this alert.
+      # @note HTML formatted.
+      attr_reader :full_description
+      # @return [0..99] A score that describes how an impact this alert will have on any affected services.
+      # @note The score ranges from +0-99+. It's unclear how this is calculated internally, but higher numbers seem to be worse.
+      attr_reader :score
+      # @return [String] The hex color used to color text related to this alert on transitchicago.com
+      attr_reader :severity_color
+      # @return [Symbol] One of +[:normal, :planned, :major, :minor]+
+      attr_reader :category
+      # @return [String] Descriptive text detailing the impact of this alert.
+      attr_reader :impact
+      # @return [DateTime] The date and time at which this alert takes effect.
+      attr_reader :start
+      # @return [DateTime] The date and time at which this alert ends. May be unknown.
+      attr_reader :end
+      # @return [true,false] Returns true if the alert is 'TBD' - that is, the end time is unknown.
+      attr_reader :tbd
+      # @return [true,false] Returns true if the alert is 'major' - that is the CTA is displaying it prominently on transitchicago.com and expects it to cause major headaches.
+      attr_reader :major_alert
+      # @return [true,false] Returns true if the alert is 'major' - that is the CTA is displaying it prominently on transitchicago.com and expects it to cause major headaches.
+      attr_reader :is_major_alert
+      # @return [String] A URL where customers could learn more about the alert.
+      attr_reader :url
+      # @return [Array<CTA::Route>] An array of {CTA::Route} objects that are impacted by this alert.
+      attr_reader :services
 
       def initialize(a)
         @id = @alert_id = a["AlertId"].to_i
@@ -41,12 +81,14 @@ module CTA
         end
       end
 
+      # @return [true,false] Returns true if the alert is 'major' - that is the CTA is displaying it prominently on transitchicago.com and expects it to cause major headaches.
       def major?
         @major_alert
       end
     end
 
     class AlertsResponse < CTA::API::Response
+      # @return [Array<Alert>] An array of {Alert} objects that match the requested query.
       attr_reader :alerts
 
       def initialize(parsed_body, raw_body, debug)
@@ -56,6 +98,7 @@ module CTA
     end
 
     class RouteStatusResponse < CTA::API::Response
+      # @return [Array<RouteStatus>] An array of {RouteStatus} objects that match the requested query.
       attr_reader :routes
 
       def initialize(parsed_body, raw_body, debug)

data/lib/cta_redux/api/train_tracker.rb

@@ -1,7 +1,14 @@
 module CTA
   class TrainTracker
     class ArrivalsResponse < CTA::API::Response
-      attr_reader :routes, :trains, :predictions
+      # @return [Array<CTA::Route>] An array of {CTA::Route} objects that correspond to the predictions requested.
+      attr_reader :routes
+      # @return [Array<CTA::Train>] An array of {CTA::Train} objects that correspond to the predictions requested.
+      # @note Convenience method, equivalent to calling +routes.map { |r| r.vehicles }.flatten+
+      attr_reader :trains
+      # @return [Array<CTA::Train::Prediction>] An array of {CTA::Train::Prediction} objects that correspond to the predictions requested.
+      # @note Convenience method, equivalent to calling +trains.map { |t| t.live.predictions }.flatten+
+      attr_reader :predictions
 
       def initialize(parsed_body, raw_body, debug)
         super(parsed_body, raw_body, debug)
@@ -20,24 +27,28 @@ module CTA
               train = CTA::Train.find_active_run(t["rn"], self.timestamp, true).first
             end
             position = t.select { |k,v| ["lat", "lon", "heading"].include?(k) }
-            train.live!(position, t)
+            train.live = CTA::Train::Live.new(position, t)
 
             train
           end
 
           route = CTA::Route.where(:route_id => rt.capitalize).first
-          route.live!(trains)
+          route.live = CTA::Route::Live.new(trains)
 
           route
         end
 
-        @trains = @routes.map(&:vehicles).flatten
-        @predictions = @trains.map(&:predictions).flatten
+        @trains = @routes.map { |r| r.live.vehicles }.flatten
+        @predictions = @trains.map { |t| t.live.predictions }.flatten
       end
     end
 
     class FollowResponse < CTA::API::Response
-      attr_reader :train, :predictions
+      # @return [CTA::Train] The {CTA::Train} that corresponds to the train for which you've requested follow predictions.
+      attr_reader :train
+      # @return [Array<CTA::Train::Prediction>] An array of {CTA::Train::Prediction} objects that correspond to the predictions requested.
+      # @note Convenience method, equivalent to calling +train.map { |t| t.live.predictions }.flatten+
+      attr_reader :predictions
 
       def initialize(parsed_body, raw_body, debug)
         super(parsed_body, raw_body, debug)
@@ -47,13 +58,20 @@ module CTA
         if !@train
           @train = CTA::Train.find_active_run(train_info["rn"], self.timestamp, true).first
         end
-        @train.live!(parsed_body["ctatt"]["position"], parsed_body["ctatt"]["eta"])
-        @predictions = @train.predictions
+        @train.live = CTA::Train::Live.new(parsed_body["ctatt"]["position"], parsed_body["ctatt"]["eta"])
+        @predictions = @train.live.predictions
       end
     end
 
     class PositionsResponse < CTA::API::Response
-      attr_reader :routes, :trains, :predictions
+      # @return [Array<CTA::Route>] An array of {CTA::Route} objects that correspond to the positions requested.
+      attr_reader :routes
+      # @return [Array<CTA::Train>] An array of {CTA::Train} objects that correspond to the positions requested.
+      # @note Convenience method, equivalent to calling +routes.compact.map { |r| r.live.vehicles }.flatten+
+      attr_reader :trains
+      # @return [Array<CTA::Train::Prediction>] An array of {CTA::Train::Prediction} objects that correspond to the positions requested.
+      # @note Convenience method, equivalent to calling +trains.map { |t| t.live.predictions }.flatten+
+      attr_reader :predictions
 
       def initialize(parsed_body, raw_body, debug)
         super(parsed_body, raw_body, debug)
@@ -72,17 +90,17 @@ module CTA
             end
 
             position = train.select { |k,v| ["lat", "lon", "heading"].include?(k) }
-            t.live!(position, train)
+            t.live = CTA::Train::Live.new(position, train)
 
             t
           end
 
-          rt.live!(trains)
+          rt.live = CTA::Route::Live.new(trains)
           rt
         end.compact
 
-        @trains = @routes.compact.map(&:vehicles).flatten
-        @predictions = @trains.compact.map(&:predictions).flatten
+        @trains = @routes.compact.map { |r| r.live.vehicles }.flatten
+        @predictions = @trains.compact.map { |t| t.live.predictions }.flatten
       end
     end
   end

data/lib/cta_redux/bus_tracker.rb

@@ -1,5 +1,7 @@
 module CTA
   class BusTracker
+    @cache_responses = true
+
     # 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
@@ -9,7 +11,9 @@ module CTA
         faraday.params = { :key => @key }
 
         faraday.use CTA::BusTracker::Parser, !!@debug
-        faraday.response :caching, SimpleCache.new(Hash.new)
+        if @cache_responses
+          faraday.response :caching, (@cache || SimpleCache.new(Hash.new))
+        end
         faraday.adapter Faraday.default_adapter
       end
     end
@@ -80,7 +84,7 @@ module CTA
     end
 
     # Returns the stops along a route and direction
-    # @params [Hash] options
+    # @param [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]
@@ -113,7 +117,7 @@ module CTA
     end
 
     # Returns available patterns for a route
-    # @params [Hash] options
+    # @param [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]
@@ -143,7 +147,7 @@ module CTA
     end
 
     # Returns a set of arrival/departure predictions.
-    # @params [Hash] options
+    # @param [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
@@ -175,7 +179,7 @@ module CTA
 
     # Returns active bulletins.
     # @note Consider using {CTA::CustomerAlerts.alerts!} or {CTA::CustomerAlerts.status!}, as those are not rate-limited.
-    # @params [Hash] options
+    # @param [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.
@@ -245,5 +249,38 @@ module CTA
       @debug = debug
       @connection = nil
     end
+
+    # Returns whether or not cta_redux is caching responses
+    # @return [true, false]
+    def self.cache_responses
+      @cache_responses
+    end
+
+    # Sets whether or not cta_redux is caching responses
+    # @param [true, false] should_cache
+    def self.cache_responses=(should_cache)
+      @cache_responses = should_cache
+      @connection = nil
+    end
+
+    # Returns the underlying cache object caching responses (if we're actually caching responses)
+    # @return [Object]
+    def self.cache
+      if self.cache_responses
+        # This is ugly
+        @cache || self.connection.builder.handlers.find { |x| x == FaradayMiddleware::Caching }.instance_variable_get(:@args).first
+      else
+        nil
+      end
+    end
+
+    # Sets the underlying cache object caching responses. Any object can be used that responds to #read, #write, and #fetch
+    # @note Setting the cache object resets the connection. If you're using the default SimpleCache strategy (built-in 60
+    #  second caching), then it will also *clear* the cache.
+    # @param [Object] cache
+    def self.cache=(cache)
+      @cache = cache
+      @connection = nil
+    end
   end
 end