deepl-rb 3.6.0 → 3.6.1

data/lib/deepl.rb

@@ -0,0 +1,158 @@
+# Copyright 2018 Daniel Herzog
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+# -- Dependencies
+require 'json'
+require 'net/http'
+
+# -- Exceptions
+require 'deepl/exceptions/error'
+require 'deepl/exceptions/request_error'
+require 'deepl/exceptions/authorization_failed'
+require 'deepl/exceptions/bad_request'
+require 'deepl/exceptions/limit_exceeded'
+require 'deepl/exceptions/quota_exceeded'
+require 'deepl/exceptions/not_found'
+require 'deepl/exceptions/not_supported'
+require 'deepl/exceptions/request_entity_too_large'
+require 'deepl/exceptions/document_translation_error'
+require 'deepl/exceptions/server_error'
+
+# -- Requests
+require 'deepl/requests/base'
+require 'deepl/requests/document/download'
+require 'deepl/requests/document/get_status'
+require 'deepl/requests/document/upload'
+require 'deepl/requests/glossary/create'
+require 'deepl/requests/glossary/destroy'
+require 'deepl/requests/glossary/entries'
+require 'deepl/requests/glossary/find'
+require 'deepl/requests/glossary/language_pairs'
+require 'deepl/requests/glossary/list'
+require 'deepl/requests/style_rule/list'
+require 'deepl/requests/languages'
+require 'deepl/requests/translate'
+require 'deepl/requests/usage'
+require 'deepl/requests/rephrase'
+
+# -- Responses and resources
+require 'deepl/resources/base'
+require 'deepl/resources/document_handle'
+require 'deepl/resources/document_translation_status'
+require 'deepl/resources/glossary'
+require 'deepl/resources/style_rule'
+require 'deepl/resources/language'
+require 'deepl/resources/language_pair'
+require 'deepl/resources/text'
+require 'deepl/resources/usage'
+
+# -- Utils
+require 'deepl/utils/exception_builder'
+require 'deepl/utils/backoff_timer'
+
+# -- Constants
+require 'deepl/constants/base_constant'
+require 'deepl/constants/formality'
+require 'deepl/constants/model_type'
+require 'deepl/constants/split_sentences'
+require 'deepl/constants/tag_handling'
+require 'deepl/constants/tone'
+require 'deepl/constants/writing_style'
+
+# -- HTTP Utils
+require 'http_client_options'
+
+# -- Version
+require 'version'
+
+# -- Other wrappers
+require 'deepl/api'
+require 'deepl/configuration'
+require 'deepl/document_api'
+require 'deepl/glossary_api'
+require 'deepl/style_rule_api'
+
+# -- Gem interface
+module DeepL
+  extend self
+
+  ## -- API shortcuts
+
+  def api
+    @api ||= API.new(configuration)
+  end
+
+  def languages(options = {})
+    Requests::Languages.new(api, options).request
+  end
+
+  def translate(text, source_lang, target_lang, options = {})
+    configure if @configuration.nil?
+    Requests::Translate.new(api, text, source_lang, target_lang, options).request
+  end
+
+  def document(options = {})
+    configure if @configuration.nil?
+    DocumentApi.new(api, options)
+  end
+
+  def glossaries(options = {})
+    configure if @configuration.nil?
+    GlossaryApi.new(api, options)
+  end
+
+  def style_rules(options = {})
+    configure if @configuration.nil?
+    StyleRuleApi.new(api, options)
+  end
+
+  def rephrase(text, target_lang = nil, writing_style = nil, tone = nil, options = {}) # rubocop:disable Metrics/ParameterLists
+    configure if @configuration.nil?
+    Requests::Rephrase.new(api, text, target_lang, writing_style, tone, options).request
+  end
+
+  def usage(options = {})
+    configure if @configuration.nil?
+    Requests::Usage.new(api, options).request
+  end
+
+  def http_client
+    @http_client
+  end
+
+  def with_session(client_options = HTTPClientOptions.new()) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+    raise ArgumentError 'This method requires a block to be passed in which contains the actual API calls, see README for example usage.' unless block_given? # rubocop:disable Layout/LineLength
+
+    has_proxy = client_options.proxy.key?('proxy_addr') and client_options.proxy.key?('proxy_port')
+    begin
+      uri = URI(configuration.host)
+      http = Net::HTTP.new(uri.host, uri.port, has_proxy ? client_options.proxy['proxy_addr'] : nil,
+                           has_proxy ? client_options.proxy['proxy_port'] : nil)
+      http.use_ssl = client_options.enable_ssl_verification
+      http.ca_file = client_options.cert_path if client_options.cert_path
+      http.open_timeout = client_options.open_timeout unless client_options.open_timeout.nil?
+      http.read_timeout = client_options.read_timeout unless client_options.read_timeout.nil?
+      http.write_timeout = client_options.write_timeout unless client_options.write_timeout.nil?
+      http.ssl_timeout = client_options.ssl_timeout unless client_options.ssl_timeout.nil?
+      http.start
+      @http_client = http
+      api.update_http_client(http)
+      yield
+    ensure
+      http.finish
+    end
+  end
+
+  # -- Configuration
+
+  def configuration
+    @configuration ||= Configuration.new
+  end
+
+  def configure
+    yield configuration if block_given?
+    configuration.validate!
+  end
+end

data/lib/http_client_options.rb

