programming:python:libgal3
Differences
This shows you the differences between two versions of the page.
Next revision | Previous revisionNext revisionBoth sides next revision | ||
programming:python:libgal3 [2010/12/16 04:07] – created jay | programming:python:libgal3 [2012/09/26 04:33] – [Exploring the Root Album] jay | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== What is it? ====== | + | ====== Python Gallery 3 Library ====== |
+ | |||
+ | ===== What is it? ===== | ||
This is a library to wrap the new Gallery 3 REST API in a nice, handy Python library. | This is a library to wrap the new Gallery 3 REST API in a nice, handy Python library. | ||
This is still an early release, but it functions quite well and has some nice features from a performance standpoint like //lazy// access to sub-items (the images in an album, for example). | This is still an early release, but it functions quite well and has some nice features from a performance standpoint like //lazy// access to sub-items (the images in an album, for example). | ||
- | ====== | + | ===== License |
- | You can download the package here: {{: | + | This project is licensed under the GPLv3. |
+ | |||
+ | ===== Downloading | ||
+ | You can download the package here: {{: | ||
+ | |||
+ | You can also track this project on [[https:// | ||
+ | |||
+ | ===== Donations ===== | ||
+ | By no means should anyone feel they //have// to donate. | ||
- | ====== | + | < |
+ | <form action=" | ||
+ | <input type=" | ||
+ | <input type=" | ||
+ | <input type=" | ||
+ | <img alt="" | ||
+ | </ | ||
+ | </ | ||
+ | ===== Installing | ||
Install is pretty easy if you've ever installed another Python package. | Install is pretty easy if you've ever installed another Python package. | ||
< | < | ||
- | $ tar -xvzf pylibgal3-*.tar.gz | + | # tar -xvzf pylibgal3-*.tar.gz |
- | $ cd pylibgal3-* | + | # cd pylibgal3-* |
- | $ sudo python setup.py install | + | # sudo python setup.py install |
</ | </ | ||
That's about it for the install. | That's about it for the install. | ||
- | ====== Usage ====== | + | ===== Usage ===== |
+ | ==== Logging In ==== | ||
This is a pretty simple to use library. | This is a pretty simple to use library. | ||
Line 33: | Line 53: | ||
# access with ssl=True. | # access with ssl=True. | ||
# standard ssl port of 443, you would use this for your constructor: | # standard ssl port of 443, you would use this for your constructor: | ||
- | # gal = libg3.Gallery3(hostname , apiKey , g3Base=g3Base , port=443 , ssl=True | + | # gal = libg3.Gallery3(hostname , apiKey , g3Base=g3Base , port=443 , ssl=True) |
</ | </ | ||
We'll get to usage on the '' | We'll get to usage on the '' | ||
Line 49: | Line 69: | ||
Now that you have your Gallery3 object, let's get to what you can do with it. | Now that you have your Gallery3 object, let's get to what you can do with it. | ||
+ | ==== Core Gallery Items ==== | ||
+ | First, lets give you a brief explanation of the basic elements you will be dealing with, There are a total of five core Gallery elements that we will explore here. | ||
+ | - **Album** - Basically, this is a container to hold other items, including other albums. | ||
+ | - **RemoteImage** - This pertains to an image in the remote gallery. | ||
+ | - **RemoteMovie** - This is essentially just a descendant, and very similar to, a RemoteImage. | ||
+ | - **Tag** - Albums, images and movies can all be tagged in your gallery. | ||
+ | - **Comment** - People can leave comments on images and movies. | ||
+ | |||
+ | |||
+ | ==== Exploring the Root Album ==== | ||
+ | As you may, or may not, be aware, the root of your gallery is considered to be an album just like any other album you create within it. This means that it is the base of a tree structure you create. | ||
+ | |||
+ | Let's take a look at getting the root album and a dump of the root album dictionary. | ||
+ | <code python> | ||
+ | from pprint import pprint | ||
+ | |||
+ | # Assume we are using the " | ||
+ | root = gal.getRoot() | ||
+ | # Note that after you call getRoot() initially, you can access the root element | ||
+ | # as a property of your base Gallery3 object with " | ||
+ | print root | ||
+ | # Outputs: < | ||
+ | |||
+ | pprint(root.__dict__) | ||
+ | # Outputs: | ||
+ | {' | ||
+ | ' | ||
+ | u' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | | ||
+ | | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | </ | ||
+ | Those are all the basic, default properties that are pulled from the server for your gallery root. There are some other convenience properties that we can also access in that root Album (or any other album, for that matter) that will make your access to certain elements easier. | ||
+ | <code python> | ||
+ | # Again, we are using the previously created " | ||
+ | root = gal.getRoot() | ||
+ | |||
+ | # We can access all the member items (children) of this album with the | ||
+ | # members property. | ||
+ | pprint(root.members) | ||
+ | |||
+ | # We can also get just the Albums, Images or Movies. | ||
+ | # are all lists of their respective types: | ||
+ | pprint(root.Albums) | ||
+ | pprint(root.Images) | ||
+ | pprint(root.Movies) | ||
+ | |||
+ | # We can get the image that is being used as the album cover. | ||
+ | pprint(root.album_cover) | ||
+ | |||
+ | # We can also get any tags associated with the root album. | ||
+ | # list of Tag objects | ||
+ | pprint(root.tags) | ||
+ | |||
+ | # There a couple of simple convenience methods to get '' | ||
+ | # for the 2 timestamp fields: | ||
+ | creationDatetime = root.getCrDT() | ||
+ | updatedDatetime = root.getUpdDT() | ||
+ | </ | ||
+ | An important thing to note with some of the above. | ||
+ | |||
+ | ==== Images ==== | ||
+ | Now, let's take a look at a RemoteImage: | ||
+ | <code python> | ||
+ | root = gal.getRoot() | ||
+ | |||
+ | firstImage = root.Images[0] | ||
+ | print firstImage | ||
+ | # Outputs: < | ||
+ | pprint(firstImage.__dict__) | ||
+ | # Outputs: | ||
+ | {' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | | ||
+ | | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | </ | ||
+ | Things look a bit different here, but there are some similarities. | ||
+ | <code python> | ||
+ | # Continuing with the " | ||
+ | |||
+ | # We have access to the parent object (in this example, the root album) via the " | ||
+ | print firstImage.parent | ||
+ | # Outputs: < | ||
+ | |||
+ | # You can access the comments for this image with the " | ||
+ | # This will give you a list of all this image' | ||
+ | pprint(firstImage.comments) | ||
+ | |||
+ | # Again, you can access the tags | ||
+ | pprint(firstImage.tags) | ||
+ | |||
+ | # You can get the created and updated datetimes here too | ||
+ | pprint(firstImage.getCrDT()) | ||
+ | pprint(firstImage.getUpdDT()) | ||
+ | </ | ||
+ | |||
+ | ==== Comments ==== | ||
+ | We will only look at comments (and tags) briefly. | ||
+ | |||
+ | Here is what a Comment object looks like: | ||
+ | <code python> | ||
+ | # Again using the " | ||
+ | firstComment = firstImage.comments[0] | ||
+ | |||
+ | print type(firstComment) | ||
+ | # Outputs: <class ' | ||
+ | |||
+ | pprint(firstComment.__dict__) | ||
+ | # Outputs: | ||
+ | {' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | |||
+ | # You can also just print the comment " | ||
+ | print firstComment | ||
+ | # Outputs: test comment | ||
+ | </ | ||
+ | |||
+ | ==== Tags ==== | ||
+ | Tags are a bit like comments. | ||
+ | <code python> | ||
+ | # Again using the " | ||
+ | firstTag = firstImage.tags[0] | ||
+ | |||
+ | print type(firstTag) | ||
+ | # Outputs: <class ' | ||
+ | |||
+ | pprint(firstTag.__dict__) | ||
+ | # Outputs: | ||
+ | {' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | u' | ||
+ | ' | ||
+ | ' | ||
+ | |||
+ | print firstTag | ||
+ | # Outputs the name property: dave | ||
+ | </ | ||
+ | |||
+ | ==== Additional Info ==== | ||
+ | That about finishes up with the basics of the readable attributes for each of the core items. | ||
+ | * pydoc libg3.G3Items.Album | ||
+ | * pydoc libg3.G3Items.RemoteImage | ||
+ | * pydoc libg3.G3Items.RemoteMovie | ||
+ | * pydoc libg3.G3Items.Comment | ||
+ | * pydoc libg3.G3Items.Tag | ||
+ | * pydoc libg3.Gallery3 | ||
+ | |||
+ | Now, let's move on to working with our different items. | ||
+ | |||
+ | ==== Working With Albums ==== | ||
+ | This is about as easy as it gets. You just call the '' | ||
+ | <code python> | ||
+ | # Assume we have our gallery object here | ||
+ | root = gal.getRoot() | ||
+ | albumName = 'test album 1' | ||
+ | albumTitle = 'A testing album' | ||
+ | albumDesc = 'My description' | ||
+ | newAlbumObject = root.addAlbum(albumName , albumTitle , albumDesc) | ||
+ | # That's it. You can now use that " | ||
+ | </ | ||
+ | Now, let's " | ||
+ | <code python> | ||
+ | newTag = newAlbumObject.tag(' | ||
+ | </ | ||
+ | Let's change the title and description of this album | ||
+ | <code python> | ||
+ | newAlbumObject.update(newTitle , newDesc) | ||
+ | </ | ||
+ | If you don't want the album on your site anymore, just delete() it | ||
+ | <code python> | ||
+ | newAlbumObject.delete() | ||
+ | </ | ||
+ | Ok, we have this album, but now you probably want to add an image to it, right. | ||
+ | <code python> | ||
+ | imagePath = '/ | ||
+ | locImage = libg3.LocalImage(imagePath) | ||
+ | imageTitle = ' | ||
+ | imageDesc = 'The best image EVER' | ||
+ | # This will return the new RemoteImage instance | ||
+ | newRemoteImage = newAlbumObject.addImage(locImage , imageTitle , imageDesc) | ||
+ | |||
+ | # Since this is "the best image EVER", let's set it as the album cover | ||
+ | newAlbumObject.setCover(newRemoteImage) | ||
+ | </ | ||
+ | To do the same with a movie, just use " | ||
+ | |||
+ | ==== Working With Images ==== | ||
+ | Now, there are not as many things you can do with images (or movies) as you can with albums so this will be brief. | ||
+ | |||
+ | We can add a comment to an image | ||
+ | <code python> | ||
+ | comment = 'I love cheese' | ||
+ | commentObj = newRemoteImage.addComment(comment) | ||
+ | </ | ||
+ | |||
+ | Updates work just like albums. | ||
+ | <code python> | ||
+ | newRemoteImage.update(newTitle , newDesc) | ||
+ | </ | ||
+ | |||
+ | Downloading the image is also pretty easy, just use the read() method of the RemoteImage. | ||
+ | <code python> | ||
+ | # You can also access and download this image with the read call: | ||
+ | binaryImage = '' | ||
+ | buf = newRemoteImage.read(4096) | ||
+ | while buf: | ||
+ | binaryImage += buf | ||
+ | buf = newRemoteImage.read(4096) | ||
+ | if not buf: break | ||
+ | # Or more simply | ||
+ | binaryImage = newRemoteImage.read() | ||
+ | # Then you can just write this out as a local file | ||
+ | open(newRemoteImage.name , ' | ||
+ | |||
+ | # Get a handle to the resized image and download it | ||
+ | resized = firstImage.getResizeHandle() | ||
+ | outfile = open(' | ||
+ | outfile.write(resized.read()) | ||
+ | outfile.close() | ||
+ | |||
+ | # Get a handle to the resized image and download it | ||
+ | thumb = firstImage.getThumbHandle() | ||
+ | outfile = open(' | ||
+ | outfile.write(thumb.read()) | ||
+ | outfile.close() | ||
+ | </ | ||
+ | |||
+ | Of course, you can tag images too. | ||
+ | <code python> | ||
+ | tag = 'Best image ever' | ||
+ | newTag = newRemoteImage.tag(tag) | ||
+ | </ | ||
+ | |||
+ | You can perform all these same operations with a RemoteMovie object as well. | ||
+ | |||
+ | ==== Another Item of Interest ==== | ||
+ | It should also be pointed out that almost all of the functionality described above can also be done with different objects and method calls to your main Gallery3 object. | ||
+ | <code python> | ||
+ | gal = libg3.Gallery3(hostname , apiKey , g3Base=g3Base) | ||
+ | root = gal.getRoot() | ||
+ | firstAlbum = root.Albums[0] | ||
+ | # Now let's get the first image out of the first sub-album: | ||
+ | image = firstAlbum.Images[0] | ||
+ | # Now, we can always tag this image with the following: | ||
+ | image.tag(' | ||
+ | # But, we can also tag an item (image or album) by using our main " | ||
+ | gal.tagItem(image , ' | ||
+ | # For another example, let's show the 2 ways we can set the cover for an album | ||
+ | # First is using an album object: | ||
+ | firstAlbum.setCover(image) | ||
+ | # But we can also use our main " | ||
+ | gal.setAlbumCover(firstAlbum , image) | ||
+ | </ | ||
+ | It's worth noting that calling '' | ||
+ | ==== The Future ==== | ||
+ | As you can see, there is a good deal of functionality here, but it is by no means complete. | ||
+ | * Make images and thumbnails resizable | ||
+ | * Reordering of members in an album | ||
+ | * Make all editable properties editable | ||
+ | |||
+ | If anyone has any problems, suggestions or whatever, feel free to email me directly at < |
programming/python/libgal3.txt · Last modified: 2023/11/10 20:06 by jay