docs: add docstrings from Metabase API docs

Signed-off-by: Charles Larivier <charles@dribbble.com>

Author: Charles Larivier

metabase/resources/dataset.py

@@ -39,6 +39,7 @@ class Dataset(CreateResource):
 
     @classmethod
     def create(cls, database: int, type: str, query: dict, **kwargs) -> Dataset:
+        """Execute a query and retrieve the results in the usual format."""
         dataset = super(Dataset, cls).create(database=database, type=type, query=query)
         dataset.data = Data(**dataset.data)
         return dataset

metabase/resources/field.py

@@ -112,6 +112,7 @@ class VisibilityType(str, Enum):
 
     @classmethod
     def get(cls, id: int) -> Field:
+        """Get Field with ID."""
         return super(Field, cls).get(id)
 
     def update(
@@ -128,6 +129,7 @@ def update(
         coercion_strategy: str = MISSING,
         **kwargs,
     ) -> None:
+        """Update Field with ID."""
         return super(Field, self).update(
             display_name=display_name,
             description=description,
@@ -142,18 +144,32 @@ def update(
         )
 
     def related(self) -> Dict[str, Any]:
+        """Return related entities."""
         return (
             self.connection()
             .get(self.ENDPOINT + f"/{getattr(self, self.PRIMARY_KEY)}" + "/related")
             .json()
         )
 
     def discard_values(self):
-        self.connection().post(
+        """
+        Discard the FieldValues belonging to this Field. Only applies to fields
+        that have FieldValues. If this Field’s Database is set up to automatically
+        sync FieldValues, they will be recreated during the next cycle.
+
+        You must be a superuser to do this.
+        """
+        return self.connection().post(
             self.ENDPOINT + f"/{getattr(self, self.PRIMARY_KEY)}" + "/discard_values"
         )
 
     def rescan_values(self):
-        self.connection().post(
+        """
+        Manually trigger an update for the FieldValues for this Field. Only applies
+        to Fields that are eligible for FieldValues.
+
+        You must be a superuser to do this.
+        """
+        return self.connection().post(
             self.ENDPOINT + f"/{getattr(self, self.PRIMARY_KEY)}" + "/rescan_values"
         )

metabase/resources/metric.py

@@ -82,6 +82,7 @@ def update(
         )
 
     def archive(self):
+        """Archive a Metric."""
         return self.update(
             archived=True, revision_message="Archived by metabase-python."
         )

metabase/resources/permission_group.py

@@ -22,15 +22,43 @@ class PermissionGroup(
 
     @classmethod
     def list(cls) -> List[PermissionGroup]:
+        """
+        Fetch all PermissionsGroups, including a count of the number of :members in that group.
+
+        You must be a superuser to do this.
+        """
         return super(PermissionGroup, cls).list()
 
     @classmethod
     def get(cls, id: int) -> PermissionGroup:
+        """
+        Fetch the details for a certain permissions group.
+
+        You must be a superuser to do this.
+        """
         return super(PermissionGroup, cls).get(id)
 
     @classmethod
     def create(cls, name: str, **kwargs) -> PermissionGroup:
+        """
+        Create a new PermissionsGroup.
+
+        You must be a superuser to do this.
+        """
         return super(PermissionGroup, cls).create(name=name, **kwargs)
 
     def update(self, name: str, **kwargs) -> None:
+        """
+        Update the name of a PermissionsGroup.
+
+        You must be a superuser to do this.
+        """
         return super(PermissionGroup, self).update(name=name, **kwargs)
+
+    def delete(self) -> None:
+        """
+        Delete a specific PermissionsGroup.
+
+        You must be a superuser to do this.
+        """
+        return super(PermissionGroup, self).delete()

metabase/resources/permission_membership.py

@@ -25,6 +25,13 @@ class PermissionMembership(ListResource, CreateResource, DeleteResource):
 
     @classmethod
     def list(cls) -> List[PermissionMembership]:
+        """
+        Fetch a map describing the group memberships of various users. This map’s format is:
+
+        {<user-id> [{:membership_id <id>
+                     :group_id      <id>}]}.
+        You must be a superuser to do this.
+        """
         response = cls.connection().get(cls.ENDPOINT)
         all_memberships = [
             item for sublist in response.json().values() for item in sublist
@@ -34,6 +41,11 @@ def list(cls) -> List[PermissionMembership]:
 
     @classmethod
     def create(cls, group_id: int, user_id: int, **kwargs) -> PermissionMembership:
+        """
+        Add a User to a PermissionsGroup. Returns updated list of members belonging to the group.
+
+        You must be a superuser to do this.
+        """
         response = cls.connection().post(
             cls.ENDPOINT, json={"group_id": group_id, "user_id": user_id}
         )

metabase/resources/segment.py

@@ -76,6 +76,7 @@ def update(
         )
 
     def archive(self):
+        """Archive a Segment."""
         return self.update(
             archived=True, revision_message="Archived by metabase-python."
         )

metabase/resources/table.py

@@ -61,10 +61,12 @@ class FieldOrder(str, Enum):
 
     @classmethod
     def list(cls) -> List[Table]:
+        """Get all Tables."""
         return super(Table, cls).list()
 
     @classmethod
     def get(cls, id: int) -> Table:
+        """Get Table with ID."""
         return super(Table, cls).get(id)
 
     def update(
@@ -79,6 +81,7 @@ def update(
         show_in_getting_started: bool = MISSING,
         **kwargs,
     ) -> None:
+        """Update Table with ID."""
         return super(Table, self).update(
             display_name=display_name,
             description=description,
@@ -90,14 +93,25 @@ def update(
             show_in_getting_started=show_in_getting_started,
         )
 
-    def foreign_keys(self) -> List[dict]:
+    def fks(self) -> List[dict]:
+        """Get all foreign keys whose destination is a Field that belongs to this Table."""
         return (
             self.connection()
             .get(self.ENDPOINT + f"/{getattr(self, self.PRIMARY_KEY)}" + "/fks")
             .json()
         )
 
     def query_metadata(self) -> Dict[str, Any]:
+        """
+        Get metadata about a Table useful for running queries. Returns DB, fields,
+        field FKs, and field values.
+
+        Passing include_hidden_fields=true will include any hidden Fields in the response.
+        Defaults to false Passing include_sensitive_fields=true will include any sensitive
+        Fields in the response. Defaults to false.
+
+        These options are provided for use in the Admin Edit Metadata page.
+        """
         return (
             self.connection()
             .get(
@@ -109,26 +123,42 @@ def query_metadata(self) -> Dict[str, Any]:
         )
 
     def related(self) -> Dict[str, Any]:
+        """Return related entities."""
         return (
             self.connection()
             .get(self.ENDPOINT + f"/{getattr(self, self.PRIMARY_KEY)}" + "/related")
             .json()
         )
 
     def discard_values(self):
+        """
+        Discard the FieldValues belonging to the Fields in this Table. Only applies to
+        fields that have FieldValues. If this Table’s Database is set up to automatically
+        sync FieldValues, they will be recreated during the next cycle.
+
+        You must be a superuser to do this.
+        """
         self.connection().post(
             self.ENDPOINT + f"/{getattr(self, self.PRIMARY_KEY)}" + "/discard_values"
         )
 
     def rescan_values(self):
+        """
+        Manually trigger an update for the FieldValues for the Fields belonging to this Table.
+        Only applies to Fields that are eligible for FieldValues.
+
+        You must be a superuser to do this.
+        """
         self.connection().post(
             self.ENDPOINT + f"/{getattr(self, self.PRIMARY_KEY)}" + "/rescan_values"
         )
 
     def fields(self) -> List[Field]:
+        """Get all Fields associated with this Table.."""
         return [Field(**field) for field in self.query_metadata().get("fields")]
 
     def dimensions(self) -> List[Dimension]:
+        """Get all Dimensions associated with this Table."""
         return [
             Dimension(id=id, **dimension)
             for id, dimension in self.query_metadata()
@@ -137,19 +167,9 @@ def dimensions(self) -> List[Dimension]:
         ]
 
     def metrics(self) -> List[Metric]:
+        """Get all Metrics associated with this Table."""
         return [Metric(**metric) for metric in self.related().get("metrics")]
 
     def segments(self) -> List[Segment]:
+        """Get all Segments associated with this Table."""
         return [Segment(**segment) for segment in self.related().get("segments")]
-
-    def get_field(self, id: int) -> Field:
-        return next(filter(lambda field: field.id == id, self.fields()))
-
-    def get_dimension(self, id: str) -> Dimension:
-        return next(filter(lambda dimension: dimension.id == id, self.dimensions()))
-
-    def get_metric(self, id: int) -> Metric:
-        return next(filter(lambda metric: metric.id == id, self.metrics()))
-
-    def get_segment(self, id: int) -> Segment:
-        return next(filter(lambda segment: segment.id == id, self.segments()))

metabase/resources/user.py

@@ -38,6 +38,15 @@ class User(ListResource, CreateResource, GetResource, UpdateResource, DeleteReso
 
     @classmethod
     def list(cls) -> List[User]:
+        """
+        Fetch a list of Users. By default returns every active user but only active users.
+
+        If status is deactivated, include deactivated users only. If status is all, include all users (active and inactive). Also supports include_deactivated, which if true, is equivalent to status=all. status and included_deactivated requires superuser permissions.
+
+        For users with segmented permissions, return only themselves.
+
+        Takes limit, offset for pagination. Takes query for filtering on first name, last name, email. Also takes group_id, which filters on group id.
+        """
         response = cls.connection().get(cls.ENDPOINT)
         records = [cls(**user) for user in response.json().get("data", [])]
         return records
@@ -53,6 +62,11 @@ def create(
         login_attributes: Dict[str, Any] = None,
         **kwargs,
     ) -> User:
+        """
+        Create a new User, return a 400 if the email address is already taken.
+
+        You must be a superuser to do this.
+        """
         return super(User, cls).create(
             first_name=first_name,
             last_name=last_name,
@@ -68,28 +82,52 @@ def update(
         first_name: str = MISSING,
         last_name: str = MISSING,
         email: str = MISSING,
-        password: str = MISSING,
         group_ids: List[int] = MISSING,
         is_superuser: bool = MISSING,
         locale: str = MISSING,
         **kwargs,
     ) -> None:
+        """Update an existing, active User."""
         return super(User, self).update(
             first_name=first_name,
             last_name=last_name,
             email=email,
-            password=password,
             group_ids=group_ids,
             locale=locale,
             **kwargs,
         )
 
+    def delete(self) -> None:
+        """
+        Disable a User. This does not remove the User from the DB, but instead disables their account.
+
+        You must be a superuser to do this.
+        """
+        return super(User, self).delete()
+
+    def password(self, password: str, old_password: str):
+        """Update a user’s password."""
+        return self.connection().put(
+            self.ENDPOINT + f"/{getattr(self, self.PRIMARY_KEY)}" + "/password",
+            json={"password": password, "old_password": old_password},
+        )
+
     def send_invite(self):
-        self.connection().put(
+        """
+        Resend the user invite email for a given user.
+
+        You must be a superuser to do this.
+        """
+        return self.connection().put(
             self.ENDPOINT + f"/{getattr(self, self.PRIMARY_KEY)}" + "/send_invite"
         )
 
     def reactivate(self):
-        self.connection().put(
+        """
+        Reactivate user at :id.
+
+        You must be a superuser to do this.
+        """
+        return self.connection().put(
             self.ENDPOINT + f"/{getattr(self, self.PRIMARY_KEY)}" + "/reactivate"
         )

tests/resources/test_table.py

@@ -49,9 +49,9 @@ def test_update(self):
         t.update(display_name=display_name)
 
     def test_foreign_keys(self):
-        """Ensure Table.foreign_keys() returns a list of foreign keys as dict."""
+        """Ensure Table.fks() returns a list of foreign keys as dict."""
         table = Table.get(1)
-        fks = table.foreign_keys()
+        fks = table.fks()
 
         self.assertIsInstance(fks, list)
         self.assertTrue(len(fks) > 0)