Merge pull request #6 from comfuture/PEP-0727

Implement PEP-0727 Doc in Annotation metadata

Author: comfuture

function_schema/core.py

@@ -12,6 +12,50 @@
 else:
     UnionType = typing.Union  # type: ignore
 
+try:
+    from typing import Doc
+except ImportError:
+    try:
+        from typing_extensions import Doc
+    except ImportError:
+        class Doc:
+            def __init__(self, documentation: str, /):
+                self.documentation = documentation
+
+__all__ = ("get_function_schema", "guess_type", "Doc")
+
+def is_doc_meta(obj):
+    """
+    Check if the given object is a documentation object.
+    Parameters:
+        obj (object): The object to be checked.
+    Returns:
+        bool: True if the object is a documentation object, False otherwise.
+
+    Example:
+    >>> is_doc_meta(Doc("This is a documentation object"))
+    True
+    """
+    return getattr(obj, '__class__') == Doc and hasattr(obj, 'documentation')
+
+def unwrap_doc(obj: typing.Union[Doc, str]):
+    """
+    Get the documentation string from the given object.
+    Parameters:
+        obj (Doc | str): The object to get the documentation string from.
+    Returns:
+        str: The documentation string.
+
+    Example:
+    >>> unwrap_doc(Doc("This is a documentation object"))
+    'This is a documentation object'
+    >>> unwrap_doc("This is a documentation string")
+    'This is a documentation string'
+    """
+    if is_doc_meta(obj):
+        return obj.documentation
+    return str(obj)
+
 
 def get_function_schema(
     func: typing.Annotated[typing.Callable, "The function to get the schema for"],
@@ -83,7 +127,7 @@ def get_function_schema(
 
             # find description in param_args tuple
             description = next(
-                (arg for arg in param_args if isinstance(arg, str)),
+                (unwrap_doc(arg) for arg in param_args if isinstance(arg, (Doc, str))),
                 f"The {name} parameter",
             )
 

pyproject.toml

@@ -17,9 +17,6 @@ classifiers = [
   "Programming Language :: Python :: 3.9",
 ]
 
-[project.optional-dependencies]
-test = ["pytest"]
-
 [project.urls]
 Homepage = "https://github.com/comfuture/function-schema"
 Repository = "https://github.com/comfuture/function-schema"
@@ -30,3 +27,9 @@ function_schema = "function_schema.cli:main"
 [build-system]
 requires = ["flit_core >=3.9,<4"]
 build-backend = "flit_core.buildapi"
+
+[tool.uv]
+dev-dependencies = [
+    "pytest>=8.3.2",
+    "typing-extensions>=4.12.2",
+]

test/test_pep_0727_doc.py

@@ -0,0 +1,33 @@
+from typing import Annotated
+from enum import Enum
+from function_schema.core import get_function_schema, Doc
+
+
+def test_docs_in_annotation():
+    """Test a function with annotations with Doc"""
+    def func1(a: Annotated[int, Doc("An integer parameter")]):
+        """My function"""
+        ...
+
+    schema = get_function_schema(func1)
+    assert schema["name"] == "func1", "Function name should be func1"
+    assert schema["description"] == "My function", "Function description should be there"
+    assert schema["parameters"]["properties"]["a"]["type"] == "number", "parameter a should be an integer"
+    assert schema["parameters"]["properties"]["a"]["description"] == "An integer parameter", "parameter a should have a description"
+    assert schema["parameters"]["required"] == [
+        "a"], "parameter a should be required"
+
+
+def test_doc_in_nth_args():
+    """Test a function with annotations with Doc in nth args"""
+    def func1(a: Annotated[str, Enum("Candidates", "a b c"), Doc("A string parameter")]):
+        """My function"""
+        ...
+
+    schema = get_function_schema(func1)
+    assert schema["name"] == "func1", "Function name should be func1"
+    assert schema["description"] == "My function", "Function description should be there"
+    assert schema["parameters"]["properties"]["a"]["type"] == "string", "parameter a should be an string"
+    assert schema["parameters"]["properties"]["a"]["description"] == "A string parameter", "parameter a should have a description"
+    assert schema["parameters"]["properties"]["a"]["enum"] == [
+        "a", "b", "c"], "parameter a should have enum values"