Flickr::Upload(3pm)

💖 Flickr::Upload 💖

okay bestie, so this is the manual page for Flickr::Upload(3pm) — it's from the User Contributed Perl Documentation crew, and it's literally your backstage pass to yeeting images up onto flickr.com. sit down, grab a boba, we're doing this together 🧋✨

---

✨ NAME ✨

Flickr::Upload — upload images to flickr.com 💅

---

🌸 SYNOPSIS 🌸

use Flickr::Upload;

my $ua = Flickr::Upload->new(
    {
        'key' => '90909354',
        'secret' => '37465825'
    });
$ua->upload(
    'photo' => '/tmp/image.jpg',
    'auth_token' => $auth_token,
    'tags' => 'me myself eye',
    'is_public' => 1,
    'is_friend' => 1,
    'is_family' => 1
) or die "Failed to upload /tmp/image.jpg";

look at that. it's giving competence. 🫶

---

🦋 DESCRIPTION 🦋

Upload an image to flickr.com. that's it, that's the whole vibe. 🎀

---

👑 METHODS 👑

💜 new

Using Flickr Authentication 🔑

my $ua = Flickr::Upload->new(
    {
        'key' => '90909354',
        'secret' => '37465825'
    });

Using OAuth Authentication 🌈

my $ua = Flickr::Upload->new(
    {
        'consumer_key' => 'your_api_key',
        'consumer_secret' => 'your_app_secret',
    });

Retrieve saved configuration (possibly including OAuth access token) 💾

my $config_file = "$ENV{HOME}/saved-flickr.st";
my $ua = Flickr::Upload->import_storable_config($config_file);

okay so what this does: it instantiates a Flickr::Upload instance, and you get to pick your flavour — either the Flickr Authentication route or the OAuth Authentication route. the "key" or "consumer_key" argument is your API key, and the "secret" or "consumer_secret" argument is the API secret that goes with it. to snag yourself an API key and secret, go to <https://www.flickr.com/services/api/key.gne>. 🎟️

and here's the cute part: the Flickr::Upload instance you get back is a subclass of Flickr::API, so you can use it for literally any other Flickr API calls too. which means — plot twist — Flickr::Upload is also a subclass of LWP::UserAgent. nested inheritance, main character energy, we love to see it. ✨

💅 upload

my $photoid = $ua->upload(
    'photo' => '/tmp/image.jpg',
    'auth_token' => $auth_token,
    'tags' => 'me myself eye',
    'is_public' => 1,
    'is_friend' => 1,
    'is_family' => 1
    'async' => 0,
);

you hand it a Flickr::Upload instance called $ua, and ngl this is basically a direct interface to the Flickr Photo Upload API. required parameters are "photo" and — when you're doing Flickr Authentication — "auth_token". heads up tho: that "auth_token" must have been issued against the API key and secret you used to instantiate the uploader. no mixing and matching, bestie. 🚫

when you're using OAuth, "auth_token" is not required — instead the Flickr::Upload instance must contain a valid Net::OAuth access token, which you add by calling the Flickr::API "oauth_access_token" method. 🔐

returns the resulting identifier of the uploaded photo on success, and "undef" on failure. and per the API documentation, after an upload the user should be directed to this page:

<https://www.flickr.com/tools/uploader_edit.gne?ids=$photoid>

if the "async" option is non-zero, the photo gets uploaded asynchronously and a successful upload returns a ticket identifier instead. more deets here: <https://www.flickr.com/services/api/upload.async.html>. then you, the caller, can periodically poll for a photo id using the "check_upload" method. ⏰

⚠️ note that photo and ticket identifiers aren't necessarily numeric. don't come for me, it's just how it is.

🍓 check_upload

my %status2txt = (0 => 'not complete', 1 => 'completed', 2 => 'failed');
my @rc = $ua->check_upload( @ticketids );
for( @rc ) {
    print "Ticket $_->{id} has $status2txt{$_->{complete}}\n";
    print "\tPhoto id is $_->{photoid}\n" if exists $_->{photoid};
}

this function checks the status of one or more asynchronous uploads. you give it a list of ticket identifiers (@ticketids) and each one gets checked. it's basically just a wrapper around the Flickr API "flickr.photos.upload.checkTickets" method. 🎫

on success you get back a list of hash references. each hash contains an "id" (the ticket id), "complete", and — if completed — "photoid" members. "invalid" may also be returned. the status codes (for "complete") are documented at <https://www.flickr.com/services/api/upload.async.html> and, actually, the returned fields are identical to the ones listed in the "ticket" tag of the response. also the returned list isn't guaranteed to be in any particular order, so don't get attached to the sequence. 🙈

🛑 this function polls a web server, so please, for the love of everything, avoid calling it too frequently. it's giving "stop refreshing the page".

🧚 make_upload_request

