Metadata-Version: 2.4
Name: useshards
Version: 0.1.0a1
Summary: A minimal Shard API client. This alpha supports server version requests.
License-Expression: Apache-2.0
Project-URL: Homepage, https://useshards.com
Project-URL: Repository, https://github.com/presmihaylov/shard
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# useshards

A minimal Python client for [Shard](https://github.com/presmihaylov/shard).

This alpha supports only `GET /v0/version`. Sandbox creation, command execution,
and file operations are not available in this release. Python 3.10 or later is required.
The package has no runtime dependencies.

```sh
pip install --pre useshards
```

```python
from useshards import Shard

shard = Shard(url="https://shard.example.com", api_key="YOUR_API_KEY")
print(shard.version())
```

```python
import asyncio
from useshards import AsyncShard

async def main():
    shard = AsyncShard()  # Uses SHARD_REMOTE and SHARD_API_KEY.
    print(await shard.version())

asyncio.run(main())
```

`url` defaults to `SHARD_REMOTE`. `api_key` defaults to `SHARD_API_KEY`.
Use the server base URL without `/v0`. Base paths are supported.
The current server requires a token with `daemon:read` or `*` for this endpoint.
Use HTTPS for remote connections. HTTP supports local servers or a trusted network.
Redirects are rejected. The socket timeout defaults to 30 seconds:

```python
print(shard.version(timeout=5))
```

`AsyncShard` uses a worker thread for HTTP requests in this minimal release.
Cancellation stops the await, but the HTTP request can continue until its timeout.
HTTP failures, malformed responses, and connection failures raise exceptions.
The API is experimental. Future alpha releases can change it.

Website: https://useshards.com

License: Apache-2.0
