Add documentation.

Author: elprans

.flake8

@@ -2,4 +2,4 @@
 ignore = E402,E731
 exclude =
     .git, __pycache__, build, dist, .eggs, .github, .local,
-    Samples, azure/worker/protos/
+    Samples, azure/worker/protos/, docs/

azure/__init__.py renamed to azure/__init__.pyi

@@ -8,62 +8,80 @@
 
 
 class Out(abc.ABC, typing.Generic[T]):
+    """An interface to set function output parameters."""
 
     @abc.abstractmethod
     def set(self, val: T) -> None:
+        """Set the value of the output parameter."""
         pass
 
     @abc.abstractmethod
     def get(self) -> T:
+        """Get the value of the output parameter."""
         pass
 
 
 class Context(abc.ABC):
+    """Function invocation context."""
 
     @property
     @abc.abstractmethod
     def invocation_id(self) -> str:
+        """Function invocation ID."""
         pass
 
     @property
     @abc.abstractmethod
     def function_name(self) -> str:
+        """Function name."""
         pass
 
     @property
     @abc.abstractmethod
     def function_directory(self) -> str:
+        """Function directory."""
         pass
 
 
 class HttpRequest(abc.ABC):
+    """HTTP request object."""
 
     @property
     @abc.abstractmethod
     def method(self) -> str:
+        """Request method."""
         pass
 
     @property
     @abc.abstractmethod
     def url(self) -> str:
+        """Request URL."""
         pass
 
     @property
     @abc.abstractmethod
     def headers(self) -> typing.Mapping[str, str]:
+        """A dictionary containing request headers."""
         pass
 
     @property
     @abc.abstractmethod
     def params(self) -> typing.Mapping[str, str]:
+        """A dictionary containing request GET parameters."""
         pass
 
     @abc.abstractmethod
     def get_body(self) -> bytes:
+        """Return request body as bytes."""
         pass
 
     @abc.abstractmethod
     def get_json(self) -> typing.Any:
+        """Decode and return request body as JSON.
+
+        :raises ValueError:
+            when the request does not contain valid JSON data.
+        """
         pass
 
 
@@ -95,17 +113,30 @@ def get_body(self) -> bytes:
 
 
 class TimerRequest(abc.ABC):
+    """Timer request object."""
 
     @property
     @abc.abstractmethod
     def past_due(self) -> bool:
+        """Whether the timer is past due."""
         pass
 
 
 class InputStream(io.BufferedIOBase, abc.ABC):
+    """File-like object representing an input blob."""
 
     @abc.abstractmethod
     def read(self, size=-1) -> bytes:
+        """Return and read up to *size* bytes.
+
+        :param int size:
+            The number of bytes to read.  If the argument is omitted,
+            ``None``, or negative, data is read and returned until
+            EOF is reached.
+
+        :return:
+            Bytes read from the input stream.
+        """
         pass
 
 

azure/functions/_abc.py

@@ -40,7 +40,25 @@ def __delitem__(self, key: str):
 
 
 class HttpResponse(_abc.HttpResponse):
-    """An HTTP response object."""
+    """An HTTP response object.
+
+    :param str/bytes body:
+        Optional response body.
+
+    :param int status_code:
+        Response status code.  If not specified, defaults to 200.
+
+    :param dict headers:
+        An optional mapping containing response HTTP headers.
+
+    :param str mimetype:
+        An optional response MIME type.  If not specified, defaults to
+        ``'text/plain'``.
+
+    :param str charset:
+        Response content text encoding.  If not specified, defaults to
+        ``'utf-8'``.
+    """
 
     def __init__(self, body=None, *,
                  status_code=None, headers=None, mimetype=None, charset=None):
@@ -67,18 +85,22 @@ def __init__(self, body=None, *,
 
     @property
     def mimetype(self):
+        """Response MIME type."""
         return self.__mimetype
 
     @property
     def charset(self):
+        """Response text encoding."""
         return self.__charset
 
     @property
     def headers(self):
+        """A dictionary of response HTTP headers."""
         return self.__headers
 
     @property
     def status_code(self):
+        """Response status code."""
         return self.__status_code
 
     def __set_body(self, body):
@@ -93,4 +115,5 @@ def __set_body(self, body):
         self.__body = bytes(body)
 
     def get_body(self) -> bytes:
+        """Response body as a bytes object."""
         return self.__body

azure/functions/_http.py

@@ -6,7 +6,17 @@
 
 
 class QueueMessage(_abc.QueueMessage):
-    """An HTTP response object."""
+    """A Queue message object.
+
+    :param str id:
+        An optional string specifying the ID of the message.
+
+    :param body:
+        A string or bytes instance specifying the message body.
+
+    :param str pop_receipt:
+        An optional string containing the pop receipt token.
+    """
 
     def __init__(self, *,
                  id: typing.Optional[str]=None,
@@ -21,26 +31,32 @@ def __init__(self, *,
 
     @property
     def id(self) -> typing.Optional[str]:
+        """Message ID."""
         return self.__id
 
     @property
     def dequeue_count(self) -> typing.Optional[int]:
+        """The number of times this message has been dequeued."""
         return None
 
     @property
     def expiration_time(self) -> typing.Optional[datetime.datetime]:
+        """A datetime object with the message expiry time."""
         return None
 
     @property
     def insertion_time(self) -> typing.Optional[datetime.datetime]:
+        """A datetime object with the message queue insertion time."""
         return None
 
     @property
     def next_visible_time(self) -> typing.Optional[datetime.datetime]:
+        """A datetime object with the time the message will be visible next."""
         return None
 
     @property
     def pop_receipt(self) -> typing.Optional[str]:
+        """The message pop receipt token as a string."""
         return self.__pop_receipt
 
     def __set_body(self, body):
@@ -55,9 +71,18 @@ def __set_body(self, body):
         self.__body = bytes(body)
 
     def get_body(self) -> bytes:
+        """Return message content as bytes."""
         return self.__body
 
     def get_json(self) -> typing.Any:
+        """Decode and return message content as a JSON object.
+
+        :return:
+            Decoded JSON data.
+
+        :raises ValueError:
+            when the body of the message does not contain valid JSON data.
+        """
         return json.loads(self.__body)
 
     def __repr__(self) -> str:

azure/functions/_queue.py

@@ -0,0 +1,2 @@
+_build
+_templates

docs/.gitignore

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = AzureFunctionsforPython
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/Makefile

@@ -0,0 +1,65 @@
+.. _azure-functions-reference:
+
+=============
+API Reference
+=============
+
+.. module:: azure.functions
+    :synopsis: Azure Functions bindings.
+
+.. currentmodule:: azure.functions
+
+
+.. _azure-functions-bindings-blob:
+
+Blob Bindings
+=============
+
+.. autoclass:: azure.functions.InputStream
+   :members:
+
+
+.. _azure-functions-bindings-http:
+
+HTTP Bindings
+=============
+
+.. autoclass:: azure.functions.HttpRequest
+   :members:
+
+.. autoclass:: azure.functions.HttpResponse
+   :members:
+
+
+.. _azure-functions-bindings-queue:
+
+Queue Bindings
+==============
+
+.. autoclass:: azure.functions.QueueMessage
+   :members:
+
+
+.. _azure-functions-bindings-timer:
+
+Timer Bindings
+==============
+
+.. autoclass:: azure.functions.TimerRequest
+   :members:
+
+
+.. _azure-functions-bindings-context:
+
+Function Context
+================
+
+.. autoclass:: azure.functions.Context
+   :members:
+
+
+Out Parameters
+==============
+
+.. autoclass:: azure.functions.Out
+   :members: