deepl-rb 2.5.3 → 3.0.0

data/lib/deepl/resources/document_translation_status.rb

@@ -0,0 +1,54 @@
+# 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
+  module Resources
+    class DocumentTranslationStatus < Base
+      attr_reader :document_id, :status, :seconds_remaining, :billed_characters, :error_message
+
+      def initialize(response, *args)
+        super(*args)
+
+        @document_id = response['document_id']
+        @status = response['status']
+        @seconds_remaining = response['seconds_remaining']
+        @billed_characters = response['billed_characters']
+        @error_message = response['error_message']
+      end
+
+      def to_s
+        "DocumentTranslationStatus: ID: #{document_id} - Status: #{status} " \
+          "- Error message: #{error_message}"
+      end
+
+      ##
+      # Checks if the translation finished successfully
+      #
+      # @return [true] if so
+
+      def successful?
+        status == 'done'
+      end
+
+      ##
+      # Checks if there was an error during translation
+      #
+      # @return [true] if so
+
+      def error?
+        status == 'error'
+      end
+
+      ##
+      # Checks if the translation process terminated. Note that this could be due to an error as
+      # well, but means no further waiting is necessary.
+      #
+      # @return [true] if so
+      def finished?
+        successful? || error?
+      end
+    end
+  end
+end

data/lib/deepl/resources/glossary.rb

@@ -1,3 +1,6 @@
+# Copyright 2022 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
 
 module DeepL

data/lib/deepl/resources/language.rb

@@ -1,3 +1,6 @@
+# Copyright 2021 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
 
 module DeepL

data/lib/deepl/resources/language_pair.rb

@@ -1,3 +1,6 @@
+# Copyright 2022 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
 
 module DeepL

data/lib/deepl/resources/text.rb

@@ -1,3 +1,6 @@
+# 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
 
 module DeepL

data/lib/deepl/resources/usage.rb

@@ -1,3 +1,6 @@
+# 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
 
 module DeepL

data/lib/deepl/utils/backoff_timer.rb

@@ -0,0 +1,46 @@
+# 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
+  module Utils
+    class BackoffTimer
+      # Implements exponential-backoff strategy.
+      # This strategy is based on the GRPC Connection Backoff Protocol:
+      # https://github.com/grpc/grpc/blob/master/doc/connection-backoff.md
+
+      BACKOFF_INITIAL = 1.0
+      BACKOFF_MAX = 120.0
+      BACKOFF_JITTER = 0.23
+      BACKOFF_MULTIPLIER = 1.6
+
+      attr_reader :num_retries
+
+      def initialize(min_connection_timeout = 10.0)
+        @num_retries = 0
+        @backoff = BACKOFF_INITIAL
+        @deadline = Time.now.to_f + @backoff
+        @min_connection_timeout = min_connection_timeout
+      end
+
+      def current_request_timeout
+        [time_until_deadline, @min_connection_timeout].max
+      end
+
+      def time_until_deadline
+        [@deadline - Time.now.to_f, 0.0].max
+      end
+
+      def sleep_until_deadline
+        sleep(time_until_deadline)
+        # Apply multiplier to current backoff time
+        @backoff = [@backoff * BACKOFF_MULTIPLIER, BACKOFF_MAX].min
+        # Get deadline by applying jitter as a proportion of backoff:
+        # if jitter is 0.1, then multiply backoff by random value in [0.9, 1.1]
+        @deadline = Time.now.to_f + (@backoff * (1 + (BACKOFF_JITTER * rand(-1.0..1.0))))
+        @num_retries += 1
+      end
+    end
+  end
+end

data/lib/deepl/utils/exception_builder.rb

@@ -1,3 +1,6 @@
+# Copyright 2022 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
 
 module DeepL
@@ -5,24 +8,26 @@ module DeepL
     class ExceptionBuilder
       attr_reader :request, :response
 
-      ERROR_CODE_CLASS_MAP = {
-        '400' => Exceptions::BadRequest,
-        '401' => Exceptions::AuthorizationFailed,
-        '403' => Exceptions::AuthorizationFailed,
-        '404' => Exceptions::NotFound,
-        '413' => Exceptions::RequestEntityTooLarge,
-        '429' => Exceptions::LimitExceeded,
-        '456' => Exceptions::QuotaExceeded
-      }.freeze
+      def self.error_class_from_response_code(code) # rubocop:disable Metrics/CyclomaticComplexity
+        case code
+        when 400 then Exceptions::BadRequest
+        when 401, 403 then Exceptions::AuthorizationFailed
+        when 404 then Exceptions::NotFound
+        when 413 then Exceptions::RequestEntityTooLarge
+        when 429 then Exceptions::LimitExceeded
+        when 456 then Exceptions::QuotaExceeded
+        when 500..599 then Exceptions::ServerError
+        else Exceptions::RequestError
+        end
+      end
 
