seaports 1.3.0 → 1.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 81941b82925782c4a729e31a7f94ce4dc91141925dc63cf41ec4d02208f1ec3b
4
- data.tar.gz: 5402ea838c815f3aea42081a90a5433aff0098af0a21f3ae06594f69e04482d6
3
+ metadata.gz: 11b13cb21a14214009a3a60e888c4c3a33873099313e11acc3ba5bec61283ca6
4
+ data.tar.gz: 2857b86897b1e914b3b5239aea0dbc7a0205ea785f461ef7add1dedb95a14085
5
5
  SHA512:
6
- metadata.gz: 2d2706c5d32eb05d5ba1719a676435f8d51548b75f2f9ed6c52f075d6f7e18325dc00b9c8faff392491743bf86c790638a953c7d9ad400761985e0839848fee4
7
- data.tar.gz: 8450652525c5f1507fed28e5130a8907d018e957056612bc42d88e4381ad0879b98d0357fd7b4767b1f0e541502e37c318f9c733bf3fab7f8833bfa22f9fa0d7
6
+ metadata.gz: 599488e3cc5f26ae27c3e0016fed72df78d51dab98d7321af83d360b73e1b48caed8594ef28a1a54c32a9d16706c5a2e139cb6e8499e3b27625e4569f0e36e07
7
+ data.tar.gz: 719eda2767d8e76722de04e7c957f4cab5e730e8aefe52c093d788466dee1c8ff1c3984546b8cec4e455bff18bdfed22024e503775bcb23bbc92c1874d433052
data/CHANGELOG.md CHANGED
@@ -3,6 +3,14 @@
3
3
  Every entry below the first is a UN/LOCODE refresh, opened as a pull request by
4
4
  `.github/workflows/refresh.yml` and merged by a person.
5
5
 
6
+ ## 1.3.1 — 2026-11-08
7
+
8
+ `Seaports.data_release` no longer claims an edition the table did not come from. The mirror stopped publishing a release number, so refreshes kept the old "2024-2" label on newer data. It is now nil when the source names no edition, and a refresh clears it rather than leaving the previous value.
9
+
10
+ Adds `Seaports.data_refreshed_on`, the Date a refresh last changed the table. Use it instead of `data_release` to check how old the data is, and handle nil if you call `data_release`.
11
+
12
+ Same ports, names and positions as 1.3.0.
13
+
6
14
  ## 1.3.0 — 2026-11-02
7
15
 
8
16
  UN/LOCODE release unknown. 17567 sea ports (17527 before): 46 added, 6 removed, 9 renamed, 22 repositioned, 2 with a new subdivision (0 moved to another principal one).
data/README.md CHANGED
@@ -31,13 +31,14 @@ out of the default gems.
31
31
  ## What is in it
32
32
 
33
33
  Every entry UN/LOCODE classifies as a sea port: **17,527 ports**, 11,820 of them
34
- with published coordinates and 14,567 with a subdivision, built from
35
- **UN/LOCODE 2024-2**.
34
+ with published coordinates and 14,567 with a subdivision, rebuilt from UNECE's
35
+ latest published list whenever it changes.
36
36
 
37
37
  ```ruby
38
- Seaports.count # => 17527
39
- Seaports.all # => [#<data Seaports::Port ...>, ...]
40
- Seaports.data_release # => "2024-2"
38
+ Seaports.count # => 17527
39
+ Seaports.all # => [#<data Seaports::Port ...>, ...]
40
+ Seaports.data_refreshed_on # => #<Date: 2026-11-02>
41
+ Seaports.data_release # => nil, or "2024-2" when the source names an edition
41
42
  ```
42
43
 
43
44
  The table ships inside the gem as a CSV. It is reference data that changes
