piwigo-api 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f0808e4bf6d4c5d9800c348b749a34b812d137a7268f76954895089127b0dc4
-  data.tar.gz: bba4ab540b38076e7c32e1e6d2b776e15a135ffd59a2d5f8b0e76c33b5d1ece9
+  metadata.gz: 5051a29ebbe23995bb4c2d6436d6534b197f1b3794f7f857e0678e612d544501
+  data.tar.gz: f0c5dc53eede301abf914eb04fecb42e3c607281786939ef51db3dc50a6c8e98
 SHA512:
-  metadata.gz: 0b5f0499e2d5f445b023f3252d6b4d10802e5374c19be951b872d59bc5e64e33b7c0f85c1dffc3e3503b4b98ff0faa71928e36d0223f540b73530763331b1740
-  data.tar.gz: 8d37ee9536426d15f36c4c25ca12cd1c0019819410af4332bc6515c9f9a9dc57329532fdd8be0e89c24581993ea1766a129ac4738e6b187b133e2c69bb35ebcf
+  metadata.gz: 0fa2225cd04231a474299be116ff723a7ecbc70f44ada895041adfa2e47131663d08f60b399dd2ca98eb5e8f24ebf403195f2ff8aaf929d2e17e63bb7345c7cb
+  data.tar.gz: 4dfb369883eadfe868eaa6853a9c3c70661fef1ad9fd01b57011cf6e30454c5c56caf559f855465939ec9a2c9ab11f7c21a01eb99d6c0c063129441cdef340c1

data/.gitignore

@@ -7,3 +7,4 @@
 /spec/reports/
 /tmp/
 *.gem
+main.rb

data/.vscode/launch.json

