Net::A...:Bucket(3pm)

💖 Net::Amazon::S3::Client::Bucket 💖

okay bestie, so this is Net::Amazon::S3::Client::Bucket — an easy-to-use Amazon S3 client bucket, from the User Contributed Perl Documentation corner of the universe. yes it's a real module, yes it's legit, and yes we are going to learn her together 🫶

---

✨ VERSION ✨

version 0.992 — that's the one, that's the girl ✨

---

🌸 SYNOPSIS 🌸

okay so here's the vibe, literally the whole point of existing:

# return the bucket name
print $bucket->name . "\n";

# return the bucket location constraint
print "Bucket is in the " . $bucket->location_constraint . "\n";

# return the ACL XML
my $acl = $bucket->acl;

# list objects in the bucket
# this returns a L<Data::Stream::Bulk> object which returns a
# stream of L<Net::Amazon::S3::Client::Object> objects, as it may
# have to issue multiple API requests
my $stream = $bucket->list;
until ( $stream->is_done ) {
  foreach my $object ( $stream->items ) {
    ...
  }
}

# or list by a prefix
my $prefix_stream = $bucket->list( { prefix => 'logs/' } );

# returns a L<Net::Amazon::S3::Client::Object>, which can then
# be used to get or put
my $object = $bucket->object( key => 'this is the key' );

# delete the bucket (it must be empty)
$bucket->delete;

like... she does it ALL 💅 and yes, that delete is doing the most important job: the bucket must be empty. no cap.

---

🦋 DESCRIPTION 🦋

This module represents buckets. that's it, that's the thesis statement. it's the bucket. it's giving structural integrity ✨

---

👑 METHODS 👑

💜 acl

grab yourself the ACL XML, iconic.

# return the ACL XML
my $acl = $bucket->acl;

💜 add_tags

slap some tags on it, keys and values, go off:

$bucket->add_tags (
        tags => { tag1 => 'val1', ... },
)

💜 delete_tags

and when the tags gotta go, they gotta go:

$bucket->delete_tags;

💜 delete

bestie. do not forget: the bucket has to be empty. empty empty. this is not a drill 🔥

# delete the bucket (it must be empty)
$bucket->delete;

💜 list

okay this one is the main character. listing objects in the bucket. she returns a Data::Stream::Bulk object that streams a bunch of Net::Amazon::S3::Client::Object objects at you — and that's because she might have to hit the API multiple times, so she streams instead of dumping everything at once. very demure, very mindful 💅

# list objects in the bucket
# this returns a L<Data::Stream::Bulk> object which returns a
# stream of L<Net::Amazon::S3::Client::Object> objects, as it may
# have to issue multiple API requests
my $stream = $bucket->list;
until ( $stream->is_done ) {
  foreach my $object ( $stream->items ) {
    ...
  }
}

# or list by a prefix
my $prefix_stream = $bucket->list( { prefix => 'logs/' } );

# you can emulate folders by using prefix with delimiter
# which shows only entries starting with the prefix but
# not containing any more delimiter (thus no subfolders).
my $folder_stream = $bucket->list( { prefix => 'logs/', delimiter => '/' } );

and the folder thing?? iconic. prefix + delimiter and boom, you got fake folders — only entries starting with the prefix, but with no more delimiters in them, so no subfolders sneak in 🎀

💜 location_constraint

where in the world is this bucket? tell me, bestie:

# return the bucket location constraint
print "Bucket is in the " . $bucket->location_constraint . "\n";

💜 name

the name. her name. as a string, printed, with a newline, the whole thing:

# return the bucket name
print $bucket->name . "\n";

💜 object

hand her a key and she hands you back a Net::Amazon::S3::Client::Object — which you can then use to get or put. it's the pipeline. it's the lore. 🧚

# returns a L<Net::Amazon::S3::Client::Object>, which can then
# be used to get or put
my $object = $bucket->object( key => 'this is the key' );

💜 delete_multi_object

multi object delete operation, the efficient queen that she is. she accepts a list of Net::Amazon::S3::Client::Object or String objects:

# delete multiple objects using a multi object delete operation
# Accepts a list of L<Net::Amazon::S3::Client::Object or String> objects.
$bucket->delete_multi_object($object1, $object2)

💜 object_class

returns the string "Net::Amazon::S3::Client::Object" — and the whole point of that is so subclasses can add their own behavior. customisation, slay.

# returns string "Net::Amazon::S3::Client::Object"
# allowing subclasses to add behavior.
my $object_class = $bucket->object_class;

---

⭐ AUTHOR ⭐

Branislav Zahradník <barney@cpan.org> — we love him, we thank him, periodt 💖

---

🌈 COPYRIGHT AND LICENSE 🌈

This software is copyright (c) 2025 by Amazon Digital Services, Leon Brocard, Brad Fitzpatrick, Pedro Figueiredo, Rusty Conover, Branislav Zahradník.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

and that's the whole page bestie 🫶 this was perl v5.40.1, dated 2025-12-07, filed under Net::A...:Bucket(3pm) — go forth and bucket responsibly 💅✨🌸