Metadata-Version: 2.4
Name: gpcore-sdk
Version: 0.2.3
Summary: Official Python SDK for the G-PORTAL gpcore API
Project-URL: Homepage, https://github.com/G-PORTAL/gpcore-py
Project-URL: Repository, https://github.com/G-PORTAL/gpcore-py
Project-URL: Issues, https://github.com/G-PORTAL/gpcore-py/issues
Author-email: G-PORTAL <support@g-portal.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: grpcio>=1.50.0
Requires-Dist: protobuf>=3.20
Requires-Dist: pyjwt>=2.10.1
Requires-Dist: python-keycloak>=6.0.0
Requires-Dist: requests>=2.28.0
Description-Content-Type: text/markdown

# gpcore-py

The official Python SDK for the [G-PORTAL](https://www.g-portal.com) gpcore API.

This is the Python counterpart to [gpcore-go](https://github.com/G-PORTAL/gpcore-go).
It provides a pre-configured OIDC client and auto-generated protobuf/gRPC bindings
for interacting with the gpcore API.

## Installation

```bash
pip install gpcore-sdk
```

## Usage

The following example authenticates using the client credentials flow and
fetches the current user:

```python
import grpc
from gpcore_sdk.client import APIClient
from gpcore_sdk.auth_strategies import (
    ClientCredentialsStrategy,
    CachedAuthStrategy,
)

from gpcore_sdk.protos.gpcore.api.auth.v1.rpc_pb2_grpc import AuthServiceStub
from gpcore_sdk.protos.gpcore.api.admin.v1.requests_pb2 import GetUserRequest


def main():
    auth = ClientCredentialsStrategy(
        client_id="YOUR_CLIENT_ID",
        client_secret="YOUR_CLIENT_SECRET",
    )

    client = APIClient(strategy=CachedAuthStrategy(auth, 30))
    stub = AuthServiceStub(client.channel)

    try:
        response = stub.GetUser(GetUserRequest())
        print(f"User: {response}")
    except grpc.RpcError as e:
        print(f"gRPC error: {e.code()} - {e.details()}")


if __name__ == "__main__":
    main()
```

### Authentication Strategies

| Strategy | Description |
|---|---|
| `ClientCredentialsStrategy` | OAuth2 client credentials flow. Recommended for service-to-service authentication. |
| `UserPasswordStrategy` | Resource owner password flow. Requires a dedicated Keycloak OIDC client. |
| `CachedAuthStrategy` | Wrapper that caches and auto-refreshes tokens from any underlying strategy. |

## Development

### Regenerating protobuf bindings

If the API definitions have changed, regenerate the Python protobuf/gRPC code:

```bash
scripts/update_proto.sh
```

### Local install

```bash
pip install -e .
```

## Releasing

1. Update the version in `pyproject.toml`.
2. Commit, tag with the version number, and push the tag.
3. The GitHub Actions workflow will build and publish to PyPI automatically.

## License

This project is licensed under the [Apache License 2.0](LICENSE).