@@ -5,6 +5,7 @@
     "version": "0.2.0",
     "configurations": [
     
+    
         {
             "name": "Debug Local File",
             "type": "Ruby",

data/CHANGELOG.md

@@ -6,6 +6,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+0.2.0 - 2019-11-17
+- Refactored the Session to make iteasier to use
+- Support adding/deleting & listing albums
 
 0.1.1 - 2019-11-16 
 - Initial Version, supports login/logout against a piwigo server

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    piwigo-api (0.1.0)
+    piwigo-api (0.2.0)
       http (~> 4.2)
       logger (~> 1.4)
 

data/README.md

@@ -1,8 +1,8 @@
 # Piwigo-API
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/piwigo`. To experiment with that code, run `bin/console` for an interactive prompt.
+Piwigo is open source web application to manage your collection of photos, and other medias. Piwigo provides an API for interacting with it. 
 
-TODO: Delete this and the text above, and describe your gem
+This is a ruby-based client for interacting with a Piwigo instance using the Piwigo API.
 
 ## Installation
 
@@ -22,7 +22,32 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Just include 'piwigo/session' and the related classes, then querying Piwigo is fairly quick and straightforward.
+
+# Get the second album and all of it's children
+
+
+```
+require 'piwigo/session'
+require 'piwigo/albums'
+
+session = Piwigo::Session.login('mypiwigo.fqdn', 'Adrian', 'mypassword', https: false) 
+unless session.nil? 
+    albums = Piwigo::Albums.list(session, album_id: 2, recursive: true)
+    albums.each { |album| p "#{album.id}, #{album.name} - # of photos: #{album.total_nb_images}" }
+end
+```
+
+# Add a new album
+```
+session = Piwigo::Session.login('10.100.230.78', 'Adrian', 'secret', https: false) 
+unless session.nil? 
+    album = Piwigo::Albums::Album.new
+    album.name = "My First Album"
+    album = Piwigo::Albums.add(session, album)
+end
+```
+
 
 ## Development
 
@@ -32,7 +57,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/kkdad/piwigo.
+Bug reports and pull requests are welcome on GitHub at https://github.com/kkdad/piwigo-ruby.
 
 ## License
 

data/lib/piwigo/albums.rb

@@ -0,0 +1,187 @@
+require 'net/http'
+require 'uri'
+require 'json'
+require 'logger'
+
+# Piwigo organizes images by albums. The album tree has unlimted depth and each photo can belong to multiple albums. The Piwigo API
+# refers to a Album as a Category.
+module Piwigo
+    class Albums
+        class Album
+            # @return [Number] Album ID
+            attr_accessor :id
+
+            # @return [String] Name of the Album
+            attr_accessor :name
+
+            # @return [String] Album Description
+            attr_accessor :comment
+
+            # ???
+            attr_accessor :permalink
+
+            # @return [String] public or private
+            attr_accessor :status
+
+            # ???
+            attr_accessor :uppercats
+
+            # The rank of an album
+            attr_accessor :global_rank
+
+            # @return [Number] ID of the parent album, nil of this is a top-level album (Aka ParentID)
+            attr_accessor :id_uppercat
+
+            # @return [Number] Number of the Newest photos, excluding child albums
+            attr_accessor :nb_images
+
+            # @return [Number] Number of the Newest photos, including child albums
+            attr_accessor :total_nb_images
+
+            # ID of the representative photo for an album. This photo doesn't have to belong to the album.
+            attr_accessor :representative_picture_id
+
+            # @return [DateTime] Date of the Newest photos, excluding child albums
+            attr_accessor :date_last
+
+            # @return [DateTime] Date of the Newest photos, including child albums
+            attr_accessor :max_date_last
+
+            # @return [Number] Number of child albums inside this album
+            attr_accessor :nb_categories
+
+            # @return [Atring] Album URL
+            attr_accessor :url
+
+            # @return [String] Thumbnail URL
+            attr_accessor :tn_url  
+
+            def initialize(hash: nil)                
+                hash.each { |key, value| send("#{key}=", value) } unless hash.nil?
+            end
+        end
+           
+        
+        # Returns a list of albums
+        #
+        # @param [Session] session - Session
+        # @param [Number] album_id - Album to fetch, Optional
+        # @param [Boolean] recursive - Include subalbums, Optional
+        # @param [Boolean] public - Only include public albums, Optional 
+        # @param [Boolean] fullname - ???, Optional
+        # @param [String] thumbnail_size - Size of thumbname to return, One of: square, thumb, 2small, xsmall, small, medium, large, xlarge, xxlarge. Optional
+        # @param [Logger] logger logger to output debug messages to (Optional)        
+        #
+        # @return [Array<Album>] All albums that match the criteria, or nil there were no matches
+        #
+        def self.list(session, album_id: nil, recursive: false, public: false, fullname: false, thumbnail_size: 'thumb', logger: nil)
+            raise "Invalid session" if session.uri.nil?
+            logger = logger || Logger.new(STDOUT)     
+
+
+            begin
+                http = Net::HTTP.new(session.uri.host, session.uri.port)
+                request = Net::HTTP::Post.new(session.uri.request_uri)
+                request.body = "method=pwg.categories.getList&cat_id=#{album_id}&recursive=#{recursive}&public=#{public}&fullname=#{fullname}&thumbnail_size=#{thumbnail_size}"                
+                request['Cookie'] = [session.id]
+                
+                # Send the request
+                response = http.request(request) 
+                if response.code == '200'
+                    data = JSON.parse(response.body)
+                    albums = data['result']['categories'].map{ |hash| Album.new(hash: hash) }
+                    logger.info "Album List succeeded: #{albums.size} albums retrieved."
+                    albums
+                else                
+                    nil
+                end                      
+            rescue Timeout::Error, Errno::EINVAL, Errno::ECONNRESET, EOFError, Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError, Net::ProtocolError => e
+                logger.error "Album List failed: #{e.messages}"
+                nil
+            end            
+        end
+
+
+        # Adds an album.
+        #
+        # @param [Session] session to interact with Piwigo
+        # @param [Album] album album to create
+        # @param [Logger] logger logger to output debug messages to (Optional)        
+        #
+        # @return [Album] newly created album
+        def self.add(session, album, logger: nil)
+            raise "Invalid session" if session.uri.nil?
+            raise "Invalid album" if album.nil?
+
+            logger = logger || Logger.new(STDOUT)     
+
+            begin
+                http = Net::HTTP.new(session.uri.host, session.uri.port)
+                request = Net::HTTP::Post.new(session.uri.request_uri)
+                request.body = "method=pwg.categories.add&name=#{album.name}"                
+                request.body.concat "&parent=#{album.id_uppercat}" unless album.id_uppercat.nil?
+                request.body.concat "&comment=#{album.comment}" unless album.comment.nil?
+                request.body.concat "&status=#{album.status}" unless album.status.nil?
+                request['Cookie'] = [session.id]
+                
+                # Send the request
+                response = http.request(request) 
+                if response.code == '200'
+                    data = JSON.parse(response.body)
+                    album.id = albums = data['result']['id']
+                    logger.info "Album Add succeeded: #{album.id} created."
+                    album
+                else                
+                    nil
+
+                end                      
+            rescue Timeout::Error, Errno::EINVAL, Errno::ECONNRESET, EOFError, Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError, Net::ProtocolError => e
+                logger.error "Album Add failed: #{e.messages}"
+                nil
+            end            
+        end   
+        
+        
+        # Deletes album(s).
+        #
+        # @param [Session] piwigo session 
+        # @param [Number] id of the album to remove
+        # @param [String] photo_deletion_mode can be "no_delete" (may create orphan photos), "delete_orphans" (default mode, only deletes photos linked to no other album) 
+        #                 or "force_delete" (delete all photos, even those linked to other albums)
+        # @param [Logger] logger logger to output debug messages to (Optional)        
+        #
+        # @return [Boolean] true if album was deleted        
+        def self.delete(session, id, photo_deletion_mode: nil, logger: nil)
+            raise "Invalid session" if session.uri.nil?
+
+            logger = logger || Logger.new(STDOUT)     
+
+            begin
+                http = Net::HTTP.new(session.uri.host, session.uri.port)
+                request = Net::HTTP::Post.new(session.uri.request_uri)
+                request.body = "method=pwg.categories.delete&category_id=#{id}"                
+                request.body.concat "&photo_deletion_mode=#{photo_deletion_mode}" unless photo_deletion_mode.nil?
+                request.body.concat "&pwg_token=#{session.pwg_token}"
+                request['Cookie'] = [session.id]
+                
+                # Send the request
+                response = http.request(request) 
+                if response.code == '200'
+                    data = JSON.parse(response.body)
+                    logger.info "Album Delete succeeded."
+                    true
+                else 
+                    p response.code               
+                    p response.body               
+                    false
+
+                end                      
+            rescue Timeout::Error, Errno::EINVAL, Errno::ECONNRESET, EOFError, Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError, Net::ProtocolError => e
+                logger.error "Album delete: #{e.messages}"
+                false
+            end            
+        end         
+
+
+    end
+end    

data/lib/piwigo/session.rb

@@ -7,70 +7,112 @@ module Piwigo
     # Class to hold the Piwigo session the rest of the API needs to pass in order to access the API
     class Session
         
-        def session_id
-            @session_id
+        # @return [String] Piwigo session cookie
+        attr_accessor :id
+
+        # @return [URI::HTTP] Piwigo host associated with this session
+        attr_accessor :uri
+
+        # @return [String] token required for admin methods
+        attr_accessor :pwg_token
+
+        # @return [String] token required for admin methods
+        attr_accessor :username
+
+
+        def initialize(id, uri)
+            self.id = id
+            self.uri = uri
+
+            status            
         end
+          
+        # Gets information about the current session. Also provides a token useable with admin methods.
+        # {"stat":"ok","result":{"username":"Adrian","status":"webmaster","theme":"modus","language":"en_GB","pwg_token":"9edde6a1ae535934cca6a2423f9bcbe7","charset":"utf-8","current_datetime":"2019-11-17 21:57:58","version":"2.10.1","available_sizes":["square","thumb","2small","xsmall","small","medium","large","xlarge","xxlarge"],"upload_file_types":"jpg,jpeg,png,gif","upload_form_chunk_size":500}}
+        # @return [<Type>] <description>
+        def status
+            logger = logger || Logger.new(STDOUT)     
+
+            begin                       
+                # Create the HTTP objects
+                http = Net::HTTP.new(uri.host, uri.port)
+                request = Net::HTTP::Post.new(uri.request_uri)
+                request.body = "method=pwg.session.getStatus"
+                request['Cookie'] = self.id
+                
+                # Send the request
+                response = http.request(request)    
+            
+                if response.code == '200'
+                    logger.info "Status succeeded"
+                    data = JSON.parse(response.body)
+                    self.pwg_token = data['result']['pwg_token']
+                    self.username = data['result']['username']
+                end
+
+            rescue Timeout::Error, Errno::EINVAL, Errno::ECONNRESET, EOFError, Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError, Net::ProtocolError => e
+                    logger.error "Unexpected failed: #{e.messages}"
+            end
+            nil              
             
-        # Instantion a new  Session object
-        # @param [Logger] logger logger to output debug messages to (Optional)
-        def initialize(logger: nil)
-            @session_id=nil
-            @uri=nil       
-            @logger = logger || Logger.new(STDOUT)     
         end
+           
+        # Logout of the current session
+        # @param [Logger] logger logger to output debug messages to (Optional)        
+        def logout(logger: nil)            
+            raise "This session has already been logged out" if uri.nil?
+            logger = logger || Logger.new(STDOUT)     
 
+            # Create the HTTP objects
+            http = Net::HTTP.new(self.uri.host, self.uri.port)
+            request = Net::HTTP::Get.new(self.uri.request_uri + "&method=pwg.session.logout")
+            request['Cookie'] = self.id
+            
+            # Send the request
+            response = http.request(request)               
+            logger.info "Logout succeeded: #{response.body}" if response.code == '200'    
+            self.id = nil
+            self.uri = nil
+        end
+        
+        
         # Log into the piwigo API and grab the session id for subsequent calls.
         # @param [string] piwigo - host to connect to. Can be fqdn or ip. 
         # @param [string] username - user to connect as
         # @param [string] password - password for user
         # @param [boolean] https - Use HTTPS?
-        def login(host, username, password, https: true)
+        # @param [Logger] logger logger to output debug messages to (Optional)        
+        def self.login(host, username, password, https: true, logger: nil)
 
             raise "host should not be nil" if host.nil?
             raise "username should not be nil" if username.nil?
+            logger = logger || Logger.new(STDOUT)     
 
             begin
             
-                @uri = https ? URI::HTTPS.build(host: host, path: "/ws.php", query: "format=json") :
-                               URI::HTTP.build(host: host, path: "/ws.php", query: "format=json")                 
+                uri = https ? URI::HTTPS.build(host: host, path: "/ws.php", query: "format=json") :
+                                   URI::HTTP.build(host: host, path: "/ws.php", query: "format=json")                 
             
                 # Create the HTTP objects
-                http = Net::HTTP.new(@uri.host, @uri.port)
-                request = Net::HTTP::Post.new(@uri.request_uri)
+                http = Net::HTTP.new(uri.host, uri.port)
+                request = Net::HTTP::Post.new(uri.request_uri)
                 request.body = "method=pwg.session.login&username=#{username}&password=#{password}"
                 
                 # Send the request
                 response = http.request(request)    
             
                 if response.code == '200'
-                    @logger.info "Login succeeded: #{response.body}"
-                    @session_id = response.response['set-cookie'].split(';').select { |i| i.strip.start_with? "pwg_id" }
-                    return true
+                    logger.info "Login succeeded: #{response.body}"
+                    pwg_id = response.response['set-cookie'].split(';').select { |i| i.strip.start_with? "pwg_id" }.first
+                    return Session.new(pwg_id, uri)
                 else
-                    @logger.error "Login failed: #{response.body}"
-                    @session_id = nil
-                    @uri = nil
+                    logger.error "Login failed: #{response.body}"
                 end
 
             rescue Timeout::Error, Errno::EINVAL, Errno::ECONNRESET, EOFError, Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError, Net::ProtocolError => e
-                    @logger.error "Login failed: #{e.messages}"
+                    logger.error "Login failed: #{e.messages}"
             end
-            false    
-        end   
-    
-        def logout
-            raise "login must be successfully called before logout" if @uri.nil?
-
-            # Create the HTTP objects
-            http = Net::HTTP.new(@uri.host, @uri.port)
-            request = Net::HTTP::Get.new(@uri.request_uri + "&method=pwg.session.logout")
-            request['Cookie'] = @session_id
-            
-            # Send the request
-            response = http.request(request)               
-            @logger.info "Logout succeeded: #{response.body}" if response.code == '200'    
-            @session_id = nil
-            @uri = nil
-        end
+            nil                
+        end       
     end
 end

data/lib/piwigo/version.rb

@@ -1,3 +1,3 @@
 module Piwigo
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/piwigo-api.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Adrian Gilbert"]
   spec.email         = ["adrian@gilbert.ca"]
 
-  spec.summary       = %q{Ruby gem to interact with the Piwigo API}
-  spec.description   = %q{Ruby gem to interact with the Piwigo API}
+  spec.summary       = %q{Gem to interact with the Piwigo API}
+  spec.description   = %q{Piwigo is open source web application to manage your collection of photos, and other medias. Piwigo provides an API for interacting with it. This is a ruby-based client for interacting with a Piwigo instance using the Piwigo API.}
   spec.homepage      = "https://github.com/kkdad/piwigo-api"
   spec.license       = "MIT"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: piwigo-api
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Adrian Gilbert
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-11-16 00:00:00.000000000 Z
+date: 2019-11-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -80,7 +80,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.2'
-description: Ruby gem to interact with the Piwigo API
+description: Piwigo is open source web application to manage your collection of photos,
+  and other medias. Piwigo provides an API for interacting with it. This is a ruby-based
+  client for interacting with a Piwigo instance using the Piwigo API.
 email:
 - adrian@gilbert.ca
 executables: []
@@ -100,9 +102,9 @@ files:
 - bin/console
 - bin/setup
 - lib/piwigo.rb
+- lib/piwigo/albums.rb
 - lib/piwigo/session.rb
 - lib/piwigo/version.rb
-- main.rb
 - piwigo-api.gemspec
 homepage: https://github.com/kkdad/piwigo-api
 licenses:
@@ -129,5 +131,5 @@ requirements: []
 rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
-summary: Ruby gem to interact with the Piwigo API
+summary: Gem to interact with the Piwigo API
 test_files: []

data/main.rb

@@ -1,8 +0,0 @@
-require_relative 'lib/piwigo/session'
-
-puts "BEGIN"
-session = Piwigo::Session.new
-session.login('10.100.230.78', 'Adrian', 'secret', https: false)
-session.logout
-
-puts "END"