stackmachine 0.2.1__tar.gz → 0.3.0__tar.gz

stackmachine-0.3.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: stackmachine
+Version: 0.3.0
+Summary: Python SDK for StackMachine.
+Project-URL: Homepage, https://github.com/stackmachine/sdks/tree/main/python
+Project-URL: Repository, https://github.com/stackmachine/sdks
+Project-URL: Issues, https://github.com/stackmachine/sdks/issues
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: websocket-client<2,>=1.8
+Requires-Dist: websockets<16,>=12
+Description-Content-Type: text/markdown
+
+# StackMachine Python SDK
+
+Python SDK for StackMachine. It mirrors the JavaScript SDK surface with a
+Pythonic sync client and a native async client.
+
+## Installation
+
+```bash
+uv add stackmachine
+```
+
+## Usage
+
+```python
+from stackmachine import StackMachine
+
+with StackMachine("sk_stackmachine_...") as stackmachine:
+    app = stackmachine.apps.retrieve_by_name("my-app")
+    print(app.url)
+```
+
+```python
+from stackmachine import AsyncStackMachine
+
+async with AsyncStackMachine("sk_stackmachine_...") as stackmachine:
+    app = await stackmachine.apps.retrieve_by_name("my-app")
+    print(app.url)
+```
+
+## Clients
+
+`StackMachine` exposes sync methods. `AsyncStackMachine` exposes the same
+resource tree with awaitable methods.
+
+```python
+from stackmachine import AsyncStackMachine, StackMachine
+
+stackmachine = StackMachine("sk_stackmachine_...")
+async_stackmachine = AsyncStackMachine("sk_stackmachine_...")
+```
+
+Both clients accept JavaScript-style aliases during initialization:
+
+```python
+stackmachine = StackMachine.init(
+    {
+        "token": "sk_stackmachine_...",
+        "apiUrl": "https://api.stackmachine.com/graphql",
+        "maxNetworkRetries": 2,
+    }
+)
+```
+
+## Apps
+
+```python
+apps = stackmachine.apps.list(limit=10)
+
+for app in apps:
+    print(app.id, app.name)
+
+app = stackmachine.apps.retrieve("app_id")
+app = stackmachine.apps.retrieve_by_name("my-app")
+apps = stackmachine.apps.retrieve_many(["app_1", "app_2"])
+stackmachine.apps.delete("app_id")
+```
+
+Async lists can either be awaited for the first page or iterated directly:
+
+```python
+apps = async_stackmachine.apps.list(limit=10)
+first_page = await apps
+
+async for app in apps:
+    print(app.name)
+```
+
+## Deployments
+
+```python
+deployment = stackmachine.deployments.create(
+    {
+        "file": "https://example.com/app.zip",
+        "name": "my-app",
+    }
+)
+
+version = deployment.wait()
+```
+
+```python
+deployment = stackmachine.apps.autobuild(
+    {
+        "file": "https://example.com/app.zip",
+        "name": "my-app",
+    }
+)
+```
+
+## Files
+
+```python
+from stackmachine import create_zip
+
+zip_bytes = create_zip({"index.html": "<h1>Hello</h1>"})
+url = stackmachine.files.upload(zip_bytes)
+```
+
+## Domains
+
+```python
+domain = stackmachine.apps.domains.create(
+    app="app_id",
+    hostname="example.com",
+)
+
+is_verified = stackmachine.apps.domains.verify(domain.id)
+stackmachine.apps.domains.delete(domain.id)
+```
+
+## SSH
+
+```python
+server = stackmachine.apps.ssh.retrieve("app_id")
+server = stackmachine.apps.ssh.update("app_id", enabled=True)
+token = stackmachine.apps.ssh.tokens.create(app="app_id")
+
+users = stackmachine.apps.ssh.users.list(app="app_id")
+user = stackmachine.apps.ssh.users.retrieve("ssh_user_id")
+password = stackmachine.apps.ssh.users.passwords.rotate("ssh_user_id")
+
+key = stackmachine.apps.ssh.users.authorized_keys.create(
+    user="ssh_user_id",
+    public_key="ssh-ed25519 AAAA...",
+)
+```
+
+## Request Options
+
+Most methods accept `request_options` for per-request configuration:
+
+```python
+app = stackmachine.apps.retrieve(
+    "app_id",
+    request_options={
+        "api_key": "sk_stackmachine_other",
+        "timeout": 30,
+        "idempotency_key": "deploy-123",
+    },
+)
+```
+
+## Development
+
+```bash
+cd python
+uv sync --dev
+uv run ruff check src examples tests
+uv run pytest
+uv build --no-sources
+```
+
+## Manual Publish
+
+Use this path only for manual package uploads:
+
+```bash
+cd python
+uv sync --dev
+uv build --no-sources
+uv publish
+```

