light_uk 1.0.0

data/README.md

@@ -0,0 +1,150 @@
+# LightUk
+
+A simple gem to pull cinemas and performances from the [Light cinemas website](https://thelight.co.uk) and spit out useful formatted info.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'light_uk'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install light_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 language
+versions, years, anniversary restorations, Q&A add-ons and festival prefixes.
+
+No token or setup is needed. Each venue has its own site, such as
+`https://sheffield.thelight.co.uk`, built by Glitterfish. Every venue's home
+page lists all the venues and shows its own address.
+
+### Cinema
+
+The venue list is cached for an hour. The first call to an address method reads
+the cinema's home page. The website gives no coordinates, so `latitude` and
+`longitude` are `nil`.
+
+``` ruby
+LightUk::Cinema.all
+#=> [<LightUk::Cinema ...>, <LightUk::Cinema ...>, ...]
+
+cinema = LightUk::Cinema.new(3)
+#=> <LightUk::Cinema ...>
+
+cinema.adr
+#=> {
+  street_address:   'Cambridge Leisure Park',
+  extended_address: 'Clifton Way',
+  locality:         'Cambridge',
+  region:           nil,
+  postal_code:      'CB1 7DY',
+  country_name:     'United Kingdom'
+}
+
+cinema.brand
+#=> 'Light'
+
+cinema.full_name
+#=> 'Light Cambridge'
+
+cinema.id
+#=> '3'
+
+cinema.url
+#=> 'https://cambridge.thelight.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 guide only
+covers a fortnight, so it also reads the coming soon page, which holds every
+session of films that have not opened yet, however far ahead. That is two
+requests for all of the cinema's advertised dates.
+
+``` ruby
+LightUk::Performance.at(3, from: Date.today, to: Date.today + 2)
+#=> [<LightUk::Performance ...>, <LightUk::Performance ...>, ...]
+
+performance = LightUk::Performance.at(3).first
+#=> <LightUk::Performance ...>
+
+performance.film_name
+#=> 'Ramayana: Rise of a Legend'
+
+performance.language
+#=> 'Hindi' # from '(Hindi)' in the title
+
+performance.film_year
+#=> nil # from the title, e.g. 1996 for 'From Dusk Till Dawn (1996)'
+
+performance.dimension
+#=> '3d'
+
+performance.variant
+#=> ['imax']
+
+performance.subtitled?
+#=> false
+
+performance.festival
+#=> nil # e.g. #<data Cinebase::Festival name="CFF", year=2026>
+
+performance.starting_at
+#=> 2026-11-08 19:50:00 UTC
+
+performance.booking_url
+#=> 'https://cambridge.thelight.co.uk/#!book/cinema/83478'
+
+performance.cinema_name
+#=> 'Cambridge'
+
+performance.cinema_id
+#=> '3'
+```
+
+Booking links open the booking panel on the venue's home page. Sessions that
+have started have no booking link.
+
+Variants are `arts`, `audio_described`, `baby`, `imax`, `kids`, `q&a`,
+`relaxed`, `senior` and `subtitled`.
+
+## Tests
+
+```sh
+bundle exec rake          # unit tests against fixtures
+bundle exec rake live     # live thelight.co.uk
+```
+
+Fixtures in `test/fixtures` are pages captured from the Cambridge venue's
+website and trimmed to a few films. `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 website
+changes, update the shape first, then the fixtures.
+
+The website's certificate chains to Sectigo's Public Server Authentication Root
+R46. Trust stores without it, such as macOS's `/etc/ssl/cert.pem`, fail to
+verify it; point `SSL_CERT_FILE` at a current Mozilla bundle instead.
+
+## 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/light_uk/cinema.rb

@@ -0,0 +1,112 @@
+module LightUk
+  # The object representing a cinema on the Light website
+  class Cinema < Cinebase::Cinema
+    # @!attribute [r] id
+    #   @return [String] the Light id of the cinema, e.g. '7'
+
+    # Worker processes outlive a day's listings, so refetch the venue list
+    CACHE_SECONDS = 3600
+
+    # UK postcode, the last part of an address
+    POSTCODE = /\A[A-Z]{1,2}\d[A-Z\d]? ?\d[A-Z]{2}\z/i.freeze
+
+    # Constructor
+    # @param [Integer, String] id the cinema id of the format 7/'7'
+    # @return [LightUk::Cinema]
+    def initialize(id)
+      @id = id.to_s
+    end
+
+    # Return basic cinema information for all cinemas
+    # @return [Array<LightUk::Cinema>]
+    # @example
+    #   LightUk::Cinema.all
+    #   #=> [<LightUk::Cinema>, <LightUk::Cinema>, ...]
+    def self.all
+      sites_hash.keys.map { |id| new(id) }
+    end
+
+    # @!method address
+    #   Address of the cinema
+    #   @return [Hash] of different address parts
+    #   @see #adr
+
+    # Address of the cinema, read from the footer of its home page
+    # @return [Hash] contains :street_address, :extended_address,
+    # :locality, :region, :postal_code, :country_name
+    # @example
+    #   cinema = LightUk::Cinema.new(3)
+    #   cinema.adr
+    #   #=> {
+    #         street_address:   'Cambridge Leisure Park',
+    #         extended_address: 'Clifton Way',
+    #         locality:         'Cambridge',
+    #         region:           nil,
+    #         postal_code:      'CB1 7DY',
+    #         country_name:     'United Kingdom'
+    #       }
+    # @note Uses method naming as at http://microformats.org/wiki/adr
+    def adr
+      parts = address_parts
+      postal_code = parts.pop if parts.last&.match?(POSTCODE)
+      # Some addresses leave out the town, which every venue is named after
+      town_at = parts.index(name) || parts.size
+      lines = parts.first(town_at)
+      region = parts.drop(town_at + 1)
+      {
+        street_address:   lines.shift,
+        extended_address: lines.empty? ? nil : lines.join(', '),
+        locality:         name,
+        region:           region.empty? ? nil : region.join(', '),
+        postal_code:      postal_code,
+        country_name:     'United Kingdom'.freeze
+      }
+    end
+
+    # Brand of the cinema
+    # @return [String] which will always be 'Light'
+    def brand
+      'Light'.freeze
+    end
+
+    # The name of the cinema
+    # @return [String]
+    # @example
+    #   LightUk::Cinema.new(7).name
+    #   #=> 'Sheffield'
+    def name
+      site['title'].to_s
+    end
+
+    # The url of the cinema's home page on the Light website
+    # @return [String]
+    # @example
+    #   LightUk::Cinema.new(7).url
+    #   #=> 'https://sheffield.thelight.co.uk'
+    def url
+      site['url'].to_s
+    end
+
+    # @api private
+    def self.sites_hash
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      if @sites_hash.nil? || now - @fetched_at > CACHE_SECONDS
+        @fetched_at = now
+        @sites_hash = LightUk::Internal::Website.new.sites.to_h { |site| [site.fetch('id').to_s, site] }
+      end
+      @sites_hash
+    end
+    private_class_method :sites_hash
+
+    private
+
+    def address_parts
+      @address ||= LightUk::Internal::Website.new.address(url).to_s
+      @address.split(',').map(&:strip).reject(&:empty?)
+    end
+
+    def site
+      self.class.send(:sites_hash).fetch(id, {})
+    end
+  end
+end

data/lib/light_uk/internal/http.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "net/http"
+
+module LightUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Requests to thelight.co.uk
+    module Http
+      private
+
+      def get(url)
+        uri = URI(url)
+        request = Net::HTTP::Get.new(uri)
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: true,
+                                                       open_timeout: 10, read_timeout: 30) do |http|
+          http.request(request)
+        end
+        # Omit response bodies from errors, and never follow redirects.
+        raise "Light HTTP error #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+        String.new(response.body, encoding: Encoding::UTF_8)
+      end
+    end
+  end
+end

