|
1 | 1 | import posixpath |
2 | | -from typing import Optional, TypedDict, overload |
| 2 | +from typing import Literal, Optional, TypedDict, overload |
3 | 3 |
|
4 | 4 | from typing_extensions import NotRequired, Required, Unpack |
5 | 5 |
|
| 6 | +from posit.connect.context import requires |
| 7 | +from posit.connect.paginator import Paginator |
| 8 | + |
6 | 9 | from .resources import Active, ActiveFinderMethods, ActiveSequence |
7 | 10 |
|
8 | 11 |
|
9 | | -class Package(Active): |
| 12 | +class ContentPackage(Active): |
10 | 13 | class _Package(TypedDict): |
11 | 14 | language: Required[str] |
12 | 15 | name: Required[str] |
13 | 16 | version: Required[str] |
14 | 17 | hash: Required[Optional[str]] |
15 | 18 |
|
16 | | - def __init__(self, ctx, path, /, **attributes: Unpack[_Package]): |
17 | | - super().__init__(ctx, path, **attributes) |
| 19 | + def __init__(self, ctx, /, **attributes: Unpack[_Package]): |
| 20 | + # todo - passing "" is a hack since path isn't needed. Instead, this class should inherit from Resource, but ActiveSequence is designed to operate on Active. That should change. |
| 21 | + super().__init__(ctx, "", **attributes) |
18 | 22 |
|
19 | 23 |
|
20 | | -class Packages(ActiveFinderMethods["Package"], ActiveSequence["Package"]): |
| 24 | +class ContentPackages(ActiveFinderMethods["ContentPackage"], ActiveSequence["ContentPackage"]): |
21 | 25 | """A collection of packages.""" |
22 | 26 |
|
23 | 27 | def __init__(self, ctx, path): |
24 | 28 | super().__init__(ctx, path, "name") |
25 | 29 |
|
26 | 30 | def _create_instance(self, path, /, **attributes): |
27 | | - return Package(self._ctx, path, **attributes) |
| 31 | + return ContentPackage(self._ctx, **attributes) |
| 32 | + |
| 33 | + def find(self, uid): |
| 34 | + raise NotImplementedError("The 'find' method is not support by the Packages API.") |
28 | 35 |
|
29 | 36 | class _FindBy(TypedDict, total=False): |
30 | | - language: NotRequired[str] |
| 37 | + language: NotRequired[Literal["python", "r"]] |
| 38 | + """Programming language ecosystem, options are 'python' and 'r'""" |
| 39 | + |
31 | 40 | name: NotRequired[str] |
| 41 | + """The package name""" |
| 42 | + |
32 | 43 | version: NotRequired[str] |
| 44 | + """The package version""" |
| 45 | + |
33 | 46 | hash: NotRequired[Optional[str]] |
| 47 | + """Package description hash for R packages.""" |
34 | 48 |
|
35 | 49 | @overload |
36 | 50 | def find_by(self, **conditions: Unpack[_FindBy]): |
37 | | - ... |
| 51 | + """ |
| 52 | + Find the first record matching the specified conditions. |
| 53 | +
|
| 54 | + There is no implied ordering, so if order matters, you should specify it yourself. |
| 55 | +
|
| 56 | + Parameters |
| 57 | + ---------- |
| 58 | + **conditions : Unpack[_FindBy] |
| 59 | + Conditions for filtering packages. The following keys are accepted: |
| 60 | +
|
| 61 | + language : {"python", "r"}, not required |
| 62 | + Programming language ecosystem, options are 'python' and 'r' |
| 63 | +
|
| 64 | + name : str, not required |
| 65 | + The package name |
| 66 | +
|
| 67 | + version : str, not required |
| 68 | + The package version |
| 69 | +
|
| 70 | + hash : str or None, optional, not required |
| 71 | + Package description hash for R packages. |
| 72 | +
|
| 73 | + Returns |
| 74 | + ------- |
| 75 | + Optional[T] |
| 76 | + The first record matching the specified conditions, or `None` if no such record exists. |
| 77 | + """ |
38 | 78 |
|
39 | 79 | @overload |
40 | | - def find_by(self, **conditions): |
41 | | - ... |
| 80 | + def find_by(self, **conditions): ... |
42 | 81 |
|
43 | 82 | def find_by(self, **conditions): |
44 | 83 | return super().find_by(**conditions) |
45 | 84 |
|
46 | | -class PackagesMixin(Active): |
| 85 | + |
| 86 | +class ContentPackagesMixin(Active): |
47 | 87 | """Mixin class to add a packages attribute.""" |
48 | 88 |
|
49 | | - def __init__(self, ctx, path, /, **attributes): |
50 | | - """Mixin class which adds a `packages` attribute. |
| 89 | + @property |
| 90 | + @requires(version="2024.11.0") |
| 91 | + def packages(self): |
| 92 | + path = posixpath.join(self._path, "packages") |
| 93 | + return ContentPackages(self._ctx, path) |
| 94 | + |
| 95 | + |
| 96 | +class GlobalPackage(Active): |
| 97 | + class _GlobalPackage(TypedDict): |
| 98 | + language: Required[str] |
| 99 | + name: Required[str] |
| 100 | + version: Required[str] |
| 101 | + hash: Required[Optional[str]] |
| 102 | + |
| 103 | + def __init__(self, ctx, /, **attributes: Unpack[_GlobalPackage]): |
| 104 | + # todo - passing "" is a hack since path isn't needed. Instead, this class should inherit from Resource, but ActiveSequence is designed to operate on Active. That should change. |
| 105 | + super().__init__(ctx, "", **attributes) |
| 106 | + |
| 107 | + |
| 108 | +class GlobalPackages(ContentPackages): |
| 109 | + def __init__(self, ctx, path): |
| 110 | + super().__init__(ctx, path, "name") |
| 111 | + |
| 112 | + def _create_instance(self, path, /, **attributes): |
| 113 | + return ContentPackage(self._ctx, **attributes) |
| 114 | + |
| 115 | + def find(self, uid): |
| 116 | + raise NotImplementedError("The 'find' method is not support by the Packages API.") |
| 117 | + |
| 118 | + class _FindBy(TypedDict, total=False): |
| 119 | + language: NotRequired[Literal["python", "r"]] |
| 120 | + """Programming language ecosystem, options are 'python' and 'r'""" |
| 121 | + |
| 122 | + name: NotRequired[str] |
| 123 | + """The package name""" |
| 124 | + |
| 125 | + version: NotRequired[str] |
| 126 | + """The package version""" |
| 127 | + |
| 128 | + hash: NotRequired[Optional[str]] |
| 129 | + """Package description hash for R packages.""" |
| 130 | + |
| 131 | + def fetch(self, **conditions): |
| 132 | + url = self._ctx.url + self._path |
| 133 | + paginator = Paginator(self._ctx.session, url, conditions) |
| 134 | + results = paginator.fetch_results() |
| 135 | + return [self._create_instance("", **result) for result in results] |
| 136 | + |
| 137 | + @overload |
| 138 | + def find_by(self, **conditions: Unpack[_FindBy]): |
| 139 | + """ |
| 140 | + Find the first record matching the specified conditions. |
| 141 | +
|
| 142 | + There is no implied ordering, so if order matters, you should specify it yourself. |
51 | 143 |
|
52 | 144 | Parameters |
53 | 145 | ---------- |
54 | | - ctx : Context |
55 | | - The context object containing the session and URL for API interactions |
56 | | - path : str |
57 | | - The HTTP path component for the resource endpoint |
58 | | - **attributes : dict |
59 | | - Resource attributes passed |
| 146 | + **conditions : Unpack[_FindBy] |
| 147 | + Conditions for filtering packages. The following keys are accepted: |
| 148 | +
|
| 149 | + language : {"python", "r"}, not required |
| 150 | + Programming language ecosystem, options are 'python' and 'r' |
| 151 | +
|
| 152 | + name : str, not required |
| 153 | + The package name |
| 154 | +
|
| 155 | + version : str, not required |
| 156 | + The package version |
| 157 | +
|
| 158 | + hash : str or None, optional, not required |
| 159 | + Package description hash for R packages. |
| 160 | +
|
| 161 | + Returns |
| 162 | + ------- |
| 163 | + Optional[T] |
| 164 | + The first record matching the specified conditions, or `None` if no such record exists. |
60 | 165 | """ |
61 | | - super().__init__(ctx, path, **attributes) |
62 | 166 |
|
63 | | - path = posixpath.join(path, "packages") |
64 | | - self.packages = Packages(ctx, path) |
| 167 | + @overload |
| 168 | + def find_by(self, **conditions): ... |
| 169 | + |
| 170 | + def find_by(self, **conditions): |
| 171 | + return super().find_by(**conditions) |
0 commit comments