sportdb-formats 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7b1daae3f04961c06c34b98e84438ee39a80c5ca
-  data.tar.gz: 872154cb339bb6b6c8f440a392f250dc7d7387d9
+  metadata.gz: 4a27c364d2003ece8da886c892d34d595ffcffcc
+  data.tar.gz: 81530dfec5decf5d9476a3f2be90bcbeb0195824
 SHA512:
-  metadata.gz: 853b0362fde6f9d8b17db7036ae954768500ab681acff7bf859b8cbf59b7d8bc4bec9d153f21e3c7ac069b6486b10386ce99fe151d4229df815c006a27dccbe0
-  data.tar.gz: e356061bfb0f15ff8274651ce107ec3be00818996d0c29a2ffb26bd5b71c385a3bd1464eea42e2e11ab60dc24ce96663a701e28fa6a8aebd27d434525c71a1f4
+  metadata.gz: 4a2aabb65968939d55f2000c64e4ac5df4cbedfe6b3786fd12ff86d26bd5e6af12c32ea129b59a7ddf30736afa6f093e0e4f2e97f2c6f0b23bffd6901a83ca91
+  data.tar.gz: 63f4ca42ebb537173334a931a02331b8cbdc27d9e953052c8126d9e683e54a3103eb496103fea400283c6b0b08fa7c6e738466f215e26f9567a3b822a80c172d

data/Manifest.txt

@@ -17,6 +17,7 @@ lib/sportdb/formats/match/mapper.rb
 lib/sportdb/formats/match/mapper_teams.rb
 lib/sportdb/formats/match/match_parser.rb
 lib/sportdb/formats/match/match_parser_auto_conf.rb
+lib/sportdb/formats/match/match_parser_csv.rb
 lib/sportdb/formats/name_helper.rb
 lib/sportdb/formats/outline_reader.rb
 lib/sportdb/formats/package.rb
@@ -49,8 +50,11 @@ test/test_clubs.rb
 test/test_conf.rb
 test/test_country_index.rb
 test/test_country_reader.rb
+test/test_csv_match_parser.rb
+test/test_csv_match_parser_utils.rb
 test/test_csv_reader.rb
 test/test_datafile.rb
+test/test_datafile_package.rb
 test/test_goals.rb
 test/test_league_index.rb
 test/test_league_outline_reader.rb

data/Rakefile

@@ -3,7 +3,7 @@ require './lib/sportdb/formats/version.rb'
 
 Hoe.spec 'sportdb-formats' do
 
-  self.version = SportDb::Formats::VERSION
+  self.version = SportDb::Module::Formats::VERSION
 
   self.summary = "sportdb-formats - sport.db format and text utilities"
   self.description = summary