-      def initialize(request, response)
-        @request = request
+      def initialize(response)
         @response = response
       end
 
       def build
-        error_class = ERROR_CODE_CLASS_MAP[response.code.to_s] || Exceptions::RequestError
-        error_class.new(request, response)
+        error_class = self.class.error_class_from_response_code(response.code.to_i)
+        error_class.new(response)
       end
     end
   end

data/lib/deepl.rb

@@ -1,3 +1,6 @@
+# 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
@@ -14,9 +17,14 @@ 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'
@@ -29,6 +37,8 @@ require 'deepl/requests/usage'
 
 # -- 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/language'
 require 'deepl/resources/language_pair'
@@ -37,10 +47,15 @@ require 'deepl/resources/usage'
 
 # -- Utils
 require 'deepl/utils/exception_builder'
+require 'deepl/utils/backoff_timer'
+
+# -- HTTP Utils
+require 'http_client_options'
 
 # -- Other wrappers
 require 'deepl/api'
 require 'deepl/configuration'
+require 'deepl/document_api'
 require 'deepl/glossary_api'
 
 # -- Gem interface
@@ -62,6 +77,11 @@ module DeepL
     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)
@@ -72,6 +92,33 @@ module DeepL
     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

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/license_checker.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+# Usage: ./license_checker.sh source_code_pattern
+# Example: ./license_checker.sh '*.rb'
+# This will search all .rb files, ignoring anything not tracked in your git tree
+
+git ls-files -z $1 | xargs -0 -n 10 -I{} sh -c 'RES=$(head -n 3 "{}" | grep "Copyright 20[0-9][0-9] DeepL SE (https://www.deepl.com)\|Copyright 20[0-9][0-9] Daniel Herzog"); if [ ! "${RES}" ] ; then echo "Lacking copyright header in" "{}" ; fi'
+

data/spec/api/api_spec.rb

@@ -1,15 +1,19 @@
+# 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 }
-  subject { DeepL::API.new(configuration) }
 
   describe '#initialize' do
-    context 'When building an API object' do
-      it 'should save the configuration' do
-        expect(subject.configuration).to be(configuration)
+    context 'when building an API object' do
+      it 'saves the configuration' do
+        expect(api.configuration).to be(configuration)
       end
     end
   end

data/spec/api/configuration_spec.rb

@@ -1,27 +1,101 @@
+# 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) { {} }
-  subject { DeepL::Configuration.new(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 'should use default attributes' do
-        expect(subject.auth_key).to eq(ENV.fetch('DEEPL_AUTH_KEY', nil))
-        expect(subject.host).to eq('https://api.deepl.com')
-        expect(subject.version).to eq('v2')
+    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 using custom configuration attributes' do
-      let(:attributes) { { auth_key: 'SAMPLE', host: 'https://api-free.deepl.com', version: 'v1' } }
+    context 'when registering an app and not sending platform info' do
+      subject(:config) { described_class.new(attributes, 'MyTestApp', '0.1.3', false) }
 
-      it 'should use custom attributes' do
-        expect(subject.auth_key).to eq(attributes[:auth_key])
-        expect(subject.host).to eq(attributes[:host])
-        expect(subject.version).to eq(attributes[:version])
+      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
@@ -29,19 +103,19 @@ describe DeepL::Configuration do
   describe '#validate!' do
     let(:auth_message) { 'auth_key not provided' }
 
-    context 'When providing a valid auth key' do
+    context 'when providing a valid auth key' do
       let(:attributes) { { auth_key: '' } }
 
-      it 'should raise an error' do
-        expect { subject.validate! }.to raise_error(DeepL::Exceptions::Error, auth_message)
+      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
+    context 'when providing an invalid auth key' do
       let(:attributes) { { auth_key: 'not-empty' } }
 
-      it 'should not raise an error' do
-        expect { subject.validate! }.not_to raise_error
+      it 'does not raise an error' do
+        expect { config.validate! }.not_to raise_error
       end
     end
   end