feat: adds usage

src/posit/connect/client.py

@@ -11,6 +11,7 @@
 from .config import Config
 from .oauth import OAuthIntegration
 from .content import Content
+from .usage import Usage
 from .users import User, Users
 from .visits import Visits
 
@@ -96,6 +97,10 @@ def content(self) -> Content:
         """
         return Content(config=self.config, session=self.session)
 
+    @property
+    def usage(self) -> Usage:
+        return Usage(self.config, self.session)
+
     @property
     def visits(self) -> Visits:
         return Visits(self.config, self.session)

src/posit/connect/content.py

@@ -212,12 +212,6 @@ def tags(self) -> List[dict]:
 
     # CRUD Methods
 
-    @property
-    def tags(self) -> List[dict]:
-        return self.get("tags", [])
-
-    # CRUD Methods
-
     def delete(self) -> None:
         """Delete the content item."""
         path = f"v1/content/{self.guid}"

src/posit/connect/usage.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+from typing import List, overload
+
+from . import urls
+
+from .cursors import CursorPaginator
+from .resources import Resource, Resources
+
+
+class UsageEvent(Resource):
+    @property
+    def content_guid(self) -> str:
+        """The associated unique content identifier.
+
+        Returns
+        -------
+        str
+        """
+        return self["content_guid"]
+
+    @property
+    def user_guid(self) -> str:
+        """The associated unique user identifier.
+
+        Returns
+        -------
+        str
+        """
+        return self["user_guid"]
+
+    @property
+    def started(self) -> str:
+        """The started timestamp.
+
+        Returns
+        -------
+        str
+        """
+        return self["started"]
+
+    @property
+    def ended(self) -> str:
+        """The ended timestamp.
+
+        Returns
+        -------
+        str
+        """
+        return self["ended"]
+
+    @property
+    def data_version(self) -> int:
+        """The data version.
+
+        Returns
+        -------
+        int
+        """
+        return self["data_version"]
+
+
+class Usage(Resources):
+    @overload
+    def find(
+        self,
+        content_guid: str = ...,
+        min_data_version: int = ...,
+        start: str = ...,
+        end: str = ...,
+    ) -> List[UsageEvent]:
+        """Find usage.
+
+        Parameters
+        ----------
+        content_guid : str, optional
+            Filter by an associated unique content identifer, by default ...
+        min_data_version : int, optional
+            Filter by a minimum data version, by default ...
+        start : str, optional
+            Filter by the start time, by default ...
+        end : str, optional
+            Filter by the end time, by default ...
+
+        Returns
+        -------
+        List[UsageEvent]
+        """
+        ...
+
+    @overload
+    def find(self, *args, **kwargs) -> List[UsageEvent]:
+        """Find usage.
+
+        Returns
+        -------
+        List[UsageEvent]
+        """
+        ...
+
+    def find(self, *args, **kwargs) -> List[UsageEvent]:
+        """Find usage.
+
+        Returns
+        -------
+        List[UsageEvent]
+        """
+        params = dict(*args, **kwargs)
+        params = rename_params(params)
+
+        path = "/v1/instrumentation/shiny/usage"
+        url = urls.append_path(self.config.url, path)
+        paginator = CursorPaginator(self.session, url, params=params)
+        results = paginator.fetch_results()
+        return [
+            UsageEvent(
+                config=self.config,
+                session=self.session,
+                **result,
+            )
+            for result in results
+        ]
+
+    @overload
+    def find_one(
+        self,
+        content_guid: str = ...,
+        min_data_version: int = ...,
+        start: str = ...,
+        end: str = ...,
+    ) -> UsageEvent | None:
+        """Find a usage event.
+
+        Parameters
+        ----------
+        content_guid : str, optional
+            Filter by an associated unique content identifer, by default ...
+        min_data_version : int, optional
+            Filter by a minimum data version, by default ...
+        start : str, optional
+            Filter by the start time, by default ...
+        end : str, optional
+            Filter by the end time, by default ...
+
+        Returns
+        -------
+        UsageEvent | None
+        """
+        ...
+
+    @overload
+    def find_one(self, *args, **kwargs) -> UsageEvent | None:
+        """Find a usage event.
+
+        Returns
+        -------
+        UsageEvent | None
+        """
+        ...
+
+    def find_one(self, *args, **kwargs) -> UsageEvent | None:
+        """Find a usage event.
+
+        Returns
+        -------
+        UsageEvent | None
+        """
+        params = dict(*args, **kwargs)
+        params = rename_params(params)
+        path = "/v1/instrumentation/shiny/usage"
+        url = urls.append_path(self.config.url, path)
+        paginator = CursorPaginator(self.session, url, params=params)
+        pages = paginator.fetch_pages()
+        results = (result for page in pages for result in page.results)
+        visits = (
+            UsageEvent(
+                config=self.config,
+                session=self.session,
+                **result,
+            )
+            for result in results
+        )
+        return next(visits, None)
+
+
+def rename_params(params: dict) -> dict:
+    """Rename params from the internal to the external signature.
+
+    The API accepts `from` as a querystring parameter. Since `from` is a reserved word in Python, the SDK uses the name `start` instead. The querystring parameter `to` takes the same form for consistency.
+
+    Parameters
+    ----------
+    params : dict
+
+    Returns
+    -------
+    dict
+    """
+    if "start" in params:
+        params["from"] = params["start"]
+        del params["start"]
+
+    if "end" in params:
+        params["to"] = params["end"]
+        del params["end"]
+
+    return params

tests/posit/connect/__api__/v1/instrumentation/shiny/usage?limit=500&next=23948901087.json

@@ -0,0 +1,10 @@
+{
+    "paging": {
+        "cursors": {
+            "previous": "23948901087"
+        },
+        "first": "http://localhost:3443/__api__/v1/instrumentation/content/visits",
+        "previous": "http://localhost:3443/__api__/v1/instrumentation/content/visits?previous=23948901087"
+    },
+    "results": []
+}

tests/posit/connect/__api__/v1/instrumentation/shiny/usage?limit=500.json

@@ -0,0 +1,21 @@
+{
+    "paging": {
+        "cursors": {
+            "previous": "23948901087",
+            "next": "23948901087"
+        },
+        "first": "http://localhost:3443/__api__/v1/instrumentation/shiny/usage",
+        "previous": "http://localhost:3443/__api__/v1/instrumentation/shiny/usage?previous=23948901087",
+        "next": "http://localhost:3443/__api__/v1/instrumentation/shiny/usage?next=23948901087",
+        "last": "http://localhost:3443/__api__/v1/instrumentation/shiny/usage?last=true"
+    },
+    "results": [
+        {
+            "content_guid": "bd1d2285-6c80-49af-8a83-a200effe3cb3",
+            "user_guid": "08e3a41d-1f8e-47f2-8855-f05ea3b0d4b2",
+            "started": "2018-09-15T18:00:00-05:00",
+            "ended": "2018-09-15T18:01:00-05:00",
+            "data_version": 1
+        }
+    ]
+}