scott_uk 1.0.0

data/README.md

@@ -0,0 +1,151 @@
+# ScottUk
+
+A simple gem to pull cinemas and performances from the [Scott Cinemas website](https://www.scottcinemas.co.uk) and spit out useful formatted info.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'scott_uk'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install scott_uk
+
+## Usage
+
+The gem conforms to the API set down in the `cinebase` gem, [andycroll/cinebase](https://github.com/andycroll/cinebase), which provides a lot of useful base vocabulary and repetitive code for this series of cinema focussed gems.
+
+Performance titles are sanitized as much as possible, removing years,
+festival suffixes, the parent and baby suffix and the film society prefix,
+and naming National Theatre Live and Royal Ballet and Opera screenings in
+full.
+
+No token or setup is needed. Scott Cinemas publishes a JSON feed of each
+venue's listings, documented at https://www.scottcinemas.co.uk/api. Tickets
+are sold through TapOS, behind each venue's own booking pages.
+
+### Cinema
+
+The website keeps the chosen cinema in a cookie and has no plain list of
+venues, so the gem holds them: names, addresses and feed codes from the
+website's cinema and API pages, and coordinates from its cinema finder. Cinema
+methods make no requests. The four WTW cinemas in Cornwall, which share the
+website's cinema menu, run a separate site and are not included.
+
+``` ruby
+ScottUk::Cinema.all
+#=> [<ScottUk::Cinema ...>, <ScottUk::Cinema ...>, ...]
+
+cinema = ScottUk::Cinema.new('SCOBWR')
+#=> <ScottUk::Cinema ...>
+
+cinema.adr
+#=> {
+  street_address:   'Northgate Yard',
+  extended_address: 'Mount Street',
+  locality:         'Bridgwater',
+  region:           'Somerset',
+  postal_code:      'TA6 3FQ',
+  country_name:     'United Kingdom'
+}
+
+cinema.brand
+#=> 'Scott Cinemas'
+
+cinema.full_name
+#=> 'Scott Cinemas Bridgwater'
+
+cinema.id
+#=> 'SCOBWR'
+
+cinema.latitude
+#=> 51.12985
+
+cinema.url
+#=> 'https://bridgwater.scottcinemas.co.uk'
+```
+
+### Performances
+
+`Performance.at` returns performances for an inclusive range of showing dates,
+defaulting to today in London and the following 13 days. The venue's feed
+holds every advertised date, so any range is one request.
+
+``` ruby
+ScottUk::Performance.at('SCOBWR', from: Date.today, to: Date.today + 2)
+#=> [<ScottUk::Performance ...>, <ScottUk::Performance ...>, ...]
+
+performance = ScottUk::Performance.at('SCOBWR').first
+#=> <ScottUk::Performance ...>
+
+performance.film_name
+#=> 'Ghosts: The Possession of Button House' # from '... (Parent and Baby Only Show)'
+
+performance.film_year
+#=> nil # from the title, e.g. 1975 for 'Barry Lyndon (1975)'
+
+performance.dimension
+#=> '2d'
+
+performance.variant
+#=> ['baby']
+
+performance.subtitled?
+#=> false
+
+performance.festival
+#=> nil # e.g. #<data Cinebase::Festival name="Exmouth Film Festival", year=2026>
+
+performance.starting_at
+#=> 2026-11-04 11:00:00 UTC
+
+performance.booking_url
+#=> 'https://bridgwater.scottcinemas.co.uk/book-now/ghosts-the-possession-parent-baby/76429'
+
+performance.cinema_name
+#=> 'Bridgwater'
+
+performance.cinema_id
+#=> 'SCOBWR'
+```
+
+Booking links are the feed's own, to the venue's booking page, which holds
+the TapOS seat selection.
+
+Variants come from the feed's flags and fields: `arts` (event cinema:
+theatre, opera, ballet, musicals, music, art and television), `baby`,
+`relaxed` (autism friendly), `senior` (Silver Screen) and `subtitled`. Most
+screenings offer audio description, so it is not a variant. Strobe warnings,
+ticket offers and premium screens are not variants either.
+
+## Tests
+
+```sh
+bundle exec rake          # unit tests against fixtures
+bundle exec rake live     # live scottcinemas.co.uk
+```
+
+The fixture in `test/fixtures` is Bridgwater's feed, trimmed to a few dates
+with shortened descriptions. `test/support/api_shapes.rb` describes the fields
+the gem reads. The unit suite checks the fixture against it and the live suite
+checks every venue's real feed, held only in memory. When the feed changes,
+update the shape first, then the fixture.
+
+## Releasing
+
+Bump the version, merge, then run the **Release Gem** workflow in GitHub
+Actions. It runs the tests, tags the version and publishes the gem through
+RubyGems trusted publishing.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/lib/scott_uk/cinema.rb

@@ -0,0 +1,123 @@
+module ScottUk
+  # The object representing a cinema on the Scott Cinemas website
+  class Cinema < Cinebase::Cinema
+    # @!attribute [r] id
+    #   @return [String] the cinema's feed code, e.g. 'SCOBAR'
+
+    # The website keeps the chosen cinema in a cookie and has no plain venue
+    # list, so the gem holds the venues: names, addresses and feed codes
+    # from the website's cinema and API pages, coordinates from its cinema
+    # finder.
+    VENUES = {
+      'SCOBAR' => {
+        name: 'Barnstaple', subdomain: 'barnstaple', street_address: 'Boutport Street', locality: 'Barnstaple',
+        region: 'Devon', postal_code: 'EX31 1SR', latitude: 51.07933, longitude: -4.05859
+      },
+      'SCOBWR' => {
+        name: 'Bridgwater', subdomain: 'bridgwater', street_address: 'Northgate Yard',
+        extended_address: 'Mount Street', locality: 'Bridgwater', region: 'Somerset', postal_code: 'TA6 3FQ',
+        latitude: 51.12985, longitude: -3.006949
+      },
+      'SCOORP' => {
+        name: 'Bristol, Westbury Park', subdomain: 'bristolwestburypark', street_address: 'Northumbria Drive',
+        extended_address: 'Westbury Park', locality: 'Bristol', postal_code: 'BS9 4HN',
+        latitude: 51.480392, longitude: -2.612085
+      },
+      'SCOEXM' => {
+        name: 'Exmouth', subdomain: 'exmouth', street_address: 'Strand Gardens', locality: 'Exmouth',
+        region: 'Devon', postal_code: 'EX8 1HP', latitude: 50.619789, longitude: -3.413336
+      },
+      'SCONEW' => {
+        name: 'Newton Abbot', subdomain: 'newtonabbot', street_address: 'Market Street', locality: 'Newton Abbot',
+        region: 'Devon', postal_code: 'TQ12 2RB', latitude: 50.530781, longitude: -3.61197
+      },
+      'SCORAD' => {
+        name: 'Sidmouth', subdomain: 'sidmouth', street_address: 'Radway Place', locality: 'Sidmouth',
+        region: 'Devon', postal_code: 'EX10 8TL', latitude: 50.682728, longitude: -3.238649
+      }
+    }.freeze
+
+    ADDRESS_PARTS = %i(street_address extended_address locality region postal_code).freeze
+
+    # Constructor
+    # @param [String] id the cinema's feed code, e.g. 'SCOBAR' or 'scobar'
+    # @return [ScottUk::Cinema]
+    def initialize(id)
+      @id = id.to_s.upcase
+    end
+
+    # Return basic cinema information for all cinemas
+    # @return [Array<ScottUk::Cinema>]
+    # @example
+    #   ScottUk::Cinema.all
+    #   #=> [<ScottUk::Cinema>, <ScottUk::Cinema>, ...]
+    def self.all
+      VENUES.keys.map { |id| new(id) }
+    end
+
+    # @!method address
+    #   Address of the cinema
+    #   @return [Hash] of different address parts
+    #   @see #adr
+
+    # Address of the cinema
+    # @return [Hash] contains :street_address, :extended_address,
+    # :locality, :region, :postal_code, :country_name
+    # @example
+    #   cinema = ScottUk::Cinema.new('SCOBWR')
+    #   cinema.adr
+    #   #=> {
+    #         street_address:   'Northgate Yard',
+    #         extended_address: 'Mount Street',
+    #         locality:         'Bridgwater',
+    #         region:           'Somerset',
+    #         postal_code:      'TA6 3FQ',
+    #         country_name:     'United Kingdom'
+    #       }
+    # @note Uses method naming as at http://microformats.org/wiki/adr
+    def adr
+      ADDRESS_PARTS.to_h { |part| [part, venue[part]] }.merge(country_name: 'United Kingdom')
+    end
+
+    # Brand of the cinema
+    # @return [String] which will always be 'Scott Cinemas'
+    def brand
+      'Scott Cinemas'.freeze
+    end
+
+    # @return [Float, nil]
+    def latitude
+      venue[:latitude]
+    end
+
+    # @return [Float, nil]
+    def longitude
+      venue[:longitude]
+    end
+
+    # The name of the cinema
+    # @return [String]
+    # @example
+    #   ScottUk::Cinema.new('SCOORP').name
+    #   #=> 'Bristol, Westbury Park'
+    def name
+      venue[:name].to_s
+    end
+
+    # The url of the cinema's pages on the Scott Cinemas website
+    # @return [String]
+    # @example
+    #   ScottUk::Cinema.new('SCOBAR').url
+    #   #=> 'https://barnstaple.scottcinemas.co.uk'
+    def url
+      subdomain = venue[:subdomain]
+      subdomain ? "https://#{subdomain}.scottcinemas.co.uk" : ''
+    end
+
+    private
+
+    def venue
+      VENUES.fetch(id, {})
+    end
+  end
+end

data/lib/scott_uk/internal/feed.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ScottUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Reads Scott Cinemas' public JSON listings feed, documented at
+    # https://www.scottcinemas.co.uk/api. Each venue's feed holds every
+    # advertised date.
+    class Feed
+      include Http
+
+      URL = 'https://www.scottcinemas.co.uk/json.php'
+
+      # @param [String] code a venue's feed code, e.g. 'SCOBAR'
+      # @return [Hash] the feed: 'cinema', 'films' by id, and 'schedule' of
+      #   showtimes by local midnight, then screen, then start, each a Unix
+      #   timestamp
+      def listings(code)
+        JSON.parse(get("#{URL}?cinema=#{CGI.escape(code)}"))
+      end
+    end
+  end
+end

data/lib/scott_uk/internal/http.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'net/http'
+
+module ScottUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Requests to scottcinemas.co.uk
+    module Http
+      RETRIES = 2
+      TRANSIENT_ERRORS = [
+        EOFError, Errno::ECONNRESET, Errno::ECONNREFUSED, Net::OpenTimeout, Net::ReadTimeout, OpenSSL::SSL::SSLError
+      ].freeze
+
+      private
+
+      def get(url)
+        uri = URI(url)
+        attempts = 0
+        begin
+          response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 30) do |http|
+            http.request(Net::HTTP::Get.new(uri))
+          end
+        rescue *TRANSIENT_ERRORS
+          attempts += 1
+          raise if attempts > RETRIES
+
+          sleep(attempts)
+          retry
+        end
+        # Omit response bodies from errors, and never follow redirects.
+        raise "Scott Cinemas HTTP error #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+        String.new(response.body, encoding: Encoding::UTF_8)
+      end
+    end
+  end
+end

