block-style-cms-sdk 0.0.1__tar.gz

block_style_cms_sdk-0.0.1/.gitignore

@@ -0,0 +1,10 @@
+node_modules/
+dist/
+.venv/
+**/__pycache__/
+**/*.egg-info/
+.pytest_cache/
+.ruff_cache/
+*.pyc
+.DS_Store
+coverage/

block_style_cms_sdk-0.0.1/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.5
+Name: block-style-cms-sdk
+Version: 0.0.1
+Summary: Python SDK for Block Style CMS
+Author-email: Biscuit Zhou <biscuit_zhou@outlook.com>
+License: MIT
+Keywords: blocknote,cms,markdown,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT 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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# block-style-cms-sdk
+
+Python SDK for [Block Style CMS](https://github.com/Byte-Biscuit/block-style-cms).
+
+## Install
+
+```bash
+pip install block-style-cms-sdk
+# or: uv add block-style-cms-sdk
+```
+
+## Auth
+
+Create an API token in the CMS admin UI. Pass it when constructing the client:
+
+- Header: `x-api-key: <token>` (default), or
+- `Authorization: Bearer <token>`
+
+## Publish from Markdown
+
+1. Collect relative images from markdown (e.g. `./assets/foo.png`)
+2. Resolve files under the required `assetsDir`
+3. Upload via `POST /api/m/images`
+4. Rewrite paths to `/images/{filename}`
+5. Submit via `POST /api/m/articles/from-markdown`
+
+```python
+from block_style_cms_sdk import BlockStyleCmsClient
+
+client = BlockStyleCmsClient(
+    base_url="https://cms.example.com",
+    api_key="bsc_...",
+)
+
+client.articles.publish_from_markdown(
+    title="Hello",
+    slug="hello-article-slug",
+    summary="A short summary of at least ten chars",
+    tags=["demo"],
+    language="en-US",
+    md_file="./posts/hello.md",
+    assets_dir="./posts/assets",
+    published=False,
+)
+```
+
+## Content metadata
+
+Before publishing, discover site configuration:
+
+- `GET /api/m/locales` — supported article languages (`zh-CN`, `zh-TW`, `en-US`)
+- `GET /api/m/channels` — site channels from CMS settings
+
+```python
+locales = client.content.list_locales()
+channels = client.content.list_channels()
+```
+
+## Develop
+
+From `packages/python`:
+
+```bash
+uv sync --extra dev
+uv run ruff check .
+uv run ruff format .
+```
+
+Remote API check with the shared sample fixture ([`samples/`](../../samples/)):
+
+```bash
+cd packages/python
+BSC_BASE_URL=https://your-cms.example.com \
+BSC_API_KEY=bsc_... \
+uv run python tests/publish_sample_article.py
+```
+
+## Release
+
+1. Bump `version` in [`pyproject.toml`](pyproject.toml).
+2. Tag `py-vX.Y.Z`, push, and **Publish** a GitHub Release for that tag.
+3. GitHub Actions uploads to PyPI via [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC; no `PYPI_TOKEN` secret).
+
+Example: version `0.0.1` → tag `py-v0.0.1` → GitHub Release → PyPI.

block_style_cms_sdk-0.0.1/README.md

@@ -0,0 +1,84 @@
+# block-style-cms-sdk
+
+Python SDK for [Block Style CMS](https://github.com/Byte-Biscuit/block-style-cms).
+
+## Install
+
+```bash
+pip install block-style-cms-sdk
+# or: uv add block-style-cms-sdk
+```
+
+## Auth
+
+Create an API token in the CMS admin UI. Pass it when constructing the client:
+
+- Header: `x-api-key: <token>` (default), or
+- `Authorization: Bearer <token>`
+
+## Publish from Markdown
+
+1. Collect relative images from markdown (e.g. `./assets/foo.png`)
+2. Resolve files under the required `assetsDir`
+3. Upload via `POST /api/m/images`
+4. Rewrite paths to `/images/{filename}`
+5. Submit via `POST /api/m/articles/from-markdown`
+
+```python
+from block_style_cms_sdk import BlockStyleCmsClient
+
+client = BlockStyleCmsClient(
+    base_url="https://cms.example.com",
+    api_key="bsc_...",
+)
+
+client.articles.publish_from_markdown(
+    title="Hello",
+    slug="hello-article-slug",
+    summary="A short summary of at least ten chars",
+    tags=["demo"],
+    language="en-US",
+    md_file="./posts/hello.md",
+    assets_dir="./posts/assets",
+    published=False,
+)
+```
+
+## Content metadata
+
+Before publishing, discover site configuration:
+
+- `GET /api/m/locales` — supported article languages (`zh-CN`, `zh-TW`, `en-US`)
+- `GET /api/m/channels` — site channels from CMS settings
+
+```python
+locales = client.content.list_locales()
+channels = client.content.list_channels()
+```
+
+## Develop
+
+From `packages/python`:
+
+```bash
+uv sync --extra dev
+uv run ruff check .
+uv run ruff format .
+```
+
+Remote API check with the shared sample fixture ([`samples/`](../../samples/)):
+
+```bash
+cd packages/python
+BSC_BASE_URL=https://your-cms.example.com \
+BSC_API_KEY=bsc_... \
+uv run python tests/publish_sample_article.py
+```
+
+## Release
+
+1. Bump `version` in [`pyproject.toml`](pyproject.toml).
+2. Tag `py-vX.Y.Z`, push, and **Publish** a GitHub Release for that tag.
+3. GitHub Actions uploads to PyPI via [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC; no `PYPI_TOKEN` secret).
+
+Example: version `0.0.1` → tag `py-v0.0.1` → GitHub Release → PyPI.

block_style_cms_sdk-0.0.1/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "block-style-cms-sdk"
+version = "0.0.1"
+description = "Python SDK for Block Style CMS"
+authors=[
+  { name = "Biscuit Zhou", email = "biscuit_zhou@outlook.com" }
+]
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = ["cms", "blocknote", "markdown", "sdk"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27",
+  "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "ruff>=0.9",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/block_style_cms_sdk"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.ruff.format]
+quote-style = "double"

block_style_cms_sdk-0.0.1/src/block_style_cms_sdk/__init__.py

@@ -0,0 +1,25 @@
+"""Block Style CMS Python SDK."""
+
+from .client import ApiError, BlockStyleCmsClient, HttpClient
+from .markdown.images import (
+    collect_relative_image_srcs,
+    is_relative_image_src,
+    is_skippable_image_src,
+    rewrite_all_image_srcs,
+    rewrite_image_src,
+)
+from .resources.articles import MissingAssetsError
+
+__all__ = [
+    "ApiError",
+    "BlockStyleCmsClient",
+    "HttpClient",
+    "MissingAssetsError",
+    "collect_relative_image_srcs",
+    "is_relative_image_src",
+    "is_skippable_image_src",
+    "rewrite_all_image_srcs",
+    "rewrite_image_src",
+]
+
+__version__ = "0.1.0"

block_style_cms_sdk-0.0.1/src/block_style_cms_sdk/client.py

@@ -0,0 +1,248 @@
+from __future__ import annotations
+
+import logging
+import time
+from pathlib import Path
+from typing import Any, Literal
+
+import httpx
+
+from .models import (
+    ApiResult,
+    FromMarkdownPayload,
+    FromMarkdownRequest,
+    ImageMetaInfo,
+    ImageUploadOptions,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class ApiError(Exception):
+    def __init__(self, message: str, code: int, payload: Any = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.payload = payload if payload is not None else {}
+
+
+class HttpClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        auth_style: Literal["api-key", "bearer"] = "api-key",
+        max_retries: int = 2,
+        timeout: float = 60.0,
+    ) -> None:
+        if not base_url or not base_url.strip():
+            raise ValueError("base_url is required")
+        if not api_key or not api_key.strip():
+            raise ValueError("api_key is required")
+        self.base_url = base_url.strip().rstrip("/")
+        self.api_key = api_key.strip()
+        self.auth_style = auth_style
+        self.max_retries = max_retries
+        self._client = httpx.Client(timeout=timeout)
+        logger.debug(
+            "HttpClient base_url=%s auth_style=%s max_retries=%d timeout=%s",
+            self.base_url,
+            auth_style,
+            max_retries,
+            timeout,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> HttpClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def _auth_headers(self) -> dict[str, str]:
+        if self.auth_style == "bearer":
+            return {"Authorization": f"Bearer {self.api_key}"}
+        return {"x-api-key": self.api_key}
+
+    def request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+        files: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> ApiResult:
+        url = f"{self.base_url}{path if path.startswith('/') else '/' + path}"
+        hdrs = {**self._auth_headers(), **(headers or {})}
+        last_error: Exception | None = None
+        attempts = self.max_retries + 1
+
+        for attempt in range(attempts):
+            logger.debug("%s %s (attempt %d/%d)", method, url, attempt + 1, attempts)
+            try:
+                res = self._client.request(
+                    method,
+                    url,
+                    json=json,
+                    data=data,
+                    files=files,
+                    headers=hdrs,
+                )
+                body = res.json()
+                result = ApiResult.model_validate(body)
+                if res.status_code >= 500 or result.code >= 500:
+                    if attempt < self.max_retries:
+                        logger.warning(
+                            "server error %s %s: HTTP %s code=%s "
+                            "(attempt %d), retrying",
+                            method,
+                            url,
+                            res.status_code,
+                            result.code,
+                            attempt + 1,
+                        )
+                        time.sleep(0.2 * (attempt + 1))
+                        continue
+                if not res.is_success or result.code != 200:
+                    logger.error(
+                        "API error %s %s: HTTP %s code=%s message=%s",
+                        method,
+                        url,
+                        res.status_code,
+                        result.code,
+                        result.message,
+                    )
+                    raise ApiError(
+                        result.message or f"HTTP {res.status_code}",
+                        result.code or res.status_code,
+                        result.payload,
+                    )
+                logger.debug(
+                    "%s %s -> HTTP %s code=%s message=%s",
+                    method,
+                    url,
+                    res.status_code,
+                    result.code,
+                    result.message,
+                )
+                return result
+            except ApiError:
+                raise
+            except Exception as err:  # noqa: BLE001 — retry network blips
+                last_error = err
+                if attempt < self.max_retries:
+                    logger.warning(
+                        "request failed %s %s (attempt %d/%d): %s",
+                        method,
+                        url,
+                        attempt + 1,
+                        attempts,
+                        err,
+                    )
+                    time.sleep(0.2 * (attempt + 1))
+                    continue
+                logger.error(
+                    "request failed %s %s after %d attempts: %s",
+                    method,
+                    url,
+                    attempts,
+                    err,
+                )
+                raise
+        assert last_error is not None
+        raise last_error
+
+    def upload_image(
+        self,
+        file_bytes: bytes,
+        filename: str,
+        options: ImageUploadOptions | None = None,
+    ) -> ImageMetaInfo:
+        logger.info("uploading image %s (%d bytes)", filename, len(file_bytes))
+        files = {"file": (filename, file_bytes)}
+        data = None
+        if options is not None:
+            data = {
+                "options": options.model_dump_json(exclude_none=True),
+            }
+        result = self.request_json(
+            "POST",
+            "/api/m/images",
+            data=data,
+            files=files,
+        )
+        meta = ImageMetaInfo.model_validate(result.payload)
+        logger.info("uploaded image %s -> /images/%s", filename, meta.filename)
+        return meta
+
+    def upload_image_file(
+        self,
+        file_path: str | Path,
+        options: ImageUploadOptions | None = None,
+    ) -> ImageMetaInfo:
+        path = Path(file_path)
+        logger.debug("reading image file %s", path)
+        return self.upload_image(path.read_bytes(), path.name, options)
+
+    def create_article_from_markdown(
+        self, body: FromMarkdownRequest
+    ) -> FromMarkdownPayload:
+        logger.info(
+            "creating article from markdown slug=%s language=%s published=%s",
+            body.slug,
+            body.language,
+            body.published,
+        )
+        payload = body.model_dump(by_alias=True, exclude_none=True)
+        result = self.request_json(
+            "POST",
+            "/api/m/articles/from-markdown",
+            json=payload,
+        )
+        article = FromMarkdownPayload.model_validate(result.payload)
+        logger.info(
+            "created article id=%s slug=%s locale=%s",
+            article.id,
+            article.slug,
+            article.locale,
+        )
+        return article
+
+
+class BlockStyleCmsClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        auth_style: Literal["api-key", "bearer"] = "api-key",
+        max_retries: int = 2,
+        timeout: float = 60.0,
+    ) -> None:
+        from .resources.articles import ArticlesResource
+        from .resources.content import ContentResource
+        from .resources.media import MediaResource
+
+        self.http = HttpClient(
+            base_url=base_url,
+            api_key=api_key,
+            auth_style=auth_style,
+            max_retries=max_retries,
+            timeout=timeout,
+        )
+        self.media = MediaResource(self.http)
+        self.articles = ArticlesResource(self.http)
+        self.content = ContentResource(self.http)
+
+    def close(self) -> None:
+        self.http.close()
+
+    def __enter__(self) -> BlockStyleCmsClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()

block_style_cms_sdk-0.0.1/src/block_style_cms_sdk/markdown/__init__.py

@@ -0,0 +1 @@
+"""Markdown image helpers."""

block_style_cms_sdk-0.0.1/src/block_style_cms_sdk/markdown/images.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+_MD_IMAGE_RE = re.compile(r"!\[([^\]]*)\]\(([^)\s]+)(?:\s+\"[^\"]*\")?\)")
+_HTML_IMG_RE = re.compile(r"<img\b[^>]*\bsrc=[\"']([^\"']+)[\"'][^>]*>", re.I)
+
+
+def is_skippable_image_src(src: str) -> bool:
+    s = src.strip()
+    if not s:
+        return False
+    if s.startswith("/images/"):
+        return True
+    if re.match(r"^https?://", s, re.I):
+        return True
+    return False
+
+
+def is_relative_image_src(src: str) -> bool:
+    s = src.strip()
+    if not s:
+        return True
+    if is_skippable_image_src(s):
+        return False
+    if s.startswith("/"):
+        return False
+    return True
+
+
+def collect_relative_image_srcs(md: str) -> list[str]:
+    found: set[str] = set()
+    for match in _MD_IMAGE_RE.finditer(md):
+        src = match.group(2).strip()
+        if is_relative_image_src(src):
+            found.add(src)
+    for match in _HTML_IMG_RE.finditer(md):
+        src = match.group(1).strip()
+        if is_relative_image_src(src):
+            found.add(src)
+    return sorted(found)
+
+
+def resolve_image_path(assets_dir: str | Path, src: str) -> Path:
+    cleaned = src[2:] if src.startswith("./") else src
+    under_assets = cleaned[7:] if cleaned.startswith("assets/") else cleaned
+    return (Path(assets_dir) / under_assets).resolve()
+
+
+def rewrite_image_src(md: str, from_src: str, to_src: str) -> str:
+    escaped = re.escape(from_src)
+    md_re = re.compile(rf"(!\[[^\]]*\]\(){escaped}((?:\s+\"[^\"]*\")?\))")
+    out = md_re.sub(rf"\g<1>{to_src}\g<2>", md)
+    html_re = re.compile(
+        rf"(<img\b[^>]*\bsrc=[\"']){escaped}([\"'])",
+        re.I,
+    )
+    return html_re.sub(rf"\g<1>{to_src}\g<2>", out)
+
+
+def rewrite_all_image_srcs(md: str, mapping: dict[str, str]) -> str:
+    out = md
+    for from_src, to_src in mapping.items():
+        out = rewrite_image_src(out, from_src, to_src)
+    return out

block_style_cms_sdk-0.0.1/src/block_style_cms_sdk/models.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+Locale = Literal["zh-CN", "zh-TW", "en-US"]
+
+
+class ApiResult(BaseModel):
+    code: int
+    message: str
+    payload: Any = Field(default_factory=dict)
+    tt: float | None = None
+
+
+class ImageUploadOptions(BaseModel):
+    quality: int | None = None
+    maxWidth: int | None = None
+    maxHeight: int | None = None
+    enableWebP: bool | None = None
+
+
+class ImageMetaInfo(BaseModel):
+    filename: str
+    originalName: str
+    size: int
+    width: int
+    height: int
+    mimeType: str
+    uploadedAt: str
+    fullUrl: str | None = None
+    title: str | None = None
+    description: str | None = None
+    tags: list[str] | None = None
+    altText: str | None = None
+
+
+class FromMarkdownRequest(BaseModel):
+    title: str
+    slug: str
+    language: Locale
+    summary: str = ""
+    tags: list[str] = Field(default_factory=list)
+    keywords: list[str] = Field(default_factory=list)
+    mdContent: str | None = None
+    cover: str = ""
+    published: bool = False
+    locale_param: str | None = Field(default=None, alias="__locale__")
+
+    model_config = {"populate_by_name": True}
+
+
+class FromMarkdownPayload(BaseModel):
+    id: str
+    slug: str
+    locale: Locale
+
+
+ChannelItemType = Literal["tag", "page"]
+
+
+class ChannelItem(BaseModel):
+    id: str
+    type: ChannelItemType
+    href: str
+    tag: str | None = None
+    icon: str | None = None
+
+
+class LocaleInfo(BaseModel):
+    code: Locale
+    name: str
+    nativeName: str
+    englishName: str
+    flag: str

block_style_cms_sdk-0.0.1/src/block_style_cms_sdk/resources/__init__.py

@@ -0,0 +1 @@
+"""API resource modules."""