stackmachine-0.3.0/README.md

@@ -0,0 +1,172 @@
+# StackMachine Python SDK
+
+Python SDK for StackMachine. It mirrors the JavaScript SDK surface with a
+Pythonic sync client and a native async client.
+
+## Installation
+
+```bash
+uv add stackmachine
+```
+
+## Usage
+
+```python
+from stackmachine import StackMachine
+
+with StackMachine("sk_stackmachine_...") as stackmachine:
+    app = stackmachine.apps.retrieve_by_name("my-app")
+    print(app.url)
+```
+
+```python
+from stackmachine import AsyncStackMachine
+
+async with AsyncStackMachine("sk_stackmachine_...") as stackmachine:
+    app = await stackmachine.apps.retrieve_by_name("my-app")
+    print(app.url)
+```
+
+## Clients
+
+`StackMachine` exposes sync methods. `AsyncStackMachine` exposes the same
+resource tree with awaitable methods.
+
+```python
+from stackmachine import AsyncStackMachine, StackMachine
+
+stackmachine = StackMachine("sk_stackmachine_...")
+async_stackmachine = AsyncStackMachine("sk_stackmachine_...")
+```
+
+Both clients accept JavaScript-style aliases during initialization:
+
+```python
+stackmachine = StackMachine.init(
+    {
+        "token": "sk_stackmachine_...",
+        "apiUrl": "https://api.stackmachine.com/graphql",
+        "maxNetworkRetries": 2,
+    }
+)
+```
+
+## Apps
+
+```python
+apps = stackmachine.apps.list(limit=10)
+
+for app in apps:
+    print(app.id, app.name)
+
+app = stackmachine.apps.retrieve("app_id")
+app = stackmachine.apps.retrieve_by_name("my-app")
+apps = stackmachine.apps.retrieve_many(["app_1", "app_2"])
+stackmachine.apps.delete("app_id")
+```
+
+Async lists can either be awaited for the first page or iterated directly:
+
+```python
+apps = async_stackmachine.apps.list(limit=10)
+first_page = await apps
+
+async for app in apps:
+    print(app.name)
+```
+
+## Deployments
+
+```python
+deployment = stackmachine.deployments.create(
+    {
+        "file": "https://example.com/app.zip",
+        "name": "my-app",
+    }
+)
+
+version = deployment.wait()
+```
+
+```python
+deployment = stackmachine.apps.autobuild(
+    {
+        "file": "https://example.com/app.zip",
+        "name": "my-app",
+    }
+)
+```
+
+## Files
+
+```python
+from stackmachine import create_zip
+
+zip_bytes = create_zip({"index.html": "<h1>Hello</h1>"})
+url = stackmachine.files.upload(zip_bytes)
+```
+
+## Domains
+
+```python
+domain = stackmachine.apps.domains.create(
+    app="app_id",
+    hostname="example.com",
+)
+
+is_verified = stackmachine.apps.domains.verify(domain.id)
+stackmachine.apps.domains.delete(domain.id)
+```
+
+## SSH
+
+```python
+server = stackmachine.apps.ssh.retrieve("app_id")
+server = stackmachine.apps.ssh.update("app_id", enabled=True)
+token = stackmachine.apps.ssh.tokens.create(app="app_id")
+
+users = stackmachine.apps.ssh.users.list(app="app_id")
+user = stackmachine.apps.ssh.users.retrieve("ssh_user_id")
+password = stackmachine.apps.ssh.users.passwords.rotate("ssh_user_id")
+
+key = stackmachine.apps.ssh.users.authorized_keys.create(
+    user="ssh_user_id",
+    public_key="ssh-ed25519 AAAA...",
+)
+```
+
+## Request Options
+
+Most methods accept `request_options` for per-request configuration:
+
+```python
+app = stackmachine.apps.retrieve(
+    "app_id",
+    request_options={
+        "api_key": "sk_stackmachine_other",
+        "timeout": 30,
+        "idempotency_key": "deploy-123",
+    },
+)
+```
+
+## Development
+
+```bash
+cd python
+uv sync --dev
+uv run ruff check src examples tests
+uv run pytest
+uv build --no-sources
+```
+
+## Manual Publish
+
+Use this path only for manual package uploads:
+
+```bash
+cd python
+uv sync --dev
+uv build --no-sources
+uv publish
+```

stackmachine-0.3.0/examples/async_usage.py

