### Install sample dependencies

Source: https://github.com/googleapis/python-storage/blob/main/samples/README.md

Navigate to the samples/snippets directory and install all required dependencies from requirements.txt.

```bash
cd samples/snippets
pip install -r requirements.txt
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/googleapis/python-storage/blob/main/scripts/readme-gen/templates/install_deps.tmpl.rst

Install all required Python packages for the samples using the pip package installer and a requirements file.

```bash
pip install -r requirements.txt
```

--------------------------------

### Install Google Cloud Storage Client

Source: https://github.com/googleapis/python-storage/blob/main/docs/README.rst

Installs the google-cloud-storage library and sets up a virtual environment.

```console
py -m venv <your-env>
.\<your-env>\Scripts\activate
pip install google-cloud-storage
```

--------------------------------

### Install google-cloud-storage on Mac/Linux

Source: https://github.com/googleapis/python-storage/blob/main/docs/README.rst

Install the library in a virtual environment using venv on Mac or Linux.

```console
python3 -m venv <your-env>
source <your-env>/bin/activate
pip install google-cloud-storage
```

--------------------------------

### Install nox for testing

Source: https://github.com/googleapis/python-storage/blob/main/samples/README.md

Install nox, a tool used to instrument tests for the Google Cloud Storage Python samples.

```bash
pip install nox
```

--------------------------------

### Install Google Cloud Storage Client with Tracing Support

Source: https://github.com/googleapis/python-storage/blob/main/docs/README.rst

Installs the google-cloud-storage library with the necessary dependencies for OpenTelemetry tracing.

```console
pip install google-cloud-storage[tracing]
```

--------------------------------

### Install PortAudio on macOS using Homebrew

Source: https://github.com/googleapis/python-storage/blob/main/scripts/readme-gen/templates/install_portaudio.tmpl.rst

Use this command to install PortAudio on macOS via Homebrew. This is a prerequisite for installing PyAudio.

```bash
brew install portaudio
```

--------------------------------

### Install PyAudio with PortAudio flags

Source: https://github.com/googleapis/python-storage/blob/main/scripts/readme-gen/templates/install_portaudio.tmpl.rst

If pip install encounters an error finding 'portaudio.h', use these flags to specify include and library paths for PortAudio during PyAudio installation.

```bash
pip install --global-option='build_ext'     --global-option='-I/usr/local/include'     --global-option='-L/usr/local/lib'     pyaudio
```

--------------------------------

### Install Zonal Buckets dependencies

Source: https://github.com/googleapis/python-storage/blob/main/samples/README.md

Install the necessary dependencies for running zonal buckets samples, including gRPC support.

```bash
pip install "google-cloud-storage[grpc]"
```

--------------------------------

### Install OpenTelemetry Exporters and Instrumentations

Source: https://github.com/googleapis/python-storage/blob/main/docs/README.rst

Installs the Google Cloud Trace exporter, propagator, and optional Requests Instrumentation for OpenTelemetry.

```console
# Install the Google Cloud Trace exporter and propagator, however you can use any exporter of your choice.
pip install opentelemetry-exporter-gcp-trace opentelemetry-propagator-gcp

# [Optional] Install the OpenTelemetry Requests Instrumentation to trace the underlying HTTP requests.
pip install opentelemetry-instrumentation-requests
```

--------------------------------

### Get Help for a Python Storage Sample

Source: https://github.com/googleapis/python-storage/blob/main/scripts/readme-gen/templates/README.tmpl.rst

Display the help message for a Python sample script to understand its usage and options. This is useful for verifying command-line arguments.

```bash
{{get_help(sample.file)|indent}}
```

--------------------------------

### Install PortAudio on Debian/Ubuntu Linux

Source: https://github.com/googleapis/python-storage/blob/main/scripts/readme-gen/templates/install_portaudio.tmpl.rst

Use this command to install PortAudio development files on Debian or Ubuntu-based Linux distributions.

```bash
apt-get install portaudio19-dev python-all-dev
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/googleapis/python-storage/blob/main/CONTRIBUTING.rst

Enable pre-commit hooks to automatically enforce linting and style checks before committing.

```bash
pre-commit install
pre-commit installed at .git/hooks/pre-commit
```

--------------------------------

### Install Python Development Headers

Source: https://github.com/googleapis/python-storage/blob/main/CONTRIBUTING.rst

Install python-dev package on Debian/Ubuntu systems to resolve Python.h not found errors.

```bash
sudo apt-get install python-dev
```

--------------------------------

