cta_redux 0.2.0 → 0.3.1

data/lib/cta_redux/models/stop_time.rb

@@ -1,6 +1,39 @@
 module CTA
+  # A {http://sequel.jeremyevans.net/rdoc/classes/Sequel/Model.html Sequel::Model}.
+  # This corresponds to {https://developers.google.com/transit/gtfs/reference?csw=1#stop_times_txt___Field_Definitions stop_times.txt} in the
+  # GTFS feed, though the CTA does not fully implement the standard.
+  # This object can give you the scheduled times that a vehicle should stop along a {CTA::Route} (or really, a {CTA::Trip} if you're being specific).
+  # It can also function as somewhat of a 'join table' between trips and stops.
+  # @note Current columns: [:trip_id, :arrival_time, :departure_time, :stop_id, :stop_sequence, :stop_headsign, :pickup_type, :shape_dist_traveled]
   class StopTime < Sequel::Model
+    # @!method trip
+    #   @return [CTA::Trip] The {CTA::Trip} associated with this {CTA::StopTime}
     many_to_one :trip, :key => :trip_id
+    # @!method stop
+    #   @return [CTA::Stop] The {CTA::Stop} associated with this {CTA::StopTime}
     many_to_one :stop, :key => :stop_id
+
+    # @!method trip_id
+    #  @return [Integer]
+    # @!method arrival_time
+    #  @return [String]
+    #  @note This is a string because ruby has no concept of storing a time without a date
+    # @!method departure_time
+    #  @return [String]
+    #  @note This is a string because ruby has no concept of storing a time without a date
+    # @!method stop_id
+    #  @return [Integer]
+    # @!method stop_sequence
+    #  @return [Integer]
+    # @!method stop_headsign
+    #  @return [String]
+    # @!method pickup_type
+    #  @return [Integer]
+    # @!method shape_dist_traveled
+    #  @return [Integer]
+    alias_method :sequence, :stop_sequence
+    alias_method :headsign, :stop_headsign
+    alias_method :distance, :shape_dist_traveled
+    alias_method :distance_traveled, :shape_dist_traveled
   end
 end

data/lib/cta_redux/models/train.rb

@@ -1,5 +1,13 @@
 module CTA
+  # A {http://sequel.jeremyevans.net/rdoc/classes/Sequel/Model.html Sequel::Model}, inherited from {CTA::Trip}
+  # This corresponds to {https://developers.google.com/transit/gtfs/reference?csw=1#trips_txt___Field_Definitions trips.txt} in the
+  # GTFS feed, though the CTA does not fully implement the standard.
+  # @note Current columns: [:route_id, :service_id, :trip_id, :direction_id, :block_id, :shape_id, :direction, :wheelchair_accessible, :schd_trip_id]
   class Train < CTA::Trip