@@ -0,0 +1,16 @@
+import asyncio
+import os
+
+from stackmachine import AsyncStackMachine
+
+
+async def main():
+    async with AsyncStackMachine(os.environ["STACKMACHINE_API_KEY"]) as client:
+        viewer = await client.viewer()
+        print(viewer.username if viewer else "anonymous")
+
+        async for app in client.apps.list(limit=10):
+            print(app.name, app.url)
+
+
+asyncio.run(main())

stackmachine-0.3.0/examples/basic_usage.py

@@ -0,0 +1,13 @@
+import os
+
+from stackmachine import StackMachine
+
+client = StackMachine(os.environ["STACKMACHINE_API_KEY"])
+
+viewer = client.viewer()
+print(viewer.username if viewer else "anonymous")
+
+for app in client.apps.list(limit=10):
+    print(app.name, app.url)
+
+client.close()

stackmachine-0.3.0/examples/deploy_app.py

@@ -0,0 +1,31 @@
+import os
+
+from stackmachine import StackMachine, create_zip
+
+client = StackMachine(os.environ["STACKMACHINE_API_KEY"])
+
+zip_file = create_zip(
+    {
+        "index.php": "<html><body><h1>Hello StackMachine</h1></body></html>",
+    }
+)
+
+upload_url = client.files.upload(
+    zip_file,
+    on_progress=lambda progress: print("Uploading", progress.percent * 100, "%"),
+)
+
+deployment = client.deployments.create(
+    app_name="hello-stackmachine",
+    owner="stackmachine",
+    upload_url=upload_url,
+)
+
+app_version = deployment.wait(
+    on_progress=lambda event: print(
+        event.datetime, event.stream, event.kind, event.message
+    )
+)
+
+print(app_version.app.url)
+client.close()

stackmachine-0.3.0/examples/list_apps.py

@@ -0,0 +1,10 @@
+import os
+
+from stackmachine import StackMachine
+
+with StackMachine(os.environ["STACKMACHINE_API_KEY"]) as client:
+    apps = client.apps.list(limit=25)
+    print("First page:", len(apps.data))
+
+    for app in apps:
+        print(app.name, app.url)

{stackmachine-0.2.1 → stackmachine-0.3.0}/pyproject.toml

@@ -4,11 +4,15 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stackmachine"
-version = "0.2.1"
+version = "0.3.0"
 description = "Python SDK for StackMachine."
 readme = "README.md"
 requires-python = ">=3.9"
-dependencies = []
+dependencies = [
+  "httpx>=0.27,<1",
+  "websocket-client>=1.8,<2",
+  "websockets>=12,<16",
+]
 classifiers = [
   "Development Status :: 2 - Pre-Alpha",
   "Intended Audience :: Developers",
@@ -28,18 +32,29 @@ Issues = "https://github.com/stackmachine/sdks/issues"
 [dependency-groups]
 dev = [
   "pytest>=8.0",
+  "pytest-asyncio>=0.24",
+  "ruff>=0.8",
 ]
 
+[tool.ruff]
+line-length = 88
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/stackmachine"]
 
 [tool.hatch.build.targets.sdist]
 include = [
   "/README.md",
+  "/examples",
   "/pyproject.toml",
   "/src",
   "/tests",
 ]
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]

stackmachine-0.3.0/src/stackmachine/__init__.py