data/lib/light_uk/internal/parser/coming_soon.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "json"
+
+module LightUk
+  # @api private
+  module Internal
+    module Parser
+      # Reads the films and sessions embedded in a venue's coming soon page
+      class ComingSoon
+        # Each film's markup starts with its programme id
+        FILM = /<div data-prog="(\d+)" class="prog">/
+        TITLE = %r{<h2><a href="[^"]*">(.*?)</a></h2>}m
+
+        # @param [String] html the coming soon page
+        def initialize(html)
+          @html = html
+        end
+
+        # @return [Array<Hash>] films in the shape of the miniguide's Schedule
+        def films
+          @html.split(FILM).drop(1).each_slice(2).filter_map do |id, markup|
+            title = markup[TITLE, 1]
+            dates = markup[/ScheduleBrowser\(\{selector: '#prog-#{id}'.*?, data:(\[.*?\])\}\)\}\);<\/script>/m, 1]
+            if title && dates
+              { "ID" => id.to_i, "Title" => title, "Dates" => JSON.parse(dates) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/light_uk/internal/parser/session.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module LightUk
+  # @api private
+  module Internal
+    module Parser
+      # Parses a single Light session into performance attributes
+      class Session
+        # Booking opens in a panel on the venue's home page
+        BOOKING_PATH = "/#!book/cinema/"
+
+        # Light collection titles
+        VARIANTS = {
+          "Audio Description" => "audio_described",
+          "Baby-friendly screenings" => "baby",
+          "Captioned for hard of hearing" => "subtitled",
+          "Dementia-friendly screenings" => "relaxed",
+          "Family Specials" => "kids",
+          "IMAX" => "imax",
+          "Museums & Galleries on Screen" => "arts",
+          "Music" => "arts",
+          "Musicals" => "arts",
+          "Opera & Dance" => "arts",
+          "Q&A" => "q&a",
+          "Relaxed Screenings" => "relaxed",
+          "Silver Screen" => "senior",
+          "Theatre" => "arts",
+          "Toddler Time" => "kids"
+        }.freeze
+
+        # FormatDisplay, e.g. '2D', '3D', 'IMAX' or 'IMAX 3D'
+        THREE_D = /\b3D\b/i
+        IMAX = /\bIMAX\b/i
+
+        LANGUAGE = /\((#{Cinebase::TitleSanitizer::LANGUAGES.join('|')})\)/i
+        TIME_ZONE = "Europe/London"
+
+        # @param [Hash] session one session
+        # @param [Hash] film the film the session shows
+        # @param [Hash] date the listings date the session is on
+        # @param [String] venue_url the venue's home page
+        def initialize(session, film:, date:, venue_url:)
+          @session = session
+          @film = film
+          @date = date
+          @venue_url = venue_url
+        end
+
+        # @return [Hash] options for LightUk::Performance.new
+        def to_hash
+          {
+            booking_url: booking_url,
+            dimension: format.match?(THREE_D) ? "3d" : "2d",
+            festival: Cinebase::Festival.from_title(title, year: starting_at.year),
+            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
+
+        # Sessions that have started have no booking id
+        def booking_url
+          id = @session["BOID"]
+          "#{@venue_url.chomp('/')}#{BOOKING_PATH}#{id}" if id
+        end
+
+        def format
+          @session["FormatDisplay"].to_s
+        end
+
+        # Dates are keys such as '20261031' and times are London time such as '18.15'
+        def starting_at
+          @starting_at ||= begin
+            year, month, day = @date.fetch("Key").unpack("a4a2a2").map(&:to_i)
+            hour, minute = @session.fetch("Display").scan(/\d+/).map(&:to_i)
+            local = Time.utc(year, month, day, hour, minute)
+            TZInfo::Timezone.get(TIME_ZONE).local_to_utc(local) { |periods| periods.first }.utc
+          end
+        end
+
+        def title
+          @title ||= CGI.unescapeHTML(@film.fetch("Title"))
+        end
+
+        def variant
+          variants = @session.fetch("Collections", []).filter_map { |collection| VARIANTS[collection["Title"]] }
+          variants << "imax" if format.match?(IMAX)
+          variants.uniq
+        end
+      end
+    end
+  end
+end

data/lib/light_uk/internal/title_sanitizer.rb

@@ -0,0 +1,38 @@
+module LightUk
+  # 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 [LightUk::Internal::TitleSanitizer]
+
+      # @!method sanitized
+      #   sanitized and standardized title
+      #   @return [String] sanitised title
+
+      private
+
+      # strings and regex to be removed
+      def remove
+        [
+          /\ACrafty Cinema:\s*/i,                       # craft activity before the film
+          /\s*\(\d+(st|nd|rd|th) Anniversary [^)]*\)/i, # anniversary restoration
+          /\s*\(4K Restoration\)/i,                     # restoration
+          /\s*\(Encore\)/i,                             # encore broadcast
+          /\s*\+\s*Mulled Wine\b.*\z/i                  # seasonal extras
+        ] + COMMON_REMOVE
+      end
+
+      # regexes and their replacements
+      def replace
+        {
+          /EXHIBITION ON SCREEN:\s*(.*)/i         => 'Exhibition on Screen: ',
+          /(?:NT|National Theatre) Live:\s*(.*)/ => 'National Theatre Live: '
+        }.merge(COMMON_REPLACE)
+      end
+    end
+  end
+end

data/lib/light_uk/internal/website.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "json"
+
+module LightUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Reads venues and listings from the Light websites, one per venue
+    class Website
+      include Http
+
+      # Every venue's home page lists all the venues
+      SITES_URL = "https://sheffield.thelight.co.uk/"
+      MINIGUIDE_PATH = "/resource/services/miniguide/data.ashx"
+      COMING_SOON_PATH = "/cinema/comingsoon"
+
+      # @return [Array<Hash>] venues, e.g. { 'id' => 7, 'title' => 'Sheffield',
+      #   'url' => 'https://sheffield.thelight.co.uk' }
+      def sites
+        JSON.parse(get(SITES_URL)[/var __sites = (\[.*?\]);/, 1] || "[]")
+      end
+
+      # @param [String] url a venue's home page
+      # @return [String, nil] the address in the page footer, e.g.
+      #   'The Moor, Sheffield, S1 4PF'
+      def address(url)
+        address = get(url)[%r{<p class="address">(.*?)</p>}m, 1]
+        CGI.unescapeHTML(address).strip if address
+      end
+
+      # The guide behind the venue's listings, which covers a fortnight
+      # @param [String] url a venue's home page
+      # @return [Array<Hash>] films with their sessions on each date
+      def miniguide(url)
+        script = get(URI.join(url, MINIGUIDE_PATH).to_s)
+        JSON.parse(script[/var __gfminiguidedata = (\{.*\});/m, 1] || "{}").fetch("Schedule", [])
+      end
+
+      # Every session of films not yet showing, however far ahead
+      # @param [String] url a venue's home page
+      # @return [Array<Hash>] films in the shape of #miniguide
+      def coming_soon(url)
+        Parser::ComingSoon.new(get(URI.join(url, COMING_SOON_PATH).to_s)).films
+      end
+    end
+  end
+end

data/lib/light_uk/performance.rb

@@ -0,0 +1,77 @@
+module LightUk
+  # A single screening of a film on the Light 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
+
+    # Performances within an inclusive range of showing dates, from two
+    # requests for all of the cinema's advertised dates: the next fortnight's
+    # guide and the coming soon page.
+    # @param [Integer, String] cinema_id id of the cinema
+    # @param [Date] from first date (defaults to today in London)
+    # @param [Date] to last date (defaults to 13 days after from)
+    # @return [Array<LightUk::Performance>]
+    def self.at(
+      cinema_id,
+      from: TZInfo::Timezone.get('Europe/London').now.to_date,
+      to: from + 13
+    )
+      raise ArgumentError, 'to must not precede from' if to < from
+
+      cinema = Cinema.new(cinema_id)
+      website = LightUk::Internal::Website.new
+      films = website.miniguide(cinema.url) + website.coming_soon(cinema.url)
+      performances = sessions_between(films, from, to).map do |film, date, session|
+        parsed = LightUk::Internal::Parser::Session.new(session, film: film, date: date, venue_url: cinema.url)
+        new(parsed.to_hash.merge(cinema_id: cinema.id, cinema_name: cinema.name))
+      end
+      performances.sort_by(&:starting_at)
+    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, subtitled ...)
+    #   @return <Array[String]>
+
+    # private
+
+    # The coming soon page repeats the sessions of films that open within the
+    # guide's fortnight, and sessions that have started have no booking id.
+    def self.sessions_between(films, from, to)
+      sessions = films.flat_map do |film|
+        film.fetch('Dates', [])
+            .select { |date| (from..to).cover?(Date.iso8601(date.fetch('Key'))) }
+            .flat_map { |date| date.fetch('Sessions', []).map { |session| [film, date, session] } }
+      end
+      sessions.uniq { |film, date, session| session['BOID'] || [film['ID'], date['Key'], session['Display']] }
+    end
+    private_class_method :sessions_between
+  end
+end

data/lib/light_uk/version.rb

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

data/lib/light_uk.rb

@@ -0,0 +1,20 @@
+require 'cgi/escape'
+require 'json'
+
+require 'cinebase'
+
+require_relative './light_uk/version'
+
+require_relative './light_uk/internal/http'
+require_relative './light_uk/internal/website'
+require_relative './light_uk/internal/title_sanitizer'
+
+require_relative './light_uk/internal/parser/coming_soon'
+require_relative './light_uk/internal/parser/session'
+
+require_relative './light_uk/cinema'
+require_relative './light_uk/performance'
+
+# light_uk gem
+module LightUk
+end