Metadata-Version: 2.3
Name: botoplier
Version: 0.0.1.dev1
Summary: A powerful yet simple way to use AWS APIs, built on boto3
Project-URL: Repository, https://github.com/ManoManoTech/botoplier
Author-email: Elie Bleton <elie.bleton@manomano.com>
License: Copyright (c) 2024 "ManoMano" Colibri SAS
        
        Permission to use, copy, modify, and distribute this software for any purpose
        with or without fee is hereby granted, provided that the above copyright notice
        and this permission notice appear in all copies.
        
        THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
        REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
        FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
        INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
        OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
        TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
        THIS SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: ISC License (ISCL)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: boto3>=1.34.139
Requires-Dist: jq>=1.7
Requires-Dist: treelib>=1.7
Description-Content-Type: text/markdown

# botoplier 🚀

[![PyPI - Version](https://img.shields.io/pypi/v/botoplier)](https://pypi.org/project/botoplier/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/botoplier)](https://pypi.org/project/botoplier/) [![PyPI - License](https://img.shields.io/pypi/l/botoplier)](https://github.com/ManoManoTech/botoplier/blob/main/LICENSE) [![pdm-managed](https://img.shields.io/badge/pdm-managed-blueviolet)](https://pdm.fming.dev) [![types - Mypy](https://img.shields.io/badge/types-Mypy-blue.svg)](https://github.com/python/mypy) [![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch) [![linting - Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v0.json)](https://github.com/astral-sh/ruff)

Enhance your AWS API interactions using `botoplier`, a Python library built on top of [boto3](https://github.com/boto/boto3) and [botocore](https://github.com/boto/botocore), facilitating simplified API operations through automated fetch, session management, and data handling features.

## Features

- **Multi-session management:** Efficient management of multiple AWS sessions.
- **Automatic pagination:** Seamless handling of API pagination.
- **Deep un-nesting:** Auto-structuring of complex JSON responses into a simplified format.
- **Custom un-nesting:** Advanced data extraction using a `jq`-like syntax.
- **Flexible configuration:** Tailor the tool to meet various operational needs.
- **Asyncio support:** Can be used synchronously or asynchronously with `asyncio`.

## Installation

Botoplier is distributed on [PyPI](https://pypi.org/project/botoplier/), and can be installed with `pip`, `poetry`, `pdm`, or any other Python package manager:

```bash
pip install botoplier
```

## `smart_query`

### Basic examples

```python
from botoplier.sync.smart_query import smart_query

# Describe all EC2 instances across multiple sessions and regions
result = smart_query(sessions, "ec2", "describe_instances")
```

### Result shape and un-nesting

The `smart_query` function automatically processes and simplifies the response structure from AWS services. It neatly
organizes deeply nested data into a more readable and usable format.

### Pagination detection

`smart_query` automatically detects and handles API pagination, ensuring that all data across pages is fetched and
returned as a single cohesive response.

## Multi-session / Parallelism

### Creating / Configuring multi-session

You can create and configure multi-sessions to simultaneously work across different AWS accounts and regions:

```python
from botoplier.sync.sessions import make_sessions

sessions = make_sessions({"account1": "123456789012"}, ["us-west-2", "us-east-1"], {"account1": "roleName"})
```

### Synchronizing with `gather_dict`

Use `gather_dict` to execute multiple asynchronous tasks concurrently:

```python
from botoplier.asyncio.sessions import make_sessions
from botoplier.asyncio import smart_query
from botoplier.util.dictutils import gather_dict


async def in_async():
    sessions = await make_sessions({"account1": "123456789012"}, ["us-west-2", "us-east-1"], {"account1": "roleName"})
    results = await gather_dict({
        'task1': smart_query(sessions, "s3", "list_buckets"),
        'task2': smart_query(sessions, "ec2", "describe_instances")
    })
```

## Smart query cookbook

- Use cases and recipes for common tasks and challenges one might face while using AWS services via `botoplier`.

## Environment variables

### Changing the environment variable prefix

If you're writing a tool that uses botoplier, it is sometimes more expedient to
change the recognized prefix for environment variables, which defaults to `BOTOPLIER`.

In your `src/__init__.py`, or before any botoplier import:

```python
import botoplier.config

botoplier.config.PREFIX = "MYTOOL"
```

### CLI Usage

Botoplier ships with a simple CLI to easily inspect the output shape of AWS APIs.

```shell
botoplier output-shape ec2 describe_instances
```

## Contributing

We value contributions from the community! Please read our [Contributing Guidelines](./CONTRIBUTING.md) and our [Code of Conduct](./.github/CODE_OF_CONDUCT.md) for information on how to get involved.

### Quick setup guide

We use [mise](https://mise.jdx.dev/) and [PDM](https://pdm-project.org/) for local development.

With these installed:

```bash
mise install
pdm install
pdm run botoplier --help # Test the installation of the CLI
pdm build # Build the package wheel and sdist
pdm run pytest # Run the tests
# etc...
```

We use [pre-commit](https://pre-commit.com/#install) hooks to ensure code quality.

## Supported versions

We currently support Python 3.9, 3.10, 3.11 and 3.12.

We may drop the support for a Python version before its end of life, to keep the codebase up to date with the latest Python features: i.e.: we will endeavor to support either the last 3 or 4 stable Python releases.

We don't plan to support earlier versions or different runtimes, but contributions are welcome.

### Roadmap

Syntax and advance type-hinting tricks are areas we'd like to improve.

The multi-region / multi-account support takes some of the tedium away. We're open
to improving this aspect further should an interested party come up with something.

Outside of this, we're happy with the limited scope of this library and are unlikely to
accept contributions widening its scope.

### TODO

- [ ] Support `smart_query` default session
- [ ] Replace `jq` by `jmespath` for un-nesting
- [ ] Rename `smart_query` module to query module, to avoid confusion with `smart_query` function
- [ ] Proper online documentation, with published object inventory