@@ -0,0 +1,72 @@
+"""StackMachine Python SDK."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from ._async_client import AsyncStackMachine
+from ._client import StackMachine
+from ._config import RequestOptions
+from ._errors import (
+    StackMachineAPIError,
+    StackMachineAuthenticationError,
+    StackMachineConnectionError,
+    StackMachineError,
+    StackMachineGraphQLError,
+    StackMachineInvalidRequestError,
+    StackMachinePermissionError,
+    StackMachineRateLimitError,
+    StackMachineValidationError,
+    is_stackmachine_error,
+)
+from ._models import (
+    AppAlias,
+    AppSshServer,
+    DeployApp,
+    DeployAppKindWordPress,
+    DeployAppVersion,
+    DeploymentProgress,
+    ExpectedDNSRecord,
+    Log,
+    SshAuthorizedKey,
+    SshUser,
+    UploadProgress,
+    Viewer,
+)
+from ._pagination import AsyncStackMachineList, StackMachineList
+from ._uploads import create_zip
+
+try:
+    __version__ = version("stackmachine")
+except PackageNotFoundError:
+    __version__ = "0.3.0"
+
+__all__ = [
+    "AppAlias",
+    "AppSshServer",
+    "AsyncStackMachine",
+    "AsyncStackMachineList",
+    "DeployApp",
+    "DeployAppKindWordPress",
+    "DeployAppVersion",
+    "DeploymentProgress",
+    "ExpectedDNSRecord",
+    "Log",
+    "RequestOptions",
+    "SshAuthorizedKey",
+    "SshUser",
+    "StackMachine",
+    "StackMachineAPIError",
+    "StackMachineAuthenticationError",
+    "StackMachineConnectionError",
+    "StackMachineError",
+    "StackMachineGraphQLError",
+    "StackMachineInvalidRequestError",
+    "StackMachineList",
+    "StackMachinePermissionError",
+    "StackMachineRateLimitError",
+    "StackMachineValidationError",
+    "UploadProgress",
+    "Viewer",
+    "__version__",
+    "create_zip",
+    "is_stackmachine_error",
+]

stackmachine-0.3.0/src/stackmachine/_async_client.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+import httpx
+
+from ._config import (
+    DEFAULT_API_URL,
+    DEFAULT_MAX_NETWORK_RETRIES,
+    DEFAULT_TIMEOUT,
+    ClientConfig,
+)
+from ._graphql import operations as gql
+from ._models import Viewer
+from ._transport import AsyncTransport
+from ._uploads import AsyncUploader
+from .resources.apps import AsyncDeployAppsResource
+from .resources.deployments import AsyncDeploymentsResource
+from .resources.files import AsyncFilesResource
+
+
+class AsyncStackMachine:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        api_url: str = DEFAULT_API_URL,
+        headers: Optional[Mapping[str, str]] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_network_retries: int = DEFAULT_MAX_NETWORK_RETRIES,
+        http_client: Optional[httpx.AsyncClient] = None,
+        http_transport: Optional[httpx.AsyncBaseTransport] = None,
+    ) -> None:
+        self.api_key = api_key
+        self.api_url = api_url
+        self.apiUrl = api_url
+        self.timeout = timeout
+        self.max_network_retries = max_network_retries
+        self.maxNetworkRetries = max_network_retries
+        self._config = ClientConfig(
+            api_url=api_url,
+            headers=headers,
+            timeout=timeout,
+            max_network_retries=max_network_retries,
+        )
+        self._transport = AsyncTransport(
+            api_key,
+            self._config,
+            http_client=http_client,
+            http_transport=http_transport,
+        )
+        self.deployments = AsyncDeploymentsResource(self)
+        self.apps = AsyncDeployAppsResource(self, self.deployments)
+        self.files = AsyncFilesResource(self, AsyncUploader(self._transport))
+
+    @classmethod
+    def init(
+        cls,
+        settings: Optional[Mapping[str, Any]] = None,
+        **kwargs: Any,
+    ) -> "AsyncStackMachine":
+        values = {**dict(settings or {}), **kwargs}
+        api_key = values.pop("api_key", None) or values.pop("token", None) or ""
+        if "apiUrl" in values:
+            values["api_url"] = values.pop("apiUrl")
+        if "maxNetworkRetries" in values:
+            values["max_network_retries"] = values.pop("maxNetworkRetries")
+        return cls(api_key, **values)
+
+    async def close(self) -> None:
+        await self._transport.close()
+
+    async def __aenter__(self) -> "AsyncStackMachine":
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.close()
+
+    async def _query(
+        self,
+        query: str,
+        variables: Optional[Mapping[str, Any]] = None,
+        *,
+        request_options: Optional[Mapping[str, Any]] = None,
+    ) -> Any:
+        return await self._transport.execute(
+            query,
+            variables,
+            request_options=request_options,
+        )
+
+    async def _mutation(
+        self,
+        query: str,
+        variables: Optional[Mapping[str, Any]] = None,
+        *,
+        request_options: Optional[Mapping[str, Any]] = None,
+    ) -> Any:
+        return await self._transport.execute(
+            query,
+            variables,
+            request_options=request_options,
+            mutation=True,
+        )
+
+    def _subscribe_deployment(
+        self, build_id: str, request_options: Optional[Mapping[str, Any]] = None
+    ):
+        return self._transport.subscribe(
+            gql.AUTOBUILD_SUBSCRIPTION,
+            {"buildId": build_id},
+            request_options=request_options,
+        )
+
+    async def viewer(
+        self, *, request_options: Optional[Mapping[str, Any]] = None
+    ) -> Optional[Viewer]:
+        response = await self._query(
+            gql.VIEWER_QUERY, {}, request_options=request_options
+        )
+        viewer = response.get("viewer") if response else None
+        return Viewer(username=viewer["username"]) if viewer else None