@@ -21,7 +21,7 @@ Hoe.spec 'sportdb-formats' do
 
   self.extra_deps = [
     ['alphabets',     '>= 1.0.0'],
-    ['date-formats',  '>= 1.0.0'],
+    ['date-formats',  '>= 1.0.1'],
     ['csvreader',     '>= 1.2.4'],
     ['sportdb-langs', '>= 0.1.0'],
 

data/lib/sportdb/formats.rb

@@ -10,15 +10,26 @@ require 'zip'     ## todo/check: if zip is alreay included in a required module
 
 
 
-def read_csv( path )
-  CsvHash.read( path, :header_converters => :symbol )
+def read_csv( path, sep:             nil,
+                    symbolize_names: nil )
+  opts = {}
+  opts[:sep]               = sep         if sep
+  opts[:header_converters] = :symbol     if symbolize_names
+
+  CsvHash.read( path, **opts )
 end
 
-def parse_csv( txt )
-  CsvHash.parse( txt, :header_converters => :symbol )
+def parse_csv( txt, sep:             nil,
+                    symbolize_names: nil )
+  opts = {}
+  opts[:sep]               = sep         if sep
+  opts[:header_converters] = :symbol     if symbolize_names
+
+  CsvHash.parse( txt, **opts )
 end
 
 
+
 ## more sportdb libs/gems
 require 'sportdb/langs'
 
@@ -68,6 +79,7 @@ require 'sportdb/formats/match/match_parser'
 require 'sportdb/formats/match/match_parser_auto_conf'
 require 'sportdb/formats/match/conf_parser'
 
+require 'sportdb/formats/match/match_parser_csv'
 
 require 'sportdb/formats/country/country_reader'
 require 'sportdb/formats/country/country_index'
@@ -147,4 +159,4 @@ end   # module SportDb
 
 
 
-puts SportDb::Formats.banner   # say hello
+puts SportDb::Module::Formats.banner   # say hello

data/lib/sportdb/formats/datafile_package.rb

@@ -30,7 +30,7 @@ class Entry
     @name = path[ pack.path.length+1..-1 ]
   end
   def name()  @name; end
-  def read()  File.open( @path, 'r:utf-8' ).read; end
+  def read()  File.open( @path, 'r:utf-8' ) {|f| f.read }; end
 end  # class DirPackage::Entry
 
 
@@ -44,17 +44,20 @@ end  # class DirPackage::Entry
     @name = basename
   end
 
-  def each( pattern:,  extension: 'txt' )    ## todo/check: rename to glob or something - why? why not?
+  ## todo/check:  change pattern: to re:  - why? why not?
+  def each( pattern: )    ## todo/check: rename to glob or something - why? why not?
     ##   use just .* for extension or remove and check if File.file? and skip File.directory? - why? why not?
     ## note: incl. files starting with dot (.)) as candidates (normally excluded with just *)
-    Dir.glob( "#{@path}/**/{*,.*}.#{extension}" ).each do |path|
-      ## todo/fix: (auto) skip and check for directories
-      if EXCLUDE_RE.match( path )
-        ## note: skip dot dirs (e.g. .build/, .git/, etc.)
+    ##   todo/check/fix:   is there a better (simpler) glob pattern?  yes? no?
+    Dir.glob( "#{@path}/**/{*,.*}.*" ).each do |path|
+      if File.directory?( path )
+         ## always skip directories / folders
+      elsif EXCLUDE_RE.match( path )
+         ## note: skip dot dirs (e.g. .build/, .git/, etc.)
       elsif pattern.match( path )
         yield( Entry.new( self, path ))
       else
-        ## puts "  skipping >#{path}<"
+         ## puts "  skipping >#{path}<"
       end
     end
   end

data/lib/sportdb/formats/match/match_parser_csv.rb

@@ -0,0 +1,314 @@
+# encoding: utf-8
+
+
+module SportDb
+  class CsvMatchParser
+
+  #############
+  # helpers
+  def self.find_seasons( path, col: 'Season', sep: nil, headers: nil )
+
+    ## check if headers incl. season if yes,has priority over col mapping
+    ##  e.g. no need to specify twice (if using headers)
+    col = headers[:season]    if headers && headers[:season]
+
+    seasons = Hash.new( 0 )   ## default value is 0
+
+    ## todo/fix: yes, use CsvHash.foreach  - why? why not?
+    ##                    use read_csv with block  to switch to foreach!!!!
+    rows = read_csv( path, sep: sep )
+
+    rows.each_with_index do |row,i|
+      puts "[#{i}] " + row.inspect  if i < 2
+
+      season = row[ col ]   ## column name defaults to 'Season'
+      seasons[ season ] += 1
+    end
+
+    pp seasons
+
+    ## note: only return season keys/names (not hash with usage counter)
+    seasons.keys
+  end
+
+
+  ##########
+  # main machinery
+
+  ##  todo/fix: use a generic "global" parse_csv method - why? why not?
+  ## def self.parse_csv( text, sep: ',' )    ## helper -lets you change the csv library in one place if needed/desired
+  ##   ## note:  do NOT symbolize keys - keep them as is!!!!!!
+  ##  ##   todo/fix: move "upstream" and remove symbolize keys too!!! - why? why not?
+  ##   CsvHash.parse( text, sep: sep )
+  ## end
+
+  def self.read( path, headers: nil, filters: nil, converters: nil, sep: nil )
+     txt = File.open( path, 'r:utf-8' ) {|f| f.read }   ## note: make sure to use (assume) utf-8
+     parse( txt, headers: headers,
+                 filters: filters,
+                 converters: converters,
+                 sep: sep )
+  end
+
+  def self.parse( txt, headers: nil, filters: nil, converters: nil, sep: nil )
+     new( txt ).parse( headers: headers,
+                        filters: filters,
+                        converters: converters,
+                        sep: sep )
+  end
+
+
+  def initialize( txt )
+    @txt = txt
+  end
+
+  def parse( headers: nil, filters: nil, converters: nil, sep: nil )
+
+    headers_mapping = {}
+
+    rows = parse_csv( @txt, sep: sep )
+
+    return []   if rows.empty?      ## no rows / empty?
+
+
+    ## fix/todo: use logger!!!!
+    ## pp csv
+
+    if headers   ## use user supplied headers if present
+      headers_mapping = headers_mapping.merge( headers )
+    else
+
+      ## note: returns an array of strings (header names)  - assume all rows have the same columns/fields!!!
+      headers = rows[0].keys
+      pp headers
+
+      # note: greece 2001-02 etc. use HT  -  check CVS reader  row['HomeTeam'] may not be nil but an empty string?
+      #   e.g. row['HomeTeam'] || row['HT'] will NOT work for now
+
+      if find_header( headers, ['Team 1']) && find_header( headers, ['Team 2'])
+         ## assume our own football.csv format, see github.com/footballcsv
+         headers_mapping[:team1]  = find_header( headers, ['Team 1'] )
+         headers_mapping[:team2]  = find_header( headers, ['Team 2'] )
+         headers_mapping[:date]   = find_header( headers, ['Date'] )
+
+         ## check for all-in-one full time (ft) and half time (ht9 scores?
+         headers_mapping[:score]  = find_header( headers, ['FT'] )
+         headers_mapping[:scorei] = find_header( headers, ['HT'] )
+
+         headers_mapping[:round]  = find_header( headers, ['Round'] )
+
+         ## optional headers - note: find_header returns nil if header NOT found
+         header_stage = find_header( headers, ['Stage'] )
+         headers_mapping[:stage]  =  header_stage   if header_stage
+      else
+         ## else try footballdata.uk and others
+         headers_mapping[:team1]  = find_header( headers, ['HomeTeam', 'HT', 'Home'] )
+         headers_mapping[:team2]  = find_header( headers, ['AwayTeam', 'AT', 'Away'] )
+         headers_mapping[:date]   = find_header( headers, ['Date'] )
+
+         ## note: FT = Full Time, HG = Home Goal, AG = Away Goal
+         headers_mapping[:score1] = find_header( headers, ['FTHG', 'HG'] )
+         headers_mapping[:score2] = find_header( headers, ['FTAG', 'AG'] )
+
+         ## check for half time scores ?
+         ##  note: HT = Half Time
+         headers_mapping[:score1i] = find_header( headers, ['HTHG'] )
+         headers_mapping[:score2i] = find_header( headers, ['HTAG'] )
+      end
+    end
+
+    pp headers_mapping
+
+    ### todo/fix: check headers - how?
+    ##  if present HomeTeam or HT required etc.
+    ##   issue error/warn is not present
+    ##
+    ## puts "*** !!! wrong (unknown) headers format; cannot continue; fix it; sorry"
+    ##    exit 1
+    ##
+
+    matches = []
+
+    rows.each_with_index do |row,i|
+
+      ## fix/todo: use logger!!!!
+      ## puts "[#{i}] " + row.inspect  if i < 2
+
+
+      ## todo/fix: move to its own (helper) method - filter or such!!!!
+       if filters    ## filter MUST match if present e.g. row['Season'] == '2017/2018'
+         skip = false
+         filters.each do |header, value|
+           if row[ header ] != value   ## e.g. row['Season']
+             skip = true
+             break
+           end
+         end
+         next if skip   ## if header values NOT matching
+       end
+
+
+      ## note:
+      ##   add converters after filters for now (why not before filters?)
+      if converters   ## any converters defined?
+        ## convert single proc shortcut to array with single converter
+        converters = [converters]    if converters.is_a?( Proc )
+
+        ## assumes array of procs
+        converters.each do |converter|
+          row = converter.call( row )
+        end
+      end
+
+
+
+      team1 = row[ headers_mapping[ :team1 ]]
+      team2 = row[ headers_mapping[ :team2 ]]
+
+
+      ## check if data present - if not skip (might be empty row)
+      if team1.nil? && team2.nil?
+        puts "*** WARN: skipping empty? row[#{i}] - no teams found:"
+        pp row
+        next
+      end
+
+      ## remove possible match played counters e.g. (4) (11) etc.
+      team1 = team1.sub( /\(\d+\)/, '' ).strip
+      team2 = team2.sub( /\(\d+\)/, '' ).strip
+
+
+
+      col = row[ headers_mapping[ :date ]]
+      col = col.strip   # make sure not leading or trailing spaces left over
+
+      if col.empty? || col == '-' || col == '?'
+         ## note: allow missing / unknown date for match
+         date = nil
+      else
+        ## remove possible weekday or weeknumber  e.g. (Fri) (4) etc.
+        col = col.sub( /\(W?\d{1,2}\)/, '' )  ## e.g. (W11), (4), (21) etc.
+        col = col.sub( /\(\w+\)/, '' )  ## e.g. (Fri), (Fr) etc.
+        col = col.strip   # make sure not leading or trailing spaces left over
+
+        if col =~ /^\d{2}\/\d{2}\/\d{4}$/
+          date_fmt = '%d/%m/%Y'   # e.g. 17/08/2002
+        elsif col =~ /^\d{2}\/\d{2}\/\d{2}$/
+          date_fmt = '%d/%m/%y'   # e.g. 17/08/02
+        elsif col =~ /^\d{4}-\d{2}-\d{2}$/      ## "standard" / default date format
+          date_fmt = '%Y-%m-%d'   # e.g. 1995-08-04
+        elsif col =~ /^\d{1,2} \w{3} \d{4}$/
+          date_fmt = '%d %b %Y'   # e.g. 8 Jul 2017
+        else
+          puts "*** !!! wrong (unknown) date format >>#{col}<<; cannot continue; fix it; sorry"
+          ## todo/fix: add to errors/warns list - why? why not?
+          exit 1
+        end
+
+        ## todo/check: use date object (keep string?) - why? why not?
+        ##  todo/fix: yes!! use date object!!!! do NOT use string
+        date = Date.strptime( col, date_fmt ).strftime( '%Y-%m-%d' )
+      end
+
+
+      round   = nil
+      ## check for (optional) round / matchday
+      if headers_mapping[ :round ]
+        col = row[ headers_mapping[ :round ]]
+        ## todo: issue warning if not ? or - (and just empty string) why? why not
+        round = col.to_i  if col =~ /^\d{1,2}$/     # check format - e.g. ignore ? or - or such non-numbers for now
+      end
+
+
+      score1  = nil
+      score2  = nil
+      score1i = nil
+      score2i = nil
+
+      ## check for full time scores ?
+      if headers_mapping[ :score1 ] && headers_mapping[ :score2 ]
+        ft = [ row[ headers_mapping[ :score1 ]],
+               row[ headers_mapping[ :score2 ]] ]
+
+        ## todo/fix: issue warning if not ? or - (and just empty string) why? why not
+        score1 = ft[0].to_i  if ft[0] =~ /^\d{1,2}$/
+        score2 = ft[1].to_i  if ft[1] =~ /^\d{1,2}$/
+      end
+
+      ## check for half time scores ?
+      if headers_mapping[ :score1i ] && headers_mapping[ :score2i ]
+        ht = [ row[ headers_mapping[ :score1i ]],
+               row[ headers_mapping[ :score2i ]] ]
+
+        ## todo/fix: issue warning if not ? or - (and just empty string) why? why not
+        score1i = ht[0].to_i  if ht[0] =~ /^\d{1,2}$/
+        score2i = ht[1].to_i  if ht[1] =~ /^\d{1,2}$/
+      end
+
+      ## check for all-in-one full time scores?
+      if headers_mapping[ :score ]
+        ft = row[ headers_mapping[ :score ] ]
+        if ft =~ /^\d{1,2}[\-:]\d{1,2}$/   ## sanity check scores format
+          scores = ft.split( /[\-:]/ )
+          score1 = scores[0].to_i
+          score2 = scores[1].to_i
+        end
+        ## todo/fix: issue warning if non-empty!!! and not matching format!!!!
+      end
+
+      if headers_mapping[ :scorei ]
+        ht = row[ headers_mapping[ :scorei ] ]
+        if ht =~ /^\d{1,2}[\-:]\d{1,2}$/   ## sanity check scores format
+          scores = ht.split( /[\-:]/)   ## allow 1-1 and 1:1
+          score1i = scores[0].to_i
+          score2i = scores[1].to_i
+        end
+        ## todo/fix: issue warning if non-empty!!! and not matching format!!!!
+      end
+
+
+      ## try some optional headings / columns
+      stage = nil
+      if headers_mapping[ :stage ]
+        col = row[ headers_mapping[ :stage ]]
+        ## todo/fix: check can col be nil e.g. col.nil? possible?
+        stage =  if col.nil? || col.empty? || col == '-' || col == 'n/a'
+                    ## note: allow missing stage for match / defaults to "regular"
+                    nil
+                 elsif col == '?'
+                     ## note: default explicit unknown to unknown for now AND not regular - why? why not?
+                    '?'   ## todo/check: use unkown and NOT ?  - why? why not?
+                 else
+                    col
+                 end
+      end
+
+
+      match = Import::Match.new( date:    date,
+                                 team1:   team1,   team2:   team2,
+                                 score1:  score1,  score2:  score2,
+                                 score1i: score1i, score2i: score2i,
+                                 round:   round,
+                                 stage:   stage )
+      matches << match
+    end
+
+    ## pp matches
+    matches
+  end
+
+
+  private
+
+  def find_header( headers, candidates )
+     ## todo/fix: use find_first from enumare of similar ?! - why? more idiomatic code?
+
+    candidates.each do |candidate|
+       return candidate   if headers.include?( candidate ) ## bingo!!!
+    end
+    nil  ## no matching header  found!!!
+  end
+
+  end # class CsvMatchParser
+  end # module SportDb
+

data/lib/sportdb/formats/package.rb

@@ -2,6 +2,9 @@
 module SportDb
   class Package
 
+    ## todo/fix:   make all regexes case-insensitive with /i option - why? why not?
+    ##                e.g. .TXT and .txt
+
     CONF_RE = %r{  (?: ^|/ )               # beginning (^) or beginning of path (/)
         \.conf\.txt$
     }x
@@ -26,14 +29,33 @@ module SportDb
         clubs\.props\.txt$
     }x
 
