depot_uk 1.0.0

data/README.md

@@ -0,0 +1,159 @@
+# DepotUk
+
+A simple gem to pull the cinema and performances from the website of
+[Depot](https://lewesdepot.org), the independent cinema in Lewes, and spit
+out useful formatted info.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'depot_uk'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install depot_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 the parent
+and baby, Knitflicks and See It First prefixes, the Cinecity suffix and
+opera and ballet labels, and naming Royal Ballet and Opera screenings in
+full.
+
+No token or setup is needed. The website runs WordPress with Jacro's
+plugin, and tickets are sold through Jacro's booking site.
+
+### Cinema
+
+Depot is one venue, so the gem holds it: the address from the website's
+travel page and the coordinates from OpenStreetMap. Its id is `'deplew'`,
+the Jacro code in the website's booking links. Cinema methods make no
+requests.
+
+``` ruby
+DepotUk::Cinema.all
+#=> [<DepotUk::Cinema ...>]
+
+cinema = DepotUk::Cinema.new('deplew')
+#=> <DepotUk::Cinema ...>
+
+cinema.adr
+#=> {
+  street_address:   'Pinwell Road',
+  extended_address: nil,
+  locality:         'Lewes',
+  region:           'East Sussex',
+  postal_code:      'BN7 2JS',
+  country_name:     'United Kingdom'
+}
+
+cinema.brand
+#=> 'Independent'
+
+cinema.name
+#=> 'Depot'
+
+cinema.latitude
+#=> 50.8715417
+
+cinema.url
+#=> 'https://lewesdepot.org'
+```
+
+### Performances
+
+`Performance.at` returns performances for an inclusive range of showing dates,
+defaulting to today in London and the following 13 days.
+
+The website's calendar holds every advertised date, so any range takes five
+requests: the calendar, the home page for the full titles the calendar
+shortens, and the descriptive subtitles, relaxed and autism friendly access
+pages. A range with no performances takes one. The site is slow: expect
+about five seconds.
+
+``` ruby
+DepotUk::Performance.at('deplew', from: Date.today, to: Date.today + 2)
+#=> [<DepotUk::Performance ...>, <DepotUk::Performance ...>, ...]
+
+performance = DepotUk::Performance.at('deplew').first
+#=> <DepotUk::Performance ...>
+
+performance.film_name
+#=> 'Wicker' # from 'Parent & Baby ONLY: Wicker'
+
+performance.film_year
+#=> nil # from the title, e.g. 1990 for 'Misery (1990)'
+
+performance.dimension
+#=> '2d'
+
+performance.variant
+#=> ['baby', 'relaxed', 'subtitled']
+
+performance.subtitled?
+#=> true
+
+performance.festival
+#=> nil # e.g. #<data Cinebase::Festival name="Cinecity", year=2026>
+
+performance.starting_at
+#=> 2026-11-02 11:00:00 UTC
+
+performance.booking_url
+#=> 'https://lewesdepot.org/film/parent-baby-only-wicker/booknow/40631087'
+
+performance.cinema_name
+#=> 'Depot'
+
+performance.cinema_id
+#=> 'deplew'
+```
+
+Booking links are the website's own, to the page that holds Jacro's seat
+selection.
+
+Only films are returned. Films play in the numbered screens, so the gem
+drops listings marked 'Depot event' or held in the studio: talks,
+workshops, courses and tastings.
+
+Variants come from the access pages and from titles: `subtitled`
+(descriptive subtitles), `relaxed` (relaxed and autism friendly), `baby`
+(parent and baby), `kids` (CBeebies and sensory friendly), `arts` (Royal
+Ballet and Opera, National Theatre Live, Exhibition on Screen, musicals,
+plays and pantomimes) and `q&a`. Films subtitled from another language are
+not a variant.
+
+## Tests
+
+```sh
+bundle exec rake          # unit tests against fixtures
+bundle exec rake live     # live lewesdepot.org
+```
+
+The fixtures in `test/fixtures` are the website's pages, trimmed to the
+parts the gem reads: a few calendar days, the home page's film list and the
+access pages' listings. `test/support/api_shapes.rb` describes those parts.
+The unit suite checks the fixtures against it and the live suite checks the
+real pages, held only in memory. When the website 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/depot_uk/cinema.rb

@@ -0,0 +1,100 @@
+module DepotUk
+  # The object representing the Depot cinema in Lewes
+  class Cinema < Cinebase::Cinema
+    # @!attribute [r] id
+    #   @return [String] the cinema's Jacro code, 'deplew'
+
+    # Depot is one venue. Its id is the Jacro code in the website's booking
+    # links. The address is from the website's travel page, the coordinates
+    # from the cinema's OpenStreetMap node 44767219.
+    VENUES = {
+      'deplew' => {
+        name: 'Depot', street_address: 'Pinwell Road', locality: 'Lewes', region: 'East Sussex',
+        postal_code: 'BN7 2JS', latitude: 50.8715417, longitude: 0.0120094
+      }
+    }.freeze
+
+    ADDRESS_PARTS = %i(street_address extended_address locality region postal_code).freeze
+    URL = 'https://lewesdepot.org'.freeze
+
+    # Constructor
+    # @param [String] id the cinema's Jacro code, 'deplew' or 'DEPLEW'
+    # @return [DepotUk::Cinema]
+    def initialize(id)
+      @id = id.to_s.downcase
+    end
+
+    # Return basic cinema information for all cinemas
+    # @return [Array<DepotUk::Cinema>]
+    # @example
+    #   DepotUk::Cinema.all
+    #   #=> [<DepotUk::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 = DepotUk::Cinema.new('deplew')
+    #   cinema.adr
+    #   #=> {
+    #         street_address:   'Pinwell Road',
+    #         extended_address: nil,
+    #         locality:         'Lewes',
+    #         region:           'East Sussex',
+    #         postal_code:      'BN7 2JS',
+    #         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
+    #   DepotUk::Cinema.new('deplew').name
+    #   #=> 'Depot'
+    def name
+      venue[:name].to_s
+    end
+
+    # The url of the cinema's website
+    # @return [String]
+    # @example
+    #   DepotUk::Cinema.new('deplew').url
+    #   #=> 'https://lewesdepot.org'
+    def url
+      venue.empty? ? '' : URL
+    end
+
+    private
+
+    def venue
+      VENUES.fetch(id, {})
+    end
+  end
+end

data/lib/depot_uk/internal/http.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'net/http'
+
+module DepotUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Requests to lewesdepot.org over one kept-alive connection. The site is
+    # slow, so timeouts are long.
+    module Http
+      HOST = 'lewesdepot.org'
+      TIMEOUT = 40
+      RETRIES = 2
+      USER_AGENT = 'Mozilla/5.0 (compatible; depot_uk; +https://github.com/andycroll/depot_uk)'
+      TRANSIENT_ERRORS = [
+        EOFError, Errno::ECONNRESET, Errno::ECONNREFUSED, Net::OpenTimeout, Net::ReadTimeout, OpenSSL::SSL::SSLError
+      ].freeze
+
+      # Close the connection
+      # @return [nil]
+      def close
+        @connection.finish if @connection&.started?
+        @connection = nil
+      end
+
+      private
+
+      def get(path)
+        attempts = 0
+        begin
+          response = connection.request(Net::HTTP::Get.new(path, 'User-Agent' => USER_AGENT))
+        rescue *TRANSIENT_ERRORS
+          close
+          attempts += 1
+          raise if attempts > RETRIES
+
+          sleep(attempts)
+          retry
+        end
+        # Omit response bodies from errors, and never follow redirects.
+        raise "Depot HTTP error #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+        String.new(response.body, encoding: Encoding::UTF_8)
+      end
+
+      def connection
+        @connection ||= Net::HTTP.start(HOST, 443, use_ssl: true, open_timeout: TIMEOUT, read_timeout: TIMEOUT)
+      end
+    end
+  end
+end

data/lib/depot_uk/internal/parser/calendar.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module DepotUk
+  # @api private
+  module Internal
+    module Parser
+      # Reads the website's calendar: every advertised date, each with its
+      # listings and their start times. Dates have no year.
+      class Calendar
+        # One performance of a film
+        Entry = Data.define(:id, :slug, :heading, :date, :starting_at)
+
+        DAY = %r{<h2>(\w{3})<br>(\d{1,2}) (\w+)</h2>}
+        LISTING = %r{
+          data-link="/film/([^"]+)"\s*><div\sclass="contents"><h3>(.*?)</h3>
+          (.*?)<div\sclass="calendar-perf-buttons">(.*?)</div>
+        }mx
+        PERFORMANCE = %r{perf-popup\.php\?id=(\d+)"[^>]*>\s*(\d{1,2}):(\d{2})\s*</a>}
+        LINE_BREAK = %r{<br\s*/?>}
+
+        # Films play in numbered screens. Talks, workshops and tastings are
+        # 'Depot event' or in the studio.
+        FILM_SCREEN = /\AScreen \d/
+
+        # A day and month falls on a different weekday in each of three
+        # neighbouring years
+        YEARS_AROUND = (-1..1)
+        TIME_ZONE = 'Europe/London'
+
+        # @param [String] html the calendar page
+        # @param [Date] near a date within a year of the listings, which sets
+        #   their years
+        def initialize(html, near:)
+          @html = html
+          @near = near
+        end
+
+        # @return [Array<DepotUk::Internal::Parser::Calendar::Entry>] film
+        #   performances in calendar order
+        def entries
+          date = nil
+          @html.scan(Regexp.union(DAY, LISTING)).flat_map do |weekday, day, month, slug, heading, details, buttons|
+            if weekday
+              date = date_of(weekday, day.to_i, month)
+              []
+            elsif date && film?(details)
+              performances(buttons, slug: slug, heading: CGI.unescapeHTML(heading).strip, date: date)
+            else
+              []
+            end
+          end
+        end
+
+        private
+
+        def date_of(weekday, day, month_name)
+          month = Date::MONTHNAMES.index(month_name)
+          if month
+            YEARS_AROUND.filter_map do |offset|
+              year = @near.year + offset
+              Date.new(year, month, day) if Date.valid_date?(year, month, day)
+            end.find { |date| date.strftime('%a') == weekday }
+          end
+        end
+
+        def film?(details)
+          details.split(LINE_BREAK).any? { |line| line.strip.match?(FILM_SCREEN) }
+        end
+
+        def performances(buttons, slug:, heading:, date:)
+          buttons.scan(PERFORMANCE).map do |id, hour, minute|
+            local = Time.utc(date.year, date.month, date.day, hour.to_i, minute.to_i)
+            starting_at = TZInfo::Timezone.get(TIME_ZONE).local_to_utc(local)
+            Entry.new(id: id, slug: slug, heading: heading, date: date, starting_at: starting_at)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module DepotUk
+  # @api private
+  module Internal
+    module Parser
+      # Turns one calendar entry into performance attributes
+      class Showtime
+        BOOKING_URL = 'https://lewesdepot.org/film/%<slug>s/booknow/%<id>s'
+
+        # The calendar cuts long headings at a word and adds this
+        TRUNCATION = '...'
+
+        # Titles and the variants they mean. The access pages mark
+        # subtitled and relaxed performances.
+        TITLE_VARIANTS = {
+          /\AParent (?:&|and) Baby\b/i => 'baby',
+          /\ASensory Friendly\b/i => %w(relaxed kids),
+          /\ACbeebies\b/i => 'kids',
+          /\bQ\s?&\s?A\b/i => 'q&a',
+          /\A(?:RBO|National Theatre Live|NT Live|Met Opera|Exhibition on Screen):/i => 'arts',
+          /\bThe (?:Musical|Play)\z|\bLive On Stage\z|\bPanto\b/i => 'arts'
+        }.freeze
+
+        CINECITY = /\(Cinecity\)/i
+        CINECITY_NAME = 'Cinecity'
+        THREE_D = /\b3D\b/i
+
+        # @param [DepotUk::Internal::Parser::Calendar::Entry] entry
+        # @param [Array<String>] titles every advertised title in full
+        # @param [Array<String>] variants from the access pages
+        def initialize(entry, titles:, variants:)
+          @entry = entry
+          @titles = titles
+          @variants = variants
+        end
+
+        # @return [Hash] options for DepotUk::Performance.new
+        def to_hash
+          {
+            booking_url: format(BOOKING_URL, slug: @entry.slug, id: @entry.id),
+            dimension: title.match?(THREE_D) ? '3d' : '2d',
+            festival: festival,
+            film_name: TitleSanitizer.new(title).sanitized,
+            film_year: Cinebase::TitleSanitizer.film_year(title),
+            starting_at: @entry.starting_at,
+            variant: variant
+          }
+        end
+
+        # WordPress's slug for a title, e.g. 'de-gaulle-liberte'
+        # @param [String] title
+        # @return [String]
+        def self.slug(title)
+          ascii = title.unicode_normalize(:nfkd).gsub(/\p{Mn}/, '').downcase.delete("'’")
+          ascii.gsub(/[^a-z0-9]+/, '-').delete_prefix('-').delete_suffix('-')
+        end
+
+        private
+
+        def festival
+          year = @entry.date.year
+          if title.match?(CINECITY)
+            Cinebase::Festival.new(name: CINECITY_NAME, year: year)
+          else
+            Cinebase::Festival.from_title(title, year: year)
+          end
+        end
+
+        def title
+          @title ||= if @entry.heading.end_with?(TRUNCATION)
+                       full_title(@entry.heading.delete_suffix(TRUNCATION))
+                     else
+                       @entry.heading
+                     end
+        end
+
+        # The film's slug settles a shortened heading that starts several
+        # titles, e.g. 'Exhibition on Screen:...'
+        def full_title(start)
+          matches = @titles.select { |candidate| candidate.start_with?(start) }
+          if matches.one?
+            matches.first
+          else
+            matches.find { |candidate| self.class.slug(candidate) == @entry.slug } || start
+          end
+        end
+
+        def variant
+          from_title = TITLE_VARIANTS.flat_map { |pattern, variants| title.match?(pattern) ? Array(variants) : [] }
+          (from_title + @variants).uniq
+        end
+      end
+    end
+  end
+end

data/lib/depot_uk/internal/title_sanitizer.rb

@@ -0,0 +1,37 @@
+module DepotUk
+  # 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 [DepotUk::Internal::TitleSanitizer]
+
+      # @!method sanitized
+      #   sanitized and standardized title
+      #   @return [String] sanitised title
+
+      private
+
+      # strings and regex to be removed
+      def remove
+        [
+          /\AParent (?:&|and) Baby ONLY:\s*/i,                  # parent and baby screening
+          /\AKNITFLICKS:\s*/i,                                  # knit-along screening
+          /\ASee It First\s*[–-]\s*/i,                          # preview
+          /\s*\(Cinecity\)/i,                                   # festival suffix
+          /\s*\((?:MET )?(?:Opera|Ballet)\)\z/i                 # event cinema genre
+        ] + COMMON_REMOVE
+      end
+
+      # regexes and their replacements
+      def replace
+        {
+          /\ARBO: (.*)/ => 'Royal Ballet and Opera: '
+        }.merge(COMMON_REPLACE)
+      end
+    end
+  end
+end

data/lib/depot_uk/internal/website.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module DepotUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Reads the pages of lewesdepot.org that, together, describe every
+    # advertised performance: the calendar, the home page's film list and
+    # the access pages.
+    class Website
+      include Http
+
+      CALENDAR_PATH = '/whats-on/calendar'
+      HOME_PATH = '/'
+
+      # Each access page lists every upcoming performance of its kind
+      ACCESS_PAGES = {
+        '/access/descriptive-subtitles' => 'subtitled',
+        '/access/relaxed' => 'relaxed',
+        '/access/autism-friendly' => 'relaxed'
+      }.freeze
+
+      FILM_SELECT = %r{<select[^>]*id="film_select"[^>]*>(.*?)</select>}m
+      FILM_OPTION = %r{<option value="\d+">([^<]+)</option>}
+      PERFORMANCE_ID = /perf-popup\.php\?id=(\d+)/
+
+      # Yield a website, closing its connection afterwards
+      # @yieldparam [DepotUk::Internal::Website] website
+      # @return the block's result
+      def self.open
+        website = new
+        yield website
+      ensure
+        website.close
+      end
+
+      # @return [String] the calendar page, every advertised date
+      def calendar
+        get(CALENDAR_PATH)
+      end
+
+      # The calendar shortens long titles, the home page's film list does
+      # not
+      # @return [Array<String>] every advertised title, e.g. 'Ghosts: The
+      #   Possession of Button House'
+      def titles
+        films = get(HOME_PATH)[FILM_SELECT, 1].to_s
+        films.scan(FILM_OPTION).map { |(title)| CGI.unescapeHTML(title).strip }
+      end
+
+      # @return [Hash{String => Array<String>}] variants by performance id,
+      #   e.g. { '40631087' => ['subtitled', 'relaxed'] }
+      def variants
+        ACCESS_PAGES.each_with_object({}) do |(path, variant), variants|
+          get(path).scan(PERFORMANCE_ID).each do |(id)|
+            variants[id] = (variants[id] || []) | [variant]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/depot_uk/performance.rb

@@ -0,0 +1,80 @@
+module DepotUk
+  # A single screening of a film at the Depot cinema
+  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 [Time] :starting_at listed start time of the performance
+
+    TIME_ZONE = 'Europe/London'.freeze
+
+    # Performances within an inclusive range of showing dates. The calendar
+    # holds every advertised date, so any range takes five requests: the
+    # calendar, the home page for titles the calendar shortens, and three
+    # access pages. A range with no performances takes one.
+    # @param [String] cinema_id the cinema's Jacro code, 'deplew'
+    # @param [Date] from first date (defaults to today in London)
+    # @param [Date] to last date (defaults to 13 days after from)
+    # @return [Array<DepotUk::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
+        performances = Internal::Website.open { |website| read(website, cinema, from..to) }
+        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, baby, kids, q&a, relaxed, subtitled)
+    #   @return <Array[String]>
+
+    def self.read(website, cinema, dates)
+      entries = Internal::Parser::Calendar.new(website.calendar, near: dates.first).entries
+      entries = entries.select { |entry| dates.cover?(entry.date) }
+      if entries.empty?
+        []
+      else
+        titles = website.titles
+        variants = website.variants
+        entries.map do |entry|
+          showtime = Internal::Parser::Showtime.new(entry, titles: titles, variants: variants.fetch(entry.id, []))
+          new(showtime.to_hash.merge(cinema_id: cinema.id, cinema_name: cinema.name))
+        end
+      end
+    end
+    private_class_method :read
+  end
+end

data/lib/depot_uk/version.rb

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

data/lib/depot_uk.rb

@@ -0,0 +1,18 @@
+require 'cgi/escape'
+
+require 'cinebase'
+
+require_relative './depot_uk/version'
+
+require_relative './depot_uk/internal/http'
+require_relative './depot_uk/internal/website'
+require_relative './depot_uk/internal/title_sanitizer'
+require_relative './depot_uk/internal/parser/calendar'
+require_relative './depot_uk/internal/parser/showtime'
+
+require_relative './depot_uk/cinema'
+require_relative './depot_uk/performance'
+
+# depot_uk gem
+module DepotUk
+end