### Run Benchmarking Script

Source: https://github.com/googleapis/python-storage/blob/main/tests/perf/README.md

Execute the benchmarking script with specified sample count, object size range, and output type. Ensure the google-cloud-storage library is installed locally.

```bash
$ cd python-storage
$ pip install -e . # install google.cloud.storage locally
$ cd tests/perf
$ python3 benchmarking.py --num_samples 10000 --object_size 5120..16384 --output_type csv
```

--------------------------------

### Bucket.from_uri

Source: https://github.com/googleapis/python-storage/blob/main/docs/storage/bucket.md

Get a constructor for bucket object by URI.

```APIDOC
## Bucket.from_uri

### Description
Get a constructor for bucket object by URI.

### Parameters
#### Path Parameters
None

#### Query Parameters
* **uri** (*str*) - The bucket uri pass to get bucket object.
* **client** ([`Client`](client.md#google.cloud.storage.client.Client) or `NoneType`) - Optional - The client to use. Application code should *always* pass `client`.

### Request Example
```python
from google.cloud import storage
from google.cloud.storage.bucket import Bucket
client = storage.Client()
bucket = Bucket.from_uri("gs://bucket", client=client)
```

### Response
#### Success Response (200)
* **Bucket** - The bucket object created.

#### Response Example
None
```

--------------------------------

### Bucket.from_string

Source: https://github.com/googleapis/python-storage/blob/main/docs/storage/bucket.md

Get a constructor for bucket object by URI. Deprecated alias for `from_uri()`.

```APIDOC
## Bucket.from_string

### Description
Get a constructor for bucket object by URI. Deprecated alias for `from_uri()`.

### Parameters
#### Path Parameters
None

#### Query Parameters
* **uri** (*str*) - The bucket uri pass to get bucket object.
* **client** ([`Client`](client.md#google.cloud.storage.client.Client) or `NoneType`) - Optional - The client to use. Application code should *always* pass `client`.

### Request Example
```python
from google.cloud import storage
from google.cloud.storage.bucket import Bucket
client = storage.Client()
bucket = Bucket.from_string("gs://bucket", client=client)
```

### Response
#### Success Response (200)
* **Bucket** - The bucket object created.

#### Response Example
None
```

--------------------------------

### Run Conformance Test Suite Locally

Source: https://github.com/googleapis/python-storage/blob/main/tests/conformance/README.md

Execute the entire retry strategy conformance test suite locally using Nox. Ensure you have Python 3.8, Nox, and Docker installed.

```bash
nox -s conftest_retry-3.8
```

--------------------------------

### Create a Google Cloud Storage Bucket

Source: https://github.com/googleapis/python-storage/blob/main/docs/README.rst

Demonstrates how to instantiate the client library and create a new storage bucket.

```python
# Imports the Google Cloud client library
from google.cloud import storage

# Instantiates a client
storage_client = storage.Client()

# The name for the new bucket
bucket_name = "my-new-bucket"

# Creates the new bucket
bucket = storage_client.create_bucket(bucket_name)

print(f"Bucket {bucket.name} created.")
```

--------------------------------

### Run a Python Storage Sample

Source: https://github.com/googleapis/python-storage/blob/main/scripts/readme-gen/templates/README.tmpl.rst

Execute a Python sample script for Google Cloud Storage. Ensure you have the necessary API enabled and role permissions.

```bash
$ python {{sample.file}}
```

--------------------------------

### Run Zonal Buckets sample

Source: https://github.com/googleapis/python-storage/blob/main/samples/README.md

Execute a sample for zonal buckets, providing the bucket name and object name as arguments.

```bash
python samples/snippets/zonal_buckets/storage_create_and_write_appendable_object.py --bucket_name <BUCKET_NAME> --object_name <OBJECT_NAME>
```

--------------------------------

### Clone and Set Up Local Repository

Source: https://github.com/googleapis/python-storage/blob/main/CONTRIBUTING.rst

Clone the python-storage repository and configure remotes for pulling upstream changes.

```bash
cd ${HOME}
git clone git@github.com:USERNAME/python-storage.git hack-on-python-storage
cd hack-on-python-storage
# Configure remotes such that you can pull changes from the googleapis/python-storage
# repository into your local repository.
git remote add upstream git@github.com:googleapis/python-storage.git
# fetch and merge changes from upstream into main
git fetch upstream
git merge upstream/main
```

--------------------------------

### soft_delete_time

Source: https://github.com/googleapis/python-storage/blob/main/docs/storage/bucket.md

