watershed_uk 1.0.0

data/README.md

@@ -0,0 +1,169 @@
+# WatershedUk
+
+A simple gem to pull cinema and performance information for [Watershed](https://www.watershed.co.uk), the independent cinema in Bristol, and spit out useful formatted info.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'watershed_uk'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install watershed_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 BBFC
+certificates and the `S` and `PS` (partly subtitled) markers after them,
+presenter, partner, preview and strand prefixes (`Bristol Bad Film Club
+presents:`, `Spike Island x Watershed:`, `Preview:`, `Bristol Surf Cinema:`,
+`Sonic Cinema:`), 35mm, director's cut and anniversary markers, years, and
+Q&A and panel discussion add-ons, and naming National Theatre Live and Royal
+Ballet and Opera screenings in full.
+
+No token or setup is needed. Watershed sells tickets through Ticketsolve,
+whose public XML feed lists every show on sale.
+
+### Cinema
+
+Watershed is one venue. The feed names it but gives no address, so the gem
+holds it: the address from the website's footer and coordinates from
+OpenStreetMap. Cinema methods make no requests.
+
+``` ruby
+WatershedUk::Cinema.all
+#=> [<WatershedUk::Cinema ...>]
+
+cinema = WatershedUk::Cinema.new('watershed')
+#=> <WatershedUk::Cinema ...>
+
+cinema.adr
+#=> {
+  street_address:   '1 Canons Road',
+  extended_address: 'Harbourside',
+  locality:         'Bristol',
+  region:           nil,
+  postal_code:      'BS1 5TX',
+  country_name:     'United Kingdom'
+}
+
+cinema.brand
+#=> 'Independent'
+
+cinema.name
+#=> 'Watershed'
+
+cinema.full_name
+#=> 'Independent Watershed'
+
+cinema.id
+#=> 'watershed'
+
+cinema.latitude
+#=> 51.4517753
+
+cinema.longitude
+#=> -2.598143
+
+cinema.url
+#=> 'https://www.watershed.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 Ticketsolve feed
+holds every advertised date, about six months ahead, so any range is one
+request of about 320 KB.
+
+``` ruby
+WatershedUk::Performance.at('watershed', from: Date.today, to: Date.today + 2)
+#=> [<WatershedUk::Performance ...>, <WatershedUk::Performance ...>, ...]
+
+performance = WatershedUk::Performance.at('watershed').first
+#=> <WatershedUk::Performance ...>
+
+performance.film_name
+#=> 'Daïchi Saïto' # from 'Sonic Cinema: Daïchi Saïto (35mm) (18 CTBA)'
+
+performance.film_year
+#=> nil # from the title, e.g. 1983 for 'The Store (1983) (18 CTBA)'
+
+performance.dimension
+#=> '2d'
+
+performance.variant
+#=> ['35mm', 'q&a']
+
+performance.subtitled?
+#=> false
+
+performance.festival
+#=> nil # e.g. #<data Cinebase::Festival name="Afrika Eye", year=2026>
+
+performance.starting_at
+#=> 2026-11-26 18:30:00 UTC
+
+performance.booking_url
+#=> 'https://watershed.ticketsolve.com/shows/1173695141/events/428916513'
+
+performance.cinema_name
+#=> 'Watershed'
+
+performance.cinema_id
+#=> 'watershed'
+```
+
+Booking links are each event's Ticketsolve page, which leads to ticket and
+seat selection. Sold out performances have no booking link.
+
+Only films at Watershed itself are returned. The feed also holds Watershed's
+partner venues, its event spaces and the Pervasive Media Studio, which the gem
+skips. Within the cinema it keeps the `Film` and `Event Cinema` categories,
+and shows with no category that have a certificate in their name. Talks,
+workshops, other events and seat sponsorships are dropped. Screenings with
+an introduction, a Q&A or a panel are films.
+
+Variants come from show tags, each event's comment and titles: `subtitled`
+(descriptive subtitles or captions), `relaxed`, `baby` (parents and carers
+of babies), `audio_described`, `35mm`, `arts` (National Theatre Live and
+other event cinema) and `q&a`. Films subtitled from another language are
+not a variant.
+
+Festival tags name Afrika Eye and the Bristol Palestine Film Festival
+editions.
+
+## Tests
+
+```sh
+bundle exec rake          # unit tests against fixtures
+bundle exec rake live     # live Ticketsolve feed
+```
+
+The fixture in `test/fixtures` is the Ticketsolve feed, trimmed to a few
+shows at three of its venues, a few events each and no descriptions or
+images. `test/support/api_shapes.rb` describes the parts the gem reads. The
+unit suite checks the fixture against it and the live suite checks the 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/watershed_uk/cinema.rb

@@ -0,0 +1,107 @@
+module WatershedUk
+  # The object representing the Watershed cinema in Bristol
+  class Cinema < Cinebase::Cinema
+    # @!attribute [r] id
+    #   @return [String] the cinema's id, 'watershed'
+
+    # Watershed is one venue, sold through Ticketsolve alongside its partner
+    # venues and event spaces. The address is from the website's footer, the
+    # coordinates from the cinema's OpenStreetMap node 12973154703.
+    VENUES = {
+      'watershed' => {
+        name: 'Watershed', ticketsolve_venue_id: '426565625',
+        street_address: '1 Canons Road', extended_address: 'Harbourside', locality: 'Bristol',
+        postal_code: 'BS1 5TX', latitude: 51.4517753, longitude: -2.598143
+      }
+    }.freeze
+
+    ADDRESS_PARTS = %i(street_address extended_address locality region postal_code).freeze
+    URL = 'https://www.watershed.co.uk'.freeze
+
+    # Constructor
+    # @param [String] id the cinema's id, 'watershed'
+    # @return [WatershedUk::Cinema]
+    def initialize(id)
+      @id = id.to_s.downcase
+    end
+
+    # Return basic cinema information for all cinemas
+    # @return [Array<WatershedUk::Cinema>]
+    # @example
+    #   WatershedUk::Cinema.all
+    #   #=> [<WatershedUk::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 = WatershedUk::Cinema.new('watershed')
+    #   cinema.adr
+    #   #=> {
+    #         street_address:   '1 Canons Road',
+    #         extended_address: 'Harbourside',
+    #         locality:         'Bristol',
+    #         region:           nil,
+    #         postal_code:      'BS1 5TX',
+    #         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
+    #   WatershedUk::Cinema.new('watershed').name
+    #   #=> 'Watershed'
+    def name
+      venue[:name].to_s
+    end
+
+    # The url of the cinema's website
+    # @return [String]
+    # @example
+    #   WatershedUk::Cinema.new('watershed').url
+    #   #=> 'https://www.watershed.co.uk'
+    def url
+      venue.empty? ? '' : URL
+    end
+
+    # @api private
+    # @return [String, nil] the venue's id in the Ticketsolve feed
+    def ticketsolve_venue_id
+      venue[:ticketsolve_venue_id]
+    end
+
+    private
+
+    def venue
+      VENUES.fetch(id, {})
+    end
+  end
+end

data/lib/watershed_uk/internal/http.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'net/http'
+
+module WatershedUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Requests to Ticketsolve
+    module Http
+      TIMEOUT = 30
+      RETRIES = 2
+      USER_AGENT = 'Mozilla/5.0 (compatible; watershed_uk; +https://github.com/andycroll/watershed_uk)'
+      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: TIMEOUT, read_timeout: TIMEOUT) do |http|
+            http.request(Net::HTTP::Get.new(uri, 'User-Agent' => USER_AGENT))
+          end
+        rescue *TRANSIENT_ERRORS
+          attempts += 1
+          raise if attempts > RETRIES
+
+          sleep(attempts)
+          retry
+        end
+        # Omit response bodies from errors, and never follow redirects.
+        raise "Ticketsolve HTTP error #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+        String.new(response.body, encoding: Encoding::UTF_8)
+      end
+    end
+  end
+end

data/lib/watershed_uk/internal/parser/feed.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module WatershedUk
+  # @api private
+  module Internal
+    module Parser
+      # Parses a Ticketsolve shows.xml feed: venues, each with its shows, each
+      # with its events. Nothing here is particular to Watershed.
+      class Feed
+        # A Ticketsolve venue, e.g. id '426565625', name 'Watershed Cinemas'
+        Venue = Data.define(:id, :name, :shows)
+
+        # A production on sale, e.g. a film, with the tags and category the
+        # box office gives it
+        Show = Data.define(:id, :name, :category, :tags, :url, :events)
+
+        # A single performance of a show, with its UTC start, its status such
+        # as 'available' or 'sold out', the box office's comment and its
+        # booking page
+        Event = Data.define(:id, :starting_at, :status, :comment, :url)
+
+        # @param [String] xml a shows.xml document
+        def initialize(xml)
+          @document = REXML::Document.new(xml)
+        end
+
+        # @return [Array<Venue>]
+        def venues
+          @document.get_elements('venues/venue').map do |venue|
+            Venue.new(id: venue.attributes['id'], name: text(venue, 'name'),
+                      shows: venue.get_elements('shows/show').map { |show| show(show) })
+          end
+        end
+
+        private
+
+        def show(show)
+          Show.new(
+            id: show.attributes['id'],
+            name: text(show, 'name'),
+            category: text(show, 'event_category'),
+            tags: show.get_elements('tags/tag').map { |tag| tag.text.to_s.strip },
+            url: text(show, 'url'),
+            events: show.get_elements('events/event').map { |event| event(event) }
+          )
+        end
+
+        def event(event)
+          Event.new(
+            id: event.attributes['id'],
+            starting_at: Time.iso8601(text(event, 'date_time_iso')).utc,
+            status: text(event, 'status'),
+            comment: text(event, 'comment'),
+            url: text(event, 'url')
+          )
+        end
+
+        # Names and comments are CDATA sections between whitespace
+        def text(element, path)
+          node = element.elements[path]
+          node ? node.texts.map(&:value).join.strip : ""
+        end
+      end
+    end
+  end
+end

data/lib/watershed_uk/internal/parser/screening.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module WatershedUk
+  # @api private
+  module Internal
+    module Parser
+      # Reads one Ticketsolve event of a Watershed show as a film screening
+      class Screening
+        # Watershed's categories for screenings, including broadcasts such as
+        # National Theatre Live. Talks, workshops and other events have their
+        # own categories.
+        FILM_CATEGORIES = ['Film', 'Event Cinema'].freeze
+
+        SOLD_OUT = 'sold out'
+
+        CATEGORY_VARIANTS = { 'Event Cinema' => 'arts' }.freeze
+        TAG_VARIANTS = { '35mm' => '35mm', 'audio_description' => 'audio_described', 'ntl' => 'arts' }.freeze
+
+        # The box office notes each event's access and extras in its comment,
+        # e.g. 'This screening has descriptive subtitles'
+        COMMENT_VARIANTS = {
+          /descriptive subtitles|captioned/i => 'subtitled',
+          /\bbabies\b/i => 'baby',
+          /\brelaxed screening\b/i => 'relaxed',
+          /\bQ&A\b/ => 'q&a'
+        }.freeze
+        TITLE_VARIANTS = { /\(35mm\b/i => '35mm', /\bQ&A\b/ => 'q&a' }.freeze
+
+        # Festival tags carry a two digit year, e.g. 'afrika_eye_ae26'
+        FESTIVAL_TAGS = {
+          /\Aafrika_eye_ae(\d{2})\z/ => 'Afrika Eye',
+          /\Abpff(\d{2})_/ => 'Bristol Palestine Film Festival'
+        }.freeze
+
+        # National Theatre Live shows are tagged, and often untitled as such
+        NT_LIVE_TAG = 'ntl'
+        NT_LIVE = /\A(?:NT|National Theatre) Live:/
+        THREE_D = /\b3D\b/i
+
+        # @param [Feed::Show] show
+        # @return [Boolean] whether the show is a film, rather than a talk,
+        #   workshop or other event. Some films have no category, but every
+        #   film has a certificate in its name.
+        def self.film?(show)
+          if show.category.empty?
+            show.name.match?(TitleSanitizer::CERTIFICATE)
+          else
+            FILM_CATEGORIES.include?(show.category)
+          end
+        end
+
+        # @param [Feed::Show] show the film
+        # @param [Feed::Event] event one screening of it
+        def initialize(show, event)
+          @show = show
+          @event = event
+        end
+
+        # @return [Hash] options for WatershedUk::Performance.new
+        def to_hash
+          {
+            booking_url: @event.status == SOLD_OUT ? nil : @event.url,
+            dimension: @show.name.match?(THREE_D) ? '3d' : '2d',
+            festival: festival,
+            film_name: TitleSanitizer.new(title).sanitized,
+            film_year: Cinebase::TitleSanitizer.film_year(title),
+            starting_at: @event.starting_at,
+            variant: variant
+          }
+        end
+
+        private
+
+        def festival
+          FESTIVAL_TAGS.each do |pattern, name|
+            tag = @show.tags.grep(pattern).first
+            return Cinebase::Festival.new(name: name, year: 2000 + tag[pattern, 1].to_i) if tag
+          end
+          Cinebase::Festival.from_title(title, year: @event.starting_at.year)
+        end
+
+        def title
+          if @show.tags.include?(NT_LIVE_TAG) && !@show.name.match?(NT_LIVE)
+            "NT Live: #{@show.name}"
+          else
+            @show.name
+          end
+        end
+
+        def variant
+          variants = @show.tags.filter_map { |tag| TAG_VARIANTS[tag] }
+          variants << CATEGORY_VARIANTS[@show.category]
+          variants += COMMENT_VARIANTS.filter_map { |pattern, variant| variant if @event.comment.match?(pattern) }
+          variants += TITLE_VARIANTS.filter_map { |pattern, variant| variant if @show.name.match?(pattern) }
+          variants.compact.uniq
+        end
+      end
+    end
+  end
+end

data/lib/watershed_uk/internal/ticketsolve.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module WatershedUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Reads Watershed's Ticketsolve box office
+    class Ticketsolve
+      include Http
+
+      # Every show on sale at Watershed and its partner venues, with every
+      # advertised event, in one public document
+      FEED_URL = 'https://watershed.ticketsolve.com/shows.xml'
+
+      # @return [String] the shows feed, parsed by {Parser::Feed}
+      def feed
+        get(FEED_URL)
+      end
+    end
+  end
+end

data/lib/watershed_uk/internal/title_sanitizer.rb

@@ -0,0 +1,43 @@
+module WatershedUk
+  # 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 [WatershedUk::Internal::TitleSanitizer]
+
+      # @!method sanitized
+      #   sanitized and standardized title
+      #   @return [String] sanitised title
+
+      # BBFC certificate, or CTBA when it is yet to be announced, e.g. '(15)',
+      # '(18 CTBA)' or '(18) CTBA'
+      CERTIFICATE = /\((?:U|PG|12A?|15|18|CTBA)(?: CTBA)?\)(?:\s*CTBA)?/
+
+      private
+
+      # strings and regex to be removed
+      def remove
+        [
+          /\s*#{CERTIFICATE}(?:\s+P?S)?\s*\z/,    # certificate, then (partly) subtitled
+          /\A[^:]+ presents:\s*/i,                 # presenter
+          /\A[^:]+ x Watershed:\s*/i,              # partner
+          /\A(?:Preview|Bristol Surf Cinema|Sonic Cinema):\s*/i, # strand
+          /\s*\(35mm [^)]*\)/i,                    # film print tour
+          /\s*\(Director[’']s Cut\)/i,             # cut
+          /\s*\+\s*panel discussion\z/i            # panel 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/watershed_uk/performance.rb

@@ -0,0 +1,77 @@
+module WatershedUk
+  # A single screening of a film at the Watershed cinema
+  class Performance < Cinebase::Performance
+    # @!attribute [r] booking_url
+    #   @return [String, nil] the Ticketsolve 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 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 Ticketsolve
+    # feed holds every advertised date, so any range is one request.
+    # @param [String] cinema_id the cinema's id, 'watershed'
+    # @param [Date] from first date (defaults to today in London)
+    # @param [Date] to last date (defaults to 13 days after from)
+    # @return [Array<WatershedUk::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
+        venues = Internal::Parser::Feed.new(Internal::Ticketsolve.new.feed).venues
+        shows = venues.select { |venue| venue.id == cinema.ticketsolve_venue_id }.flat_map(&:shows)
+        performances = screenings(shows, from..to).map do |screening|
+          new(screening.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 (35mm, arts, audio_described, baby, q&a,
+    #   relaxed, subtitled)
+    #   @return <Array[String]>
+
+    def self.screenings(shows, dates)
+      london = TZInfo::Timezone.get(TIME_ZONE)
+      shows.select { |show| Internal::Parser::Screening.film?(show) }.flat_map do |show|
+        show.events
+            .select { |event| dates.cover?(london.to_local(event.starting_at).to_date) }
+            .map { |event| Internal::Parser::Screening.new(show, event) }
+      end
+    end
+    private_class_method :screenings
+  end
+end

data/lib/watershed_uk/version.rb

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

data/lib/watershed_uk.rb

@@ -0,0 +1,20 @@
+require 'rexml/document'
+require 'time'
+
+require 'cinebase'
+
+require_relative './watershed_uk/version'
+
+require_relative './watershed_uk/internal/http'
+require_relative './watershed_uk/internal/ticketsolve'
+require_relative './watershed_uk/internal/title_sanitizer'
+
+require_relative './watershed_uk/internal/parser/feed'
+require_relative './watershed_uk/internal/parser/screening'
+
+require_relative './watershed_uk/cinema'
+require_relative './watershed_uk/performance'
+
+# watershed_uk gem
+module WatershedUk
+end