Skip to content

armgit / E2B

Public Imported from GitHub
0

Open-source, secure environment with real-world tools for enterprise-grade agents.

feat: add getTags/get_tags to list all tags for a template (#1132)

Berrye83cf86454d0
diff --git a/.changeset/get-template-tags.md b/.changeset/get-template-tags.md
new file mode 100644
index 000000000..cec61f781
--- /dev/null
+++ b/.changeset/get-template-tags.md
@@ -0,0 +1,6 @@
+---
+'e2b': patch
+'@e2b/python-sdk': patch
+---
+
+Add `getTags`/`get_tags` method to list all tags for a template
diff --git a/packages/js-sdk/src/template/buildApi.ts b/packages/js-sdk/src/template/buildApi.ts
index d56d953c6..d699efe03 100644
--- a/packages/js-sdk/src/template/buildApi.ts
+++ b/packages/js-sdk/src/template/buildApi.ts
@@ -1,4 +1,4 @@
-import { ApiClient, handleApiError, paths } from '../api'
+import { ApiClient, handleApiError, paths, components } from '../api'
import { stripAnsi } from '../utils'
import { BuildError, FileUploadError, TemplateError } from '../errors'
import { LogEntry } from './logger'
@@ -7,6 +7,7 @@ import {
BuildStatusReason,
TemplateBuildStatus,
TemplateBuildStatusResponse,
+ TemplateTag,
TemplateTagInfo,
} from './types'
@@ -358,3 +359,31 @@ export async function removeTags(
throw error
}
}
+
+export async function getTemplateTags(
+ client: ApiClient,
+ { templateID }: { templateID: string }
+): Promise<TemplateTag[]> {
+ const res = await client.api.GET('/templates/{templateID}/tags', {
+ params: {
+ path: {
+ templateID,
+ },
+ },
+ })
+
+ const error = handleApiError(res, TemplateError)
+ if (error) {
+ throw error
+ }
+
+ if (!res.data) {
+ throw new TemplateError('Failed to get template tags')
+ }
+
+ return res.data.map((item: components['schemas']['TemplateTag']) => ({
+ tag: item.tag,
+ buildId: item.buildID,
+ createdAt: new Date(item.createdAt),
+ }))
+}
diff --git a/packages/js-sdk/src/template/index.ts b/packages/js-sdk/src/template/index.ts
index 78d903590..e7bc1e674 100644
--- a/packages/js-sdk/src/template/index.ts
+++ b/packages/js-sdk/src/template/index.ts
@@ -6,6 +6,7 @@ import { runtime } from '../utils'
import {
assignTags,
checkAliasExists,
+ getTemplateTags,
removeTags,
getBuildStatus,
getFileUploadLink,
@@ -34,6 +35,7 @@ import {
TemplateFinal,
TemplateFromImage,
TemplateOptions,
+ TemplateTag,
TemplateTagInfo,
} from './types'
import {
@@ -371,6 +373,30 @@ export class TemplateBase
return removeTags(client, { name, tags: normalizedTags })
}
+ /**
+ * Get all tags for a template.
+ *
+ * @param templateId Template ID or name
+ * @param options Authentication options
+ * @returns Array of tag details including tag name, buildId, and creation date
+ *
+ * @example
+ * ```ts
+ * const tags = await Template.getTags('my-template')
+ * for (const tag of tags) {
+ * console.log(`Tag: ${tag.tag}, Build: ${tag.buildId}, Created: ${tag.createdAt}`)
+ * }
+ * ```
+ */
+ static async getTags(
+ templateId: string,
+ options?: ConnectionOpts
+ ): Promise<TemplateTag[]> {
+ const config = new ConnectionConfig(options)
+ const client = new ApiClient(config)
+ return getTemplateTags(client, { templateID: templateId })
+ }
+
fromDebianImage(variant: string = 'stable'): TemplateBuilder {
return this.fromImage(`debian:${variant}`)
}
@@ -1265,6 +1291,7 @@ Template.exists = TemplateBase.exists
Template.aliasExists = TemplateBase.aliasExists
Template.assignTags = TemplateBase.assignTags
Template.removeTags = TemplateBase.removeTags
+Template.getTags = TemplateBase.getTags
Template.toJSON = TemplateBase.toJSON
Template.toDockerfile = TemplateBase.toDockerfile
@@ -1279,5 +1306,6 @@ export type {
TemplateBuildStatus,
TemplateBuildStatusResponse,
TemplateClass,
+ TemplateTag,
TemplateTagInfo,
} from './types'
diff --git a/packages/js-sdk/src/template/types.ts b/packages/js-sdk/src/template/types.ts
index 23999de7c..4b032b6ba 100644
--- a/packages/js-sdk/src/template/types.ts
+++ b/packages/js-sdk/src/template/types.ts
@@ -158,6 +158,24 @@ export type TemplateTagInfo = {
tags: string[]
}
+/**
+ * Detailed information about a single template tag.
+ */
+export type TemplateTag = {
+ /**
+ * Name of the tag.
+ */
+ tag: string
+ /**
+ * Build identifier associated with this tag.
+ */
+ buildId: string
+ /**
+ * When this tag was assigned.
+ */
+ createdAt: Date
+}
+
/**
* Types of instructions that can be used in a template.
*/
diff --git a/packages/js-sdk/tests/template/tags.test.ts b/packages/js-sdk/tests/template/tags.test.ts
index 76f862178..63de16040 100644
--- a/packages/js-sdk/tests/template/tags.test.ts
+++ b/packages/js-sdk/tests/template/tags.test.ts
@@ -18,6 +18,28 @@ const mockHandlers = [
tags: tags,
})
}),
+ // Get template tags endpoint
+ http.get(apiUrl('/templates/:templateID/tags'), ({ params }) => {
+ const { templateID } = params
+ if (templateID === 'nonexistent') {
+ return HttpResponse.json(
+ { message: 'Template not found' },
+ { status: 404 }
+ )
+ }
+ return HttpResponse.json([
+ {
+ tag: 'v1.0',
+ buildID: '00000000-0000-0000-0000-000000000000',
+ createdAt: '2024-01-15T10:30:00Z',
+ },
+ {
+ tag: 'latest',
+ buildID: '11111111-1111-1111-1111-111111111111',
+ createdAt: '2024-01-16T12:00:00Z',
+ },
+ ])
+ }),
// Bulk delete endpoint
http.delete(apiUrl('/templates/tags'), async ({ request }) => {
const { name } = (await request.clone().json()) as {
@@ -81,6 +103,23 @@ describe('Template tags unit tests', () => {
).rejects.toThrow()
})
})
+
+ describe('Template.getTags', () => {
+ test('returns tags for a template', async () => {
+ const tags = await Template.getTags('my-template-id')
+ expect(tags).toHaveLength(2)
+ expect(tags[0].tag).toBe('v1.0')
+ expect(tags[0].buildId).toBe('00000000-0000-0000-0000-000000000000')
+ expect(tags[0].createdAt).toBeInstanceOf(Date)
+ expect(tags[1].tag).toBe('latest')
+ expect(tags[1].buildId).toBe('11111111-1111-1111-1111-111111111111')
+ expect(tags[1].createdAt).toBeInstanceOf(Date)
+ })
+
+ test('handles 404 for nonexistent template', async () => {
+ await expect(Template.getTags('nonexistent')).rejects.toThrow()
+ })
+ })
})
// Integration tests
diff --git a/packages/python-sdk/e2b/__init__.py b/packages/python-sdk/e2b/__init__.py
index e290261e5..9fe172afa 100644
--- a/packages/python-sdk/e2b/__init__.py
+++ b/packages/python-sdk/e2b/__init__.py
@@ -104,6 +104,7 @@ from .template.types import (
CopyItem,
TemplateBuildStatus,
TemplateBuildStatusResponse,
+ TemplateTag,
TemplateTagInfo,
)
from .template_async.main import AsyncTemplate
@@ -179,6 +180,7 @@ __all__ = [
"BuildStatusReason",
"TemplateBuildStatus",
"TemplateBuildStatusResponse",
+ "TemplateTag",
"TemplateTagInfo",
"ReadyCmd",
"wait_for_file",
diff --git a/packages/python-sdk/e2b/template/types.py b/packages/python-sdk/e2b/template/types.py
index b1ed5c6d1..05b6307d4 100644
--- a/packages/python-sdk/e2b/template/types.py
+++ b/packages/python-sdk/e2b/template/types.py
@@ -1,4 +1,5 @@
from dataclasses import dataclass, field
+from datetime import datetime
from enum import Enum
from pathlib import Path
from typing import List, Literal, Optional, TypedDict, Union
@@ -73,6 +74,22 @@ class TemplateTagInfo:
"""Assigned tags of the template."""
+@dataclass
+class TemplateTag:
+ """
+ Detailed information about a single template tag.
+ """
+
+ tag: str
+ """Name of the tag."""
+
+ build_id: str
+ """Build identifier associated with this tag."""
+
+ created_at: datetime
+ """When this tag was assigned."""
+
+
class InstructionType(str, Enum):
"""
Types of instructions that can be used in a template.
diff --git a/packages/python-sdk/e2b/template_async/build_api.py b/packages/python-sdk/e2b/template_async/build_api.py
index b45937a84..7da04b1d8 100644
--- a/packages/python-sdk/e2b/template_async/build_api.py
+++ b/packages/python-sdk/e2b/template_async/build_api.py
@@ -15,6 +15,7 @@ from e2b.api.client.api.templates import (
from e2b.api.client.api.tags import (
post_templates_tags,
delete_templates_tags,
+ get_templates_template_id_tags,
)
from e2b.api.client.client import AuthenticatedClient
from e2b.api.client.models import (
@@ -33,6 +34,7 @@ from e2b.template.types import (
BuildStatusReason,
TemplateBuildStatus,
TemplateBuildStatusResponse,
+ TemplateTag,
TemplateTagInfo,
)
from e2b.template.utils import get_build_step_index, tar_file_stream
@@ -336,3 +338,37 @@ async def remove_tags(client: AuthenticatedClient, name: str, tags: List[str]) -
if res.status_code >= 300:
raise handle_api_exception(res, TemplateException)
+
+
+async def get_template_tags(
+ client: AuthenticatedClient, template_id: str
+) -> List[TemplateTag]:
+ """
+ Get all tags for a template.
+
+ Args:
+ client: Authenticated API client
+ template_id: Template ID or name
+ """
+ res = await get_templates_template_id_tags.asyncio_detailed(
+ template_id=template_id,
+ client=client,
+ )
+
+ if res.status_code >= 300:
+ raise handle_api_exception(res, TemplateException)
+
+ if isinstance(res.parsed, Error):
+ raise TemplateException(f"API error: {res.parsed.message}")
+
+ if res.parsed is None:
+ raise TemplateException("Failed to get template tags")
+
+ return [
+ TemplateTag(
+ tag=item.tag,
+ build_id=str(item.build_id),
+ created_at=item.created_at,
+ )
+ for item in res.parsed
+ ]
diff --git a/packages/python-sdk/e2b/template_async/main.py b/packages/python-sdk/e2b/template_async/main.py
index a459af2cc..b894ffb1f 100644
--- a/packages/python-sdk/e2b/template_async/main.py
+++ b/packages/python-sdk/e2b/template_async/main.py
@@ -8,12 +8,13 @@ from e2b.connection_config import ApiParams, ConnectionConfig
from e2b.template.consts import RESOLVE_SYMLINKS
from e2b.template.logger import LogEntry, LogEntryEnd, LogEntryStart
from e2b.template.main import TemplateBase, TemplateClass
-from e2b.template.types import BuildInfo, InstructionType, TemplateTagInfo
+from e2b.template.types import BuildInfo, InstructionType, TemplateTag, TemplateTagInfo
from e2b.template.utils import normalize_build_arguments, read_dockerignore
from .build_api import (
assign_tags,
check_alias_exists,
+ get_template_tags,
remove_tags,
get_build_status,
get_file_upload_link,
@@ -496,3 +497,32 @@ class AsyncTemplate(TemplateBase):
normalized_tags = [tags] if isinstance(tags, str) else tags
await remove_tags(api_client, name, normalized_tags)
+
+ @staticmethod
+ async def get_tags(
+ template_id: str,
+ **opts: Unpack[ApiParams],
+ ) -> List[TemplateTag]:
+ """
+ Get all tags for a template.
+
+ :param template_id: Template ID or name
+ :return: List of TemplateTag with tag name, build_id, and created_at
+
+ Example
+ ```python
+ from e2b import AsyncTemplate
+
+ tags = await AsyncTemplate.get_tags('my-template')
+ for tag in tags:
+ print(f"Tag: {tag.tag}, Build: {tag.build_id}, Created: {tag.created_at}")
+ ```
+ """
+ config = ConnectionConfig(**opts)
+ api_client = get_api_client(
+ config,
+ require_api_key=True,
+ require_access_token=False,
+ )
+
+ return await get_template_tags(api_client, template_id)
diff --git a/packages/python-sdk/e2b/template_sync/build_api.py b/packages/python-sdk/e2b/template_sync/build_api.py
index 87e10e95d..22f0be903 100644
--- a/packages/python-sdk/e2b/template_sync/build_api.py
+++ b/packages/python-sdk/e2b/template_sync/build_api.py
@@ -15,6 +15,7 @@ from e2b.api.client.api.templates import (
from e2b.api.client.api.tags import (
post_templates_tags,
delete_templates_tags,
+ get_templates_template_id_tags,
)
from e2b.api.client.client import AuthenticatedClient
from e2b.api.client.models import (
@@ -33,6 +34,7 @@ from e2b.template.types import (
BuildStatusReason,
TemplateBuildStatus,
TemplateBuildStatusResponse,
+ TemplateTag,
TemplateTagInfo,
)
from e2b.template.utils import get_build_step_index, tar_file_stream
@@ -333,3 +335,37 @@ def remove_tags(client: AuthenticatedClient, name: str, tags: List[str]) -> None
if res.status_code >= 300:
raise handle_api_exception(res, TemplateException)
+
+
+def get_template_tags(
+ client: AuthenticatedClient, template_id: str
+) -> List[TemplateTag]:
+ """
+ Get all tags for a template.
+
+ Args:
+ client: Authenticated API client
+ template_id: Template ID or name
+ """
+ res = get_templates_template_id_tags.sync_detailed(
+ template_id=template_id,
+ client=client,
+ )
+
+ if res.status_code >= 300:
+ raise handle_api_exception(res, TemplateException)
+
+ if isinstance(res.parsed, Error):
+ raise TemplateException(f"API error: {res.parsed.message}")
+
+ if res.parsed is None:
+ raise TemplateException("Failed to get template tags")
+
+ return [
+ TemplateTag(
+ tag=item.tag,
+ build_id=str(item.build_id),
+ created_at=item.created_at,
+ )
+ for item in res.parsed
+ ]
diff --git a/packages/python-sdk/e2b/template_sync/main.py b/packages/python-sdk/e2b/template_sync/main.py
index 1278e4d0c..075882178 100644
--- a/packages/python-sdk/e2b/template_sync/main.py
+++ b/packages/python-sdk/e2b/template_sync/main.py
@@ -10,10 +10,11 @@ from e2b.api.client_sync import get_api_client
from e2b.template.consts import RESOLVE_SYMLINKS
from e2b.template.logger import LogEntry, LogEntryEnd, LogEntryStart
from e2b.template.main import TemplateBase, TemplateClass
-from e2b.template.types import BuildInfo, InstructionType, TemplateTagInfo
+from e2b.template.types import BuildInfo, InstructionType, TemplateTag, TemplateTagInfo
from e2b.template_sync.build_api import (
assign_tags,
check_alias_exists,
+ get_template_tags,
remove_tags,
get_build_status,
get_file_upload_link,
@@ -497,3 +498,32 @@ class Template(TemplateBase):
normalized_tags = [tags] if isinstance(tags, str) else tags
remove_tags(api_client, name, normalized_tags)
+
+ @staticmethod
+ def get_tags(
+ template_id: str,
+ **opts: Unpack[ApiParams],
+ ) -> List[TemplateTag]:
+ """
+ Get all tags for a template.
+
+ :param template_id: Template ID or name
+ :return: List of TemplateTag with tag name, build_id, and created_at
+
+ Example
+ ```python
+ from e2b import Template
+
+ tags = Template.get_tags('my-template')
+ for tag in tags:
+ print(f"Tag: {tag.tag}, Build: {tag.build_id}, Created: {tag.created_at}")
+ ```
+ """
+ config = ConnectionConfig(**opts)
+ api_client = get_api_client(
+ config,
+ require_api_key=True,
+ require_access_token=False,
+ )
+
+ return get_template_tags(api_client, template_id)
diff --git a/packages/python-sdk/tests/async/template_async/test_tags.py b/packages/python-sdk/tests/async/template_async/test_tags.py
index a1faeb6ae..73eba0aaa 100644
--- a/packages/python-sdk/tests/async/template_async/test_tags.py
+++ b/packages/python-sdk/tests/async/template_async/test_tags.py
@@ -1,9 +1,10 @@
import uuid
+from datetime import datetime, timezone
from unittest.mock import AsyncMock
import pytest
-from e2b import AsyncTemplate, TemplateTagInfo, Template
+from e2b import AsyncTemplate, TemplateTag, TemplateTagInfo, Template
from e2b.exceptions import TemplateException
import e2b.template_async.main as template_async_main
@@ -115,6 +116,61 @@ class TestRemoveTags:
await AsyncTemplate.remove_tags("nonexistent", ["tag"])
+class TestGetTags:
+ """Tests for AsyncTemplate.get_tags method."""
+
+ @pytest.mark.asyncio
+ async def test_get_tags(self, monkeypatch):
+ """Test getting tags for a template."""
+ mock_get_template_tags = AsyncMock(
+ return_value=[
+ TemplateTag(
+ tag="v1.0",
+ build_id="00000000-0000-0000-0000-000000000000",
+ created_at=datetime(2024, 1, 15, 10, 30, 0, tzinfo=timezone.utc),
+ ),
+ TemplateTag(
+ tag="latest",
+ build_id="11111111-1111-1111-1111-111111111111",
+ created_at=datetime(2024, 1, 16, 12, 0, 0, tzinfo=timezone.utc),
+ ),
+ ]
+ )
+
+ monkeypatch.setattr(
+ template_async_main, "get_api_client", lambda *args, **kwargs: None
+ )
+ monkeypatch.setattr(
+ template_async_main, "get_template_tags", mock_get_template_tags
+ )
+
+ result = await AsyncTemplate.get_tags("my-template")
+
+ assert len(result) == 2
+ assert result[0].tag == "v1.0"
+ assert result[0].build_id == "00000000-0000-0000-0000-000000000000"
+ assert isinstance(result[0].created_at, datetime)
+ assert result[1].tag == "latest"
+ mock_get_template_tags.assert_called_once()
+
+ @pytest.mark.asyncio
+ async def test_get_tags_error(self, monkeypatch):
+ """Test that get_tags raises an error for nonexistent template."""
+ mock_get_template_tags = AsyncMock(
+ side_effect=TemplateException("Template not found")
+ )
+
+ monkeypatch.setattr(
+ template_async_main, "get_api_client", lambda *args, **kwargs: None
+ )
+ monkeypatch.setattr(
+ template_async_main, "get_template_tags", mock_get_template_tags
+ )
+
+ with pytest.raises(TemplateException):
+ await AsyncTemplate.get_tags("nonexistent")
+
+
# Integration tests
class TestTagsIntegration:
"""Integration tests for AsyncTemplate tags functionality."""
diff --git a/packages/python-sdk/tests/sync/template_sync/test_tags.py b/packages/python-sdk/tests/sync/template_sync/test_tags.py
index 063bb2dc3..9caaca397 100644
--- a/packages/python-sdk/tests/sync/template_sync/test_tags.py
+++ b/packages/python-sdk/tests/sync/template_sync/test_tags.py
@@ -1,9 +1,10 @@
import uuid
+from datetime import datetime, timezone
from unittest.mock import Mock
import pytest
-from e2b import TemplateTagInfo, Template
+from e2b import TemplateTag, TemplateTagInfo, Template
from e2b.exceptions import TemplateException
import e2b.template_sync.main as template_sync_main
@@ -106,6 +107,59 @@ class TestRemoveTags:
Template.remove_tags("nonexistent", ["tag"])
+class TestGetTags:
+ """Tests for Template.get_tags method."""
+
+ def test_get_tags(self, monkeypatch):
+ """Test getting tags for a template."""
+ mock_get_template_tags = Mock(
+ return_value=[
+ TemplateTag(
+ tag="v1.0",
+ build_id="00000000-0000-0000-0000-000000000000",
+ created_at=datetime(2024, 1, 15, 10, 30, 0, tzinfo=timezone.utc),
+ ),
+ TemplateTag(
+ tag="latest",
+ build_id="11111111-1111-1111-1111-111111111111",
+ created_at=datetime(2024, 1, 16, 12, 0, 0, tzinfo=timezone.utc),
+ ),
+ ]
+ )
+
+ monkeypatch.setattr(
+ template_sync_main, "get_api_client", lambda *args, **kwargs: None
+ )
+ monkeypatch.setattr(
+ template_sync_main, "get_template_tags", mock_get_template_tags
+ )
+
+ result = Template.get_tags("my-template")
+
+ assert len(result) == 2
+ assert result[0].tag == "v1.0"
+ assert result[0].build_id == "00000000-0000-0000-0000-000000000000"
+ assert isinstance(result[0].created_at, datetime)
+ assert result[1].tag == "latest"
+ mock_get_template_tags.assert_called_once()
+
+ def test_get_tags_error(self, monkeypatch):
+ """Test that get_tags raises an error for nonexistent template."""
+ mock_get_template_tags = Mock(
+ side_effect=TemplateException("Template not found")
+ )
+
+ monkeypatch.setattr(
+ template_sync_main, "get_api_client", lambda *args, **kwargs: None
+ )
+ monkeypatch.setattr(
+ template_sync_main, "get_template_tags", mock_get_template_tags
+ )
+
+ with pytest.raises(TemplateException):
+ Template.get_tags("nonexistent")
+
+
# Integration tests
class TestTagsIntegration:
"""Integration tests for Template tags functionality."""