data/lib/scott_uk/internal/parser/showtime.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module ScottUk
+  # @api private
+  module Internal
+    module Parser
+      # Parses one showtime from the feed into performance attributes
+      class Showtime
+        # Showtime flags and the variants they mean. Others, such as 'STB'
+        # (strobe lighting), 'ATF' (all tickets £5), 'LUX' and 'DOL' (screen
+        # formats), are not variants.
+        FLAGS = {
+          'AFS' => 'relaxed',
+          'ART' => 'arts',
+          'BAL' => 'arts',
+          'ECA' => 'arts',
+          'ETV' => 'arts',
+          'MSC' => 'arts',
+          'MUS' => 'arts',
+          'OPE' => 'arts',
+          'PBB' => 'baby',
+          'SSC' => 'senior',
+          'THE' => 'arts'
+        }.freeze
+
+        # Yes/no fields and the variants they mean. Most screenings offer
+        # audio description, so it does not mark one out.
+        FIELDS = {
+          'AFS' => 'relaxed',
+          'subtitles' => 'subtitled'
+        }.freeze
+
+        YES = 'Y'
+        FESTIVAL_FLAG = 'EVF'
+        FESTIVAL = 'Exmouth Film Festival'
+        THREE_D = /\A3D\z/i
+        LANGUAGE = /\((#{Cinebase::TitleSanitizer::LANGUAGES.join('|')})\)/i
+
+        # @param [Hash] showtime one showtime from the feed's schedule
+        # @param [Hash] film the feed's film for the showtime
+        # @param [Time] starting_at from the showtime's Unix timestamp
+        def initialize(showtime, film:, starting_at:)
+          @showtime = showtime
+          @film = film
+          @starting_at = starting_at
+        end
+
+        # @return [Hash] options for ScottUk::Performance.new
+        def to_hash
+          {
+            booking_url: @showtime['booking_url'],
+            dimension: @showtime['performance_type'].to_s.match?(THREE_D) ? '3d' : '2d',
+            festival: festival,
+            film_name: TitleSanitizer.new(title).sanitized,
+            film_year: Cinebase::TitleSanitizer.film_year(title),
+            language: title[LANGUAGE, 1],
+            starting_at: @starting_at,
+            variant: variant
+          }
+        end
+
+        private
+
+        def flags
+          Array(@showtime['flags'])
+        end
+
+        def festival
+          if flags.include?(FESTIVAL_FLAG)
+            Cinebase::Festival.new(name: FESTIVAL, year: @starting_at.year)
+          else
+            Cinebase::Festival.from_title(title, year: @starting_at.year)
+          end
+        end
+
+        def title
+          @title ||= CGI.unescapeHTML(@film.fetch('name')).strip
+        end
+
+        def variant
+          from_fields = FIELDS.filter_map { |field, variant| variant if @showtime[field] == YES }
+          (flags.filter_map { |flag| FLAGS[flag] } + from_fields).uniq
+        end
+      end
+    end
+  end
+end

data/lib/scott_uk/internal/title_sanitizer.rb

@@ -0,0 +1,36 @@
+module ScottUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Sanitize and standardize film titles
+    class TitleSanitizer < Cinebase::TitleSanitizer
+      # @!method initialize(title)
+      #   Constructor
+      #   @param [String] title a film title
+      #   @return [ScottUk::Internal::TitleSanitizer]
+
+      # @!method sanitized
+      #   sanitized and standardized title
+      #   @return [String] sanitised title
+
+      private
+
+      # strings and regex to be removed
+      def remove
+        [
+          /\s*\(Parent and Baby Only Show\)/i,                  # parent and baby screening
+          /\s*(?:-\s+|\()Exmouth Film Festival\)?/i,            # festival suffix
+          /\ASFS:\s*/                                           # film society prefix
+        ] + COMMON_REMOVE
+      end
+
+      # regexes and their replacements
+      def replace
+        {
+          /\ARBO \d{2}-\d{2}: (.*)/i            => 'Royal Ballet and Opera: ',
+          /\ANATIONAL THEATRE LIVE: (.*)/i      => 'National Theatre Live: '
+        }.merge(COMMON_REPLACE)
+      end
+    end
+  end
+end

data/lib/scott_uk/performance.rb

@@ -0,0 +1,90 @@
+module ScottUk
+  # A single screening of a film on the Scott Cinemas website
+  class Performance < Cinebase::Performance
+    # @!attribute [r] booking_url
+    #   @return [String] the booking URL on the cinema website
+    # @!attribute [r] cinema_name
+    #   @return [String] the cinema name
+    # @!attribute [r] cinema_id
+    #   @return [String] the cinema id
+    # @!attribute [r] dimension
+    #   @return [String] 2d or 3d
+    # @!attribute [r] film_name
+    #   @return [String] the film name
+
+    # @!method initialize(options)
+    #   @param [Hash] options options hash
+    #   @option options [String] :booking_url (nil) buying url for the screening
+    #   @option options [String] :cinema_name name of the cinema
+    #   @option options [String] :cinema_id website id of the cinema
+    #   @option options [String] :dimension ('2d') dimension of the screening
+    #   @option options [Cinebase::Festival] :festival (nil) festival edition
+    #   @option options [String] :film_name name of the film
+    #   @option options [Integer] :film_year (nil) year from the film's title
+    #   @option options [String] :language (nil) audio language, e.g. 'Hindi'
+    #   @option options [Time] :starting_at listed start time of the performance
+
+    TIME_ZONE = 'Europe/London'.freeze
+
+    # Performances within an inclusive range of showing dates, from one
+    # request: the venue's feed holds every advertised date.
+    # @param [String] cinema_id the cinema's feed code, e.g. 'SCOBAR'
+    # @param [Date] from first date (defaults to today in London)
+    # @param [Date] to last date (defaults to 13 days after from)
+    # @return [Array<ScottUk::Performance>]
+    def self.at(
+      cinema_id,
+      from: TZInfo::Timezone.get(TIME_ZONE).now.to_date,
+      to: from + 13
+    )
+      raise ArgumentError, 'to must not precede from' if to < from
+
+      cinema = Cinema.new(cinema_id)
+      if cinema.name.empty?
+        []
+      else
+        feed = ScottUk::Internal::Feed.new.listings(cinema.id)
+        performances = showtimes_between(feed, from, to).map do |showtime, film, starting_at|
+          parsed = ScottUk::Internal::Parser::Showtime.new(showtime, film: film, starting_at: starting_at)
+          new(parsed.to_hash.merge(cinema_id: cinema.id, cinema_name: cinema.name))
+        end
+        performances.sort_by(&:starting_at)
+      end
+    end
+
+    # @!method showing_on
+    #   The date of the screening
+    #   @return [Date]
+
+    # @!method starting_at
+    #   UTC time of the screening
+    #   @return [Time]
+
+    # @!method variant
+    #   The kinds of screening (arts, audio_described, baby, relaxed ...)
+    #   @return <Array[String]>
+
+    # PHP sends an empty schedule, day or screen as [] rather than {}
+    def self.showtimes_between(feed, from, to)
+      films = Hash(feed['films'])
+      Hash(feed['schedule']).flat_map do |midnight, screens|
+        if (from..to).cover?(london_date(midnight))
+          Hash(screens).values.flat_map do |showtimes|
+            Hash(showtimes).filter_map do |timestamp, showtime|
+              film = films[showtime['film_id']]
+              [showtime, film, Time.at(timestamp.to_i).utc] if film
+            end
+          end
+        else
+          []
+        end
+      end
+    end
+    private_class_method :showtimes_between
+
+    def self.london_date(timestamp)
+      TZInfo::Timezone.get(TIME_ZONE).to_local(Time.at(timestamp.to_i).utc).to_date
+    end
+    private_class_method :london_date
+  end
+end

data/lib/scott_uk/version.rb

@@ -0,0 +1,6 @@
+# Ruby interface for https://www.scottcinemas.co.uk
+# @version 1.0.0
+module ScottUk
+  # Gem version
+  VERSION = '1.0.0'.freeze
+end

data/lib/scott_uk.rb

@@ -0,0 +1,18 @@
+require 'cgi/escape'
+require 'json'
+
+require 'cinebase'
+
+require_relative './scott_uk/version'
+
+require_relative './scott_uk/internal/http'
+require_relative './scott_uk/internal/feed'
+require_relative './scott_uk/internal/title_sanitizer'
+require_relative './scott_uk/internal/parser/showtime'
+
+require_relative './scott_uk/cinema'
+require_relative './scott_uk/performance'
+
+# scott_uk gem
+module ScottUk
+end