Merge pull request #109 from machow/feat-rsc-access-type

Feat rsc access type

Author: machow

pins/__init__.py

@@ -20,4 +20,5 @@
     board_urls,
     board_rsconnect,
     board_s3,
+    board,
 )

pins/boards.py

@@ -15,7 +15,7 @@
 from .meta import Meta, MetaRaw, MetaFactory
 from .errors import PinsError
 from .drivers import load_data, save_data, default_title
-from .utils import inform
+from .utils import inform, ExtendMethodDoc
 from .config import get_allow_rsc_short_name
 
 
@@ -650,12 +650,15 @@ def __init__(self, *args, pin_paths: dict, **kwargs):
 
     #    return super().pin_read(*args, **kwargs)
 
+    @ExtendMethodDoc
     def pin_list(self):
         return list(self.pin_paths)
 
+    @ExtendMethodDoc
     def pin_versions(self, *args, **kwargs):
         raise NotImplementedError("This board does not support pin_versions.")
 
+    @ExtendMethodDoc
     def pin_meta(self, name, version=None):
         if version is not None:
             raise NotImplementedError()
@@ -680,6 +683,7 @@ def pin_meta(self, name, version=None):
 
         return meta
 
+    @ExtendMethodDoc
     def pin_download(self, name, version=None, hash=None) -> Sequence[str]:
         meta = self.pin_meta(name, version)
 
@@ -723,6 +727,7 @@ class BoardRsConnect(BaseBoard):
 
     # defaults work ----
 
+    @ExtendMethodDoc
     def pin_list(self):
         # lists all pin content on RStudio Connect server
         # we can't use fs.ls, because it will list *all content*
@@ -732,7 +737,15 @@ def pin_list(self):
         names = [f"{cont['owner_username']}/{cont['name']}" for cont in results]
         return names
 
-    def pin_write(self, *args, **kwargs):
+    @ExtendMethodDoc
+    def pin_write(self, *args, access_type=None, **kwargs):
+        """Write a pin.
+
+        Extends parent method in the following ways:
+
+        * Modifies content item to include any title and description changes.
+        * Adds access_type argument to specify who can see content. Defaults to "acl".
+        """
 
         # run parent function ---
 
@@ -757,6 +770,7 @@ def pin_write(self, *args, **kwargs):
 
         return meta
 
+    @ExtendMethodDoc
     def pin_search(self, search=None, as_df=True):
         from pins.rsconnect.api import RsConnectApiRequestError
 
@@ -793,6 +807,7 @@ def pin_search(self, search=None, as_df=True):
 
         return res
 
+    @ExtendMethodDoc
     def pin_version_delete(self, *args, **kwargs):
         from pins.rsconnect.api import RsConnectApiRequestError
 
@@ -804,6 +819,7 @@ def pin_version_delete(self, *args, **kwargs):
 
             raise PinsError("RStudio Connect cannot delete the latest pin version.")
 
+    @ExtendMethodDoc
     def pin_versions_prune(self, *args, **kwargs):
         sig = inspect.signature(super().pin_versions_prune)
         if sig.bind(*args, **kwargs).arguments.get("days") is not None:

pins/constructors.py

@@ -70,7 +70,11 @@ def board(
     storage_options: "dict | None" = None,
     board_factory: "callable | BaseBoard | None" = None,
 ):
-    """
+    """General function for constructing a pins board.
+
+    Note that this is a lower-level function. For most use cases, use a more specific
+    function like board_local(...), or board_s3(...).
+
     Parameters
     ----------
     protocol:

pins/rsconnect/api.py

@@ -304,7 +304,7 @@ def get_content_item(self, guid: str) -> Content:
         return Content(result)
 
     def post_content_item(
-        self, name, access_type, title: str = "", description: str = "", **kwargs
+        self, name, access_type: str, title: str = "", description: str = "", **kwargs
     ) -> Content:
         data = self._get_params(locals(), exclude={"kwargs"})
         result = self.query_v1("content", "POST", json={**data, **kwargs})

pins/rsconnect/fs.py

@@ -18,6 +18,17 @@
     RSC_CODE_OBJECT_DOES_NOT_EXIST,
 )
 
+# Misc ----
+
+
+def _not_impl_args_kwargs(args, kwargs):
+    return NotImplementedError(
+        "Additional args and kwargs not supported." f"\nArgs: {args}\nKwargs: {kwargs}"
+    )
+
+
+# Bundles ----
+
 
 @dataclass
 class PinBundleManifestMetadata:
