devrev-Python-SDK 2.12.2__tar.gz → 2.13.0__tar.gz

{devrev_python_sdk-2.12.2 → devrev_python_sdk-2.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devrev-Python-SDK
-Version: 2.12.2
+Version: 2.13.0
 Summary: A modern, type-safe Python SDK for the DevRev API
 Project-URL: Homepage, https://github.com/mgmonteleone/py-dev-rev
 Project-URL: Documentation, https://github.com/mgmonteleone/py-dev-rev

{devrev_python_sdk-2.12.2 → devrev_python_sdk-2.13.0}/docs/changelog.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.13.0] - 2026-04-08
+
+### Added
+
+- **Article content format detection and bidirectional conversion** (#160, PR #205)
+  - `detect_content_format()` — detects `devrev/rt`, `text/markdown`, `text/html`, or `text/plain`
+  - `devrev_rt_to_markdown()` — converts ProseMirror JSON to Markdown
+  - `devrev_rt_to_html()` — converts ProseMirror JSON to HTML with XSS-safe escaping
+  - `OutputFormat` type alias (`Literal["text/markdown", "text/html", "devrev/rt"]`)
+  - Four format constants: `CONTENT_FORMAT_DEVREV_RT`, `CONTENT_FORMAT_MARKDOWN`, `CONTENT_FORMAT_HTML`, `CONTENT_FORMAT_PLAIN`
+  - `get_with_content()` (sync + async) now accepts optional `output_format` parameter for automatic content conversion
+  - MCP tool `devrev_articles_get` accepts `output_format` when `include_content=True`
+  - `_convert_content()` validates output format and raises `ValueError` for invalid values
+  - All HTML output uses `html.escape()` for text and attributes; links include `rel="noopener noreferrer"`
+
 ## [2.12.2] - 2026-04-08
 
 ### Maintenance

{devrev_python_sdk-2.12.2 → devrev_python_sdk-2.13.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "devrev-Python-SDK"
-version = "2.12.2"
+version = "2.13.0"
 description = "A modern, type-safe Python SDK for the DevRev API"
 readme = "README.md"
 requires-python = ">=3.11"

{devrev_python_sdk-2.12.2 → devrev_python_sdk-2.13.0}/src/devrev/services/articles.py

@@ -35,15 +35,16 @@ from devrev.models.artifacts import (
 )
 from devrev.models.base import SetTagWithValue
 from devrev.services.base import AsyncBaseService, BaseService
-from devrev.utils.content_converter import html_to_devrev_rt
-
-# Content format to file extension mapping
-_CONTENT_FORMAT_EXTENSIONS: dict[str, str] = {
-    "text/html": ".html",
-    "text/markdown": ".md",
-    "text/plain": ".txt",
-    "devrev/rt": "",  # DevRev rich text uses no extension (file name "Article")
-}
+from devrev.utils.content_converter import (
+    CONTENT_FORMAT_DEVREV_RT,
+    CONTENT_FORMAT_HTML,
+    CONTENT_FORMAT_MARKDOWN,
+    OutputFormat,
+    detect_content_format,
+    devrev_rt_to_html,
+    devrev_rt_to_markdown,
+    html_to_devrev_rt,
+)
 
 
 def _extract_content_artifact_id(resource: dict[str, object]) -> str | None:
@@ -101,6 +102,69 @@ def _extract_content_format(resource: dict[str, object]) -> str:
     return "text/plain"
 
 
+def _convert_content(
+    content: str,
+    source_format: str,
+    target_format: str,
+) -> tuple[str, str]:
+    """Convert article content between formats.
+
+    Args:
+        content: The raw content string.
+        source_format: The MIME type of *content* (e.g. ``"devrev/rt"``).
+        target_format: The desired output MIME type.
+
+    Returns:
+        A ``(converted_content, actual_format)`` tuple.  If no conversion
+        is necessary (source == target, or conversion is not possible)
+        the original content and format are returned.
+    Raises:
+        ValueError: If *target_format* is not a recognised format.
+    """
+    _VALID_FORMATS = {
+        CONTENT_FORMAT_MARKDOWN,
+        CONTENT_FORMAT_HTML,
+        CONTENT_FORMAT_DEVREV_RT,
+    }
+    if target_format not in _VALID_FORMATS:
+        raise ValueError(
+            f"Invalid output_format {target_format!r}. Accepted values: {sorted(_VALID_FORMATS)}"
+        )
+
+    if source_format == target_format:
+        return content, source_format
+
+    # Auto-detect source format when unknown / generic
+    if source_format in ("text/plain", ""):
+        source_format = detect_content_format(content)
+
+    if target_format == CONTENT_FORMAT_MARKDOWN:
+        if source_format == CONTENT_FORMAT_DEVREV_RT:
+            return devrev_rt_to_markdown(content), CONTENT_FORMAT_MARKDOWN
+        # HTML or unknown → convert to devrev/rt first, then to markdown
+        if source_format == CONTENT_FORMAT_HTML:
+            rt = html_to_devrev_rt(content)
+            return devrev_rt_to_markdown(rt), CONTENT_FORMAT_MARKDOWN
+        # Already markdown or plain text
+        return content, source_format
+
+    if target_format == CONTENT_FORMAT_HTML:
+        if source_format == CONTENT_FORMAT_DEVREV_RT:
+            return devrev_rt_to_html(content), CONTENT_FORMAT_HTML
+        if source_format == CONTENT_FORMAT_MARKDOWN:
+            rt = html_to_devrev_rt(content)
+            return devrev_rt_to_html(rt), CONTENT_FORMAT_HTML
+        return content, source_format
+
+    if target_format == CONTENT_FORMAT_DEVREV_RT:
+        if source_format != CONTENT_FORMAT_DEVREV_RT:
+            return html_to_devrev_rt(content), CONTENT_FORMAT_DEVREV_RT
+        return content, source_format
+
+    # Unknown target format – return unchanged
+    return content, source_format
+
+
 class ArticlesService(BaseService):
     """Service for managing DevRev Articles."""
 
@@ -313,17 +377,27 @@ class ArticlesService(BaseService):
             # Re-raise the original error
             raise DevRevError(f"Failed to create article with content: {e}") from e
 
-    def get_with_content(self, id: str) -> ArticleWithContent:
+    def get_with_content(
+        self,
+        id: str,
+        *,
+        output_format: OutputFormat | None = None,
+    ) -> ArticleWithContent:
         """Get an article with its content loaded.
 
         This is a high-level method that:
         1. Fetches article metadata
         2. Locates the content artifact
         3. Downloads artifact content
-        4. Returns combined model
+        4. Optionally converts to the requested output format
+        5. Returns combined model
 
         Args:
             id: Article ID
+            output_format: Desired output format for the content.  Accepted
+                values: ``"text/markdown"``, ``"text/html"``, ``"devrev/rt"``.
+                When ``None`` (the default) the raw stored content is returned
+                as-is.
 
         Returns:
             ArticleWithContent with metadata and content
@@ -336,6 +410,9 @@ class ArticlesService(BaseService):
             >>> article_with_content = client.articles.get_with_content("ART-123")
             >>> print(article_with_content.article.title)
             >>> print(article_with_content.content)
+            >>> # Get content as Markdown
+            >>> md = client.articles.get_with_content("ART-123", output_format="text/markdown")
+            >>> print(md.content)
         """
         if not self._parent_client:
             raise DevRevError(
@@ -364,12 +441,18 @@ class ArticlesService(BaseService):
             # Get content format from resource metadata (more reliable than artifact.get)
             content_format = _extract_content_format(article.resource)
 
+            # Step 4: Convert to requested output format if specified
+            if output_format is not None:
+                content, content_format = _convert_content(content, content_format, output_format)
+
             return ArticleWithContent(
                 article=article,
                 content=content,
                 content_format=content_format,
                 content_version=None,
             )
+        except DevRevError:
+            raise
         except Exception as e:
             raise DevRevError(f"Failed to download content for article {id}: {e}") from e
 
@@ -772,17 +855,27 @@ class AsyncArticlesService(AsyncBaseService):
             # Re-raise the original error
             raise DevRevError(f"Failed to create article with content: {e}") from e
 
-    async def get_with_content(self, id: str) -> ArticleWithContent:
+    async def get_with_content(
+        self,
+        id: str,
+        *,
+        output_format: OutputFormat | None = None,
+    ) -> ArticleWithContent:
         """Get an article with its content loaded (async).
 
         This is a high-level method that:
         1. Fetches article metadata
         2. Locates the content artifact
         3. Downloads artifact content
-        4. Returns combined model
+        4. Optionally converts to the requested output format
+        5. Returns combined model
 
         Args:
             id: Article ID
+            output_format: Desired output format for the content.  Accepted
+                values: ``"text/markdown"``, ``"text/html"``, ``"devrev/rt"``.
+                When ``None`` (the default) the raw stored content is returned
+                as-is.
 
         Returns:
             ArticleWithContent with metadata and content
@@ -818,12 +911,18 @@ class AsyncArticlesService(AsyncBaseService):
             # Get content format from resource metadata (more reliable than artifact.get)
             content_format = _extract_content_format(article.resource)
 
+            # Step 4: Convert to requested output format if specified
+            if output_format is not None:
+                content, content_format = _convert_content(content, content_format, output_format)
+
             return ArticleWithContent(
                 article=article,
                 content=content,
                 content_format=content_format,
                 content_version=None,
             )
+        except DevRevError:
+            raise
         except Exception as e:
             raise DevRevError(f"Failed to download content for article {id}: {e}") from e
 

devrev_python_sdk-2.13.0/src/devrev/utils/__init__.py

@@ -0,0 +1,34 @@
+"""DevRev SDK Utilities.
+
+This module contains utility functions and classes used throughout the SDK.
+"""
+
+from devrev.utils.content_converter import (
+    CONTENT_FORMAT_DEVREV_RT,
+    CONTENT_FORMAT_HTML,
+    CONTENT_FORMAT_MARKDOWN,
+    CONTENT_FORMAT_PLAIN,
+    OutputFormat,
+    detect_content_format,
+    devrev_rt_to_html,
+    devrev_rt_to_markdown,
+    html_to_devrev_rt,
+)
+from devrev.utils.deprecation import deprecated
+from devrev.utils.logging import ColoredFormatter, configure_logging, get_logger
+
+__all__ = [
+    "CONTENT_FORMAT_DEVREV_RT",
+    "CONTENT_FORMAT_HTML",
+    "CONTENT_FORMAT_MARKDOWN",
+    "CONTENT_FORMAT_PLAIN",
+    "OutputFormat",
+    "ColoredFormatter",
+    "configure_logging",
+    "deprecated",
+    "detect_content_format",
+    "devrev_rt_to_html",
+    "devrev_rt_to_markdown",
+    "get_logger",
+    "html_to_devrev_rt",
+]