powo_ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 561a6110f77e9efed535f748c4a52d337cfd3793b92afc92b462e3c8b3808216
+  data.tar.gz: aa1ab89a77ccc23b3d47592b92fdc8d7ed67e895241d5361b499ed9c406a78b6
+SHA512:
+  metadata.gz: 6bdb026cf7f540f37cbdc79c59e49cefba7a8cd4991d5c8a8623a47a26a92db98f382cf6750c57408532e2a58580c353904bac51c217ee6a0c8c08f3fa0f2f72
+  data.tar.gz: 70ac333d17c161e9f03fcb9b54b4bc3afd06c2125a77f9a840a87d137da1f56749214b9a7467ec9062829b1b9d20d1f5f9e72ce49bf40c69adc4af8c1b73ef6f

data/.rubocop.yml

@@ -0,0 +1,38 @@
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  Exclude:
+    - "examples/**/*"
+    - "tmp/**/*"
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Metrics/AbcSize:
+  Max: 60
+
+Metrics/BlockLength:
+  Max: 40
+  Exclude:
+    - "spec/**/*"
+
+Metrics/ClassLength:
+  Max: 250
+
+Metrics/CyclomaticComplexity:
+  Max: 30
+
+Metrics/MethodLength:
+  Max: 60
+
+Metrics/ParameterLists:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 30
+
+Style/Documentation:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-02-12
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Reka Pap
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,201 @@
+# powo_ruby
+
+`powo_ruby` is a small, defensive, **unofficial** Ruby client for the Plants of the World Online (POWO) API.
+
+## Disclaimer
+
+- This gem is **not** an official Kew product.
+- POWO's API is **undocumented and may change or break** at any time.
+- The API is publicly accessible and does not require authentication, but you should use it responsibly.
+
+**Attribution**: Data and service provided by the Royal Botanic Gardens, Kew (POWO: Plants of the World Online).
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "powo_ruby"
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install powo_ruby
+```
+
+## Usage
+
+### Convenience clients (recommended)
+
+This gem exposes two convenience client constructors:
+
+- `PowoRuby.powo` (POWO allow-list + POWO group keys)
+- `PowoRuby.ipni` (IPNI allow-list + IPNI group keys)
+
+Both return a configured `PowoRuby::Client` instance (memoized per-thread unless you pass overrides).
+
+#### Basic search (POWO)
+
+```ruby
+require "powo_ruby"
+
+response = PowoRuby.powo.search.query(
+  query: "Apocynaceae",
+  filters: {
+    family: "Apocynaceae",
+    accepted: true
+  }
+)
+
+response.total_count #=> Integer or nil
+response.results     #=> Array of result hashes
+```
+
+#### Lookup by POWO/IPNI identifier
+
+```ruby
+taxon = PowoRuby.powo.taxa.lookup("urn:lsid:ipni.org:names:30000618-2")
+taxon.raw #=> Hash (schema may change)
+```
+
+#### Advanced search (structured)
+
+`advanced_search` only accepts parameters defined in `docs/POWO_SEARCH_TERMS.md`.
+
+Flat form:
+
+```ruby
+response = PowoRuby.powo.search.advanced(
+  family: "Fabaceae",
+  accepted: true,
+  limit: 24
+)
+```
+
+Grouped form:
+
+```ruby
+response = PowoRuby.powo.search.advanced(
+  name: { family: "Fabaceae", genus: "Acacia" },
+  geography: { country: "Brazil" },
+  accepted: true
+)
+```
+
+#### Pagination (Enumerator-based)
+
+POWO uses a cursor for paging. For most use-cases, prefer the `*_each` enumerators.
+
+```ruby
+PowoRuby.powo.search.each(query: "Acacia", filters: { accepted: true }).take(50)
+```
+
+Or for advanced search:
+
+```ruby
+enum = PowoRuby.powo.search.advanced_each(name: { family: "Fabaceae" }, accepted: true)
+enum.each do |row|
+  puts row["name"]
+end
+```
+
+## IPNI mode
+
+IPNI is exposed at the same level as POWO, and validates parameters against the **IPNI term list** found in `docs/POWO_SEARCH_TERMS.md`:
+
+```ruby
+response = PowoRuby.ipni.search.query(query: "Poa annua", filters: { family: "Poaceae" })
+```
+
+Note: POWO's API does not expose a clearly documented `/ipni/...` endpoint under `/api/2`. This gem therefore uses the same `/search` and `/taxon/<id>` endpoints but validates parameters against the IPNI allow-list.
+
+## Configuration
+
+```ruby
+PowoRuby.configure do |c|
+  c.base_url = "https://powo.science.kew.org/api/2"
+  c.timeout = 10
+  c.open_timeout = 5
+  c.retries = true
+end
+```
+
+### Logger support
+
+Pass any logger responding to `warn`:
+
+```ruby
+require "logger"
+
+PowoRuby.configure do |c|
+  c.logger = Logger.new($stdout)
+end
+```
+
+### Caching support (optional adapter)
+
+Provide an object that responds to `fetch(key, options = nil) { ... }`:
+
+```ruby
+cache = {}
+adapter = Object.new
+def adapter.fetch(key)
+  @store ||= {}
+  return @store[key] if @store.key?(key)
+  @store[key] = yield
+end
+
+PowoRuby.configure do |c|
+  c.cache = adapter
+end
+```
+
+You can also pass cache options (e.g. TTL) and a namespace for cache keys:
+
+```ruby
+PowoRuby.configure do |c|
+  c.cache = Rails.cache
+  c.cache_options = { expires_in: 60 } # seconds
+  c.cache_namespace = "my_app"
+end
+```
+
+## CLI (optional)
+
+After installation:
+
+```bash
+powo_ruby search "Acacia" --filter accepted=true --filter family=Fabaceae
+powo_ruby lookup "urn:lsid:ipni.org:names:30000618-2"
+powo_ruby ipni-search "Poa annua" --filter family=Poaceae
+```
+
+## Development
+
+```bash
+bin/setup
+bundle exec rspec
+bundle exec rubocop
+```
+
+## Examples
+
+Examples (including a tiny Sinatra app with basic views for search + taxon lookup) live in the separate repo [`rekapap/powo_ruby_examples`](https://github.com/rekapap/powo_ruby_examples).
+
+```bash
+git clone https://github.com/rekapap/powo_ruby_examples.git
+cd powo_ruby_examples/basic_app
+bundle install
+bundle exec rackup
+```
+
+## License
+
+MIT. See `LICENSE.txt`.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: %i[spec rubocop]

data/docs/POWO_SEARCH_TERMS.md

@@ -0,0 +1,63 @@
+# POWO Search Terms
+
+## Name Terms
+- full_name
+- scientific_name
+- genus
+- species
+- infraspecific
+- family
+- common_name
+- author
+- rank
+- status
+
+## Characteristic Terms
+- summary
+- appearance
+- flower
+- fruit
+- leaf
+- habit
+- habitat
+- use
+- conservation
+
+## Geography Terms
+- distribution
+- native_distribution
+- introduced_distribution
+- region
+- continent
+- country
+
+## Additional Filters
+- accepted (boolean)
+- images (boolean)
+- page (pagination)
+- limit (pagination)
+- sort (ordering)
+
+---
+
+# IPNI Search Terms
+
+## Name Terms
+- genus
+- species
+- infraspecific_rank
+- infraspecific_name
+- family
+- publication_year
+- full_name
+
+## Author Terms
+- author
+- standard_form
+- collaboration
+
+## Publication Terms
+- publication_title
+- publication_year
+- publication_place
+- publisher

data/exe/powo_ruby

@@ -0,0 +1,134 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require "powo_ruby"
+
+def parse_kv_pairs(pairs)
+  pairs.each_with_object({}) do |pair, out|
+    key, value = pair.split("=", 2)
+    raise ArgumentError, "Invalid filter '#{pair}' (expected key=value)" if key.to_s.empty?
+
+    out[key.to_sym] =
+      case value
+      when "true" then true
+      when "false" then false
+      when /\A\d+\z/ then Integer(value)
+      else
+        value
+      end
+  end
+end
+
+options = {
+  base_url: PowoRuby.config.base_url,
+  timeout: PowoRuby.config.timeout,
+  open_timeout: PowoRuby.config.open_timeout,
+  retries: PowoRuby.config.retries,
+  pretty: true,
+  cursor: "*",
+  per_page: 24
+}
+
+parser = OptionParser.new do |opts|
+  opts.banner = <<~BANNER
+    Usage: powo_ruby [options] <command> [args]
+
+    Commands:
+      search <query>
+      lookup <id>
+      ipni-search <query>
+  BANNER
+
+  opts.on("--base-url URL", "API base URL (default: #{options[:base_url]})") { |v| options[:base_url] = v }
+  opts.on("--timeout SECONDS", Integer, "Request timeout (default: #{options[:timeout]})") { |v| options[:timeout] = v }
+  opts.on("--open-timeout SECONDS", Integer, "Open timeout (default: #{options[:open_timeout]})") do |v|
+    options[:open_timeout] = v
+  end
+  opts.on("--no-retries", "Disable retry/backoff") { options[:retries] = false }
+  opts.on("--[no-]pretty", "Pretty-print JSON output (default: true)") { |v| options[:pretty] = v }
+  opts.on("-h", "--help", "Show this help") do
+    puts opts
+    exit 0
+  end
+end
+
+parser.order!
+
+command = ARGV.shift
+raise ArgumentError, "Command is required. Use --help." if command.to_s.empty?
+
+client = PowoRuby::Client.new(
+  base_url: options[:base_url],
+  timeout: options[:timeout],
+  open_timeout: options[:open_timeout],
+  retries: options[:retries]
+)
+
+case command
+when "search"
+  query = ARGV.shift
+  raise ArgumentError, "search requires <query>" if query.to_s.empty?
+
+  filters = []
+  OptionParser.new do |opts|
+    opts.on("--cursor CURSOR", "Cursor for pagination (default: '*')") { |v| options[:cursor] = v }
+    opts.on("--per-page N", Integer, "Results per page (default: 24)") { |v| options[:per_page] = v }
+    opts.on("--filter KEY=VALUE", "Repeatable filter (e.g. family=Fabaceae accepted=true)") { |v| filters << v }
+  end.parse!(ARGV)
+
+  response =
+    client.search.query(
+      query: query,
+      filters: parse_kv_pairs(filters),
+      cursor: options[:cursor],
+      per_page: options[:per_page]
+    )
+  output = { total: response.total_count, results: response.results }
+when "lookup"
+  id = ARGV.shift
+  raise ArgumentError, "lookup requires <id>" if id.to_s.empty?
+
+  response = client.taxa.lookup(id)
+  output = response.raw
+when "ipni-search"
+  query = ARGV.shift
+  raise ArgumentError, "ipni-search requires <query>" if query.to_s.empty?
+
+  filters = []
+  OptionParser.new do |opts|
+    opts.on("--cursor CURSOR", "Cursor for pagination (default: '*')") { |v| options[:cursor] = v }
+    opts.on("--per-page N", Integer, "Results per page (default: 24)") { |v| options[:per_page] = v }
+    opts.on("--filter KEY=VALUE", "Repeatable filter (validated against IPNI term list)") { |v| filters << v }
+  end.parse!(ARGV)
+
+  ipni_client =
+    PowoRuby::Client.new(
+      mode: :ipni,
+      base_url: options[:base_url],
+      timeout: options[:timeout],
+      open_timeout: options[:open_timeout],
+      retries: options[:retries]
+    )
+
+  response =
+    ipni_client.search.query(
+      query: query,
+      filters: parse_kv_pairs(filters),
+      cursor: options[:cursor],
+      per_page: options[:per_page]
+    )
+  output = { total: response.total_count, results: response.results }
+else
+  raise ArgumentError, "Unknown command '#{command}'. Use --help."
+end
+
+json =
+  if options[:pretty]
+    JSON.pretty_generate(output)
+  else
+    JSON.dump(output)
+  end
+
+puts json