Gets the time at which a bucket was soft-deleted, if applicable.

```APIDOC
## *property* soft_delete_time

### Description
If this bucket has been soft-deleted, returns the time at which it became soft-deleted.

### Parameters:
None

### Request Example:
None provided in source.

### Response:
#### Success Response
* **soft_delete_time** (`datetime.datetime` or `NoneType`) - (readonly) The time that the bucket became soft-deleted. Note this property is only set for soft-deleted buckets.

#### Response Example:
None provided in source.
```

--------------------------------

### Create and Activate Virtual Environment

Source: https://github.com/googleapis/python-storage/blob/main/scripts/readme-gen/templates/install_deps.tmpl.rst

Create a new virtual environment named 'env' and activate it. This isolates project dependencies. Samples are compatible with Python 3.7+.

```bash
virtualenv env
source env/bin/activate
```

--------------------------------

### SoftDeletePolicy.effective_time

Source: https://github.com/googleapis/python-storage/blob/main/docs/storage/bucket.md

Gets the effective time of the bucket's soft delete policy.

```APIDOC
## property effective_time

### Description
Get the effective time of the bucket’s soft delete policy.

### Return type:
datetime.datetime or `NoneType`

### Returns:
point-in time at which the bucket’s soft delte policy is
effective, or `None` if the property is not set.
```

--------------------------------

### Clone the repository

Source: https://github.com/googleapis/python-storage/blob/main/samples/README.md

Clone the Google Cloud Storage Python samples repository to your local machine.

```bash
git clone https://github.com/googleapis/python-storage.git
```

--------------------------------

### SoftDeletePolicy.retention_duration_seconds

Source: https://github.com/googleapis/python-storage/blob/main/docs/storage/bucket.md

Gets the retention duration in seconds for the bucket's soft delete policy.

```APIDOC
## property retention_duration_seconds

### Description
Get the retention duration of the bucket’s soft delete policy.

### Return type:
int or `NoneType`

### Returns:
The period of time in seconds that soft-deleted objects in the bucket
will be retained and cannot be permanently deleted; Or `None` if the
property is not set.
```

--------------------------------

### Clone Python Docs Samples Repository

Source: https://github.com/googleapis/python-storage/blob/main/scripts/readme-gen/templates/install_deps.tmpl.rst

Clone the official Python documentation samples repository from GitHub.

```bash
$ git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
```

--------------------------------

### Get Bucket ACL Object

Source: https://github.com/googleapis/python-storage/blob/main/docs/acl_guide.md

Retrieve the ACL object for a bucket to interact with its permissions.

```python
client = storage.Client()
bucket = client.get_bucket(bucket_name)
acl = bucket.acl
```

--------------------------------

### Get Bucket Metadata

Source: https://github.com/googleapis/python-storage/blob/main/samples/README.md

Retrieves the metadata for a specific bucket. Requires the bucket name as input.

```python
python storage_get_bucket_metadata.py <BUCKET_NAME>
```

--------------------------------

### Set Environment Variables for Faster Linting

Source: https://github.com/googleapis/python-storage/blob/main/CONTRIBUTING.rst

Optimize linting speed by specifying the testing remote and branch.

```bash
export GOOGLE_CLOUD_TESTING_REMOTE="upstream"
export GOOGLE_CLOUD_TESTING_BRANCH="main"
```

--------------------------------

### Upload file with customer-supplied encryption key

Source: https://github.com/googleapis/python-storage/blob/main/docs/storage/blob.md

This snippet demonstrates how to upload a file using a customer-supplied encryption key. Ensure you have the necessary key and understand the security implications.

```python
from google.cloud import storage


def upload_blob_with_customer_key(bucket_name, blob_name, file_path, kms_key_name):
    """Upload file with a customer-supplied encryption key.

    Args:
        bucket_name (str): The name of your Cloud Storage bucket.
        blob_name (str): The name of your object.
        file_path (str): Path to the file to upload.
        kms_key_name (str): The KMS key used to encrypt objects before
            uploading. This property is used to encrypt objects with a
            customer-managed encryption key. See:
            https://cloud.google.com/storage/docs/encryption/customer-managed-keys
    """
    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(blob_name)

    # Set the KMS key to encrypt the object
    blob.customer_encryption.kms_key_name = kms_key_name

    blob.upload_from_filename(file_path)

    print(
        "File {} uploaded to {} with KMS key {}".format(
            file_path, blob_name, kms_key_name
        )
    )

```

--------------------------------

