phraseapp_updater 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b9bfceed600065602f978bbafed9f6e6a729636c
-  data.tar.gz: 581f527db36b94cb44ab4fdf9eeaf621ecdbbf4e
+  metadata.gz: 8fda2274698391255a06511a13c2ee32f163986e
+  data.tar.gz: 7d8e53efb3379ca73721762d61ae3382d9c4179d
 SHA512:
-  metadata.gz: baedaa18f216752c02e01b79c12b7236c38b624089fe54d904e75abc1f0c41e26fefdb95451eaa74b6054d9dd6d7aae2a79a4bd1175d620b3d6c195d80340d33
-  data.tar.gz: 443a35fde4d991f45e4f540539aae8ed0ee1f926efce325279a5978129dbcab8d35ec7c70e1a84cff99603cdadd0d176dba3ed9c1993ca2d9f4207bb455e73aa
+  metadata.gz: 2813702a946d84e7fcb926b9ddf8e4accd6c9fd2c18ca678d389b8e953759cd041c7b09248da8d51f7032b113aa7208ae15d580f23223afb4dc518d78b6cce09
+  data.tar.gz: 67d9a874fc97e09018e464ade886851a4c32b63d05ebc8c90da46be5b4179d4368130c1bd0c23bec91c1b7cebb9f0d2699ffe44bd359dccdae1e14a51fc2e7c8

data/README.markdown

