.. image:: https://github.com/aws-samples/boto-session-manager-project/workflows/CI/badge.svg
:target: https://github.com/aws-samples/boto-session-manager-project/actions?query=workflow:CI
.. image:: https://img.shields.io/pypi/v/boto_session_manager.svg
:target: https://pypi.python.org/pypi/boto_session_manager
.. image:: https://img.shields.io/pypi/l/boto_session_manager.svg
:target: https://pypi.python.org/pypi/boto_session_manager
.. image:: https://img.shields.io/pypi/pyversions/boto_session_manager.svg
:target: https://pypi.python.org/pypi/boto_session_manager
.. image:: https://img.shields.io/pypi/dm/boto_session_manager.svg
:target: https://pypi.python.org/pypi/boto_session_manager
.. image:: https://img.shields.io/badge/STAR_Me_on_GitHub!--None.svg?style=social
:target: https://github.com/aws-samples/boto-session-manager-project
------
.. image:: https://img.shields.io/badge/Link-Install-blue.svg
:target: `install`_
.. image:: https://img.shields.io/badge/Link-GitHub-blue.svg
:target: https://github.com/aws-samples/boto-session-manager-project
.. image:: https://img.shields.io/badge/Link-Submit_Issue-blue.svg
:target: https://github.com/aws-samples/boto-session-manager-project/issues
.. image:: https://img.shields.io/badge/Link-Request_Feature-blue.svg
:target: https://github.com/aws-samples/boto-session-manager-project/issues
.. image:: https://img.shields.io/badge/Link-Download-blue.svg
:target: https://pypi.org/pypi/boto_session_manager#files
Welcome to ``boto_session_manager`` Documentation
==============================================================================
About ``boto_session_manager``
------------------------------------------------------------------------------
``boto_session_manager`` is a light weight, zero dependency python library that simplify managing your AWS boto3 session in your application code. It bring auto complete and type hint to the default ``boto3`` SDK, and provide smooth development experience with the following goodies:
- boto3 Client auto complete
- Cached boto3 Client
- Assume IAM role in application code
- Set temporary credential for AWS Cli
Additionally, if you use `boto3-stubs <https://pypi.org/project/boto3-stubs/>`_ and you did ``pip install "boto3-stubs[all]"``, then ``boto_session_manager`` comes with the auto complete and type hint for all boto3 methods out-of-the-box, without any extra configuration (such as `explicit type annotations <https://pypi.org/project/boto3-stubs/#explicit-type-annotations>`_)
Feature
------------------------------------------------------------------------------
**Boto Client Auto Complete**
Provide an Enum class to access the aws service name to create boto client.
.. code-block:: python
from boto_session_manager import BotoSesManager, AwsServiceEnum
bsm = BotoSesManager()
s3_client = bsm.s3_client
.. image:: https://github.com/MacHu-GWU/boto_session_manager-project/assets/6800411/c9f7f9bd-7b1d-4a3a-bacc-6296fd0c241a
One click to jump to the documentation:
.. image:: https://github.com/MacHu-GWU/boto_session_manager-project/assets/6800411/3d44c189-5900-4598-b493-47de97131793
Client method auto complete:
.. image:: https://github.com/MacHu-GWU/boto_session_manager-project/assets/6800411/c88ee956-b1ab-4d6c-aa3c-9df737ccd476
Arguments type hint:
.. image:: https://github.com/MacHu-GWU/boto_session_manager-project/assets/6800411/1978a8ed-ba21-4354-bde1-83e7652b4177
Note: you have to do ``pip install "boto3-stubs[all]"`` to enable "Client method auto complete" and "Arguments type hint" features.
**Cached Client**
Once an boto session is defined, each AWS Service client should be created only once in most of the case. ``boto_session_manager.BotoSesManager.get_client(service_name)`` allow you to fetch the client object from cache if possible.
.. code-block:: python
from boto_session_manager import BotoSesManager, AwsServiceEnum
bsm = BotoSesManager()
s3_client1 = bsm.get_client(AwsServiceEnum.S3)
s3_client2 = bsm.get_client(AwsServiceEnum.S3)
assert id(s3_client1) = id(s3_client2)
Or you can just do:
.. code-block:: python
bsm.s3_client.list_buckets() # it cache the client when needed
**Assume Role**
Create another boto session manager based on an assumed IAM role. Allow you to check if it is expired and maybe renew later.
.. code-block:: python
bsm_assumed = bsm.assume_role("arn:aws:iam::111122223333:role/your-assume-role-name")
sts_client = bsm_assumed.get_client(AwsServiceEnum.sts)
print(sts_client.get_caller_identity())
print(bsm_assumed.is_expired())
From ``1.5.1``, it adds support for auto-refreshable assumed role (Beta). Note that it is using ``AssumeRoleCredentialFetcher`` and ``DeferredRefreshableCredentials`` from botocore, which is not public API officially supported by botocore. This API may be unstable.
.. code-block:: python
bsm_assumed = bsm.assume_role(
"arn:aws:iam::111122223333:role/your-assume-role-name",
duration_seconds=900,
auto_refresh=True,
)
# even though the duration seconds is only 15 minutes,
# but it can keep running for 1 hour.
tick = 60
sleep = 60
for i in range(tick):
time.sleep(sleep)
print("elapsed {} seconds".format((i + 1) * sleep))
print("Account id = {}".format(bsm_new.sts_client.get_caller_identity()["Account"]))
**AWS CLI context manager**
You explicitly defined a boto session manager that is not the same as the default one used by your AWS CLI. The ``boto_session_manager.BotoSesManager.awscli()`` context manager can temporarily set your default AWS CLI credential as the same as the one you defined, and automatically revert it back.
.. code-block:: python
# explicitly define a boto session manager
bsm = BotoSesManager(
profile_name="my_aws_profile",
)
with bsm.awscli():
# now the default AWS CLI credential is the same as the ``bsm`` you defined
Here's a more detailed example:
.. code-block:: python
import os
from boto_session_manager import BotoSesManager
def print_default_aws_cli_credential():
print("AWS_ACCESS_KEY_ID =", os.environ.get("AWS_ACCESS_KEY_ID"))
print("AWS_SECRET_ACCESS_KEY =", os.environ.get("AWS_SECRET_ACCESS_KEY"))
print("AWS_SESSION_TOKEN =", os.environ.get("AWS_SESSION_TOKEN"))
print("AWS_REGION =", os.environ.get("AWS_REGION"))
print("--- before ---")
print_default_aws_cli_credential()
bsm = BotoSesManager(profile_name="aws_data_lab_open_source_us_east_1")
with bsm.awscli():
print("--- within awscli() context manager ---")
print_default_aws_cli_credential()
print("--- after ---")
print_default_aws_cli_credential()
# --- before ---
# AWS_ACCESS_KEY_ID = None
# AWS_SECRET_ACCESS_KEY = None
# AWS_SESSION_TOKEN = None
# AWS_REGION = None
# --- within awscli() context manager ---
# AWS_ACCESS_KEY_ID = ABCDEFG...
# AWS_SECRET_ACCESS_KEY = ABCDEFG...
# AWS_SESSION_TOKEN = ABCDEFG...
# AWS_REGION = us-east-1
# --- after ---
# AWS_ACCESS_KEY_ID = None
# AWS_SECRET_ACCESS_KEY = None
# AWS_SESSION_TOKEN = None
# AWS_REGION = None
.. _install:
Install
------------------------------------------------------------------------------
``boto_session_manager`` is released on PyPI, so all you need is:
.. code-block:: console
$ pip install boto_session_manager
To upgrade to latest version:
.. code-block:: console
$ pip install --upgrade boto_session_manager
Raw data
{
"_id": null,
"home_page": "https://github.com/aws-samples/boto_session_manager-project",
"name": "boto-session-manager",
"maintainer": "Sanhe Hu",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "husanhe@gmail.com",
"keywords": "",
"author": "Sanhe Hu",
"author_email": "husanhe@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/06/04/51afcfe5b091e9ddca4f6d73789404324338b062f4e535e6957f435c3db5/boto_session_manager-1.7.2.tar.gz",
"platform": "Windows",
"description": ".. image:: https://github.com/aws-samples/boto-session-manager-project/workflows/CI/badge.svg\n :target: https://github.com/aws-samples/boto-session-manager-project/actions?query=workflow:CI\n\n.. image:: https://img.shields.io/pypi/v/boto_session_manager.svg\n :target: https://pypi.python.org/pypi/boto_session_manager\n\n.. image:: https://img.shields.io/pypi/l/boto_session_manager.svg\n :target: https://pypi.python.org/pypi/boto_session_manager\n\n.. image:: https://img.shields.io/pypi/pyversions/boto_session_manager.svg\n :target: https://pypi.python.org/pypi/boto_session_manager\n\n.. image:: https://img.shields.io/pypi/dm/boto_session_manager.svg\n :target: https://pypi.python.org/pypi/boto_session_manager\n\n.. image:: https://img.shields.io/badge/STAR_Me_on_GitHub!--None.svg?style=social\n :target: https://github.com/aws-samples/boto-session-manager-project\n\n------\n\n.. image:: https://img.shields.io/badge/Link-Install-blue.svg\n :target: `install`_\n\n.. image:: https://img.shields.io/badge/Link-GitHub-blue.svg\n :target: https://github.com/aws-samples/boto-session-manager-project\n\n.. image:: https://img.shields.io/badge/Link-Submit_Issue-blue.svg\n :target: https://github.com/aws-samples/boto-session-manager-project/issues\n\n.. image:: https://img.shields.io/badge/Link-Request_Feature-blue.svg\n :target: https://github.com/aws-samples/boto-session-manager-project/issues\n\n.. image:: https://img.shields.io/badge/Link-Download-blue.svg\n :target: https://pypi.org/pypi/boto_session_manager#files\n\n\nWelcome to ``boto_session_manager`` Documentation\n==============================================================================\n\n\nAbout ``boto_session_manager``\n------------------------------------------------------------------------------\n``boto_session_manager`` is a light weight, zero dependency python library that simplify managing your AWS boto3 session in your application code. It bring auto complete and type hint to the default ``boto3`` SDK, and provide smooth development experience with the following goodies:\n\n- boto3 Client auto complete\n- Cached boto3 Client\n- Assume IAM role in application code\n- Set temporary credential for AWS Cli\n\nAdditionally, if you use `boto3-stubs <https://pypi.org/project/boto3-stubs/>`_ and you did ``pip install \"boto3-stubs[all]\"``, then ``boto_session_manager`` comes with the auto complete and type hint for all boto3 methods out-of-the-box, without any extra configuration (such as `explicit type annotations <https://pypi.org/project/boto3-stubs/#explicit-type-annotations>`_)\n\n\nFeature\n------------------------------------------------------------------------------\n**Boto Client Auto Complete**\n\nProvide an Enum class to access the aws service name to create boto client.\n\n.. code-block:: python\n\n from boto_session_manager import BotoSesManager, AwsServiceEnum\n\n bsm = BotoSesManager()\n s3_client = bsm.s3_client\n\n.. image:: https://github.com/MacHu-GWU/boto_session_manager-project/assets/6800411/c9f7f9bd-7b1d-4a3a-bacc-6296fd0c241a\n\nOne click to jump to the documentation:\n\n.. image:: https://github.com/MacHu-GWU/boto_session_manager-project/assets/6800411/3d44c189-5900-4598-b493-47de97131793\n\nClient method auto complete:\n\n.. image:: https://github.com/MacHu-GWU/boto_session_manager-project/assets/6800411/c88ee956-b1ab-4d6c-aa3c-9df737ccd476\n\nArguments type hint:\n\n.. image:: https://github.com/MacHu-GWU/boto_session_manager-project/assets/6800411/1978a8ed-ba21-4354-bde1-83e7652b4177\n\nNote: you have to do ``pip install \"boto3-stubs[all]\"`` to enable \"Client method auto complete\" and \"Arguments type hint\" features.\n\n**Cached Client**\n\nOnce an boto session is defined, each AWS Service client should be created only once in most of the case. ``boto_session_manager.BotoSesManager.get_client(service_name)`` allow you to fetch the client object from cache if possible.\n\n.. code-block:: python\n\n from boto_session_manager import BotoSesManager, AwsServiceEnum\n\n bsm = BotoSesManager()\n s3_client1 = bsm.get_client(AwsServiceEnum.S3)\n s3_client2 = bsm.get_client(AwsServiceEnum.S3)\n assert id(s3_client1) = id(s3_client2)\n \nOr you can just do:\n\n.. code-block:: python\n\n bsm.s3_client.list_buckets() # it cache the client when needed\n\n**Assume Role**\n\nCreate another boto session manager based on an assumed IAM role. Allow you to check if it is expired and maybe renew later.\n\n.. code-block:: python\n\n bsm_assumed = bsm.assume_role(\"arn:aws:iam::111122223333:role/your-assume-role-name\")\n sts_client = bsm_assumed.get_client(AwsServiceEnum.sts)\n print(sts_client.get_caller_identity())\n\n print(bsm_assumed.is_expired())\n\nFrom ``1.5.1``, it adds support for auto-refreshable assumed role (Beta). Note that it is using ``AssumeRoleCredentialFetcher`` and ``DeferredRefreshableCredentials`` from botocore, which is not public API officially supported by botocore. This API may be unstable.\n\n.. code-block:: python\n\n bsm_assumed = bsm.assume_role(\n \"arn:aws:iam::111122223333:role/your-assume-role-name\",\n duration_seconds=900,\n auto_refresh=True,\n )\n\n # even though the duration seconds is only 15 minutes,\n # but it can keep running for 1 hour.\n tick = 60\n sleep = 60\n for i in range(tick):\n time.sleep(sleep)\n print(\"elapsed {} seconds\".format((i + 1) * sleep))\n print(\"Account id = {}\".format(bsm_new.sts_client.get_caller_identity()[\"Account\"]))\n\n**AWS CLI context manager**\n\nYou explicitly defined a boto session manager that is not the same as the default one used by your AWS CLI. The ``boto_session_manager.BotoSesManager.awscli()`` context manager can temporarily set your default AWS CLI credential as the same as the one you defined, and automatically revert it back.\n\n.. code-block:: python\n\n # explicitly define a boto session manager\n bsm = BotoSesManager(\n profile_name=\"my_aws_profile\",\n )\n\n with bsm.awscli():\n # now the default AWS CLI credential is the same as the ``bsm`` you defined\n\nHere's a more detailed example:\n\n.. code-block:: python\n\n import os\n from boto_session_manager import BotoSesManager\n\n def print_default_aws_cli_credential():\n print(\"AWS_ACCESS_KEY_ID =\", os.environ.get(\"AWS_ACCESS_KEY_ID\"))\n print(\"AWS_SECRET_ACCESS_KEY =\", os.environ.get(\"AWS_SECRET_ACCESS_KEY\"))\n print(\"AWS_SESSION_TOKEN =\", os.environ.get(\"AWS_SESSION_TOKEN\"))\n print(\"AWS_REGION =\", os.environ.get(\"AWS_REGION\"))\n\n print(\"--- before ---\")\n print_default_aws_cli_credential()\n\n bsm = BotoSesManager(profile_name=\"aws_data_lab_open_source_us_east_1\")\n with bsm.awscli():\n print(\"--- within awscli() context manager ---\")\n print_default_aws_cli_credential()\n\n print(\"--- after ---\")\n print_default_aws_cli_credential()\n\n # --- before ---\n # AWS_ACCESS_KEY_ID = None\n # AWS_SECRET_ACCESS_KEY = None\n # AWS_SESSION_TOKEN = None\n # AWS_REGION = None\n # --- within awscli() context manager ---\n # AWS_ACCESS_KEY_ID = ABCDEFG...\n # AWS_SECRET_ACCESS_KEY = ABCDEFG...\n # AWS_SESSION_TOKEN = ABCDEFG...\n # AWS_REGION = us-east-1\n # --- after ---\n # AWS_ACCESS_KEY_ID = None\n # AWS_SECRET_ACCESS_KEY = None\n # AWS_SESSION_TOKEN = None\n # AWS_REGION = None\n\n\n.. _install:\n\nInstall\n------------------------------------------------------------------------------\n\n``boto_session_manager`` is released on PyPI, so all you need is:\n\n.. code-block:: console\n\n $ pip install boto_session_manager\n\nTo upgrade to latest version:\n\n.. code-block:: console\n\n $ pip install --upgrade boto_session_manager\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "Provides an alternative, or maybe a more user friendly way to use the native boto3 API.",
"version": "1.7.2",
"project_urls": {
"Download": "https://pypi.python.org/pypi/boto_session_manager/1.7.2#downloads",
"Homepage": "https://github.com/aws-samples/boto_session_manager-project"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "beeb002ae8bbfd9e1a4195a94249c027f1e5321b33cc289357bc042597f6566d",
"md5": "924a94241eb42d11fa44a21a95075f01",
"sha256": "7b3ff1ba2c96f5dbc3c23d21676aace95914f5d138a4bf0fd84ca89a5d754ec3"
},
"downloads": -1,
"filename": "boto_session_manager-1.7.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "924a94241eb42d11fa44a21a95075f01",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.7",
"size": 31295,
"upload_time": "2024-01-15T04:12:40",
"upload_time_iso_8601": "2024-01-15T04:12:40.769175Z",
"url": "https://files.pythonhosted.org/packages/be/eb/002ae8bbfd9e1a4195a94249c027f1e5321b33cc289357bc042597f6566d/boto_session_manager-1.7.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "060451afcfe5b091e9ddca4f6d73789404324338b062f4e535e6957f435c3db5",
"md5": "172dbb4201701c9a0c1d1a20bf72a368",
"sha256": "ee451b606c3beaec65d0576d0b585303d34d80e05ec04021486e04f21fa89d2e"
},
"downloads": -1,
"filename": "boto_session_manager-1.7.2.tar.gz",
"has_sig": false,
"md5_digest": "172dbb4201701c9a0c1d1a20bf72a368",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 37451,
"upload_time": "2024-01-15T04:12:42",
"upload_time_iso_8601": "2024-01-15T04:12:42.580484Z",
"url": "https://files.pythonhosted.org/packages/06/04/51afcfe5b091e9ddca4f6d73789404324338b062f4e535e6957f435c3db5/boto_session_manager-1.7.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-15 04:12:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aws-samples",
"github_project": "boto_session_manager-project",
"github_not_found": true,
"lcname": "boto-session-manager"
}
JSON