+
+    ### season folder:
+    ##            e.g. /2019-20   or
+    ##  year-only e.g. /2019      or
+    ##                 /2016--france
+    SEASON_RE = %r{ (?:
+                       \d{4}-\d{2}
+                     | \d{4}(--[^/]+)?
+                    )
+                  }x
+    SEASON = SEASON_RE.source    ## "inline" helper for embedding in other regexes - keep? why? why not?
+
+
     ## note: if pattern includes directory add here
     ##     (otherwise move to more "generic" datafile) - why? why not?
-    MATCH_RE = %r{ /(?: \d{4}-\d{2}        ## season folder e.g. /2019-20
-                      | \d{4}(--[^/]+)?    ## season year-only folder e.g. /2019 or /2016--france
-                    )
-                   /[a-z0-9_-]+\.txt$  ## txt e.g /1-premierleague.txt
+    MATCH_RE = %r{ (?: ^|/ )      # beginning (^) or beginning of path (/)
+                       #{SEASON}
+                     /[a-z0-9_-]+\.txt$  ## txt e.g /1-premierleague.txt
                 }x
 
+    MATCH_CSV_RE = %r{ (?: ^|/ )      # beginning (^) or beginning of path (/)
+                         #{SEASON}
+                       /[a-z0-9_.-]+\.csv$  ## note: allow dot (.) too e.g /eng.1.csv
+                    }x
+
+
+
     ## move class-level "static" finders to DirPackage (do NOT work for now for zip packages) - why? why not?
 
     def self.find( path, pattern )
@@ -41,7 +63,7 @@ module SportDb
 
       ## check all txt files
       ## note: incl. files starting with dot (.)) as candidates (normally excluded with just *)
-      candidates = Dir.glob( "#{path}/**/{*,.*}.txt" )
+      candidates = Dir.glob( "#{path}/**/{*,.*}.*" )
       pp candidates
       candidates.each do |candidate|
         datafiles << candidate    if pattern.match( candidate )
@@ -66,6 +88,15 @@ module SportDb
    def self.find_conf( path, pattern: CONF_RE )  find( path, pattern ); end
    def self.match_conf( path )  CONF_RE.match( path ); end
 
+   def self.find_match( path, format: 'txt' )
+      if format == 'csv'
+        find( path, MATCH_CSV_RE )
+      else  ## otherwise always assume txt for now
+        find( path, MATCH_RE )
+      end
+   end
+   ## add match_match and match_match_csv  - why? why not?
+
    class << self
      alias_method :match_clubs?, :match_clubs
      alias_method :clubs?,       :match_clubs
@@ -149,7 +180,14 @@ module SportDb
     end
 
     def each_conf( &blk )       each( pattern: CONF_RE, &blk ); end
-    def each_match( &blk )      each( pattern: MATCH_RE, &blk ); end
+    def each_match( format: 'txt', &blk )
+      if format == 'csv'
+         each( pattern: MATCH_CSV_RE, &blk );
+      else
+         each( pattern: MATCH_RE, &blk );
+      end
+    end
+    def each_match_csv( &blk )  each( pattern: MATCH_CSV_RE, &blk ); end
     def each_club_props( &blk ) each( pattern: CLUB_PROPS_RE, &blk ); end
 
     def each_leagues( &blk )    each( pattern: LEAGUES_RE, &blk ); end
@@ -157,8 +195,100 @@ module SportDb
     def each_clubs_wiki( &blk ) each( pattern: CLUBS_WIKI_RE, &blk ); end
 
     ## return all match datafile entries
-    def match()  ary=[]; each_match {|entry| ary << entry  }; ary; end
+    def match( format: 'txt' )
+      ary=[]; each_match( format: format ) {|entry| ary << entry  }; ary;
+    end
     alias_method :matches, :match
+
+
+    ## todo/check:  rename/change to match_by_dir - why? why not?
+    ##  still in use somewhere? move to attic? use match_by_season and delete by_season_dir? - why? why not?
+    def match_by_season_dir( format: 'txt' )
+      ##
+      ## [["1950s/1956-57",
+      ##    ["1950s/1956-57/1-division1.csv",
+      ##     "1950s/1956-57/2-division2.csv",
+      ##     "1950s/1956-57/3a-division3n.csv",
+      ##     "1950s/1956-57/3b-division3s.csv"]],
+      ##   ...]
+
+      h = {}
+      match( format: format ).each do |entry|
+        season_path = File.dirname( entry.name )
+
+        h[ season_path ] ||= []
+        h[ season_path ] << entry
+      end
+
+      ##  todo/fix:  - add sort entries by name - why? why not?
+      ## note: assume 1-,2- etc. gets us back sorted leagues
+      ##  - use sort. (will not sort by default?)
+
+      h.to_a    ## return as array (or keep hash) - why? why not?
+    end # method match_by_season_dir
+
+    def match_by_season( format: 'txt', start: nil )   ## change/rename to by_season_key - why? why not?
+
+      ## todo/note: in the future - season might be anything (e.g. part of a filename and NOT a directory) - why? why not?
+
+      ##  note: fold all sames seasons (even if in different directories)
+      ##     into same datafile list e.g.
+      ##   ["1957/58",
+      ##     ["1950s/1957-58/1-division1.csv",
+      ##      "1950s/1957-58/2-division2.csv",
+      ##      "1950s/1957-58/3a-division3n.csv",
+      ##      "1950s/1957-58/3b-division3s.csv"]],
+      ## and
+      ##   ["1957/58",
+      ##      ["archives/1950s/1957-58/1-division1.csv",
+      ##       "archives/1950s/1957-58/2-division2.csv",
+      ##       "archives/1950s/1957-58/3a-division3n.csv",
+      ##       "archives/1950s/1957-58/3b-division3s.csv"]],
+      ##  should be together - why? why not?
+
+      ####
+      # Example package:
+      # [["2012/13", ["2012-13/1-proleague.csv"]],
+      #  ["2013/14", ["2013-14/1-proleague.csv"]],
+      #  ["2014/15", ["2014-15/1-proleague.csv"]],
+      #  ["2015/16", ["2015-16/1-proleague.csv"]],
+      #  ["2016/17", ["2016-17/1-proleague.csv"]],
+      #  ["2017/18", ["2017-18/1-proleague.csv"]]]
+
+      ## todo/fix:  (re)use a more generic filter instead of start for start of season only
+
+      ##  todo/fix: use a "generic" filter_season helper for easy reuse
+      ##     filter_season( clause, season_key )
+      ##   or better filter = SeasonFilter.new( clause )
+      ##             filter.skip? filter.include? ( season_sason_key )?
+      ##             fiteer.before?( season_key )  etc.
+      ##              find some good method names!!!!
+      season_start = start ? Import::Season.new( start ) : nil
+
+      h = {}
+      match( format: format ).each do |entry|
+        ## note: assume last directory in datafile path is the season part/key
+        season_q = File.basename( File.dirname( entry.name ))
+        season   = Import::Season.new( season_q )  ## normalize season
+
+        ## skip if start season before this season
+        next if season_start && season_start.start_year > season.start_year
+
+        h[ season.key ] ||= []
+        h[ season.key ] << entry
+      end
+
+      ##  todo/fix:  - add sort entries by name - why? why not?
+      ## note: assume 1-,2- etc. gets us back sorted leagues
+      ##  - use sort. (will not sort by default?)
+
+      ## sort by season
+      ##   latest / newest first (and oldest last)
+
+      h.to_a.sort do |l,r|    ## return as array (or keep hash) - why? why not?
+        r[0] <=> l[0]
+      end
+    end # method match_by_season
   end   # class Package