gft_uk 1.0.0

data/README.md

@@ -0,0 +1,166 @@
+# GftUk
+
+A simple gem to pull the cinema and its performances from the [Glasgow Film Theatre website](https://www.glasgowfilm.org) and spit out useful formatted info.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'gft_uk'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install gft_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.
+
+No token or setup is needed. The website is a single page app on Indy
+Systems, the Indy Cinema Group's platform. It reads its listings from a
+GraphQL API at `/graphql`, which answers consumer queries that send the
+headers `Client-Type: consumer` and `Site-Id: 103`. The gem asks the same
+API.
+
+### Cinema
+
+Glasgow Film Theatre has one venue, keyed by its Indy site id, `103`. The
+website gives no address or coordinates, so the gem holds them, from
+OpenStreetMap. Cinema methods make no requests.
+
+``` ruby
+GftUk::Cinema.all
+#=> [<GftUk::Cinema ...>]
+
+cinema = GftUk::Cinema.new('103')
+#=> <GftUk::Cinema ...>
+
+cinema.adr
+#=> {
+  street_address:   '12 Rose Street',
+  extended_address: nil,
+  locality:         'Glasgow',
+  region:           nil,
+  postal_code:      'G3 6RB',
+  country_name:     'United Kingdom'
+}
+
+cinema.brand
+#=> 'Independent'
+
+cinema.name
+#=> 'Glasgow Film Theatre'
+
+cinema.id
+#=> '103'
+
+cinema.latitude
+#=> 55.8657225
+
+cinema.url
+#=> 'https://www.glasgowfilm.org'
+```
+
+### Performances
+
+`Performance.at` returns performances for an inclusive range of showing dates,
+defaulting to today in London and the following 13 days. The API lists the
+dates with showings in one request. The gem then asks for ten of those dates
+at a time, as aliased `showingsForDate` queries in one request. A year ahead
+is about six requests.
+
+``` ruby
+GftUk::Performance.at('103', from: Date.today, to: Date.today + 365)
+#=> [<GftUk::Performance ...>, <GftUk::Performance ...>, ...]
+
+performance = GftUk::Performance.at('103', from: Date.today, to: Date.today + 365).first
+#=> <GftUk::Performance ...>
+
+performance.film_name
+#=> 'The Money Maker' # from 'FFF: The Money Maker + Q&A'
+
+performance.film_year
+#=> 2026
+
+performance.dimension
+#=> '2d'
+
+performance.variant
+#=> ['q&a', 'subtitled']
+
+performance.subtitled?
+#=> true
+
+performance.festival
+#=> #<data Cinebase::Festival name="French Film Festival", year=2026>
+
+performance.starting_at
+#=> 2026-11-21 17:00:00 UTC
+
+performance.booking_url
+#=> 'https://www.glasgowfilm.org/checkout/showing/fff-the-money-maker-qa/500092/'
+
+performance.cinema_name
+#=> 'Glasgow Film Theatre'
+
+performance.cinema_id
+#=> '103'
+```
+
+Booking links open the website's ticket step for the showing. Sold out
+screenings, with no seats remaining, are listed with no booking link.
+
+Only films are listed. Showings that are unpublished or private, festival
+passes such as 'Scotland Loves Anime 2026 Weekend Pass', workshops, and title
+classes for live events, talks, television and education are dropped. Event
+cinema, such as National Theatre Live, is kept.
+
+Variants come from each showing's badges and from titles: `audio_described`,
+`subtitled` (subtitled, captioned and deaf friendly screenings), `relaxed`
+(autism and dementia friendly), `kids` (the Take 2 children's strand), `q&a`,
+`35mm`, `70mm` and `arts` (event cinema). 4K, introductions, previews and BSL
+interpretation are not variants.
+
+Festivals come from badges (French Film Festival, Glasgow Film Festival,
+GYFF, SLA, SMHAF) and from the `FFF:` title prefix. Film years come from a
+year in the title, or else the film's release date.
+
+Titles are cleaned up:
+
+- Festival and strand prefixes go: 'FFF:', 'Take 2:', 'Take 2 Access:',
+  'Access Film Club:', 'Movie Memories:', 'Youth Screening:' and 'Preview:'.
+- Anniversaries, restorations and prints go: 'Marie Antoinette - 20th
+  Anniversary - 4K', 'Short Cuts - 35mm', 'A Silent Voice (10th Anniversary)'.
+- Add-ons go: '+ Q&A', '+ discussion', '+ introduction'.
+- 'NT Live:' becomes 'National Theatre Live:'.
+
+## Tests
+
+```sh
+bundle exec rake                # unit tests against fixtures
+LIVE=1 bundle exec rake live    # live glasgowfilm.org
+```
+
+The fixtures in `test/fixtures` are GraphQL responses: every advertised date,
+and a few films on some of those dates. `test/support/api_shapes.rb`
+describes the fields the gem reads. The unit suite checks the fixtures against
+it and the live suite checks real responses, held only in memory. When the API
+changes, update the shape first, then the fixtures.
+
+## 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/gft_uk/cinema.rb

@@ -0,0 +1,100 @@
+module GftUk
+  # The object representing Glasgow Film Theatre
+  class Cinema < Cinebase::Cinema
+    # @!attribute [r] id
+    #   @return [String] the cinema's Indy Systems site id, '103'
+
+    # The cinema has one venue, keyed by the site id its website's GraphQL
+    # API takes. The website gives no address or coordinates, so the gem
+    # holds them.
+    VENUES = {
+      '103' => {
+        name: 'Glasgow Film Theatre', street_address: '12 Rose Street', locality: 'Glasgow',
+        postal_code: 'G3 6RB', latitude: 55.8657225, longitude: -4.2612728
+      }
+    }.freeze
+
+    ADDRESS_PARTS = %i(street_address extended_address locality region postal_code).freeze
+    URL = 'https://www.glasgowfilm.org'.freeze
+
+    # Constructor
+    # @param [Integer, String] id the cinema's Indy site id, 103 or '103'
+    # @return [GftUk::Cinema]
+    def initialize(id)
+      @id = id.to_s
+    end
+
+    # Return basic cinema information for all cinemas
+    # @return [Array<GftUk::Cinema>] the one cinema
+    # @example
+    #   GftUk::Cinema.all
+    #   #=> [<GftUk::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 = GftUk::Cinema.new('103')
+    #   cinema.adr
+    #   #=> {
+    #         street_address:   '12 Rose Street',
+    #         extended_address: nil,
+    #         locality:         'Glasgow',
+    #         region:           nil,
+    #         postal_code:      'G3 6RB',
+    #         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 'Independent'
+    def brand
+      'Independent'.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
+    #   GftUk::Cinema.new('103').name
+    #   #=> 'Glasgow Film Theatre'
+    def name
+      venue[:name].to_s
+    end
+
+    # The url of the cinema's website
+    # @return [String]
+    # @example
+    #   GftUk::Cinema.new('103').url
+    #   #=> 'https://www.glasgowfilm.org'
+    def url
+      venue.empty? ? '' : URL
+    end
+
+    private
+
+    def venue
+      VENUES.fetch(id, {})
+    end
+  end
+end

data/lib/gft_uk/internal/graphql.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+
+module GftUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Posts queries to the consumer GraphQL API of a website built on Indy
+    # Systems, the Indy Cinema Group's platform
+    class Graphql
+      RETRIES = 2
+      TRANSIENT_ERRORS = [
+        EOFError, Errno::ECONNRESET, Errno::ECONNREFUSED, Net::OpenTimeout, Net::ReadTimeout, OpenSSL::SSL::SSLError
+      ].freeze
+
+      # @param [String] url the website's GraphQL endpoint
+      # @param [String] site_id the venue's Indy site id
+      def initialize(url, site_id:)
+        @uri = URI(url)
+        @site_id = site_id
+      end
+
+      # @param [String] document a GraphQL query
+      # @param [Hash] variables the query's variables
+      # @return [Hash] the response's data
+      def query(document, variables = {})
+        body = JSON.parse(post(JSON.generate(query: document, variables: variables)))
+        # Indy reports a failed query in one 'error' object, not an 'errors' list
+        error = body['error'] || Array(body['errors']).first
+        if error
+          raise "Indy GraphQL error: #{error['message']}"
+        else
+          body.fetch('data')
+        end
+      end
+
+      private
+
+      # Indy refuses consumer queries that name no site
+      def post(body)
+        request = Net::HTTP::Post.new(@uri)
+        request['Content-Type'] = 'application/json'
+        request['Client-Type'] = 'consumer'
+        request['Site-Id'] = @site_id
+        request.body = body
+        response = with_retries { connection.request(request) }
+        # Omit response bodies from errors, and never follow redirects.
+        raise "Indy HTTP error #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+        String.new(response.body, encoding: Encoding::UTF_8)
+      end
+
+      # Net::HTTP never retries a POST itself
+      def with_retries
+        attempts = 0
+        begin
+          yield
+        rescue *TRANSIENT_ERRORS
+          attempts += 1
+          raise if attempts > RETRIES
+
+          @connection = nil
+          sleep(attempts)
+          retry
+        end
+      end
+
+      # One connection for all of an import's requests
+      def connection
+        @connection ||= Net::HTTP.start(@uri.host, @uri.port, use_ssl: true, open_timeout: 10, read_timeout: 60)
+      end
+    end
+  end
+end

data/lib/gft_uk/internal/indy.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module GftUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Reads a venue's listings from a website built on Indy Systems
+    class Indy
+      # Dates are aliased showingsForDate queries in one request. Ten keeps
+      # each response to a couple of seconds.
+      DATES_PER_REQUEST = 10
+
+      DATES_QUERY = <<~GRAPHQL
+        query ($siteIds: [ID]) { datesWithShowing(siteIds: $siteIds) { value } }
+      GRAPHQL
+
+      SHOWING_FIELDS = <<~GRAPHQL
+        data {
+          id time published private seatsRemaining
+          showingBadges { displayName }
+          movie { id name urlSlug releaseDate titleClass { name } }
+        }
+      GRAPHQL
+
+      # @param [String] url the website's home page
+      # @param [String] site_id the venue's Indy site id
+      def initialize(url, site_id:)
+        @graphql = Graphql.new("#{url}/graphql", site_id: site_id)
+        @site_id = site_id
+      end
+
+      # @return [Array<Date>] every date with showings on sale
+      def dates
+        value = @graphql.query(DATES_QUERY, siteIds: [@site_id]).dig('datesWithShowing', 'value')
+        JSON.parse(value).map { |date| Date.iso8601(date) }
+      end
+
+      # @param [Array<Date>] dates listings dates, in London
+      # @return [Array<Hash>] the showings on those dates, each with its movie
+      def showings(dates)
+        dates.each_slice(DATES_PER_REQUEST).flat_map do |slice|
+          variables = slice.each_with_index.to_h { |date, index| ["d#{index}", date.iso8601] }
+          data = @graphql.query(showings_query(variables.keys), variables.merge('siteIds' => [@site_id]))
+          variables.keys.flat_map { |key| data.dig(key, 'data') || [] }
+        end
+      end
+
+      private
+
+      def showings_query(keys)
+        params = keys.map { |key| "$#{key}: String" }.join(', ')
+        fields = keys.map { |key| "#{key}: showingsForDate(date: $#{key}, siteIds: $siteIds) { #{SHOWING_FIELDS} }" }
+        "query (#{params}, $siteIds: [ID]) { #{fields.join(' ')} }"
+      end
+    end
+  end
+end

data/lib/gft_uk/internal/parser/showing.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module GftUk
+  # @api private
+  module Internal
+    module Parser
+      # Parses a single Indy showing into performance attributes
+      class Showing
+        BOOKING_PATH = '/checkout/showing/'
+
+        # Showing badges and the variants they mean. 'Subtitled' marks
+        # foreign language films. Others, such as 'Accessible', '4K Screening',
+        # 'Introduction', 'Preview' and 'BSL Interpretation', are not variants.
+        BADGES = {
+          '35mm Screening' => %w(35mm),
+          '70mm Screening' => %w(70mm),
+          'Access Take 2' => %w(kids relaxed),
+          'As Live' => %w(arts),
+          'Audio Described' => %w(audio_described),
+          'Autism Friendly' => %w(relaxed),
+          'Captioned' => %w(subtitled),
+          'Deaf-friendly' => %w(subtitled),
+          'Dementia Friendly' => %w(relaxed),
+          'Event Cinema' => %w(arts),
+          'Event Cinema - Encore' => %w(arts),
+          'Q&A' => %w(q&a),
+          'Recorded Q&A' => %w(q&a),
+          'Subtitled' => %w(subtitled),
+          'Take 2' => %w(kids)
+        }.freeze
+
+        # Retired badges stay on old showings with this suffix, e.g.
+        # 'Take 2 - don't use'
+        RETIRED = /\s*-\s*don['’]t use\z/i
+
+        # Event cinema title classes, e.g. 'Event Cinema - Encore'
+        EVENT_CINEMA = /\AEvent Cinema\b/
+
+        # Badges naming a festival, with its edition when given
+        FESTIVALS = {
+          /\AFrench Film Festival\z/ => 'French Film Festival',
+          /\AGlasgow Film Festival\z/ => 'Glasgow Film Festival',
+          /\AGYFF\z/ => 'Glasgow Youth Film Festival',
+          /\ASLA (20\d{2})\z/ => 'Scotland Loves Anime',
+          /\ASMHAF\z/ => 'Scottish Mental Health Arts Festival'
+        }.freeze
+
+        # Title prefixes naming a festival
+        TITLE_FESTIVALS = {
+          /\AFFF: / => 'French Film Festival'
+        }.freeze
+
+        TITLE_VARIANTS = {
+          /\b35mm\b/i => '35mm',
+          /\b70mm\b/i => '70mm',
+          /\bQ&A\b/i => 'q&a'
+        }.freeze
+
+        # Title classes for live events, talks and classes, e.g. 'GFT Live
+        # Event', 'GFF Events', 'Workshops' and 'Education'
+        NON_FILM_CLASSES = /\b(?:Live|Guest|Television) Event\b|\bEvents\b|\bWorkshops?\b|\bEducation\b/i
+        NON_FILM_BADGES = %w(Workshop).freeze
+        # Festival passes are sold as showings, e.g. 'Scotland Loves Anime
+        # 2026 Weekend Pass'
+        NON_FILM_TITLES = /\b(?:Pass|Gift Card|Voucher|Membership)\z/i
+
+        THREE_D = /\b3D\b/i
+        TIME_ZONE = 'Europe/London'
+
+        # @param [Hash] showing one showing, with its movie
+        # @param [String] url the website's home page
+        def initialize(showing, url:)
+          @showing = showing
+          @url = url
+        end
+
+        # Films only, on public sale
+        # @return [Boolean]
+        def film?
+          public? && !title.match?(NON_FILM_TITLES) && !title_class.match?(NON_FILM_CLASSES) &&
+            !badges.intersect?(NON_FILM_BADGES)
+        end
+
+        # @return [Hash] options for GftUk::Performance.new
+        def to_hash
+          {
+            booking_url: booking_url,
+            dimension: title.match?(THREE_D) ? '3d' : '2d',
+            festival: festival,
+            film_name: TitleSanitizer.new(title).sanitized,
+            film_year: Cinebase::TitleSanitizer.film_year(title) || release_year,
+            starting_at: starting_at,
+            variant: variant
+          }
+        end
+
+        private
+
+        def badges
+          @badges ||= @showing.fetch('showingBadges', []).map { |badge| badge.fetch('displayName').strip.sub(RETIRED, '') }
+        end
+
+        # Sold out showings have no seats remaining
+        def booking_url
+          if @showing['seatsRemaining'].to_i.positive?
+            "#{@url}#{BOOKING_PATH}#{movie['urlSlug'] || movie['id']}/#{@showing.fetch('id')}/"
+          end
+        end
+
+        def festival
+          Cinebase::Festival.from_title(title, year: london_year) || badge_festival || title_festival
+        end
+
+        def badge_festival
+          badges.each do |badge|
+            FESTIVALS.each do |pattern, name|
+              match = badge.match(pattern)
+              return Cinebase::Festival.new(name: name, year: Integer(match[1] || london_year)) if match
+            end
+          end
+          nil
+        end
+
+        def title_festival
+          name = TITLE_FESTIVALS.find { |pattern, _| title.match?(pattern) }&.last
+          Cinebase::Festival.new(name: name, year: london_year) if name
+        end
+
+        def london_year
+          TZInfo::Timezone.get(TIME_ZONE).to_local(starting_at).year
+        end
+
+        def movie
+          @showing.fetch('movie')
+        end
+
+        def public?
+          @showing['published'] != false && @showing['private'] != true
+        end
+
+        def release_year
+          movie['releaseDate']&.slice(0, 4)&.to_i
+        end
+
+        # Times are UTC, e.g. '2026-11-01T12:00:00Z'
+        def starting_at
+          @starting_at ||= Time.iso8601(@showing.fetch('time')).utc
+        end
+
+        def title
+          @title ||= movie.fetch('name').strip
+        end
+
+        def title_class
+          movie.dig('titleClass', 'name').to_s
+        end
+
+        def variant
+          variants = badges.flat_map { |badge| BADGES.fetch(badge, []) }
+          variants << 'arts' if title_class.match?(EVENT_CINEMA)
+          variants += TITLE_VARIANTS.filter_map { |pattern, name| name if title.match?(pattern) }
+          variants.uniq
+        end
+      end
+    end
+  end
+end

data/lib/gft_uk/internal/title_sanitizer.rb

@@ -0,0 +1,41 @@
+module GftUk
+  # 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 [GftUk::Internal::TitleSanitizer]
+
+      # @!method sanitized
+      #   sanitized and standardized title
+      #   @return [String] sanitised title
+
+      private
+
+      # strings and regex to be removed
+      def remove
+        [
+          /\AFFF:\s*/,                                 # French Film Festival
+          /\ATake 2(?: Access)?:\s*/i,                 # children's strand
+          /\AAccess Film Club:\s*/i,                   # autism friendly strand
+          /\AMovie Memories:\s*/i,                     # dementia friendly strand
+          /\AYouth Screening:\s*/i,                    # 15-25 strand
+          /\APreview:\s*/i,                            # preview
+          /\s+-\s+\d+(?:st|nd|rd|th) Anniversary\b/i,  # anniversary re-release
+          /\s+-\s+(?:4K|35mm|70mm)\b/i,                # restoration or print
+          /\s*\+\s*Introduction\z/i                    # introduction add-on
+        ] + COMMON_REMOVE
+      end
+
+      # regexes and their replacements
+      def replace
+        {
+          /\A(?:NT|National Theatre) Live:\s*(.*)/ => 'National Theatre Live: '
+        }.merge(COMMON_REPLACE)
+      end
+    end
+  end
+end

data/lib/gft_uk/performance.rb

@@ -0,0 +1,77 @@
+module GftUk
+  # A single screening of a film on the Glasgow Film Theatre website
+  class Performance < Cinebase::Performance
+    # @!attribute [r] booking_url
+    #   @return [String, nil] the booking URL, nil when sold out
+    # @!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 of the film
+    #   @option options [Time] :starting_at listed start time of the performance
+
+    TIME_ZONE = 'Europe/London'.freeze
+
+    # Performances within an inclusive range of showing dates: one request
+    # for the dates with showings, then one for every ten of those dates.
+    # @param [Integer, String] cinema_id the cinema's Indy site id, '103'
+    # @param [Date] from first date (defaults to today in London)
+    # @param [Date] to last date (defaults to 13 days after from)
+    # @return [Array<GftUk::Performance>]
+    def self.at(
+      cinema_id,
+      from: today,
+      to: from + 13
+    )
+      raise ArgumentError, 'to must not precede from' if to < from
+
+      cinema = Cinema.new(cinema_id)
+      if cinema.name.empty?
+        []
+      else
+        performances = showings(cinema, from..to).map do |showing|
+          new(showing.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, kids, relaxed, subtitled ...)
+    #   @return <Array[String]>
+
+    def self.today
+      TZInfo::Timezone.get(TIME_ZONE).now.to_date
+    end
+    private_class_method :today
+
+    def self.showings(cinema, dates)
+      indy = GftUk::Internal::Indy.new(cinema.url, site_id: cinema.id)
+      indy.showings(indy.dates.select { |date| dates.cover?(date) })
+          .map { |showing| GftUk::Internal::Parser::Showing.new(showing, url: cinema.url) }
+          .select(&:film?)
+    end
+    private_class_method :showings
+  end
+end

data/lib/gft_uk/version.rb

@@ -0,0 +1,6 @@
+# Ruby interface for https://www.glasgowfilm.org
+# @version 1.0.0
+module GftUk
+  # Gem version
+  VERSION = '1.0.0'.freeze
+end