Merge pull request #739 from neptune-ai/kc/project-management-api-doc…

…strings added fixed docstirngs
neptune-ai · Oct 19, 2021 · 9f13c18 · 9f13c18
2 parents 6a94d3c + b42e3aa
commit 9f13c18
Showing 1 changed file with 157 additions and 0 deletions.
diff --git a/neptune/management/internal/api.py b/neptune/management/internal/api.py
@@ -65,6 +65,22 @@ def _get_backend_client(api_token: Optional[str] = None) -> SwaggerClient:
 
 @with_api_exceptions_handler
 def get_project_list(api_token: Optional[str] = None) -> List[str]:
+    """Get a list of projects you have access to.
+    Args:
+        api_token(str, optional): User’s API token. Defaults to `None`.
+            If `None`, the value of `NEPTUNE_API_TOKEN` environment variable will be taken.
+            .. note::
+                It is strongly recommended to use `NEPTUNE_API_TOKEN` environment variable rather than placing your
+                API token in plain text in your source code.
+    Returns:
+        ``List[str]``: list of project names of a format 'WORKSPACE/PROJECT'
+    Examples:
+        >>> from neptune import management
+        >>> management.get_project_list()
+    You may also want to check `management API reference`_.
+    .. _management API reference:
+       https://docs.neptune.ai/api-reference/management
+    """
     verify_type('api_token', api_token, (str, type(None)))
 
     backend_client = _get_backend_client(api_token=api_token)
@@ -89,6 +105,38 @@ def create_project(
         description: Optional[str] = None,
         api_token: Optional[str] = None
 ) -> str:
+    """Creates a new project in your Neptune workspace.
+    Args:
+        name(str): The name of the project in Neptune in the format 'WORKSPACE/PROJECT'.
+            If workspace argument was set, it should only contain 'PROJECT' instead of 'WORKSPACE/PROJECT'.
+        key(str): Project identifier. It has to be contain 1-10 upper case letters or numbers.
+            For example, 'GOOD5'
+        workspace(str, optional): Name of your Neptune workspace.
+            If you specify it, change the format of the name argument to 'PROJECT' instead of 'WORKSPACE/PROJECT'.
+            If 'None' it will be parsed from the `name` argument.
+        visibility(str, optional): level of visibility you want your project to have.
+            Can be set to:
+             - 'pub' for public projects
+             - 'priv' for private projects
+            If 'None' it will be set to 'priv'
+        description(str, optional): Project description.
+            If 'None', it will be left empty.
+        api_token(str, optional): User’s API token. Defaults to `None`.
+            If `None`, the value of `NEPTUNE_API_TOKEN` environment variable will be taken.
+            .. note::
+                It is strongly recommended to use `NEPTUNE_API_TOKEN` environment variable rather than placing your
+                API token in plain text in your source code.
+    Returns:
+        ``str``: name of the new project you created.
+    Examples:
+        >>> from neptune import management
+        >>> management.create_project(name="awesome-team/amazing-project",
+        ...                           key="AMA",
+        ...                           visibility="pub")
+    You may also want to check `management API reference`_.
+    .. _management API reference:
+       https://docs.neptune.ai/api-reference/management
+    """
     verify_type('name', name, str)
     verify_type('key', key, str)
     verify_type('workspace', workspace, (str, type(None)))