+    # @return [Live] Returns the {Live} data associated with this {CTA::Train} object, if available.
+    # @note a {CTA::Train} will only contain live data when augmented with an {API::Response}
+    attr_accessor :live
+
     L_ROUTES = {
       "red"   => { :name => "Red",
                    :directions => { "1" => "Howard-bound", "5" => "95th/Dan Ryan-bound" }
@@ -28,27 +36,86 @@ module CTA
     }
     FRIENDLY_L_ROUTES = Hash[L_ROUTES.values.map { |r| r[:name].downcase.to_sym }.zip(L_ROUTES.keys)]
 
+    # @!method route_id
+    #  @return [String]
+    # @!method service_id
+    #  @return [Integer]
+    # @!method trip_id
+    #  @return [Integer]
+    # @!method direction_id
+    #  @return [Integer]
+    # @!method block_id
+    #  @return [Integer]
+    # @!method shape_id
+    #  @return [Integer]
+    # @!method direction
+    #  @return [String]
+    # @!method wheelchair_accessible
+    #  @return [true,false]
+    # @!method schd_trip_id
+    #  @return [String]
+    alias_method :id, :route_id
+    alias_method :scheduled_trip_id, :schd_trip_id
+    alias_method :run, :schd_trip_id
+
+    # Follows a train, using the TrainTracker follow API
+    # @return [CTA::TrainTracker::FollowResponse] A {CTA::TrainTracker::FollowResponse} with predictions for this train
     def follow!
       CTA::TrainTracker.follow!(:run => self.schd_trip_id.gsub("R", ""))
     end
 
-    def live!(position, predictions)
-      class << self
-        attr_reader :lat, :lon, :heading, :predictions
-      end
+    class Live
+      # @return [Float] The current latitude of the train
+      attr_reader :lat
+      # @return [Float] The current longitude of the train
+      attr_reader :lon
+      # @return [Integer] The current heading of the train
+      attr_reader :heading
+      # @return [Array<Prediction>] An array of {Prediction} objects that correspond to predictions returned from the TrainTracker API
+      attr_reader :predictions
 
-      @lat = position["lat"].to_f
-      @lon = position["lon"].to_f
-      @heading = position["heading"].to_i
-
-      @predictions = Array.wrap(predictions).map { |p| Prediction.new(p) }
+      def initialize(position, predictions)
+        @lat = position["lat"].to_f
+        @lon = position["lon"].to_f
+        @heading = position["heading"].to_i
+        @predictions = Array.wrap(predictions).map { |p| Prediction.new(p) }
+      end
     end
 
     class Prediction
-      attr_reader :run, :trip, :destination, :direction, :next_station,
-                  :prediction_generated_at, :arrival_time, :minutes, :seconds,
-                  :approaching, :scheduled, :delayed, :flags, :route, :lat, :lon,
-                  :heading, :route, :direction
+      # @return [String] The run identifier for this train.
+      # @note This is returned as a string, because the API will return results like "004" and the leading zeroes are important.
+      attr_reader :run
+      # @return [CTA::Trip] The {CTA::Trip} associated with this train
+      attr_reader :trip
+      # @return [CTA::Stop] The final {CTA::Stop} of this train
+      attr_reader :destination
+      # @return [String] A human-readable direction of this train, eg "O'Hare-bound"
+      attr_reader :direction
+      # @return [CTA::Stop] The next {CTA::Stop} of this train
+      attr_reader :next_station
+      # @return [DateTime] The time this {Prediction} was generated on the TrainTracker servers
+      attr_reader :prediction_generated_at
+      # @return [DateTime] The time this train is predicted to arrive at the next_station
+      attr_reader :arrival_time
+      # @return [Integer] The number of minutes until this train arrives at the next_station
+      attr_reader :minutes
+      # @return [Integer] The number of seconds until this train arrives at the next_station
+      attr_reader :seconds
+      # @return [true,false] True if this train is considered to be 'approaching' the next_station by the CTA
+      attr_reader :approaching
+      # @return [true,false] True if this train has not yet left it's origin station and started it's run
+      attr_reader :scheduled
+      # @return [true,false] True if this train is considered to be 'delayed' by the CTA
+      # @note The CTA considers a train 'delayed' if it's not progressing along the tracks. This is *not* an indication
+      #   that a predicted arrival time will be later than a scheduled arrival time (which is how most people would consider a train
+      #   to be 'delayed'). The CTA recommends that you indicate a train is 'delayed' rather than continuing to display the last predicted
+      #   arrival time, which may no longer be accurate.
+      attr_reader :delayed
+      # @return [String] Flags for this train. Unused at this time.
+      attr_reader :flags
+      # @return [CTA::Route] The {CTA::Route} this train is running.
+      attr_reader :route
 
       def initialize(data)
         @run = data["rn"]
@@ -63,9 +130,6 @@ module CTA
         @delayed = (data["isDly"] == "1")
         @scheduled = (data["isSch"] == "1")
         @flags = data["flags"]
-        @lat = data["lat"].to_f
-        @lon = data["lon"].to_f
-        @heading = data["heading"].to_i
         @route = @trip.route
         @direction = L_ROUTES[@route.route_id.downcase][:directions][data["trDr"]]
       end

data/lib/cta_redux/models/transfer.rb

@@ -1,6 +1,23 @@
 module CTA
+  # A {http://sequel.jeremyevans.net/rdoc/classes/Sequel/Model.html Sequel::Model}.
+  # This corresponds to {https://developers.google.com/transit/gtfs/reference?csw=1#transfers_txt___Field_Definitions transfers.txt} in the
+  # GTFS feed, though the CTA does not fully implement the standard.
+  # @note Current columns: [:from_stop_id, :to_stop_id, :transfer_type]
   class Transfer < Sequel::Model
+    # @!method from_stop
+    #  The stop to transfer *from*
+    #  @return [CTA::Stop]
     many_to_one :from_stop, :class => 'CTA::Stop', :key => :from_stop_id
+    # @!method to_stop
+    #  The stop to transfer *to*
+    #  @return [CTA::Stop]
     many_to_one :to_stop, :class => 'CTA::Stop', :key => :to_stop_id
+
+    # @!method from_stop_id
+    #  @return [Integer]
+    # @!method to_stop_id
+    #  @return [Integer]
+    # @!method transfer_type
+    #  @return [Integer]
   end
 end

data/lib/cta_redux/models/trip.rb

@@ -1,4 +1,8 @@
 module CTA
+  # A {http://sequel.jeremyevans.net/rdoc/classes/Sequel/Model.html Sequel::Model}.
+  # This corresponds to {https://developers.google.com/transit/gtfs/reference?csw=1#trips_txt___Field_Definitions trips.txt} in the
+  # GTFS feed, though the CTA does not fully implement the standard.
+  # @note Current columns: [:route_id, :service_id, :trip_id, :direction_id, :block_id, :shape_id, :direction, :wheelchair_accessible, :schd_trip_id]
   class Trip < Sequel::Model
     L_ROUTES = ["Brn", "G", "Pink", "P", "Org", "Red", "Blue", "Y"]
     BUS_ROUTES = CTA::Trip.exclude(:route_id => L_ROUTES).select_map(:route_id).uniq
@@ -21,22 +25,63 @@ module CTA
 
     set_primary_key :trip_id
 
+    # @!method calendar
+    #   @return [CTA::Calendar] The {CTA::Calendar} entry for this {CTA::Trip}. Can be used to determine
+    #     if a given {CTA::Trip} is valid for a given date/time
     many_to_one :calendar, :key => :service_id
+
+    # @!method stop_times
+    #   @return [Array<CTA::StopTime>] The {CTA::StopTimes} that are serviced on this {CTA::Trip}
     one_to_many :stop_times, :key => :trip_id
 
+    # @!method route
+    #   @return [CTA::Route] The {CTA::Route} associated with this {CTA::Trip}
     many_to_one :route, :key => :route_id
 
+    # @!method stops
+    #   @return [Array<CTA::Stop>] All {CTA::Stop}s serviced on this {CTA::Trip}
     many_to_many :stops, :left_key => :trip_id, :right_key => :stop_id, :join_table => :stop_times
 
-    # DRAGONS
-    # The CTA doesn't exactly honor the GTFS spec (nor do they return GTFS trip_ids
-    # in the API, grr). They specify multiple entries of # (schd_trip_id, block_id, service_id)
-    # so the only way to know which trip_id to pick is to join against stop_times and
-    # calendar dates, and # find out which run (according to stop_times) is happening *right now*.
-    # Of course, this will break if the train is delayed more the total time
-    # it takes to complete the run... so a delayed train will start to disappear
-    # as it progresses through the run. We allow for a 'fuzz factor' to account
-    # for this...
+    # @!method route_id
+    #  @return [String]
+    # @!method service_id
+    #  @return [Integer]
+    # @!method trip_id
+    #  @return [Integer]
+    # @!method direction_id
+    #  @return [Integer]
+    # @!method block_id
+    #  @return [Integer]
+    # @!method shape_id
+    #  @return [Integer]
+    # @!method direction
+    #  @return [String]
+    # @!method wheelchair_accessible
+    #  @return [true,false]
+    # @!method schd_trip_id
+    #  @return [String]
+    alias_method :id, :route_id
+    alias_method :scheduled_trip_id, :schd_trip_id
+    alias_method :run, :schd_trip_id
+
+    # Find a {CTA::Trip} that should be happening, given a timestamp and a route or run.
+    # The CTA does not return GTFS trip_id information in either the BusTracker or TrainTracker API, so
+    # it is actually somewhat difficult to associate an API response to a {CTA::Trip}. However, we
+    # know what *should* be happening at any given time. This method attempts a fuzzy find - internally,
+    # we often first try to find the exact Trip that should be happening according to the schedule, and
+    # then failing that we assume that the CTA is running late and look for trips that should have
+    # ended within the past 90 minutes. This almost always finds something.
+    # That said, however, it means we may sometimes find a {CTA::Trip} that's incorrect. In practical usage
+    # however, that doesn't matter too much - most Trips for a run service the same stops.
+    # However, to be safe, your program may wish to compare certain other bits of the API responses to ensure
+    # we found something valid. For example, almost all Brown line trains service the same stops, so
+    # finding the wrong Trip doesn't matter too much. However, a handful of Brown line runs throughout the dat
+    # actually change to Orange line trains at Midway - so, you may wish to verify that the destination of the
+    # Trip matches the reported destination of the API.
+    # Suggestions on how to approach this problem are most welcome (as are patches for better behavior).
+    # @param [String] run The run or route to search for
+    # @param [DateTime, String] timestamp The timestamp to search against.
+    # @param [true,false] fuzz Whether or not to do an exact schedule search or a fuzzy search.
     def self.find_active_run(run, timestamp, fuzz = false)
       if self.to_s == "CTA::Train" # This is admittedly hacky.
         join_str = "WHERE t.schd_trip_id = 'R#{run}'"

data/lib/cta_redux/train_tracker.rb

@@ -1,5 +1,7 @@
 module CTA
   class TrainTracker
+    @cache_responses = true
+
     # 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
@@ -9,7 +11,9 @@ module CTA
         faraday.params = { :key => @key }
 
         faraday.use CTA::TrainTracker::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
@@ -146,5 +150,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

data/lib/cta_redux/version.rb

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

data/spec/bus_tracker_spec.rb

@@ -45,8 +45,8 @@ RSpec.describe CTA::BusTracker do
 
       expect(result.vehicles.first.route).to be_instance_of(CTA::Route)
       expect(result.vehicles.first.route.route_id).to eq("22")
-      expect(result.vehicles.first.vehicle_id).to eq(4394)
-      expect(result.vehicles.first.pattern_distance).to eq(115)
+      expect(result.vehicles.first.live.vehicle_id).to eq(4394)
+      expect(result.vehicles.first.live.pattern_distance).to eq(115)
     end
 
     it "returns information about one vehicle" do
@@ -56,8 +56,8 @@ RSpec.describe CTA::BusTracker do
       expect(result.vehicles.size).to eq(1)
       expect(result.vehicles.first.route).to be_instance_of(CTA::Route)
       expect(result.vehicles.first.route.route_id).to eq("22")
-      expect(result.vehicles.first.vehicle_id).to eq(4394)
-      expect(result.vehicles.first.heading).to eq(359)
+      expect(result.vehicles.first.live.vehicle_id).to eq(4394)
+      expect(result.vehicles.first.live.heading).to eq(359)
     end
   end
 

data/spec/train_tracker_spec.rb

@@ -43,7 +43,7 @@ RSpec.describe CTA::TrainTracker do
       expect(response.train).to be_instance_of(CTA::Train)
       expect(response.train.route_id).to eq("Blue")
       expect(response.train.route.route_id).to eq("Blue")
-      expect(response.train.predictions).to eq(response.predictions)
+      expect(response.train.live.predictions).to eq(response.predictions)
       expect(response.predictions.first.direction).to eq("O'Hare-bound")
       expect(response.predictions.first.destination.stop_name).to eq("O'Hare")
       expect(response.predictions.first.approaching).to eq(false)
@@ -61,7 +61,7 @@ RSpec.describe CTA::TrainTracker do
       expect(response.trains.size).to eq(80)
 
       expect(response.trains.last.route.route_id).to eq("Y")
-      expect(response.predictions.first.lon).to eq(-87.65338)
+      expect(response.trains.first.live.lon).to eq(-87.65338)
       expect(response.predictions.first.route.route_id).to eq("Red")
       expect(response.predictions.first.destination.stop_id).to eq(30173)
       expect(response.predictions.first.trip.service_id).to eq(104701)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cta_redux
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Andrew Hayworth
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-15 00:00:00.000000000 Z
+date: 2015-02-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -151,6 +151,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- CONTRIBUTING.md
 - Gemfile
 - LICENSE
 - README.md