Skip to content

Commit a6894dd

Browse files
schloerkeschloerke
authored
docs: Add docs for ContentItem information (#374)
1 parent e605767 commit a6894dd

File tree

1 file changed

+273
-3
lines changed

1 file changed

+273
-3
lines changed

‎src/posit/connect/content.py‎

Lines changed: 273 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,8 @@ class _AttrsBase(TypedDict, total=False):
6565
title: NotRequired[str]
6666
description: NotRequired[str]
6767
access_type: NotRequired[Literal["all", "acl", "logged_in"]]
68+
locked: NotRequired[bool]
69+
locked_message: NotRequired[str]
6870
# Timeout Settings
6971
connection_timeout: NotRequired[int]
7072
read_timeout: NotRequired[int]
@@ -81,13 +83,35 @@ class _AttrsBase(TypedDict, total=False):
8183
memory_limit: NotRequired[int]
8284
amd_gpu_limit: NotRequired[int]
8385
nvidia_gpu_limit: NotRequired[int]
84-
# Execution Settings
85-
run_as: NotRequired[str]
86-
run_as_current_user: NotRequired[bool]
86+
# Bundle info
87+
content_category: NotRequired[str]
88+
parameterized: NotRequired[bool]
89+
cluster_name: NotRequired[str]
90+
image_name: NotRequired[str]
8791
default_image_name: NotRequired[str]
8892
default_r_environment_management: NotRequired[bool]
8993
default_py_environment_management: NotRequired[bool]
9094
service_account_name: NotRequired[str]
95+
r_version: NotRequired[str]
96+
r_environment_management: NotRequired[bool]
97+
py_version: NotRequired[str]
98+
py_environment_management: NotRequired[bool]
99+
quarto_version: NotRequired[str]
100+
# Execution Settings
101+
run_as: NotRequired[str]
102+
run_as_current_user: NotRequired[bool]
103+
created_time: NotRequired[str]
104+
last_deployed_time: NotRequired[str]
105+
bundle_id: NotRequired[str]
106+
app_mode: NotRequired[str]
107+
content_url: NotRequired[str]
108+
dashboard_url: NotRequired[str]
109+
app_role: NotRequired[Literal["owner", "editor", "viewer", "none"]]
110+
vanity_url: NotRequired[str]
111+
tags: NotRequired[List[dict]]
112+
owner: NotRequired[dict]
113+
id: NotRequired[str]
114+
extension: NotRequired[bool]
91115

92116
class _AttrsNotRequired(_AttrsBase):
93117
name: NotRequired[str]
@@ -128,6 +152,252 @@ def __init__(
128152
guid: str,
129153
**kwargs: Unpack[ContentItem._AttrsNotRequired],
130154
) -> None:
155+
"""
156+
Content item.
157+
158+
The content object models all the "things" you may deploy to Posit
159+
Connect. This includes Shiny applications, R Markdown documents, Jupyter notebooks,
160+
Plumber APIs, FastAPI and Flask APIs, Python apps, plots, and pins.
161+
162+
The `app_mode` field specifies the type of content represented by this item
163+
and defines its runtime model.
164+
165+
* Active content, such as apps and APIs, executes on demand as requests arrive.
166+
* Reports render from source to output HTML. This rendering can occur based on a
167+
schedule or when explicitly triggered. It is *not* on each visit. Viewers of this type of
168+
content see a previously rendered result.
169+
* Static content is presented to viewers in its deployed form.
170+
171+
The fields `bundle_id`, `app_mode`, `content_category`, `parameterized`, `cluster_name`,
172+
`image_name`, `r_version`, `r_environment_management`, `py_version`,
173+
`py_environment_management`, and `quarto_version` are computed as a consequence of a <a
174+
href="#post-/v1/content/-guid-/deploy">POST /v1/content/{guid}/deploy</a> deployment
175+
operation.
176+
177+
Parameters
178+
----------
179+
ctx : Context
180+
Context object.
181+
guid : str
182+
The unique identifier of this content item.
183+
name: str, optional
184+
A simple, URL-friendly identifier. Allows alpha-numeric characters, hyphens ("-"), and
185+
underscores ("_").
186+
title : str, optional
187+
The title of this content.
188+
description : str, optional
189+
A rich description of this content.
190+
access_type : Literal['all', 'acl', 'logged_in'], optional
191+
Access type describes how this content manages its viewers. The value `all` is the most
192+
permissive; any visitor to Posit Connect will be able to view this content. The value
193+
`logged_in` indicates that all Posit Connect accounts may view the content. The `acl`
194+
value lets specifically enumerated users and groups view the content. Users configured
195+
as collaborators may always view content.
196+
locked : bool, optional
197+
Whether or not the content is locked.
198+
locked_message : str, optional
199+
A custom message that is displayed by the content item when locked. It is possible to
200+
format this message using Markdown.
201+
connection_timeout : int, optional
202+
Maximum number of seconds allowed without data sent or received across a client
203+
connection. A value of `0` means connections will never time-out (not recommended).
204+
When `null`, the default `Scheduler.ConnectionTimeout` is used. Applies only to content
205+
types that are executed on demand.
206+
read_timeout : int, optional
207+
Maximum number of seconds allowed without data received from a client connection. A
208+
value of `0` means a lack of client (browser) interaction never causes the connection
209+
to close. When `null`, the default `Scheduler.ReadTimeout` is used. Applies only to
210+
content types that are executed on demand.
211+
init_timeout : int, optional
212+
The maximum number of seconds allowed for an interactive application to start. Posit
213+
Connect must be able to connect to a newly launched application before this threshold
214+
has elapsed. When `null`, the default `Scheduler.InitTimeout` is used. Applies only to
215+
content types that are executed on demand.
216+
idle_timeout : int, optional
217+
The maximum number of seconds a worker process for an interactive application to remain
218+
alive after it goes idle (no active connections). When `null`, the default
219+
`Scheduler.IdleTimeout` is used. Applies only to content types that are executed on
220+
demand.
221+
max_processes : int, optional
222+
Specifies the total number of concurrent processes allowed for a single interactive
223+
application per Posit Connect node. When `null`, the default `Scheduler.MaxProcesses`
224+
is used. Applies only to content types that are executed on demand.
225+
min_processes : int, optional
226+
Specifies the minimum number of concurrent processes allowed for a single interactive
227+
application per Posit Connect node. When `null`, the default `Scheduler.MinProcesses`
228+
is used. Applies only to content types that are executed on demand.
229+
max_conns_per_process : int, optional
230+
Specifies the maximum number of client connections allowed to an individual process.
231+
Incoming connections which will exceed this limit are routed to a new process or
232+
rejected. When `null`, the default `Scheduler.MaxConnsPerProcess` is used. Applies only
233+
to content types that are executed on demand.
234+
load_factor : float, optional
235+
Controls how aggressively new processes are spawned. When `null`, the default
236+
`Scheduler.LoadFactor` is used. Applies only to content types that are executed on
237+
demand.
238+
cpu_request : float, optional
239+
The minimum amount of compute power this content needs when executing or rendering,
240+
expressed in ["CPU
241+
Units"](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu),
242+
where 1.0 unit is equivalent to 1 physical or virtual core. Fractional values are
243+
allowed. This is used when running in an off-host execution configuration to determine
244+
where the content should be run. When `null`, the default `Scheduler.CPURequest` is
245+
used.
246+
cpu_limit : float, optional
247+
The maximum amount of compute power this content will be allowed to consume when
248+
executing or rendering, expressed in ["CPU
249+
Units"](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu),
250+
where 1.0 unit is equivalent to 1 physical or virtual core. Fractional values are
251+
allowed. This is used when running in an off-host execution configuration. If the
252+
process tries to use more CPU than allowed, it will be throttled. When `null`, the
253+
default `Scheduler.CPULimit` is used.
254+
memory_request : int, optional
255+
The minimum amount of RAM this content needs when executing or rendering, expressed in
256+
bytes. This is used when running in an off-host execution configuration to determine
257+
where the content should be run. When `null`, the default `Scheduler.MemoryRequest` is
258+
used.
259+
memory_limit : int, optional
260+
The maximum amount of RAM this content will be allowed to consume when executing or
261+
rendering, expressed in bytes. If the process tries to use more memory than allowed, it
262+
will be terminated. When `null`, the default `Scheduler.MemoryLimit` is used.
263+
amd_gpu_limit : int, optional
264+
The number of AMD GPUs that will be [allocated by
265+
Kubernetes](https://kubernetes.io/docs/tasks/manage-gpus/scheduling-gpus/) to run this
266+
content. This is used when running in an off-host execution configuration. When `null`,
267+
the default `Scheduler.AMDGPULimit` is used. This setting can not exceed
268+
`Scheduler.MaxAMDGPULimit`.
269+
nvidia_gpu_limit : int, optional
270+
The number of NVIDIA GPUs that will be [allocated by
271+
Kubernetes](https://kubernetes.io/docs/tasks/manage-gpus/scheduling-gpus/) to run this
272+
content. This is used when running in an off-host execution configuration. When `null`,
273+
the default `Scheduler.NvidiaGPULimit` is used. This setting can not exceed
274+
`Scheduler.MaxNvidiaGPULimit`.
275+
created_time : str, optional
276+
The timestamp (RFC3339) indicating when this content was created.
277+
last_deployed_time : str, optional
278+
The timestamp (RFC3339) indicating when this content last had a successful bundle
279+
deployment performed.
280+
bundle_id : str, optional
281+
The identifier for the active deployment bundle. Automatically assigned upon the
282+
successful deployment of that bundle.
283+
app_mode : Literal['api', 'jupyter-static', 'jupyter-voila', 'python-api', 'python-bokeh', 'python-dash', 'python-fastapi', 'python-shiny', 'python-streamlit', 'quarto-shiny', 'quarto-static', 'rmd-shiny', 'rmd-static', 'shiny', 'static', 'tensorflow-saved-model', 'unknown'], optional
284+
The runtime model for this content. Has a value of `unknown` before data is deployed to
285+
this item. Automatically assigned upon the first successful bundle deployment.
286+
content_category : str, optional
287+
Describes the specialization of the content runtime model. Automatically assigned upon
288+
the first successful bundle deployment.
289+
parameterized : bool, optional
290+
True when R Markdown rendered content allows parameter configuration. Automatically
291+
assigned upon the first successful bundle deployment. Applies only to content with an
292+
`app_mode` of `rmd-static`.
293+
cluster_name : str, optional
294+
The location where this content runs. Content running on the same server as Connect
295+
will have either a `null` value or the string "Local". Gives the name of the cluster
296+
when run external to the Connect host. A `null` value is returned when the client does
297+
not have sufficient rights to see this information.
298+
image_name : str, optional
299+
The location where this content runs. Content running on the same server as Connect
300+
will have either a `null` value or the string "Local". References the name of the
301+
target image when content runs in a clustered environment such as Kubernetes. A `null`
302+
value is returned when the client does not have sufficient rights to see this
303+
information.
304+
default_image_name : str, optional
305+
The default image that will be used when none is defined by the bundle's manifest. A
306+
specific image may be selected by setting the `environment.image` field in the
307+
manifest. If no image is selected by the manifest file, then the `default_image_name`
308+
is used. If a target image is not defined by the manifest, and no `default_image_name`
309+
is configured, then Connect will select an image from the list of configured execution
310+
environments. A `null` value is returned when the client does not have sufficient
311+
rights to see this information. Use the `/v1/environments` API endpoints to determine
312+
which environments are available for content execution.
313+
default_r_environment_management : bool, optional
314+
Indicates whether or not Connect should create and manage an R environment (installing
315+
required packages) for this content. When `null`, Connect makes this determination
316+
based on the server configuration. A `null` value is also returned when the client does
317+
not have sufficient rights to see this information. This value is ignored if the server
318+
setting `Applications.DefaultEnvironmentManagementSelection` is disabled.
319+
default_py_environment_management : bool, optional
320+
Indicates whether or not Connect should create and manage a Python environment
321+
(installing required packages) for this content. When `null`, Connect makes this
322+
determination based on the server configuration. A `null` value is also returned when
323+
the client does not have sufficient rights to see this information. This value is
324+
ignored if the server setting `Applications.DefaultEnvironmentManagementSelection` is
325+
disabled.
326+
service_account_name : str, optional
327+
The name of the Kubernetes service account that is used to run a particular piece of
328+
content. It must adhere to valid Kubernetes service account naming rules. Connect must
329+
be configured to run with `Launcher.Enabled = true`, `Launcher.Kubernetes = true` and
330+
`Launcher.KubernetesContentServiceAccountSelection = true` for this value to be
331+
applied. It will have precedence over the `Launcher.KubernetesDefaultServiceAccount`
332+
that may be set in the configuration for Connect. If this value is defined and Connect
333+
is configured with `Launcher.KubernetesContentServiceAccountSelection = false` an error
334+
will be returned. Only administrators and publishers can view this value. Only
335+
administrators can set or change this value.
336+
r_version : str, optional
337+
The of R interpreter associated with this content. A `null` value represents that R is
338+
not used by this content, that the content has not been prepared for execution, or that
339+
the client does not have sufficient rights to see this information. Automatically
340+
assigned upon the successful deployment of a bundle.
341+
r_environment_management : bool, optional
342+
Indicates whether or not Connect is managing an R environment and has installed the
343+
required packages for this content. A `null` value represents that R is not used by
344+
this content, that the content has not been prepared for execution, or that the client
345+
does not have sufficient rights to see this information. Automatically assigned upon
346+
the successful deployment of a bundle.
347+
py_version : str, optional
348+
The version of Python associated with this content. A `null` value represents that
349+
Python is not used by this content, that the content has not been prepared for
350+
execution, or that the client does not have sufficient rights to see this information.
351+
Automatically assigned upon the successful deployment of a bundle.
352+
py_environment_management : bool, optional
353+
Indicates whether or not Connect is managing a Python environment and has installed the
354+
required packages for this content. A `null` value represents that Python is not used
355+
by this content, that the content has not been prepared for execution, or that the
356+
client does not have sufficient rights to see this information. Automatically assigned
357+
upon the successful deployment of a bundle.
358+
quarto_version : str, optional
359+
The version of Quarto associated with this content. A `null` represents that Quarto is
360+
not used by this content, that the content has not been prepared for execution, or that
361+
the client does not have sufficient rights to see this information. Automatically
362+
assigned upon the successful deployment of a bundle.
363+
run_as : str, optional
364+
The UNIX user that executes this content. When `null`, the default `Applications.RunAs`
365+
is used. Applies only to executable content types - not `static`.
366+
run_as_current_user : bool, optional
367+
Indicates that Connect should run processes for this content item under the Unix
368+
account of the user who visits it. Content accessed anonymously will continue to run as
369+
the specified `run_as` user. Connect must be configured to use PAM authentication with
370+
the server settings `Applications.RunAsCurrentUser = true` and `PAM.ForwardPassword =
371+
true`. This setting has no effect for other authentication types. This setting only
372+
applies to application content types (Shiny, Dash, Streamlit, and Bokeh).
373+
owner_guid : str, optional
374+
The unique identifier of the user who owns this content item.
375+
content_url : str, optional
376+
The URL associated with this content. Computed from the associated GUID for this
377+
content.
378+
dashboard_url : str, optional
379+
The URL within the Connect dashboard where this content can be configured. Computed
380+
from the GUID for this content.
381+
app_role : Literal['owner', 'editor', 'viewer', 'none'], optional
382+
The relationship of the accessing user to this content. A value of `owner` is returned
383+
for the content owner. `editor` indicates a collaborator. The `viewer` value is given
384+
to users who are permitted to view the content. A `none` role is returned for
385+
administrators who cannot view the content but are permitted to view its configuration.
386+
Computed at the time of the request.
387+
vanity_url : str, optional
388+
The vanity URL associated with this content item. Included in responses when the vanity
389+
URL is set and `include=vanity_url` is provided.
390+
tags : List[Tag], optional
391+
Tags associated with this content item. Included in responses when `include=tags` is
392+
provided.
393+
owner : ContentItemOwner, optional
394+
Basic details about the owner of this content item. Included in responses when
395+
`include=owner` is provided.
396+
id : str, optional
397+
The internal numeric identifier of this content item.
398+
extension : bool, optional
399+
Whether the content is a Connect Extension.
400+
"""
131401
_assert_guid(guid)
132402

133403
path = f"v1/content/{guid}"

0 commit comments

Comments
 (0)