chris.models.logged_in

  1"""
  2Subclasses of classes from `chris.models.data` which are returned
  3from an `chris.client.authed.AuthenticatedClient`.
  4These classes may have read-write functionality on the *ChRIS* API.
  5"""
  6from dataclasses import dataclass
  7from typing import Optional
  8
  9from serde import deserialize
 10
 11from chris.link import http
 12from chris.link.linked import LinkedModel
 13from chris.models.data import PluginInstanceData, FeedData, UserData, FeedNoteData
 14from chris.models.enums import PluginType
 15from chris.models.public import PublicPlugin
 16from chris.models.types import *
 17
 18
 19@deserialize
 20@dataclass(frozen=True)
 21class User(UserData, LinkedModel):
 22    pass  # TODO change_email, change_password
 23
 24
 25@deserialize
 26@dataclass(frozen=True)
 27class File(LinkedModel):
 28    """
 29    A file in CUBE.
 30    """
 31
 32    url: str
 33    fname: FileFname
 34    fsize: int
 35    file_resource: FileResourceUrl
 36
 37    @property
 38    def parent(self) -> str:
 39        """
 40        Get the parent (directory) of a file.
 41
 42        Examples
 43        --------
 44
 45        ```python
 46        assert file.fname == 'chris/feed_4/pl-dircopy_7/data/hello-world.txt'
 47        assert file.parent == 'chris/feed_4/pl-dircopy_7/data'
 48        ```
 49        """
 50        split = self.fname.split("/")
 51        if len(split) <= 1:
 52            return self.fname
 53        return "/".join(split[:-1])
 54
 55    # TODO download methods
 56
 57
 58@deserialize
 59@dataclass(frozen=True)
 60class PluginInstance(PluginInstanceData):
 61    @http.get("feed")
 62    async def get_feed(self) -> "Feed":
 63        """Get the feed this plugin instance belongs to."""
 64        ...
 65
 66    @http.put("url")
 67    async def set(
 68        self, title: Optional[str] = None, status: Optional[str] = None
 69    ) -> "PluginInstance":
 70        """
 71        Set the title or status of this plugin instance.
 72        """
 73        ...
 74
 75    @http.delete("url")
 76    async def delete(self) -> None:
 77        """Delete this plugin instance."""
 78        ...
 79
 80
 81@deserialize
 82@dataclass(frozen=True)
 83class FeedNote(FeedNoteData):
 84    @http.get("feed")
 85    async def get_feed(self) -> "Feed":
 86        """Get the feed this note belongs to."""
 87        ...
 88
 89    @http.put("url")
 90    async def set(
 91        self, title: Optional[str] = None, content: Optional[str] = None
 92    ) -> "FeedNote":
 93        """Change this note."""
 94        ...
 95
 96
 97@deserialize
 98@dataclass(frozen=True)
 99class Feed(FeedData):
100    """
101    A feed of a logged in user.
102    """
103
104    @http.put("url")
105    async def set(
106        self, name: Optional[str] = None, owner: Optional[str | Username] = None
107    ) -> "Feed":
108        """
109        Change the name or the owner of this feed.
110
111        Parameters
112        ----------
113        name
114            new name for this feed
115        owner
116            new owner for this feed
117        """
118        ...
119
120    @http.get("note")
121    async def get_note(self) -> FeedNote:
122        ...
123
124
125@deserialize
126@dataclass(frozen=True)
127class Plugin(PublicPlugin):
128    """
129    A ChRIS plugin. Create a plugin instance of this plugin to run it.
130    """
131
132    instances: ApiUrl
133
134    @http.post("instances")
135    async def _create_instance_raw(self, **kwargs) -> PluginInstance:
136        ...
137
138    async def create_instance(
139        self, previous: Optional[PluginInstance] = None, **kwargs
140    ) -> PluginInstance:
141        """
142        Create a plugin instance, i.e. "run" this plugin.
143
144        Parameters common to all plugins are described below.
145        Not all valid parameters are listed, since each plugin's parameters are different.
146        Some plugins have required parameters too.
147        To list all possible parameters, make a GET request to the specific plugin's instances link.
148
149        Parameters
150        ----------
151        previous: chris.models.data.PluginInstanceData
152            Previous plugin instance
153        previous_id: int
154            Previous plugin instance ID number (conflicts with `previous`)
155        compute_resource_name: Optional[str]
156            Name of compute resource to use
157        memory_limit: Optional[str]
158            Memory limit. Format is *x*Mi or *x*Gi where x is an integer.
159        cpu_limit: Optional[str]
160            CPU limit. Format is *x*m for *x* is an integer in millicores.
161        gpu_limit: Optional[int]
162            GPU limit.
163        """
164        if previous is not None:
165            if "previous_id" in kwargs:
166                raise ValueError("Cannot give both previous and previous_id.")
167            if not isinstance(previous, PluginInstance):
168                raise TypeError(f"{previous} is not a PluginInstance")
169            kwargs["previous_id"] = previous.id
170        if self.plugin_type is PluginType.fs:
171            if "previous_id" in kwargs:
172                raise ValueError(
173                    "Cannot create plugin instance of a fs-type plugin with a previous plugin instance."
174                )
175        elif "previous_id" not in kwargs:
176            raise ValueError(
177                f'Plugin type is "{self.plugin_type.value}" so previous is a required parameter.'
178            )
179        return await self._create_instance_raw(**kwargs)