Metadata-Version: 2.4
Name: replicated
Version: 0.1.0a2
Summary: Python SDK for Replicated customer, metrics, and instance insights
Author-email: Replicated <support@replicated.com>
License: MIT
Project-URL: Homepage, https://github.com/replicatedhq/replicated-python
Project-URL: Documentation, https://docs.replicated.com/sdk/python
Project-URL: Repository, https://github.com/replicatedhq/replicated-python
Project-URL: Bug Tracker, https://github.com/replicatedhq/replicated-python/issues
Keywords: replicated,sdk,metrics,customers
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24.0
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"

# Replicated Python SDK

A Python SDK for embedding Replicated customer, custom metrics, and instance insights data in your applications.

## Installation

Install the SDK via pip:

```bash
pip install --upgrade replicated
```

## Usage

### Sync Example

```python
from replicated import ReplicatedClient, InstanceStatus

client = ReplicatedClient(
    publishable_key="replicated_pk_...", 
    app_slug="my-app"
)

# Create a customer (or fetch an existing one)
customer = client.customer.get_or_create(email_address="xxx@yyy.com")

# Get or create the associated instance
instance = customer.get_or_create_instance()

# Use the instance for metrics and status reporting
instance.send_metric("cpu_usage", 0.83)
instance.set_status(InstanceStatus.RUNNING)
instance.set_version("1.2.0")
```

### Custom State Directory

By default, the SDK stores state in platform-specific directories. You can override this for testing, containerization, or custom deployments:

```python
from replicated import ReplicatedClient

# Use a custom directory (supports ~ and relative paths)
client = ReplicatedClient(
    publishable_key="replicated_pk_...",
    app_slug="my-app",
    state_directory="/var/lib/my-app/replicated-state"
)

# Or use a relative path (will be resolved to absolute)
client = ReplicatedClient(
    publishable_key="replicated_pk_...",
    app_slug="my-app",
    state_directory="./local-state"
)
```

**When to use custom state directories:**
- Testing with temporary directories
- Docker containers with mounted volumes
- Multi-tenant applications requiring isolated state
- Development with project-local state

### Async Example

```python
from replicated import AsyncReplicatedClient, InstanceStatus

async def main():
    async with AsyncReplicatedClient(
        publishable_key="replicated_pk_...", 
        app_slug="my-app"
    ) as client:
        customer = await client.customer.get_or_create(email_address="xxx@yyy.com")
        instance = await customer.get_or_create_instance()

        await instance.send_metric("cpu_usage", 0.83)
        await instance.set_status(InstanceStatus.RUNNING)
        await instance.set_version("1.2.0")
```

## Documentation

For detailed documentation, visit [docs.replicated.com/sdk/python](https://docs.replicated.com/sdk/python).

## License

MIT License
