gunsnprices 0.1.0

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.
@@ -0,0 +1,93 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "json"
4
+
5
+ module GunsNPrices
6
+ # A caliber (cartridge) from the GunsNPrices caliber list.
7
+ #
8
+ # @!attribute [r] id
9
+ # @return [String] stable id, e.g. "9x19mmparabellum"
10
+ # @!attribute [r] name
11
+ # @return [String] display name, e.g. "9×19mm Parabellum"
12
+ # @!attribute [r] type
13
+ # @return [String] "handgun", "rifle", "rimfire", "shotgun", "airgun" or "muzzleloader"
14
+ # @!attribute [r] url
15
+ # @return [String] the GunsNPrices page comparing prices for this caliber ("" if none)
16
+ Caliber = Struct.new(:id, :name, :type, :url, keyword_init: true) do
17
+ # @return [String] JSON object with the same field names as the Python package
18
+ def to_json(*args)
19
+ to_h.to_json(*args)
20
+ end
21
+ end
22
+
23
+ # Result of {GunsNPrices.identify_model}.
24
+ #
25
+ # @!attribute [r] brand
26
+ # @return [String] brand as named on GunsNPrices, e.g. "Glock"
27
+ # @!attribute [r] family
28
+ # @return [String] model family, e.g. "Glock 19"
29
+ # @!attribute [r] model
30
+ # @return [String] most specific model, e.g. "Glock 19 Gen 5 MOS"
31
+ # @!attribute [r] generation
32
+ # @return [String] "5", "V", "V3", ... or "" when unknown
33
+ # @!attribute [r] configs
34
+ # @return [Array<String>] configurations found, e.g. ["MOS"], ["Compact"]
35
+ # @!attribute [r] features
36
+ # @return [Array<String>] features found, e.g. ["Threaded Barrel", "FDE"]
37
+ # @!attribute [r] source
38
+ # @return [String] "title", or "mpn" when the model was decoded from a Glock part number
39
+ ModelMatch = Struct.new(:brand, :family, :model, :generation, :configs, :features, :source, keyword_init: true) do
40
+ # @return [String] JSON object with the same field names as the Python package
41
+ def to_json(*args)
42
+ to_h.to_json(*args)
43
+ end
44
+ end
45
+
46
+ # Result of {GunsNPrices.parse_title}. Fields that don't apply or weren't found are nil (or empty).
47
+ #
48
+ # @!attribute [r] title
49
+ # @return [String] the title that was parsed
50
+ # @!attribute [r] kind
51
+ # @return [String] "firearm" or "ammo"
52
+ # @!attribute [r] brand
53
+ # @return [String] brand of the identified model, else the brand you passed, else ""
54
+ # @!attribute [r] model
55
+ # @return [ModelMatch, nil] firearms only
56
+ # @!attribute [r] caliber
57
+ # @return [Caliber, nil] the first caliber in the title
58
+ # @!attribute [r] calibers
59
+ # @return [Array<Caliber>] every caliber in the title, in order (".357 Mag / .38 Special")
60
+ # @!attribute [r] capacity
61
+ # @return [Integer, nil] magazine capacity, firearms only
62
+ # @!attribute [r] barrel_length
63
+ # @return [Float, nil] barrel length in inches, firearms only
64
+ # @!attribute [r] rounds
65
+ # @return [Integer, nil] rounds per box, ammo only
66
+ # @!attribute [r] cost_per_round
67
+ # @return [Float, nil] ammo only, needs the price
68
+ ProductInfo = Struct.new(:title, :kind, :brand, :model, :caliber, :calibers, :capacity, :barrel_length, :rounds,
69
+ :cost_per_round, keyword_init: true) do
70
+ def ammo?
71
+ kind == "ammo"
72
+ end
73
+
74
+ def firearm?
75
+ kind == "firearm"
76
+ end
77
+
78
+ # A plain Hash (nested models and calibers too), ready for JSON, with the Python package's field names.
79
+ # @return [Hash{Symbol => Object}]
80
+ def to_h
81
+ {
82
+ title: title, kind: kind, brand: brand, model: model&.to_h, caliber: caliber&.to_h,
83
+ calibers: calibers.map(&:to_h), capacity: capacity, barrel_length: barrel_length, rounds: rounds,
84
+ cost_per_round: cost_per_round
85
+ }
86
+ end
87
+
88
+ # @return [String] JSON object with the same field names as the Python package
89
+ def to_json(*args)
90
+ to_h.to_json(*args)
91
+ end
92
+ end
93
+ end
@@ -0,0 +1,6 @@
1
+ # frozen_string_literal: true
2
+
3
+ module GunsNPrices
4
+ # Version of this gem.
5
+ VERSION = "0.1.0"
6
+ end
@@ -0,0 +1,192 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "gunsnprices/version"
4
+ require_relative "gunsnprices/types"
5
+ require_relative "gunsnprices/py"
6
+ require_relative "gunsnprices/data_files"
7
+ require_relative "gunsnprices/specs"
8
+ require_relative "gunsnprices/calibers"
9
+ require_relative "gunsnprices/models"
10
+
11
+ # Parse firearm and ammunition product titles into structured data: brand, model, caliber, magazine capacity, barrel
12
+ # length, rounds per box and cost per round.
13
+ #
14
+ # info = GunsNPrices.parse_title("Glock 19 Gen 5 MOS 9mm 4.02in 15rd Pistol PA195S203MOS")
15
+ # info.model.model # => "Glock 19 Gen 5 MOS"
16
+ # info.caliber.name # => "9×19mm Parabellum"
17
+ # info.capacity # => 15
18
+ # info.barrel_length # => 4.02
19
+ #
20
+ # This is the title parser behind GunsNPrices (https://gunsnprices.com), ported from the Python package
21
+ # `gunsnprices` with identical results. The model dictionaries (50 brands) and the caliber list (293 calibers) in the
22
+ # gem's data/ directory are the ones the site uses to group listings; they are licensed under CC BY 4.0.
23
+ #
24
+ # Every function accepts nil for a missing title or field, is thread-safe, and returns frozen objects. The data is
25
+ # read and the rules are compiled on first use (or by {warm_up}).
26
+ module GunsNPrices
27
+ KINDS = %w[firearm ammo].freeze
28
+ private_constant :KINDS
29
+
30
+ class << self
31
+ # Parse a product title into brand, model, caliber, capacity, barrel length, rounds per box and cost per round.
32
+ #
33
+ # @param title [String, nil] product title as a store shows it
34
+ # @param brand [String, nil] manufacturer, if known (helps with titles that don't name the brand)
35
+ # @param mpn [String, nil] manufacturer part number, if known (Glock part numbers encode the model)
36
+ # @param sku [String, nil] store SKU, if known
37
+ # @param price [Numeric, String, nil] price of the listing; for ammo it gives {ProductInfo#cost_per_round}
38
+ # @param kind [String, Symbol, nil] "firearm" or "ammo"; guessed from the title when omitted
39
+ # @return [ProductInfo]
40
+ #
41
+ # @example
42
+ # info = GunsNPrices.parse_title("Glock 19 Gen5 MOS 9mm 4.02in 15+1 Black")
43
+ # [info.model.model, info.caliber.name, info.capacity, info.barrel_length]
44
+ # # => ["Glock 19 Gen 5 MOS", "9×19mm Parabellum", 15, 4.02]
45
+ # GunsNPrices.parse_title("Federal American Eagle 9mm Luger 115gr FMJ, 50/Box", price: 18.99).cost_per_round
46
+ # # => 0.3798
47
+ def parse_title(title, brand: nil, mpn: nil, sku: nil, price: nil, kind: nil)
48
+ title = -Py.str(title) # a frozen copy; the caller's string is left as it is
49
+ kind = kind.to_s
50
+ kind = looks_like_ammo?(title) ? "ammo" : "firearm" unless KINDS.include?(kind)
51
+ brand_out = Py.present?(brand) ? -Py.str(brand) : ""
52
+ cals = find_calibers(title)
53
+ if kind == "ammo"
54
+ rounds = rounds_per_box(title)
55
+ return ProductInfo.new(
56
+ title: title, kind: kind, brand: brand_out, model: nil, caliber: cals.first, calibers: cals,
57
+ capacity: nil, barrel_length: nil, rounds: rounds,
58
+ cost_per_round: Py.present?(price) ? cost_per_round(price, rounds) : nil
59
+ ).freeze
60
+ end
61
+ model = identify_model(title, brand: brand, mpn: mpn, sku: sku)
62
+ ProductInfo.new(
63
+ title: title, kind: kind, brand: model ? model.brand : brand_out, model: model, caliber: cals.first,
64
+ calibers: cals, capacity: magazine_capacity(title), barrel_length: barrel_length(title), rounds: nil,
65
+ cost_per_round: nil
66
+ ).freeze
67
+ end
68
+
69
+ # Find the brand, model family and model in a firearm product title.
70
+ #
71
+ # Only firearms are covered: titles of accessories, parts, airguns and airsoft return nil.
72
+ #
73
+ # @param title [String, nil] e.g. "Glock 19 Gen 5 MOS 9mm 4.02in 15rd Pistol PA195S203MOS"
74
+ # @param brand [String, nil] the manufacturer, if you know it
75
+ # @param mpn [String, nil] manufacturer part number, if known
76
+ # @param sku [String, nil] store SKU, if known
77
+ # @return [ModelMatch, nil] nil when no covered brand and model is recognized
78
+ #
79
+ # @example
80
+ # m = GunsNPrices.identify_model("Sig Sauer P365 XL 9mm 3.7\" 12+1 Optic Ready")
81
+ # [m.brand, m.family, m.model] # => ["Sig Sauer", "Sig Sauer P365", "Sig Sauer P365 XL"]
82
+ def identify_model(title, brand: nil, mpn: nil, sku: nil)
83
+ Models.identify_model(title, brand: brand, mpn: mpn, sku: sku)
84
+ end
85
+
86
+ # @return [Array<String>] the 50 brands covered by the model dictionaries
87
+ def list_brands
88
+ Models.list_brands
89
+ end
90
+
91
+ # All calibers mentioned in a text, in order of appearance, without duplicates.
92
+ #
93
+ # @param text [String, nil]
94
+ # @return [Array<Caliber>]
95
+ # @example
96
+ # GunsNPrices.find_calibers("Ruger GP100 .357 Mag / .38 Special 4.2in Revolver").map(&:name)
97
+ # # => [".357 Mag", ".38 S&W Special"]
98
+ def find_calibers(text)
99
+ Calibers.find_calibers(text)
100
+ end
101
+
102
+ # The first caliber mentioned in a text.
103
+ #
104
+ # @param text [String, nil]
105
+ # @return [Caliber, nil]
106
+ def find_caliber(text)
107
+ Calibers.find_caliber(text)
108
+ end
109
+
110
+ # Normalize a caliber field from a product feed ("9mm Luger", "5.56 NATO", "12 GA").
111
+ #
112
+ # The whole value is looked up first; if it isn't a known spelling, the first caliber found inside it is returned.
113
+ #
114
+ # @param value [String, nil]
115
+ # @return [Caliber, nil]
116
+ # @example
117
+ # GunsNPrices.normalize_caliber("308 WIN (7.62X51 NATO)").name # => ".308 Win"
118
+ def normalize_caliber(value)
119
+ Calibers.normalize_caliber(value)
120
+ end
121
+
122
+ # @return [Array<Caliber>] the full caliber list (293), sorted by name
123
+ def list_calibers
124
+ Calibers.list_calibers
125
+ end
126
+
127
+ # @param id [String] a caliber id, e.g. "9x19mmparabellum"
128
+ # @return [Caliber, nil]
129
+ def caliber_by_id(id)
130
+ Calibers.caliber_by_id(id)
131
+ end
132
+
133
+ # Magazine capacity of a firearm or magazine from its title ("17RD", "15+1", "10-shot").
134
+ #
135
+ # For "15+1" the magazine capacity (15) is returned. In ammunition titles "20 rounds" means rounds per box: use
136
+ # {rounds_per_box} there.
137
+ #
138
+ # @param title [String, nil]
139
+ # @return [Integer, nil]
140
+ def magazine_capacity(title)
141
+ Specs.magazine_capacity(title)
142
+ end
143
+
144
+ # Barrel length in inches from a firearm title ('4.25"', "16 in", "20-inch", '16 1/2"', "22 BBL").
145
+ #
146
+ # Chamber length (3" on shotguns), twist rate, handguard and length-of-pull values are skipped.
147
+ #
148
+ # @param title [String, nil]
149
+ # @return [Float, nil]
150
+ def barrel_length(title)
151
+ Specs.barrel_length(title)
152
+ end
153
+
154
+ # Number of rounds in one package of ammunition ("20rds", "50/box", "Box of 25", "1,000 Rounds").
155
+ #
156
+ # @param title [String, nil]
157
+ # @return [Integer, nil]
158
+ def rounds_per_box(title)
159
+ Specs.rounds_per_box(title)
160
+ end
161
+
162
+ # Price of one round, rounded to 4 decimals (half to even, like Python's round()).
163
+ #
164
+ # @param price [Numeric, String, nil] Integer, Float, BigDecimal, Rational or a numeric String
165
+ # @param rounds [Integer, nil]
166
+ # @return [Float, nil] nil without a positive price and round count
167
+ # @example
168
+ # GunsNPrices.cost_per_round(18.99, 50) # => 0.3798
169
+ def cost_per_round(price, rounds)
170
+ Specs.cost_per_round(price, rounds)
171
+ end
172
+
173
+ # True if the title reads like ammunition (bullet weight, "ammo", "20/box", ...) rather than a firearm.
174
+ #
175
+ # @param title [String, nil]
176
+ # @return [Boolean]
177
+ def looks_like_ammo?(title)
178
+ Specs.looks_like_ammo?(title)
179
+ end
180
+
181
+ # Read the data and compile the rules now instead of on first use, for example before forking worker
182
+ # processes. Takes a fraction of a second.
183
+ #
184
+ # @return [void]
185
+ def warm_up
186
+ Calibers.index
187
+ Models.dicts
188
+ Py::Rx.registry.each(&:compile_fast)
189
+ nil
190
+ end
191
+ end
192
+ end
metadata ADDED
@@ -0,0 +1,72 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: gunsnprices
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.1.0
5
+ platform: ruby
6
+ authors:
7
+ - GunsNPrices
8
+ bindir: bin
9
+ cert_chain: []
10
+ date: 1980-01-02 00:00:00.000000000 Z
11
+ dependencies: []
12
+ description: The title parser behind GunsNPrices (gunsnprices.com), a US gun and ammo
13
+ price comparison site. Reads store titles such as "G19 GEN5 9MM 15RD FS" or "Federal
14
+ 308 150gr 20rds" and returns the brand and model (50 brands), calibers (293), magazine
15
+ capacity, barrel length, rounds per box and cost per round. Ruby port of the Python
16
+ package gunsnprices with identical results. Pure Ruby, no runtime dependencies;
17
+ the model dictionaries and caliber list (CC BY 4.0) ship inside the gem.
18
+ email:
19
+ - app@gunsnprices.com
20
+ executables:
21
+ - gunsnprices
22
+ extensions: []
23
+ extra_rdoc_files: []
24
+ files:
25
+ - CHANGELOG.md
26
+ - LICENSE
27
+ - LICENSE-DATA
28
+ - README.md
29
+ - bin/gunsnprices
30
+ - data/calibers.json
31
+ - data/models.json
32
+ - gunsnprices.gemspec
33
+ - lib/gunsnprices.rb
34
+ - lib/gunsnprices/calibers.rb
35
+ - lib/gunsnprices/cli.rb
36
+ - lib/gunsnprices/data_files.rb
37
+ - lib/gunsnprices/models.rb
38
+ - lib/gunsnprices/py.rb
39
+ - lib/gunsnprices/specs.rb
40
+ - lib/gunsnprices/tables.rb
41
+ - lib/gunsnprices/types.rb
42
+ - lib/gunsnprices/version.rb
43
+ homepage: https://gunsnprices.com
44
+ licenses:
45
+ - MIT
46
+ - CC-BY-4.0
47
+ metadata:
48
+ homepage_uri: https://gunsnprices.com
49
+ source_code_uri: https://github.com/gunsnprices/gunsnprices-ruby
50
+ documentation_uri: https://github.com/gunsnprices/gunsnprices-ruby#readme
51
+ changelog_uri: https://github.com/gunsnprices/gunsnprices-ruby/blob/main/CHANGELOG.md
52
+ bug_tracker_uri: https://github.com/gunsnprices/gunsnprices-ruby/issues
53
+ rubygems_mfa_required: 'true'
54
+ rdoc_options: []
55
+ require_paths:
56
+ - lib
57
+ required_ruby_version: !ruby/object:Gem::Requirement
58
+ requirements:
59
+ - - ">="
60
+ - !ruby/object:Gem::Version
61
+ version: '3.0'
62
+ required_rubygems_version: !ruby/object:Gem::Requirement
63
+ requirements:
64
+ - - ">="
65
+ - !ruby/object:Gem::Version
66
+ version: '0'
67
+ requirements: []
68
+ rubygems_version: 4.0.23
69
+ specification_version: 4
70
+ summary: 'Parse firearm and ammunition product titles: brand, model, caliber, magazine
71
+ capacity, barrel length, rounds per box, cost per round.'
72
+ test_files: []