diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index f6f6bf9d..69b160b7 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -22,6 +22,6 @@ RUN if [ "${NODE_VERSION}" != "none" ]; then su vscode -c "umask 0002 && . /usr/ USER vscode -RUN curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python - +RUN curl -sSL https://install.python-poetry.org | python3 - ENV PATH=$PATH:$HOME/.poetry/env diff --git a/src/specklepy/api/resources/active_user.py b/src/specklepy/api/resources/active_user.py index a59a5e6d..014bcb28 100644 --- a/src/specklepy/api/resources/active_user.py +++ b/src/specklepy/api/resources/active_user.py @@ -7,7 +7,8 @@ class Resource(CoreResource): - """API Access class for users""" + """API Access class for users. This class provides methods to get and update + the user profile, fetch user activity, and manage pending stream invitations.""" def __init__(self, account, basepath, client, server_version) -> None: super().__init__( @@ -19,13 +20,9 @@ def __init__(self, account, basepath, client, server_version) -> None: self.schema = User def get(self) -> User: - """Gets the profile of a user. If no id argument is provided, - will return the current authenticated user's profile + """Gets the profile of the current authenticated user's profile (as extracted from the authorization header). - Arguments: - id {str} -- the user id - Returns: User -- the retrieved user """ @@ -41,11 +38,11 @@ def update( ): """Updates your user profile. All arguments are optional. - Arguments: - name {str} -- your name - company {str} -- the company you may or may not work for - bio {str} -- tell us about yourself - avatar {str} -- a nice photo of yourself + Args: + name (Optional[str]): The user's name. + company (Optional[str]): The company the user works for. + bio (Optional[str]): A brief user biography. + avatar (Optional[str]): A URL to an avatar image for the user. Returns @deprecated(version=DEPRECATION_VERSION, reason=DEPRECATION_TEXT): bool -- True if your profile was updated successfully @@ -62,35 +59,30 @@ def activity( cursor: Optional[datetime] = None, ): """ - Get the activity from a given stream in an Activity collection. - Step into the activity `items` for the list of activity. - If no id argument is provided, will return the current authenticated user's - activity (as extracted from the authorization header). + Fetches collection the current authenticated user's activity + as filtered by given parameters Note: all timestamps arguments should be `datetime` of any tz as they will be converted to UTC ISO format strings - user_id {str} -- the id of the user to get the activity from - action_type {str} -- filter results to a single action type - (eg: `commit_create` or `commit_receive`) - limit {int} -- max number of Activity items to return - before {datetime} -- latest cutoff for activity - (ie: return all activity _before_ this time) - after {datetime} -- oldest cutoff for activity - (ie: return all activity _after_ this time) - cursor {datetime} -- timestamp cursor for pagination + Args: + limit (int): The maximum number of activity items to return. + action_type (Optional[str]): Filter results to a single action type. + before (Optional[datetime]): Latest cutoff for activity to include. + after (Optional[datetime]): Oldest cutoff for an activity to include. + cursor (Optional[datetime]): Timestamp cursor for pagination. + + Returns: + Activity collection, filtered according to the provided parameters. """ metrics.track(metrics.SDK, self.account, {"name": "User Active Activity"}) return super().activity(limit, action_type, before, after, cursor) def get_all_pending_invites(self) -> List[PendingStreamCollaborator]: - """Get all of the active user's pending stream invites - - Requires Speckle Server version >= 2.6.4 + """Fetches all of the current user's pending stream invitations. Returns: - List[PendingStreamCollaborator] - -- a list of pending invites for the current user + List[PendingStreamCollaborator]: A list of pending stream invitations. """ metrics.track( metrics.SDK, self.account, {"name": "User Active Invites All Get"} @@ -100,18 +92,14 @@ def get_all_pending_invites(self) -> List[PendingStreamCollaborator]: def get_pending_invite( self, stream_id: str, token: Optional[str] = None ) -> Optional[PendingStreamCollaborator]: - """Get a particular pending invite for the active user on a given stream. - If no invite_id is provided, any valid invite will be returned. - - Requires Speckle Server version >= 2.6.4 + """Fetches a specific pending invite for the current user on a given stream. - Arguments: - stream_id {str} -- the id of the stream to look for invites on - token {str} -- the token of the invite to look for (optional) + Args: + stream_id (str): The ID of the stream to look for invites on. + token (Optional[str]): The token of the invite to look for (optional). Returns: - PendingStreamCollaborator - -- the invite for the given stream (or None if it isn't found) + Optional[PendingStreamCollaborator]: The invite for the given stream, or None if not found. """ metrics.track(metrics.SDK, self.account, {"name": "User Active Invite Get"}) return super().get_pending_invite(stream_id, token) diff --git a/src/specklepy/api/resources/other_user.py b/src/specklepy/api/resources/other_user.py index f9ff35fe..b70c7fc0 100644 --- a/src/specklepy/api/resources/other_user.py +++ b/src/specklepy/api/resources/other_user.py @@ -8,7 +8,11 @@ class Resource(CoreResource): - """API Access class for other users, that are not the currently active user.""" + """ + Provides API access to other users' profiles and activities on the platform. + This class enables fetching limited information about users, searching for users by name or email, + and accessing user activity logs with appropriate privacy and access control measures in place. + """ def __init__(self, account, basepath, client, server_version) -> None: super().__init__( @@ -21,13 +25,13 @@ def __init__(self, account, basepath, client, server_version) -> None: def get(self, id: str) -> LimitedUser: """ - Gets the profile of another user. + Retrieves the profile of a user specified by their user ID. - Arguments: - id {str} -- the user id + Args: + id (str): The unique identifier of the user. Returns: - LimitedUser -- the retrieved profile of another user + LimitedUser: The profile of the user with limited information. """ metrics.track(metrics.SDK, self.account, {"name": "Other User Get"}) return super().get(id) @@ -35,18 +39,21 @@ def get(self, id: str) -> LimitedUser: def search( self, search_query: str, limit: int = 25 ) -> Union[List[LimitedUser], SpeckleException]: - """Searches for user by name or email. The search query must be at least - 3 characters long + """ + Searches for users by name or email. + The search requires a minimum query length of 3 characters. + + Args: + search_query (str): The search string. + limit (int): Maximum number of search results to return. - Arguments: - search_query {str} -- a string to search for - limit {int} -- the maximum number of results to return Returns: - List[LimitedUser] -- a list of User objects that match the search query + Union[List[LimitedUser], SpeckleException]: A list of users matching the search + query or an exception if the query is too short. """ if len(search_query) < 3: return SpeckleException( - message="User search query must be at least 3 characters" + message="User search query must be at least 3 characters." ) metrics.track(metrics.SDK, self.account, {"name": "Other User Search"}) @@ -62,21 +69,19 @@ def activity( cursor: Optional[datetime] = None, ) -> ActivityCollection: """ - Get the activity from a given stream in an Activity collection. - Step into the activity `items` for the list of activity. + Retrieves a collection of activities for a specified user, with optional filters for activity type, + time frame, and pagination. - Note: all timestamps arguments should be `datetime` of - any tz as they will be converted to UTC ISO format strings + Args: + user_id (str): The ID of the user whose activities are being requested. + limit (int): The maximum number of activity items to return. + action_type (Optional[str]): A specific type of activity to filter. + before (Optional[datetime]): Latest timestamp to include activities before. + after (Optional[datetime]): Earliest timestamp to include activities after. + cursor (Optional[datetime]): Timestamp for pagination cursor. - user_id {str} -- the id of the user to get the activity from - action_type {str} -- filter results to a single action type - (eg: `commit_create` or `commit_receive`) - limit {int} -- max number of Activity items to return - before {datetime} -- latest cutoff for activity - (ie: return all activity _before_ this time) - after {datetime} -- oldest cutoff for activity - (ie: return all activity _after_ this time) - cursor {datetime} -- timestamp cursor for pagination + Returns: + ActivityCollection: A collection of user activities filtered according to specified criteria. """ metrics.track(metrics.SDK, self.account, {"name": "Other User Activity"}) return super().activity(user_id, limit, action_type, before, after, cursor)