@@ -148,6 +159,7 @@ def put(
         rpath,
         recursive=False,
         *args,
+        access_type="acl",
         deploy=True,
         cls_manifest=PinBundleManifest,
         **kwargs,
@@ -160,6 +172,8 @@ def put(
             A path to the local bundle directory.
         rpath: str
             A path to the content where the bundle is being put.
+        access_type:
+            Who can use and view this content? Must be one of all, logged_in or acl.
         cls_manifest:
             If maniest does not exist, a class with an .add_manifest_to_directory()
             method.
@@ -168,6 +182,9 @@ def put(
 
         parsed = self.parse_path(rpath)
 
+        if len(args) or len(kwargs):
+            raise _not_impl_args_kwargs(args, kwargs)
+
         if recursive is False:
             raise NotImplementedError(
                 "Must set recursive to True in order to put any RSConnect content."
@@ -185,7 +202,7 @@ def put(
             # TODO: this could be seen as analogous to mkdir (which gets
             # called by pins anyway)
             # TODO: hard-coded acl bad?
-            content = self.api.post_content_item(parsed.content, "acl")
+            content = self.api.post_content_item(parsed.content, access_type)
 
         # Create bundle (with manifest.json inserted if missing) ----
 
@@ -265,18 +282,22 @@ def exists(self, path: str, **kwargs) -> bool:
         except RsConnectApiMissingContentError:
             return False
 
-    def mkdir(self, path, create_parents=True, **kwargs) -> None:
+    def mkdir(
+        self, path, create_parents=True, *args, access_type="acl", **kwargs
+    ) -> None:
         parsed = self.parse_path(path)
 
+        if len(args) or len(kwargs):
+            raise _not_impl_args_kwargs(args, kwargs)
+
         if not isinstance(parsed, ContentPath):
             raise ValueError(f"Requires path to content, but received: {path}")
 
         if self.exists(path):
             raise FileExistsError(path)
 
         # TODO: could implement and call makedirs, but seems overkill
-        # TODO: hard-coded "acl"?
-        self.api.post_content_item(parsed.content, "acl", **kwargs)
+        self.api.post_content_item(parsed.content, access_type, **kwargs)
 
     def info(self, path, **kwargs) -> "User | Content | Bundle":
         # TODO: source of fsspec info uses self._parent to check cache?

pins/tests/test_rsconnect_api.py

@@ -426,6 +426,25 @@ def test_rsconnect_fs_put_bundle(fs_short):
     assert f_index.read().decode() == (Path(path_to_example) / "index.html").read_text()
 
 
+def test_rsconnect_fs_put_bundle_all_access(fs_short):
+    import requests
+
+    # TODO: use pkg_resources to get this
+    path_to_example = "pins/tests/example-bundle"
+    fs_short.put(
+        path_to_example, "susan/test-content", recursive=True, access_type="all"
+    )
+
+    # access control is set at the content (not bundle) level. we need to get the
+    # content guid to recreate the "shareable" link
+    content = fs_short.info("susan/test-content")
+
+    r = requests.get(f"{fs_short.api.server_url}/content/{content['guid']}")
+    r.raise_for_status()
+
+    assert r.text == (Path(path_to_example) / "index.html").read_text()
+
+
 # fs.mkdir ----
 
 

pins/utils.py

@@ -1,5 +1,8 @@
 import sys
 
+from functools import update_wrapper
+from types import MethodType
+
 from .config import pins_options
 
 
@@ -9,3 +12,54 @@ def inform(log, msg):
 
     if not pins_options.quiet:
         print(msg, file=sys.stderr)
+
+
+class ExtendMethodDoc:
+    # Note that the indentation assumes these are top-level method docstrings,
+    # so are indented 8 spaces (after the initial sentence).
+    template = """\
+{current_doc}
+
+        Parent method documentation:
+
+        {parent_doc}
+        """
+
+    def __init__(self, func):
+        self.func = func
+
+        # allows sphinx to add the method signature to the docs
+        # this is pretty benign, since it's very hard to call a descriptor
+        # after class initialization (where __set_name__ is called).
+        self.__call__ = func
+
+    def __set_name__(self, owner, name):
+        bound_parent_meth = getattr(super(owner, owner), name)
+
+        self._parent_doc = bound_parent_meth.__doc__
+        self._orig_doc = self.func.__doc__
+
+        if self._orig_doc is not None:
+            # update the docstring of the subclass method to include parent doc.
+            self.func.__doc__ = self.template.format(
+                current_doc=self._orig_doc, parent_doc=self._parent_doc
+            )
+
+        # make descriptor look like wrapped function
+        update_wrapper(
+            self, self.func, ("__doc__", "__name__", "__module__", "__qualname__")
+        )
+
+    def __get__(self, obj, objtype=None):
+        if obj is None:
+            # accessing from class, return descriptor itself.
+            return self
+
+        # accessing from instance
+        return MethodType(self.func, obj)
+
+    def __call__(self, *args, **kwargs):
+        # this is defined, so that callable(ExtendMethodDoc(...)) is True,
+        # which allows all the inspect machinery to give sphinx the __call__
+        # attribute we set in __init__.
+        raise NotImplementedError()