my $req = $uploader->make_upload_request(
    'auth_token' => '82374523',
    'tags' => 'me myself eye',
    'is_public' => 1,
    'is_friend' => 1,
    'is_family' => 1
);
$req->header( 'X-Greetz' => 'hi cal' );
my $resp = $ua->request( $req );

creates an HTTP::Request object loaded up with all the flick upload parameters. this will also sign the request, which means you won't be able to mess any further with the upload request parameters. it's locked in, periodt. 🔒

takes all the same parameters as upload, except that the photo argument isn't required. the whole point is that the caller can include it by messing directly with the HTTP content (via $DYNAMIC_FILE_UPLOAD or the HTTP::Message class, among other things). see the "t/" directory from the source distribution for examples. 📁

returns a standard HTTP::Response POST object. then you can manually do the upload, or just call the upload_request function. easy. ✨

🌈 upload_request

my $photoid = upload_request( $ua, $request );

taking (at least) LWP::UserAgent and HTTP::Request objects as arguments, this executes the request and processes the result as a flickr upload. it's assumed that the request looks a lot like something created with make_upload_request. and note that the request must be signed according to the Flickr API authentication rules. no signature, no service. 🖊️

returns the resulting identifier of the uploaded photo (or ticket, for asynchronous uploads) on success, "undef" on failure. and according to the API documentation, after an upload the user should be directed to this page:

<https://www.flickr.com/tools/uploader_edit.gne?ids=$photoid>

⭐ file_length_in_encoded_chunk

$HTTP::Request::Common::DYNAMIC_FILE_UPLOAD = 1;
my $photo = 'image.jpeg';
my $photo_size = (stat($photo))[7];
my $req = $ua->make_upload_request( ... );
my $gen = $req->content();
die unless ref($gen) eq "CODE";

my $state;
my $size;

$req->content(
    sub {
        my $chunk = &$gen();

        $size += Flickr::Upload::file_length_in_encoded_chunk(\$chunk, \$state, $photo_size);

        warn "$size bytes have now been uploaded";

        return $chunk;
    }
);

$rc = $ua->upload_request( $req );

okay this one is a mouthful but it's actually so useful. this subroutine tells you how much of a chunk in a series of variable size multipart HTTP chunks contains a single file being uploaded — given a reference to the current chunk, a reference to a state variable that lives between calls, and the size of the file being uploaded. 🧮

it can be used along with HTTP::Request::Common's $HTTP::Request::Common::DYNAMIC_FILE_UPLOAD facility to implement upload progress bars or other upload monitors. see flickr_upload for a practical example and t/progress_request.t for tests. progress bar girlies, this one's for you. 📊💖

🎀 photosets_create

Calls Flickr's "flickr.photosets.create" method,
to create a new Set.

The set will use the PrimaryPhotoID as the thumbnail photo.

returns: UNDEF on failure, PhotosetID on success.

my $photoset_id = $ua->photosets_create( title => 'title',
                               description => 'description',
                               primary_photo_id => ID,
                               auth_token => AUTH_TOKEN );

$ua->photosets_addphoto ( photoset_id => $photoset_id,
                          photo_id => ID );

calls Flickr's "flickr.photosets.create" method to create a new Set. the set will use the PrimaryPhotoID as the thumbnail photo. 📸

returns: UNDEF on failure, PhotosetID on success.

🫶 photosets_addphoto

Calls Flickr's "flickr.photosets.addPhoto" method,
to add a (existing) photo to an existing set.

returns: UNDEF on failure, TRUE on success.

my $photoset_id = $ua->photosets_create( title => 'title',
                               description => 'description',
                               primary_photo_id => ID,
                               auth_token => AUTH_TOKEN );

$ua->photosets_addphoto ( photoset_id => $photoset_id,
                          photo_id => ID );

calls Flickr's "flickr.photosets.addPhoto" method to add a (already existing) photo to an already existing set. returns: UNDEF on failure, TRUE on success. adding to the collection, we love a curator era. 👑✨

---

🔥 SEE ALSO 🔥

• <https://www.flickr.com/services/api/>
• Flickr::API

---

💜 AUTHORS 💜

• Christophe Beauregard, cpb@cpan.org
• Ævar Arnfjörð Bjarmason, <avar@cpan.org>

---

📜 COPYRIGHT AND LICENSE 📜

this module is not an official Flickr.com (or Ludicorp, or Yahoo) service. just so we're clear. 🫡

Copyright (C) 2004-2008 by Christophe Beauregard and 2008-2009 by Ævar Arnfjörð Bjarmason

this library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.3 or, at your option, any later version of Perl 5 you may have available. 💖

---

and that's the whole page bestie, no cap 🎀✨ written up against perl v5.34.0 and dated 2022-06-14 — so yeah, this Flickr::Upload(3pm) manual page is officially a little vintage and we love her for it. go forth and upload, you absolute icon 💅🌈🦋