### Get Bucket Labels

Source: https://github.com/googleapis/python-storage/blob/main/samples/README.md

Retrieves the labels associated with a specific bucket. Requires the bucket name as input.

```python
python storage_get_bucket_labels.py <BUCKET_NAME>
```

--------------------------------

### Get HMAC Key

Source: https://github.com/googleapis/python-storage/blob/main/samples/README.md

Retrieves information about an HMAC key. Requires the access ID and project ID as input.

```python
python storage_get_hmac_key.py <ACCESS_ID> <PROJECT_ID>
```

--------------------------------

### get_notification

Source: https://github.com/googleapis/python-storage/blob/main/docs/storage/bucket.md

Get Pub/Sub notification configuration for this bucket. This method allows retrieval of specific notification configurations associated with the bucket.

```APIDOC
## get_notification

### Description
Get Pub / Sub notification for this bucket. This method allows retrieval of specific notification configurations associated with the bucket.

### Method
GET (implied by API reference)

### Endpoint
(Implied by API reference for notifications/get)

### Parameters
#### Path Parameters
* **notification_id** (str) - Required - The notification id to retrieve the notification configuration.

#### Query Parameters
None explicitly defined in this SDK method signature.

#### Request Body
None

### Request Example
None explicitly provided in source.

### Response
#### Success Response
* **BucketNotification** (google.cloud.storage.notification.BucketNotification) - The notification instance.

#### Response Example
None explicitly provided in source.
```

--------------------------------

### Run a Specific Benchmark Test

Source: https://github.com/googleapis/python-storage/blob/main/tests/perf/microbenchmarks/README.md

To run a single test, append '::' followed by the test name to the file path. This allows for focused testing of specific benchmark scenarios.

```bash
pytest --benchmark-json=output.json -vv -s tests/perf/microbenchmarks/reads/test_reads.py::test_downloads_single_proc_single_coro
```

```bash
pytest --benchmark-json=output.json -vv -s tests/perf/microbenchmarks/writes/test_writes.py::test_uploads_single_proc_single_coro
```

--------------------------------

### Get Public Access Prevention

Source: https://github.com/googleapis/python-storage/blob/main/samples/README.md

Retrieves the public access prevention configuration for a bucket. Requires the bucket name as input.

```python
python storage_get_public_access_prevention.py <BUCKET_NAME>
```

--------------------------------

### Get Metadata

Source: https://github.com/googleapis/python-storage/blob/main/samples/README.md

Retrieves the metadata for a specific object (blob) within a bucket. Requires the bucket name and blob name as input.

```python
python storage_get_metadata.py <BUCKET_NAME> <BLOB_NAME>
```

--------------------------------

### Run System Tests with Nox

Source: https://github.com/googleapis/python-storage/blob/main/CONTRIBUTING.rst

Execute system tests, which run against an actual project, using nox.

```bash
nox -s system-3.14
```

--------------------------------

### Get Default Event Based Hold

Source: https://github.com/googleapis/python-storage/blob/main/samples/README.md

Retrieves the default event-based hold configuration for a bucket. Requires the bucket name as input.

```python
python storage_get_default_event_based_hold.py <BUCKET_NAME>
```

--------------------------------

### Bucket Class Initialization

Source: https://github.com/googleapis/python-storage/blob/main/docs/storage/bucket.md

Initializes a Bucket object representing a Google Cloud Storage bucket. It requires a client object and the bucket name. Optional parameters include user_project for billing and generation for selecting a specific revision.

```APIDOC
## google.cloud.storage.bucket.Bucket

### Description
Represents a Bucket on Cloud Storage.

### Parameters
* **client** ([`google.cloud.storage.client.Client`](client.md#google.cloud.storage.client.Client)) – A client which holds credentials and project configuration for the bucket.
* **name** (*str*) – The name of the bucket. Bucket names must start and end with a number or letter.
* **user_project** (*str*) – (Optional) The project ID to be billed for API requests made via this instance.
* **generation** (*int*) – (Optional) If present, selects a specific revision of this bucket.
```

--------------------------------

### get_service_account_email

Source: https://github.com/googleapis/python-storage/blob/main/docs/storage/client.md

Get the email address of the project's Google Cloud Storage service account. The project ID can be optionally specified.