@@ -136,6 +184,25 @@ def create_project(
 
 @with_api_exceptions_handler
 def delete_project(name: str, workspace: Optional[str] = None, api_token: Optional[str] = None):
+    """Deletes a project from your Neptune workspace.
+    Args:
+        name(str): The name of the project in Neptune in the format 'WORKSPACE/PROJECT'.
+            If workspace argument was set, it should only contain 'PROJECT' instead of 'WORKSPACE/PROJECT'.
+        workspace(str, optional): Name of your Neptune workspace.
+            If you specify it, change the format of the name argument to 'PROJECT' instead of 'WORKSPACE/PROJECT'.
+            If 'None' it will be parsed from the name argument.
+        api_token(str, optional): User’s API token. Defaults to `None`.
+            If `None`, the value of `NEPTUNE_API_TOKEN` environment variable will be taken.
+            .. note::
+                It is strongly recommended to use `NEPTUNE_API_TOKEN` environment variable rather than placing your
+                API token in plain text in your source code.
+    Examples:
+        >>> from neptune import management
+        >>> management.delete_project(name="awesome-team/amazing-project")
+    You may also want to check `management API reference`_.
+    .. _management API reference:
+       https://docs.neptune.ai/api-reference/management
+    """
     verify_type('name', name, str)
     verify_type('workspace', workspace, (str, type(None)))
     verify_type('api_token', api_token, (str, type(None)))
@@ -164,6 +231,36 @@ def add_project_member(
         workspace: Optional[str] = None,
         api_token: Optional[str] = None
 ):
+    """Adds member to the Neptune project.
+    Args:
+        name(str): The name of the project in Neptune in the format 'WORKSPACE/PROJECT'.
+            If workspace argument was set, it should only contain 'PROJECT' instead of 'WORKSPACE/PROJECT'.
+        username(str): Name of the user you want to add to the project.
+        role(str): level of permissions the user should have in a project.
+            Can be set to:
+             - 'viewer': can only view project content and members
+             - 'contributor': can view and edit project content and only view members
+             - 'owner': can view and edit project content and members
+            For more information, see `user roles in a project docs`_.
+        workspace(str, optional): Name of your Neptune workspace.
+            If you specify it, change the format of the name argument to 'PROJECT' instead of 'WORKSPACE/PROJECT'.
+            If 'None' it will be parsed from the name argument.
+        api_token(str, optional): User’s API token. Defaults to `None`.
+            If `None`, the value of `NEPTUNE_API_TOKEN` environment variable will be taken.
+            .. note::
+                It is strongly recommended to use `NEPTUNE_API_TOKEN` environment variable rather than placing your
+                API token in plain text in your source code.
+    Examples:
+        >>> from neptune import management
+        >>> management.add_project_member(name="awesome-team/amazing-project",
+        ...                               username="johny",
+        ...                               role="contributor")
+    You may also want to check `management API reference`_.
+    .. _management API reference:
+       https://docs.neptune.ai/api-reference/management
+    .. _user roles in a project docs:
+       https://docs.neptune.ai/administration/user-management#roles-in-a-project
+    """
     verify_type('name', name, str)
     verify_type('username', username, str)
     verify_type('role', role, str)
@@ -196,6 +293,27 @@ def get_project_member_list(
         workspace: Optional[str] = None,
         api_token: Optional[str] = None
 ) -> Dict[str, str]:
+    """Get a list of members for a project.
+    Args:
+        name(str): The name of the project in Neptune in the format 'WORKSPACE/PROJECT'.
+            If workspace argument was set it should only contain 'PROJECT' instead of 'WORKSPACE/PROJECT'.
+        workspace(str, optional): Name of your Neptune workspace.
+            If you specify change the format of the name argument to 'PROJECT' instead of 'WORKSPACE/PROJECT'.
+            If 'None' it will be parsed from the name argument.
+        api_token(str, optional): User’s API token. Defaults to `None`.
+            If `None`, the value of `NEPTUNE_API_TOKEN` environment variable will be taken.
+            .. note::
+                It is strongly recommended to use `NEPTUNE_API_TOKEN` environment variable rather than placing your
+                API token in plain text in your source code.
+    Returns:
+        ``Dict[str, str]``: Dictionary with usernames as keys and MemberRoles ('owner', 'member', 'viewer') as values.
+    Examples:
+        >>> from neptune import management
+        >>> management.get_project_member_list(name="awesome-team/amazing-project")
+    You may also want to check `management API reference`_.
+    .. _management API reference:
+       https://docs.neptune.ai/api-reference/management
+    """
     verify_type('name', name, str)
     verify_type('workspace', workspace, (str, type(None)))
     verify_type('api_token', api_token, (str, type(None)))
@@ -222,6 +340,27 @@ def remove_project_member(
         workspace: Optional[str] = None,
         api_token: Optional[str] = None
 ):
+    """Removes member from the Neptune project.
+    Args:
+        name(str): The name of the project in Neptune in the format 'WORKSPACE/PROJECT'.
+            If workspace argument was set, it should only contain 'PROJECT' instead of 'WORKSPACE/PROJECT'.
+        username(str): name of the user you want to remove from the project.
+        workspace(str, optional): Name of your Neptune workspace.
+            If you specify change the format of the name argument to 'PROJECT' instead of 'WORKSPACE/PROJECT'.
+            If 'None' it will be parsed from the name argument.
+        api_token(str, optional): User’s API token. Defaults to `None`.
+            If `None`, the value of `NEPTUNE_API_TOKEN` environment variable will be taken.
+            .. note::
+                It is strongly recommended to use `NEPTUNE_API_TOKEN` environment variable rather than placing your
+                API token in plain text in your source code.
+    Examples:
+        >>> from neptune import management
+        >>> management.remove_project_member(name="awesome-team/amazing-project",
+        ...                                  username="johny")
+    You may also want to check `management API reference`_.
+    .. _management API reference:
+       https://docs.neptune.ai/api-reference/management
+    """
     verify_type('name', name, str)
     verify_type('username', username, str)
     verify_type('workspace', workspace, (str, type(None)))
@@ -248,6 +387,24 @@ def remove_project_member(
 
 @with_api_exceptions_handler
 def get_workspace_member_list(name: str, api_token: Optional[str] = None) -> Dict[str, str]:
+    """Get a list of members of a workspace.
+    Args:
+        name(str, optional): Name of your Neptune workspace.
+        api_token(str, optional): User’s API token. Defaults to `None`.
+            If `None`, the value of `NEPTUNE_API_TOKEN` environment variable will be taken.
+            .. note::
+                It is strongly recommended to use `NEPTUNE_API_TOKEN` environment variable rather than placing your
+                API token in plain text in your source code.
+    Returns:
+        ``Dict[str, str]``: Dictionary with usernames as keys and MemberRoles as values.
+        For example, {'johny':'owner', 'kate':'contributor', 'mark':'viewer'}.
+    Examples:
+        >>> from neptune import management
+        >>> management.get_workspace_member_list(name="awesome-team")
+    You may also want to check `management API reference`_.
+    .. _management API reference:
+       https://docs.neptune.ai/api-reference/management
+    """
     verify_type('name', name, str)
     verify_type('api_token', api_token, (str, type(None)))