https://github.com/localstack/localstack-python-client
🐍 A lightweight Python client for LocalStack
https://github.com/localstack/localstack-python-client
Last synced: about 1 month ago
JSON representation
🐍 A lightweight Python client for LocalStack
- Host: GitHub
- URL: https://github.com/localstack/localstack-python-client
- Owner: localstack
- License: apache-2.0
- Created: 2017-07-03T13:12:32.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2023-10-19T20:27:38.000Z (over 1 year ago)
- Last Synced: 2024-04-25T22:20:24.378Z (about 1 year ago)
- Language: Python
- Homepage:
- Size: 85.9 KB
- Stars: 171
- Watchers: 19
- Forks: 33
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-localstack - Python Client
- awesome-localstack - Python Client
README
# LocalStack Python Client
This is an easy-to-use Python client for [LocalStack](https://github.com/localstack/localstack).
The client library provides a thin wrapper around [boto3](https://github.com/boto/boto3) which
automatically configures the target endpoints to use LocalStack for your local cloud
application development.
## Prerequisites
To make use of this library, you need to have [LocalStack](https://github.com/localstack/localstack) installed on your local machine. In particular, the `localstack` command needs to be available.
## Installation
The easiest way to install *LocalStack* is via `pip`:
```
pip install localstack-client
```
## Usage
This library provides an API that is identical to `boto3`'s. A minimal way to try it out is to replace `import boto3` with `import localstack_client.session as boto3`. This will allow your boto3 calls to work as normal.
For example, to list all s3 buckets in localstack:
```python
import localstack_client.session as boto3
client = boto3.client('s3')
response = client.list_buckets()
```
Another example below shows using `localstack_client` directly. To list the SQS queues
in your local (LocalStack) environment, use the following code:
```python
import localstack_client.session
session = localstack_client.session.Session()
sqs = session.client('sqs')
assert sqs.list_queues() is not None
```
If you use `boto3.client` directly in your code, you can mock it.
```python
import localstack_client.session
import pytest
@pytest.fixture(autouse=True)
def boto3_localstack_patch(monkeypatch):
session_ls = localstack_client.session.Session()
monkeypatch.setattr(boto3, "client", session_ls.client)
monkeypatch.setattr(boto3, "resource", session_ls.resource)
```
```python
sqs = boto3.client('sqs')
assert sqs.list_queues() is not None # list SQS in localstack
```
## Configuration
You can use the following environment variables for configuration:
* `AWS_ENDPOINT_URL`: The endpoint URL to connect to (takes precedence over `USE_SSL`/`LOCALSTACK_HOST` below)
* `LOCALSTACK_HOST` (deprecated): A `:` variable defining where to find LocalStack (default: `localhost:4566`).
* `USE_SSL` (deprecated): Whether to use SSL when connecting to LocalStack (default: `False`).
### Enabling Transparent Local Endpoints
The library contains a small `enable_local_endpoints()` util function that can be used to transparently run all `boto3` requests against the local endpoints.
The following sample illustrates how it can be used - after calling `enable_local_endpoints()`, the S3 `ListBuckets` call will be run against LocalStack, even though we're using the default boto3 module.
```
import boto3
from localstack_client.patch import enable_local_endpoints()
enable_local_endpoints()
# the call below will automatically target the LocalStack endpoints
buckets = boto3.client("s3").list_buckets()
```
The patch can also be unapplied by calling `disable_local_endpoints()`:
```
from localstack_client.patch import disable_local_endpoints()
disable_local_endpoints()
# the call below will target the real AWS cloud again
buckets = boto3.client("s3").list_buckets()
```
## Contributing
If you are interested in contributing to LocalStack Python Client, start by reading our [`CONTRIBUTING.md`](CONTRIBUTING.md) guide. You can further navigate our codebase and [open issues](https://github.com/localstack/localstack-python-client/issues). We are thankful for all the contributions and feedback we receive.
## Changelog
Please refer to [`CHANGELOG.md`](CHANGELOG.md) to see the complete list of changes for each release.
## License
The LocalStack Python Client is released under the Apache License, Version 2.0 (see `LICENSE`).