```APIDOC
## get_service_account_email

### Description
Get the email address of the project’s GCS service account

### Method
GET

### Endpoint
/storage/v1/projects/{project}/serviceAccount

### Parameters
#### Path Parameters
- **project** (str) - Optional - Project ID to use for retrieving GCS service account email address. Defaults to the client’s project.

#### Query Parameters
- **timeout** (float or tuple) - Optional - The amount of time, in seconds, to wait for the server response.
- **retry** (google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy) - Optional - How to retry the RPC.

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **service account email address** (str) - The email address of the service account.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Create Bucket Object from String URI

Source: https://github.com/googleapis/python-storage/blob/main/docs/storage/bucket.md

Use this class method to create a Bucket object by providing a bucket URI string. Always pass the client object.

```python
from google.cloud import storage
from google.cloud.storage.bucket import Bucket
client = storage.Client()
bucket = Bucket.from_string("gs://bucket", client=client)
```

--------------------------------

### Enable OpenTelemetry Tracing for Cloud Storage Client

Source: https://github.com/googleapis/python-storage/blob/main/docs/README.rst

Sets the environment variable to enable tracing for the Cloud Storage client.

```console
export ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=True
```

--------------------------------

### Create Bucket Object from URI

Source: https://github.com/googleapis/python-storage/blob/main/docs/storage/bucket.md

Use this class method to create a Bucket object by providing a bucket URI. It is recommended to always pass the client object.

```python
from google.cloud import storage
from google.cloud.storage.bucket import Bucket
client = storage.Client()
bucket = Bucket.from_uri("gs://bucket", client=client)
```

--------------------------------

### get_blob

Source: https://github.com/googleapis/python-storage/blob/main/docs/storage/bucket.md

Get a blob object by name. This method allows for conditional retrieval based on various matching criteria and supports customer-supplied encryption keys and soft-deleted objects.

```APIDOC
## get_blob(blob_name, client=None, encryption_key=None, generation=None, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object>, soft_deleted=None, **kwargs)

### Description
Get a blob object by name. See a [code sample](https://cloud.google.com/storage/docs/samples/storage-get-metadata#storage_get_metadata-python) on how to retrieve metadata of an object. If [`user_project`](#google.cloud.storage.bucket.Bucket.user_project) is set, bills the API request to that project.

### Parameters:
#### Path Parameters
* **blob_name** (str) – The name of the blob to retrieve.

#### Optional Parameters:
* **client** ([`Client`](client.md#google.cloud.storage.client.Client) or `NoneType`) – The client to use. If not passed, falls back to the `client` stored on the current bucket.
* **encryption_key** (bytes) – 32 byte encryption key for customer-supplied encryption. See https://cloud.google.com/storage/docs/encryption#customer-supplied.
* **generation** (long) – If present, selects a specific revision of this object.
* **if_etag_match** (Union[str, Set[str]]) – See [Using if_etag_match](../generation_metageneration.md#using-if-etag-match)
* **if_etag_not_match** (Union[str, Set[str]]) – See [Using if_etag_not_match](../generation_metageneration.md#using-if-etag-not-match)
* **if_generation_match** (long) – See [Using if_generation_match](../generation_metageneration.md#using-if-generation-match)
* **if_generation_not_match** (long) – See [Using if_generation_not_match](../generation_metageneration.md#using-if-generation-not-match)
* **if_metageneration_match** (long) – See [Using if_metageneration_match](../generation_metageneration.md#using-if-metageneration-match)
* **if_metageneration_not_match** (long) – See [Using if_metageneration_not_match](../generation_metageneration.md#using-if-metageneration-not-match)
* **timeout** (float or tuple) – The amount of time, in seconds, to wait for the server response. See: [Configuring Timeouts](../retry_timeout.md#configuring-timeouts)
* **retry** (google.api_core.retry.Retry or [*google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – How to retry the RPC. See: [Configuring Retries](../retry_timeout.md#configuring-retries)
* **soft_deleted** (bool) – If True, looks for a soft-deleted object. Will only return the object metadata if the object exists and is in a soft-deleted state. Object `generation` is required if `soft_deleted` is set to True. See: https://cloud.google.com/storage/docs/soft-delete
* **kwargs** – Keyword arguments to pass to the [`Blob`](blob.md#google.cloud.storage.blob.Blob) constructor.

### Return type:
[`google.cloud.storage.blob.Blob`](blob.md#google.cloud.storage.blob.Blob) or None

### Returns:
The blob object if it exists, otherwise None.
```

--------------------------------

### Run Linting with Nox

Source: https://github.com/googleapis/python-storage/blob/main/CONTRIBUTING.rst

Check for PEP8 compliance and other linting issues using nox.

```bash
nox -s lint
```