## BSCP-PYTHON-SDK

[![license](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat)]()

[中文文档](./readme.md)

## Overview

bscp-python-sdk is the Python SDK of the Blue Whale BSCP project. It can help you easily access the configuration content of the project saved on BSCP.

## Features

- kv configuration pull
- kv configuration watch

## Quick Start

### Installation

```bash
python -m pip install bk-bscp
```

Tip: Only `Python 3.8+` is supported

### client object`BscpClient`

Use `BscpClient` to complete the main operations, which supports two different calling styles.

General style:

```python
from bk_bscp.client import BscpClient

client = BscpClient(server_addrs, token, biz_id)
try:
    pair = client.get("app1", "key1")
finally:
    client.close()
```

- general normal style requires you to manually manage connections. It is suitable for reusing long connections and is used when a large number of operations need to be completed.

Context manager style:

```python
from bk_bscp.client import BscpClient

with BscpClient(server_addrs, token, biz_id) as client:
    pair = client.get("app1", "key1")
```

- In this style, the client's connection will be automatically closed, which is suitable for scenarios where the connection is short and the number of operations is small.

### Sample files

For more sample code, please refer to the examples/ directory.

### Development Guide

Installation environment

```bash
# Install version, modify {version} to real version, such as 3.18. If there is already a version, ignore this step
uv python install {version}

# Create environment, modify {path} to the real path of python

uv venv -p {path}/python

# Install dependencies
uv sync --frozen
```

Execute unit tests:

```bash
uv run pytest -s tests/
```

Some related environment variable configuration items:

```bash
# Set the log printing level, the default is INFO
BSCP_LOG_LEVEL=DEBUG
```

#### Enable integration testing

In order to better test the functions of the SDK, this project has written some integration test cases that will connect to the real BSCP server. These tests are not enabled by default and can be enabled by configuring the following environment variables:

```bash
BSCP_SERVER_ADDRS="your-bscp.example.com:9090"
BSCP_TOKEN="your_token"
BSCP_BIZ_ID="1"

# 启用 Get 功能测试
BSCP_EXISTENT_APP_KEY="your_app,your_key"
```

#### Synchronize automatically generated gRPC source code files

In the `bk_bscp/grpc_lib` directory of the project, the Python source code files automatically generated by the grpc-related tool chain are stored. It should be noted that the original proto definition files on which these source codes depend are not saved in this SDK project, but are stored in the bscp main project. When you need to update this batch of files, please clone the bscp project locally, switch to the project root directory, and execute the following command:

```bash
find ./pkg/protocol/core ./pkg/protocol/feed-server -name "*.proto" | \
    xargs python -m grpc_tools.protoc -I. -I ./pkg/thirdparty/protobuf/ --python_out=. --pyi_out=. --grpc_python_out=.
```

Then, return to the scripts/ subdirectory of this SDK project and execute the following script to complete synchronization:

```bash
# Replace {bscp_project_path} with the real bscp project directory
bash sync_grpc_generated.sh {bscp_project_path}
```

## Support

- [bk forum](https://bk.tencent.com/s-mart/community)
- [bk DevOps online video tutorial(In Chinese)](https://cloud.tencent.com/developer/edu/major-100008)
- Contact us, technical exchange QQ group:

<img src="https://github.com/Tencent/bk-PaaS/raw/master/docs/resource/img/bk_qq_group.png" width="250" hegiht="250" align=center />

## BlueKing Community

- [BK-CI](https://github.com/Tencent/bk-ci)：a continuous integration and continuous delivery system that can easily present your R & D process to you.
- [BK-BCS](https://github.com/Tencent/bk-bcs)：a basic container service platform which provides orchestration and management for micro-service business.
- [BK-BCS-SaaS](https://github.com/Tencent/bk-bcs-saas)：a SaaS provides users with highly scalable, flexible and easy-to-use container products and services.
- [BK-PaaS](https://github.com/Tencent/bk-PaaS)：an development platform that allows developers to create, develop, deploy and manage SaaS applications easily and quickly.
- [BK-SOPS](https://github.com/Tencent/bk-sops)：an lightweight scheduling SaaS  for task flow scheduling and execution through a visual graphical interface.
- [BK-CMDB](https://github.com/Tencent/bk-cmdb)：an enterprise-level configuration management platform for assets and applications.

## Contributing

If you have good ideas or suggestions, please let us know by Issues or Pull Requests and contribute to the Blue Whale Open Source Community.

## License

bscp-go is based on the MIT protocol. Please refer to [LICENSE](./LICENSE.txt) for details.