@@ -0,0 +1,22 @@
+# Copyright 2024 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE file.
+# frozen_string_literal: true
+
+module DeepL
+  class HTTPClientOptions
+    attr_reader :proxy, :send_platform_info, :enable_ssl_verification, :cert_path, :open_timeout,
+                :read_timeout, :write_timeout, :ssl_timeout
+
+    def initialize(proxy, cert_path, enable_ssl_verification: true, open_timeout: nil, # rubocop:disable Metrics/ParameterLists
+                   read_timeout: nil, write_timeout: nil, ssl_timeout: nil)
+      @proxy = proxy
+      @enable_ssl_verification = enable_ssl_verification
+      @cert_path = cert_path
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      @write_timeout = write_timeout
+      @ssl_timeout = ssl_timeout
+    end
+  end
+end

data/lib/version.rb

@@ -0,0 +1,8 @@
+# Copyright 2025 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+module DeepL
+  VERSION = '3.6.1'
+end

data/spec/api/api_spec.rb

@@ -0,0 +1,20 @@
+# Copyright 2018 Daniel Herzog
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe DeepL::API do
+  subject(:api) { described_class.new(configuration) }
+
+  let(:configuration) { DeepL::Configuration.new }
+
+  describe '#initialize' do
+    context 'when building an API object' do
+      it 'saves the configuration' do
+        expect(api.configuration).to be(configuration)
+      end
+    end
+  end
+end

data/spec/api/configuration_spec.rb

@@ -0,0 +1,122 @@
+# Copyright 2018 Daniel Herzog
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+require 'logger'
+require 'spec_helper'
+
+describe DeepL::Configuration do
+  subject(:config) { described_class.new(attributes) }
+
+  let(:attributes) { {} }
+
+  around do |tests|
+    tmp_env = ENV.to_hash
+    ENV.clear
+    tests.call
+    ENV.replace(tmp_env)
+  end
+
+  describe '#initialize' do
+    context 'when using default configuration attributes' do
+      it 'uses default attributes' do
+        expect(config.auth_key).to eq(ENV.fetch('DEEPL_AUTH_KEY', nil))
+        expect(config.host).to eq('https://api.deepl.com')
+        expect(config.max_doc_status_queries).to be_nil
+        expect(config.version).to eq('v2')
+      end
+
+      it 'sends platform information' do
+        expect(config.user_agent).to include('deepl-ruby/')
+        expect(config.user_agent).to include('(')
+        expect(config.user_agent).to include(')')
+        expect(config.user_agent).to include(' ruby/')
+      end
+    end
+
+    context 'when using custom configuration attributes' do
+      let(:logger) { Logger.new($stdout) }
+      let(:attributes) { { auth_key: 'SAMPLE', host: 'https://api-free.deepl.com', logger: logger, max_doc_status_queries: 42, max_network_retries: 43, version: 'v1' } }
+
+      it 'uses custom attributes' do
+        expect(config.auth_key).to eq(attributes[:auth_key])
+        expect(config.host).to eq(attributes[:host])
+        expect(config.max_doc_status_queries).to eq(attributes[:max_doc_status_queries])
+        expect(config.max_network_retries).to eq(attributes[:max_network_retries])
+        expect(config.version).to eq(attributes[:version])
+      end
+    end
+
+    context 'when using a free key' do
+      let(:attributes) { { auth_key: '123e4567-e89b-12d3-a456-426614174000:fx' } }
+
+      it 'uses the free API URL' do
+        expect(config.host).to eq('https://api-free.deepl.com')
+      end
+    end
+
+    context 'when using a pro key' do
+      let(:attributes) { { auth_key: '123e4567-e89b-12d3-a456-426614174000' } }
+
+      it 'uses the pro API URL' do
+        expect(config.host).to eq('https://api.deepl.com')
+      end
+    end
+
+    context 'when opting out of sending platform info' do
+      subject(:config) { described_class.new(attributes, nil, nil, false) }
+
+      it 'does not send platform information' do
+        expect(config.user_agent).to include('deepl-ruby/')
+        expect(config.user_agent).not_to include('(')
+        expect(config.user_agent).not_to include(')')
+        expect(config.user_agent).not_to include(' ruby/')
+      end
+    end
+
+    context 'when registering an app and sending platform info' do
+      subject(:config) { described_class.new(attributes, 'MyTestApp', '0.1.3', true) }
+
+      it 'sends platform and app info' do
+        expect(config.user_agent).to include('deepl-ruby/')
+        expect(config.user_agent).to include('(')
+        expect(config.user_agent).to include(')')
+        expect(config.user_agent).to include(' ruby/')
+        expect(config.user_agent).to include('MyTestApp/0.1.3')
+      end
+    end
+
+    context 'when registering an app and not sending platform info' do
+      subject(:config) { described_class.new(attributes, 'MyTestApp', '0.1.3', false) }
+
+      it 'sends app, but not platform info' do
+        expect(config.user_agent).to include('deepl-ruby/')
+        expect(config.user_agent).not_to include('(')
+        expect(config.user_agent).not_to include(')')
+        expect(config.user_agent).not_to include(' ruby/')
+        expect(config.user_agent).to include('MyTestApp/0.1.3')
+      end
+    end
+  end
+
+  describe '#validate!' do
+    let(:auth_message) { 'auth_key not provided' }
+
+    context 'when providing a valid auth key' do
+      let(:attributes) { { auth_key: '' } }
+
+      it 'raises an error' do
+        expect { config.validate! }.to raise_error(DeepL::Exceptions::Error, auth_message)
+      end
+    end
+
+    context 'when providing an invalid auth key' do
+      let(:attributes) { { auth_key: 'not-empty' } }
+
+      it 'does not raise an error' do
+        expect { config.validate! }.not_to raise_error
+      end
+    end
+  end
+end