@@ -2,9 +2,15 @@
 
 [![Build Status](https://travis-ci.org/iknow/phraseapp_updater.svg?branch=master)](https://travis-ci.org/iknow/phraseapp_updater)
 
-**Version** 0.1.0
+**Version** 0.1.3
 
-This is a tool for performing three-way merges of [PhraseApp](https://phraseapp.com) locale data with locale data commited to your application.
+This is a tool for merging PhraseApp locale data with locale data
+committed in your project.
+
+It can perform three-way merges of [PhraseApp](https://phraseapp.com) locale data with locale data commited to your application.
+It can also pull from PhraseApp, ignoring missing keys (this is very
+useful for using "unverified" status for marking a translation as a
+draft).
 
 Our current workflow has localizers working on a `master` project on
 PhraseApp. This regularly gets pulled into the `master` branch of our
@@ -19,7 +25,7 @@ them, but the API only allows either a) completely overwriting
 PhraseApp's data or b) reapplying PhraseApp's data on top of the
 uploaded data.
 
-What we want instead is a three way merge where the uploaded data wins
+What we want instead is a three way merge where the committed data wins
 on conflict. Non-conflicting changes on PhraseApp are preserved, while
 changes on both sides take the committed data. The result of the merge
 is then sent to PhraseApp, keeping it up-to-date with the newest commit
@@ -74,15 +80,16 @@ Or install it yourself as:
 CLI
 ---
 
-`phraseapp_updater` operates on two directories and your PhraseApp API
-data. The two directories should contain the previous revision of your
-locale files and the latest revision of the same files. These will be
-used in the merge with the files on PhraseApp.
+**Push**
 
-The main command is the the `push_changes` command:
+`phraseapp_updater push` operates on two directories and your PhraseApp API
+data. The two directories should contain the previous revision of your
+locale files from PhraseApp and the latest revision of the same files
+committed to your application's respository.  These will be used in the
+merge with the files on PhraseApp.
 
 ```
-phraseapp_updater push_changes --new_locales_path="/data/previous", --previous_locales_path="/data/new" --phraseapp_api_key="yourkey" --phraseapp_project_id="projectid"
+phraseapp_updater push --new_locales_path="/data/previous", --previous_locales_path="/data/new" --phraseapp_api_key="yourkey" --phraseapp_project_id="projectid"
 ```
 
 The arguments provided to the command can also be specified as shell
@@ -95,23 +102,65 @@ PA_API_KEY
 PA_PROJECT_ID
 ```
 
+Additionally, PhraseApp credentials can be loaded from a
+`.phraseapp.yml` file, specified with `--config-file-path`
+
+**Pull**
+
+`phraseapp_updater pull` pulls data down from your PhraseApp project.
+However, when keys are missing from the PhraseApp data, it restores them
+(if present) from the files at fallback path provided. This allows you
+to mark keys as "unverified" on PhraseApp, meaning you don't pull in
+draft translations, while allowing you to keep the current version of
+that translation.
+
+If you want to pull without this fallback behavior, PhraseApp's [client](https://phraseapp.com/docs/developers/cli/)
+is the best tool to use.
+
+```
+phraseapp_updater pull --fallback_path="/data/app/locales" --phraseapp_api_key="yourkey" --phraseapp_project_id="projectid"
+```
+
+The PhraseApp data passed to the command can also be specified as shell
+variables:
+
+```
+PA_API_KEY
+PA_PROJECT_ID
+```
+
+Additionally, PhraseApp credentials can be loaded from a
+`.phraseapp.yml` file, specified with `--config-file-path`
+
 Ruby
 ---
 
-`PhraseAppUpdater.push` is analogous to the command line version:
+`PhraseAppUpdater.push` and `PhraseAppUpdater.pull` are analogous to the command line versions:
 
 ```ruby
 PhraseAppUpdater.push("api_key", "project_id", "previous/path", "current/path")
+PhraseAppUpdater.pull("api_key", "project_id", "fallback/path")
 ```
 
+
+## git-based Driver
+
+We use a small bash script for driving this library to push and pull
+from PhraseApp. While there are many ways to merge data in your
+application with PhraseApp, this works for us:
+
+https://gist.github.com/kevingriffin/d59821446ce424a56c7da2686d4ae082
+
 ## Future Improvements
 
 If you'd like to contribute, these would be very helpful!
 
-* Expose the changed files on the command line
-* Implement other `LocaleFile`s with `parse` for non-JSON types
-* Checking if PhraseApp files changed during execution before upload, to reduce the race condition window
-* More specs for the API and shell
+* Separating downloading and resolving data from PhraseApp from pushing
+  back up to it, to enable different kinds of workflows.
+* Expose the changed files on the command line.
+* Implement other `LocaleFile`s with `parse` for non-JSON types.
+* Checking if PhraseApp files changed during execution before upload, to reduce the race condition window.
+* More specs for the API and shell.
 
 ## Development
 

data/bin/phraseapp_updater

@@ -3,128 +3,137 @@ require 'thor'
 require 'phraseapp_updater'
 
 class PhraseAppUpdaterCLI < Thor
-  desc "push", "Update PhraseApp project by merging changes from locale file and PhraseApp"
-  option :new_locales_path,                type: :string
-  option :previous_locales_path,           type: :string
-  option :phraseapp_api_key,               type: :string
-  option :phraseapp_project_id,            type: :string
-  option :config_file_path,                type: :string
-  option :store_results_path,              type: :string
-  option :store_phraseapp_originals_path,  type: :string
+  desc "push", "Update PhraseApp project via a 3-way merge with local locale files and PhraseApp data."
+  option :new_locales_path,                type: :string, desc: "Path to newest revision of local files. Shell variable: PA_NEW_LOCALES_PATH"
+  option :previous_locales_path,           type: :string, desc: "Path to previous revision of local files. Shell variable: PA_PREVIOUS_LOCALES_PATH"
+  option :phraseapp_api_key,               type: :string, desc: "PhraseApp API key. Shell variable: PA_API_KEY"
+  option :phraseapp_project_id,            type: :string, desc: "PhraseApp project ID. Shell variable: PA_PROJECT_ID"
+  option :config_file_path,                type: :string, desc: "Path to .phraseapp.yml config file to read API key and project ID."
+  option :store_results_path,              type: :string, desc: "Path to write the resolved files. Shell variable: PA_STORE_RESULTS_PATH"
+  option :store_phraseapp_originals_path,  type: :string, desc: "Path to write the files downloaded from PhraseApp before the merge. Shell variable: PA_STORE_PHRASEAPP_ORIGINALS_PATH"
 
   def push
-    if options[:config_file_path]
-
-      if options[:phraseapp_api_key] || options[:phraseapp_project_id]
-        raise RuntimeError.new("Provided both a path to PhraseApp config file and command line arguments. Specify only one. #{options}")
-      end
-
-      config = PhraseAppUpdater.load_config(options[:config_file_path])
-
-      phraseapp_api_key    = config.api_key
-      phraseapp_project_id = config.project_id
-    else
-      phraseapp_api_key    = options.fetch(:phraseapp_api_key, ENV["PA_API_KEY"])
-      phraseapp_project_id = options.fetch(:phraseapp_project_id, ENV["PA_PROJECT_ID"])
-    end
-
-    if phraseapp_api_key.to_s.empty?
-      raise RuntimeError.new("Must provide Phraseapp API key. --phraseapp_api_key or PA_API_KEY")
-    end
+    phraseapp_api_key, phraseapp_project_id = load_phraseapp_credentials(options)
 
-    if phraseapp_project_id.to_s.empty?
-      raise RuntimeError.new("Must provide Phraseapp project ID. --phraseapp_project_id or PA_PROJECT_ID")
-    end
-
-    new_locales_path = options.fetch(:new_locales_path, ENV["PA_NEW_LOCALES_PATH"])
-
-    if new_locales_path.to_s.empty?
-      raise RuntimeError.new("Must provide a path to the locale files to upload. --new_locales_path or PA_NEW_LOCALES_PATH")
-    end
+    new_locales_path = options.fetch(:new_locales_path, ENV["PA_NEW_LOCALES_PATH"]).to_s
+    validate_readable_path!('new_locales_path', new_locales_path)
 
-    unless File.readable?(new_locales_path) && File.directory?(new_locales_path)
-      raise RuntimeError.new("Path to locales is not a readable directory: #{new_locales_path}")
-    end
+    previous_locales_path = options.fetch(:previous_locales_path, ENV["PA_PREVIOUS_LOCALES_PATH"]).to_s
+    validate_readable_path!('previous_locales_path', previous_locales_path)
 
-    previous_locales_path = options.fetch(:previous_locales_path, ENV["PA_PREVIOUS_LOCALES_PATH"])
-    if previous_locales_path.to_s.empty?
-      raise RuntimeError.new("Must provide a path to the locale files to upload. --previous_locales_path or PA_PREVIOUS_LOCALES_PATH")
-    end
+    store_results_path = options.fetch(:store_results_path, ENV["PA_STORE_RESULTS_PATH"]).to_s
+    validate_writable_path!('store_results_path', store_results_path)
 
-    unless File.readable?(previous_locales_path) && File.directory?(previous_locales_path)
-      raise RuntimeError.new("Path to locales is not a readable directory: #{previous_locales_path}")
-    end
-
-    store_results_path = options.fetch(:store_results_path, ENV["PA_store_results_path"]).to_s
-
-    if !store_results_path.empty? && (!File.writable?(store_results_path) || !File.directory?(store_results_path))
-      raise RuntimeError.new("Path to store results is not a writable directory: #{store_results_path}")
-    end
-
-    store_phraseapp_originals_path = options.fetch(:store_phraseapp_originals_path, ENV["PA_store_phraseapp_originals_path"]).to_s
-
-    if !store_phraseapp_originals_path.empty? && (!File.writable?(store_phraseapp_originals_path) || !File.directory?(store_phraseapp_originals_path))
-      raise RuntimeError.new("Path to store PhraseApp originals is not a writable directory: #{store_phraseapp_originals_path}")
-    end
+    store_phraseapp_originals_path = options.fetch(:store_phraseapp_originals_path, ENV["PA_STORE_PHRASEAPP_ORIGINALS_PATH"]).to_s
+    validate_writable_path!('store_phraseapp_originals_path', store_phraseapp_originals_path)
 
     begin
       result = PhraseAppUpdater.push(phraseapp_api_key, phraseapp_project_id, previous_locales_path, new_locales_path)
 
       unless store_results_path.empty?
-        result.resolved_files.each do |file|
-          path = "#{store_results_path.chomp("/")}/#{file.name}.json"
-          File.write(path, file.content)
-        end
+        write_locale_files(store_results_path, result.resolved_files)
       end
 
       unless store_phraseapp_originals_path.empty?
-        result.original_phraseapp_files.each do |file|
-          path = "#{store_phraseapp_originals_path.chomp("/")}/#{file.name}.json"
-          File.write(path, file.content)
-        end
+        write_locale_files(store_phraseapp_originals_path, result.original_phraseapp_files)
       end
+    rescue PhraseAppUpdater::PhraseAppAPI::BadAPIKeyError => e
+      puts "Bad PhraseApp API key."
+    rescue PhraseAppUpdater::PhraseAppAPI::BadProjectIDError => e
+      puts "Bad PhraseApp project ID: #{phraseapp_project_id}"
     rescue StandardError => e
-      # Like a bad API key
-      # Raise more specific errors and handle
+      puts "Unknown error when pushing files"
       raise e
     end
   end
 
 
-  desc "pull", "Pulls data from PhraseApp for deployment."
-  option :fallback_path,         type: :string,  required: true
-  option :destination_path,      type: :string
-  option :phraseapp_api_key,     type: :string
-  option :phraseapp_project_id,  type: :string
+  desc "pull", "Pulls data from PhraseApp for deployment, replacing missing keys from fallback."
+  option :fallback_path,         type: :string,  required: true, desc: "Path to the files to restore missing keys from."
+  option :destination_path,      type: :string,                  desc: "Path to write the resolved files to. If not provided, --fallback_path is used."
+  option :phraseapp_api_key,     type: :string,                  desc: "PhraseApp API key. Shell variable: PA_API_KEY"
+  option :phraseapp_project_id,  type: :string,                  desc: "PhraseApp project ID. Shell variable: PA_PROJECT_ID"
+  option :config_file_path,      type: :string,                  desc: "Path to .phraseapp.yml config file to read API key and project ID."
 
   def pull
+    phraseapp_api_key, phraseapp_project_id = load_phraseapp_credentials(options)
+
     fallback_path = options[:fallback_path]
-    unless File.readable?(fallback_path) && File.directory?(fallback_path)
-      raise RuntimeError.new("fallback_path directory is not a readable directory: #{fallback_path}")
+    validate_readable_path!('fallback_path', fallback_path)
+
+    destination_path = options.fetch(:destination_path, fallback_path).to_s
+    validate_writable_path!('destination_path', destination_path)
+
+    begin
+      files = PhraseAppUpdater.pull(phraseapp_api_key, phraseapp_project_id, fallback_path)
+      write_locale_files(destination_path, files)
+    rescue PhraseAppUpdater::PhraseAppAPI::BadAPIKeyError => e
+      puts "Bad PhraseApp API key."
+    rescue PhraseAppUpdater::PhraseAppAPI::BadProjectIDError => e
+      puts "Bad PhraseApp project ID: #{phraseapp_project_id}"
+    rescue StandardError => e
+      puts "Unknown error when pushing files"
+      raise e
     end
+  end
 
-    destination_path = options.fetch(:destination_path, fallback_path)
+  private
+
+  def load_phraseapp_credentials(options)
+    if options[:config_file_path]
 
-    unless File.writable?(fallback_path) && File.directory?(fallback_path)
-      raise RuntimeError.new("destination directory is not a writable directory: #{fallback_path}")
+      if options[:phraseapp_api_key] || options[:phraseapp_project_id]
+        raise RuntimeError.new("Provided both a path to PhraseApp config file and command line arguments. Specify only one. #{options}")
+      end
+
+      config = PhraseAppUpdater.load_config(options[:config_file_path])
+
+      phraseapp_api_key    = config.api_key
+      phraseapp_project_id = config.project_id
+    else
+      phraseapp_api_key    = options.fetch(:phraseapp_api_key, ENV["PA_API_KEY"]).to_s
+      phraseapp_project_id = options.fetch(:phraseapp_project_id, ENV["PA_PROJECT_ID"]).to_s
     end
 
-    phraseapp_api_key = options.fetch(:phraseapp_api_key, ENV["PA_API_KEY"])
-    if phraseapp_api_key.to_s.empty?
+    if phraseapp_api_key.empty?
       raise RuntimeError.new("Must provide Phraseapp API key. --phraseapp_api_key or PA_API_KEY")
     end
 
-    phraseapp_project_id = options.fetch(:phraseapp_project_id, ENV["PA_PROJECT_ID"])
-    if phraseapp_project_id.to_s.empty?
+    if phraseapp_project_id.empty?
       raise RuntimeError.new("Must provide Phraseapp project ID. --phraseapp_project_id or PA_PROJECT_ID")
     end
 
-    files = PhraseAppUpdater.pull(phraseapp_api_key, phraseapp_project_id, fallback_path)
+    return [phraseapp_api_key, phraseapp_project_id]
+  end
+
+  def validate_path!(name, path)
+    if path.empty?
+      raise RuntimeError.new("#{name} was empty.")
+    end
+  end
+
+  def validate_readable_path!(name, path)
+    validate_path!(name, path)
+
+    unless File.readable?(path) && File.directory?(path)
+      raise RuntimeError.new("#{name} path is not a readable directory: #{path}")
+    end
+  end
+
+  def validate_writable_path!(name, path)
+    validate_path!(name, path)
+
+    unless File.writable?(path) && File.directory?(path)
+      raise RuntimeError.new("#{name} path is not a writable directory: #{path}")
+    end
+  end
 
+  def write_locale_files(path, files)
     files.each do |file|
-      path = "#{destination_path.chomp("/")}/#{file.name}.json"
-      File.write(path, file.content)
+      full_path = "#{path.chomp('/')}/#{file.name_with_extension}"
+      File.write(full_path, file.content)
     end
+    puts "Wrote #{files.count} files to #{path}: #{files.map(&:name_with_extension)}"
   end
 end
 

data/lib/phraseapp_updater/locale_file.rb

@@ -24,6 +24,10 @@ class PhraseAppUpdater
       "#{name}, #{content[0,20]}..."
     end
 
+    def name_with_extension
+      "#{name}.json"
+    end
+
     private
 
     def parse(content)

data/lib/phraseapp_updater/phraseapp_api.rb

@@ -1,5 +1,5 @@
-require 'phraseapp-ruby'
 require 'phraseapp_updater/locale_file'
+require 'phraseapp-ruby'
 require 'thread'
 
 class PhraseAppUpdater
@@ -83,7 +83,17 @@ class PhraseAppUpdater
     private
 
     def phraseapp_request(&block)
-      res, err = block.call
+      begin
+        res, err = block.call
+      rescue RuntimeError => e
+        if e.message[/\(401\)/]
+          raise BadAPIKeyError.new(e)
+        elsif e.message[/not found/]
+          raise BadProjectIDError.new(e)
+        else
+          raise e
+        end
+      end
 
       unless err.nil?
         if err.respond_to?(:error)
@@ -139,7 +149,7 @@ class PhraseAppUpdater
     end
 
     def generate_upload_tag
-      "file_merge_upload_#{Time.now.strftime('%Y%m%d%H%M%S')}"
+      "phraseapp_updater_upload_#{Time.now.strftime('%Y%m%d%H%M%S')}"
     end
 
     class Locale
@@ -158,6 +168,18 @@ class PhraseAppUpdater
         "#{name} : #{id}"
       end
     end
+
+    class BadAPIKeyError < RuntimeError
+      def initialize(original_error)
+        super(original_error.message)
+      end
+    end
+
+    class BadProjectIDError < RuntimeError
+      def initialize(original_error)
+        super(original_error.message)
+      end
+    end
   end
 end
 

data/lib/phraseapp_updater/version.rb

@@ -1,3 +1,3 @@
 class PhraseAppUpdater
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phraseapp_updater
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Kevin Griffin
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-02-16 00:00:00.000000000 Z
+date: 2017-02-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -199,9 +199,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: A three-way differ for PhraseApp projects.
 test_files: []
-has_rdoc: