Skip to content

Commit

Permalink
docs(python-sdk): use google docstring format (#50)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jfeodor
jfeodor authored Nov 4, 2024
1 parent c6c35d3 commit 2d8568c
Show file tree
Hide file tree
Showing 8 changed files with 103 additions and 229 deletions.
5 changes: 5 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,11 @@ We also expect new features added to have an associated test suite, which
should be usable as documentation to understand the expectations of the new
code.

## Documentation

In the python SDK, we document modules, functions, classes, and methods using
docstrings. We use the [Google Docstring format](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings).

## Git workflow

When creating a pull request with changes, please consider the following
Expand Down
6 changes: 3 additions & 3 deletions docs/collections.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -206,14 +206,14 @@ my_deserialized_data = MyData(**data["my-data"])

## API Documentation

## ::: numerous.collection.collection.collection
## ::: numerous.collection.collection
options:
show_root_heading: true

## ::: numerous.collection.numerous_collection.NumerousCollection
## ::: numerous.collection.NumerousCollection
options:
show_root_heading: true

## ::: numerous.collection.numerous_document.NumerousDocument
## ::: numerous.collection.NumerousDocument
options:
show_root_heading: true
11 changes: 9 additions & 2 deletions python/src/numerous/collection/collection.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,18 @@ def collection(
collection_key: str, _client: Optional[Client] = None
) -> NumerousCollection:
"""
Get or create a root collection by name.
Get or create a root collection by key.
Use this function as an entry point to interact with collections.
If the collection does not exist, it is created.
Args:
collection_key: Key of the collection. A key is a string that uniquely
identifies a collection.
Returns:
The collection identified by the given key.
In cases where the collection doesn't exist, it will be created.
"""
if _client is None:
_client = get_client()
Expand Down
49 changes: 29 additions & 20 deletions python/src/numerous/collection/numerous_collection.py
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
"""Class for working with numerous collections."""

from dataclasses import dataclass
from typing import Iterator, Optional
from typing import Generator, Iterator, Optional

from numerous.collection._client import Client
from numerous.collection.numerous_document import NumerousDocument
Expand All @@ -22,7 +22,18 @@ def __init__(self, collection_ref: CollectionReference, _client: Client) -> None
self._client = _client

def collection(self, collection_key: str) -> "NumerousCollection":
"""Get or create a collection by name."""
"""
Get or create a child collection of this collection by key.
Args:
collection_key: Key of the nested collection. A key uniquely identifies a
collection within the parent collection. Keys are case sensitive, and
can be used as human-readable identifiers for collections
Returns:
NumerousCollection: The child collection identified by the given key.
"""
collection_ref = self._client.get_collection_reference(
collection_key=collection_key, parent_collection_id=self.id
)
Expand All @@ -36,9 +47,12 @@ def document(self, key: str) -> NumerousDocument:
"""
Get or create a document by key.
Attributes
----------
key (str): The key of the document.
Args:
key: Key of the document. A key uniquely identifies a document within its
collection. Keys are case sensitive.
Returns:
The document in the collection with the given key.
"""
numerous_doc_ref = self._client.get_collection_document(self.id, key)
Expand All @@ -60,17 +74,14 @@ def documents(
"""
Retrieve documents from the collection, filtered by a tag key and value.
Parameters
----------
tag_key : Optional[str]
The key of the tag used to filter documents (optional).
tag_value : Optional[str]
The value of the tag used to filter documents (optional).
Args:
tag_key: If this and `tag_value` is specified, filter documents with this
tag.
tag_value: If this and `tag_key` is specified, filter documents with this
tag.
Yields
------
NumerousDocument
Yields NumerousDocument objects from the collection.
Yields:
Documents from the collection.
"""
end_cursor = ""
Expand All @@ -97,14 +108,12 @@ def documents(
numerous_doc_ref,
)

def collections(self) -> Iterator["NumerousCollection"]:
def collections(self) -> Generator["NumerousCollection", None, None]:
"""
Retrieve nested collections from the collection.
Yields
------
NumerousCollection
Yields NumerousCollection objects.
Yields:
Nested collections of this collection.
"""
end_cursor = ""
Expand Down
20 changes: 5 additions & 15 deletions python/src/numerous/collection/numerous_document.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,9 @@ class NumerousDocument:
"""
Represents a document in a Numerous collection.
Attributes
----------
Attributes:
key (str): The key of the document.
collection_info tuple[str, str]: The id
collection_info (tuple[str, str]): The id
and key of collection document belongs to.
data (Optional[dict[str, Any]]): The data of the document.
id (Optional[str]): The unique identifier of the document.
Expand Down Expand Up @@ -65,11 +64,9 @@ def set(self, data: dict[str, Any]) -> None:
Set the data for the document.
Args:
----
data (dict[str, Any]): The data to set for the document.
Raises:
------
ValueError: If the document data setting fails.
"""
Expand All @@ -88,12 +85,10 @@ def get(self) -> Optional[dict[str, Any]]:
"""
Get the data of the document.
Returns
-------
Returns:
dict[str, Any]: The data of the document.
Raises
------
Raises:
ValueError: If the document does not exist.
"""
Expand All @@ -107,8 +102,7 @@ def delete(self) -> None:
"""
Delete the document.
Raises
------
Raises:
ValueError: If the document does not exist or deletion failed.
"""
Expand All @@ -131,12 +125,10 @@ def tag(self, key: str, value: str) -> None:
Add a tag to the document.
Args:
----
key (str): The tag key.
value (str): The tag value.
Raises:
------
ValueError: If the document does not exist.
"""
Expand All @@ -156,11 +148,9 @@ def tag_delete(self, tag_key: str) -> None:
Delete a tag from the document.
Args:
----
tag_key (str): The key of the tag to delete.
Raises:
------
ValueError: If the document does not exist.
"""
Expand Down
15 changes: 5 additions & 10 deletions python/src/numerous/experimental/marimo/_cookies/fastapi.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,16 +21,11 @@ def add_marimo_cookie_middleware(
"""
Add a middleware that enables accessing cookies in marimo apps.
Parameters
----------
app : FastAPI
The FastAPI app to add the middleware on.
session_ident : Optional[Callable[[], str]]
The identity function which must return a unique value for each session.
cookies_dir : Path | None
Path to the directory where cookies are stored.
Args:
app: The FastAPI app to add the middleware on.
session_ident: The identity function which must return a unique value for each
session.
cookies_dir: Path to the directory where cookies are stored.
"""
cookies_dir = cookies_dir or Path(
Expand Down
47 changes: 16 additions & 31 deletions python/src/numerous/experimental/marimo/_field.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,14 +26,12 @@ def _auto_label(key: str, label: Union[str, None]) -> str:
Automatically assigns a label to a key if the label is None.
Args:
----
key (str): The key to be labeled.
label (str): The label to assign to the key. If None,
the key will be used as the label.
key: The key to be labeled.
label: The label to assign to the key. If None, the key will be used as the
label.
Returns:
-------
str: The assigned label.
The assigned label.
"""
if label is None:
Expand All @@ -56,12 +54,9 @@ def __init__(
Field with a state that can be used in a Marimo app.
Args:
----
default (str | float, optional): The default value for the field.
Defaults to `...`.
annotation (type | None, optional): The type annotation for the field.
Defaults to None.
**kwargs (dict): Additional keyword arguments for the field.
default: The default value for the field.
annotation: The type annotation for the field.
kwargs: Additional keyword arguments for the field.
"""
BaseField.__init__(self, default=default, annotation=annotation, **kwargs)
Expand Down Expand Up @@ -97,14 +92,11 @@ def slider(
Create a slider UI element.
Args:
----
step (float, optional): The step size for the slider. Defaults to 1.
label (str | None, optional): The label for the slider. Defaults to None.
Defaults to None.
step: The step size for the slider.
label: The label for the slider.
Returns:
-------
mo.ui.slider: The created slider UI element.
The created slider UI element.
"""
return self._number_ui(mo.ui.slider, step, label)
Expand All @@ -118,15 +110,11 @@ def number(
Create a number UI element.
Args:
----
step (float, optional): The step value for the number UI element.
Defaults to 1.
label (str, optional): The label for the number UI element.
Defaults to None.
step: The step value for the number UI element.
label: The label for the number UI element.
Returns:
-------
mo.ui.number: The created number UI element.
The created number UI element.
"""
number_ui = self._number_ui(mo.ui.number, step, label)
Expand All @@ -142,12 +130,10 @@ def text(self, label: Union[str, None] = None) -> mo.ui.text:
Return a text field widget.
Args:
----
label (str, optional): The label for the text field. Defaults to None.
label: The label for the text field. Defaults to None.
Returns:
-------
mo.ui.text: The text field widget.
The text field widget.
"""
return mo.ui.text(
Expand All @@ -161,8 +147,7 @@ def set(self, value: Any) -> None: # noqa: ANN401
Set the value of the Marimo object.
Args:
----
value (int | str): The value to be set. It can be an integer or a string.
value: The value to be set. It can be an integer or a string.
Overrides the set method to call the mo state set_value and then calls the super
class's set method.
Expand Down
Loading

0 comments on commit 2d8568c

Please sign in to comment.