@@ -182,8 +183,9 @@ rake seaports:refresh[path/to/code-list.csv,2025-1]
182
183
  ```
183
184
 
184
185
  The source is the [datasets/un-locode][mirror] distribution, which republishes
185
- UNECE's list with headers, UTF-8 and a machine-readable release number; UNECE's
186
- own download is a zip of headerless latin-1 files.
186
+ UNECE's list with headers and UTF-8; UNECE's own download is a zip of headerless
187
+ latin-1 files. The mirror builds from UNECE's latest pre-release file, which has
188
+ no edition number, so a table can be newer than any named release.
187
189
 
188
190
  That mirror is a third party, which is the whole reason the refresh does not
189
191
  simply commit what it downloads. Seventeen thousand rows are not reviewable by
@@ -198,8 +200,9 @@ if:
198
200
  someone makes rather than a row that appears quietly.
199
201
 
200
202
  A refusal leaves the working tree exactly as it was and opens an issue. A pass
201
- bumps the minor version, records the new UN/LOCODE release, writes the
202
- changelog entry, and puts the whole diff in the pull request body — every
203
+ bumps the minor version, records the refresh date and any UN/LOCODE edition the
204
+ source names, writes the changelog entry, and puts the whole diff in the pull
205
+ request body — every
203
206
  removal listed in full, because those are the changes that break a caller, and
204
207
  position changes called out separately, because they move markers on a map.
205
208
 
@@ -217,8 +220,9 @@ Semver, where the data is the product:
217
220
  | **minor** | a UN/LOCODE refresh — ports added, renamed, repositioned |
218
221
  | **major** | an API change, or a refresh that removes ports known to be load-bearing |
219
222
 
220
- `Seaports.data_release` tells you which UN/LOCODE edition your copy carries,
221
- which is the question a gem version cannot answer.
223
+ `Seaports.data_refreshed_on` tells you the day your copy's table last changed,
224
+ which is the question a gem version cannot answer. `Seaports.data_release` names
225
+ the UN/LOCODE edition when the source gave one, and is nil otherwise.
222
226
 
223
227
  ## Licence
224
228
 
@@ -14,9 +14,8 @@ module Seaports
14
14
  #
15
15
  # UNECE's own distribution is a zip of headerless latin-1 CSVs, so the source
16
16
  # here is the datasets/un-locode mirror, which republishes the same list with
17
- # headers, UTF-8 and a machine-readable release number. It is a third party,
18
- # which is why every refresh runs through Seaports::Diff before anything
19
- # ships.
17
+ # headers and UTF-8. It is a third party, which is why every refresh runs
18
+ # through Seaports::Diff before anything ships.
20
19
  #
21
20
  # Nothing breaks if a release is skipped: a port missing from our copy falls
22
21
  # back to whatever the caller rendered before the table existed.
@@ -56,6 +55,16 @@ module Seaports
56
55
  nil
57
56
  end
58
57
 
58
+ # The text of version.rb with a refresh's facts written in. The release is
59
+ # replaced even when it is nil: keeping the previous one would label a new
60
+ # table with an edition it did not come from.
61
+ def self.stamp_version(content, version:, release:, refreshed_on:)
62
+ content
63
+ .sub(/VERSION = "[^"]*"/, %(VERSION = "#{version}"))
64
+ .sub(/DATA_RELEASE = (?:"[^"]*"|nil)/, "DATA_RELEASE = #{release.inspect}")
65
+ .sub(/DATA_REFRESHED_ON = "[^"]*"/, %(DATA_REFRESHED_ON = "#{refreshed_on}"))
66
+ end
67
+
59
68
  # Reads OVERRIDES_PATH (or +path+) into { locode => ISO 3166-2 code }.
60
69
  #
61
70
  # The file is typed by people, so a blank cell, a malformed locode or a
@@ -1,11 +1,16 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Seaports
4
- VERSION = "1.3.0"
4
+ VERSION = "1.3.1"
5
5
 
6
- # The UN/LOCODE edition the shipped table was built from. UNECE republishes
7
- # twice a year and names each release by year and half — "2024-2" is the
8
- # second release of 2024. A gem version says what the code does; this says
9
- # how old the data is, which is the question a caller actually has.
10
- DATA_RELEASE = "2024-2"
6
+ # The UN/LOCODE edition the shipped table was built from, when the source
7
+ # names one: UNECE labels each release by year and half, so "2024-2" is the
8
+ # second release of 2024. Nil when it does not, which is the normal case
9
+ # while the mirror builds from UNECE's unnumbered pre-release file.
10
+ DATA_RELEASE = nil
11
+
12
+ # The day a refresh last changed the shipped table. A gem version says what
13
+ # the code does; this says how old the data is, which is the question a
14
+ # caller actually has, and it can be answered whatever the source publishes.
15
+ DATA_REFRESHED_ON = "2026-11-02"
11
16
  end
data/lib/seaports.rb CHANGED
@@ -1,6 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require "csv"
4
+ require "date"
4
5
 
5
6
  require_relative "seaports/version"
6
7
 
@@ -118,12 +119,18 @@ module Seaports
118
119
  table.size
119
120
  end
120
121
 
121
- # Which UN/LOCODE edition the shipped table came from, for a caller that
122
- # wants to assert its data is not years old.
122
+ # Which UN/LOCODE edition the shipped table came from, or nil when its
123
+ # source did not name one. Use data_refreshed_on to ask how old the data is.
123
124
  def data_release
124
125
  DATA_RELEASE
125
126
  end
126
127
 
128
+ # The Date a refresh last changed the shipped table, for a caller that
129
+ # wants to assert its data is not years old.
130
+ def data_refreshed_on
131
+ Date.iso8601(DATA_REFRESHED_ON)
132
+ end
133
+
127
134
  private
128
135
 
129
136
  # A locode is five characters: a two-letter country and a three-character
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: seaports
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.3.0
4
+ version: 1.3.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - Édouard Brière