wip docs & cleanup

Author: mortenpi

docs/make.jl

@@ -65,6 +65,7 @@ const PAGES_REFERENCE = [
     "reference/job-submission.md",
     "reference/jobs.md",
     "reference/datasets.md",
+    "reference/projects.md",
     "reference/exceptions.md",
 ]
 Mocking.apply(mocking_patch) do

docs/src/reference/exceptions.md

@@ -24,6 +24,8 @@ InvalidRequestError
 JuliaHubConnectionError
 JuliaHubError
 PermissionError
+ProjectNotSetError
+InvalidJuliaHubVersion
 ```
 
 ## Index

docs/src/reference/projects.md

@@ -0,0 +1,53 @@
+```@meta
+CurrentModule=JuliaHub
+```
+
+# Projects
+
+These APIs allow you to interact with datasets that have been attached to projects.
+
+* [`project_datasets`](@ref) and [`project_dataset`](@ref) let you list and access datasets linked to a project
+* [`upload_project_dataset`](@ref) allows uploading new versions of project-linked datasets
+
+## Automatic project authentication
+
+The [`Authentication`](@ref) object can be associated with a default project UUID, which will
+then be used to for all _project_ operations, unless an explicit `project` gets passed to
+override the default.
+
+Importantly, [`JuliaHub.authenticate`](@ref) will automatically pick up the the JuliaHub
+project UUID from the `JULIAHUB_PROJECT_UUID` environment variable. This means in JuliaHub
+cloud jobs and IDEs, it is not necessary to manually set the project, and JuliaHub.jl
+will automatically.
+However, you can opt-out of this behavior by explicitly passing a `project=nothing` to
+[`JuliaHub.authenticate`](@ref).
+
+If you explicitly
+
+you can always pass `project=
+
+- `JULIAHUB_PROJECT_UUID`
+
+You can always verify that your operations are running in the context of the correct project
+by checking the [`Authentication`](@ref) object, e.g. via [`current_authentication`](@ref):
+
+```wip-jldoctest
+julia> JuliaHub.current_authentication()
+...
+```
+
+## Reference
+
+```@docs
+ProjectDataset
+project_datasets
+project_dataset
+upload_project_dataset
+ProjectReference
+```
+
+## Index
+
+```@index
+Pages = ["project_datasets.md"]
+```

src/authentication.jl

@@ -168,6 +168,7 @@ end
         server::AbstractString = Pkg.pkg_server();
         force::Bool = false,
         maxcount::Integer = $(_DEFAULT_authenticate_maxcount),
+        [project::Union{AbstractString, UUIDs.UUID, Nothing}],
         [hook::Base.Callable]
     ) -> JuliaHub.Authentication
     JuliaHub.authenticate(server::AbstractString, token::Union{AbstractString, JuliaHub.Secret}) -> JuliaHub.Authentication
@@ -201,6 +202,33 @@ The returned [`Authentication`](@ref) object is also cached globally (overwritin
 cached authentications), making it unnecessary to pass the returned object manually to other
 function calls. This is useful for interactive use, but should not be used in library code,
 as different authentication calls may clash.
+
+# Project Context
+
+An [`Authentication`](@ref) object can also specify the default JuliaHub project.
+This can be set by passing the optional `project` argument, which works as follows:
+
+- If the `project` value is not passed, JuliaHub.jl will attempt to pick up the the project UUID
+  from the `JULIAHUB_PROJECT_UUID` environment variable, and will fall back to the non-project
+  context if that is not set.
+
+- If you pass an explicit UUID (either as a string or an `UUID` object), that will then be used
+  as the project. Note that a UUID passed as a string must be a syntactically correct UUID.
+
+- If you pass `nothing`, that make JuliaHub.jl ignore any values in the `JULIAHUB_PROJECT_UUID`
+  environment variable.
+
+!!! note "JULIAHUB_PROJECT_UUID"
+
+    Generally, in JuliaHub jobs and cloud IDE environments that are launched in the context of a
+    project, the `JULIAHUB_PROJECT_UUID` is automatically set, and JuliaHub.jl will pick it up
+    automatically, unless explicitly disabled with `project=nothing`.
+
+!!! warn "Project access checks"
+
+    When the [`Authentication`](@ref) object is constructed, access to or existence of the specified
+    project is not checked. However, if you attempt any project operations with with such an
+    authentication object, they will fail and throw an error.
 """
 function authenticate end
 

src/datasets.jl

@@ -1,9 +1,10 @@
 const _DOCS_nondynamic_datasets_object_warning = """
 !!! warning "Non-dynamic dataset objects"
 
-    [`Dataset`](@ref) objects represents the dataset metadata when the Julia object was created
-    (e.g. with [`dataset`](@ref)), and are not automatically kept up to date. To refresh the dataset
-    metadata, you can pass the existing [`Dataset`](@ref) to [`JuliaHub.dataset`](@ref).
+    [`Dataset`](@ref) and [`ProjectDataset`](@ref) objects represents the dataset metadata when the
+    Julia object was created (e.g. with [`dataset`](@ref)), and are not automatically kept up to date.
+    To refresh the dataset metadata, you can pass the existing [`Dataset`](@ref) to [`JuliaHub.dataset`](@ref),
+    or [`ProjectDataset`](@ref) to [`project_dataset`](@ref).
 """
 
 Base.@kwdef struct _DatasetStorage

src/projects.jl

@@ -1,10 +1,31 @@
+"""
+    struct ProjectNotSetError <: JuliaHubException
+
+Exception thrown when the authentication object is not set to a project, nor was
+an explicit project UUID provided, but the operation requires a project to be
+specified.
+"""
+struct ProjectNotSetError <: JuliaHubException end
+
+function Base.showerror(io::IO, e::ProjectNotSetError)
+    print(io, "ProjectNotSetError: authentication object not associated with a project")
+end
+
+function _assert_projects_enabled(auth::Authentication)
+    # The different project APIs are only present in JuliaHub 6.9 and later.
+    if auth._api_version < v"0.2.0"
+        msg = "Project APIs got added in JuliaHub 6.9 (expected API version >= 0.2.0, got $(auth._api_version), for $(auth.server))"
+        throw(InvalidJuliaHubVersion(msg))
+    end
+end
+
 """
     struct ProjectDataset
 
 A dataset object returned by the functions that return project dataset links.
 
-Has the same fields as [`Dataset`](@ref) plus the following fields
-that are specific to the project-dataset link:
+Has the same fields as [`Dataset`](@ref) plus the following fields that are specific
+to project-dataset links:
 
 - `project_uuid::UUID`: identifies the project in the context of which the dataset was listed
 - `is_writable :: Bool`: whether this dataset has been marked writable by the dataset owner
@@ -53,20 +74,20 @@ function Base.show(io::IO, ::MIME"text/plain", pd::ProjectDataset)
 end
 
 """
-    struct ProjectNotSetError <: JuliaHubException
+    const ProjectReference :: Type
 
-Exception thrown when the authentication object is not set to a project, but the
-operation is meant to take place in the context of a project.
-"""
-struct ProjectNotSetError <: JuliaHubException end
-function Base.showerror(io::IO, e::ProjectNotSetError)
-    print(io, "ProjectNotSetError: authentication object not associated with a project")
-end
+Type constraint on the argument that specifies the project in projects-related
+APIs that (e.g. [`project_datasets`](@ref)).
 
+Presently, you can specify the project by directly passing the project UUID.
+The UUID should be either a string (`<: AbstractString`) or an `UUIDs.UUID` object.
+"""
 const ProjectReference = Union{AbstractString, UUIDs.UUID}
 
 # Parses the standard project::Union{ProjectReference, Nothing} we pass to
 # project_* function into a project UUID object (or throws the appropriate error).
+# If project is nothing, we fall back to the project_id of the authentication object,
+# if present.
 function _project_uuid(auth::Authentication, project::Union{ProjectReference, Nothing})::UUIDs.UUID
     if isnothing(project)
         if isnothing(auth.project_id)
@@ -88,17 +109,22 @@ function _project_uuid(auth::Authentication, project::Union{ProjectReference, No
 end
 
 """
-    JuliaHub.project_dataset(dataset::DatasetReference; [project::ProjectReference], [auth]) -> Dataset
+    JuliaHub.project_dataset(dataset::DatasetReference; [project::ProjectReference], [auth]) -> ProjectDataset
+
+Looks up the specified dataset among the datasets attached to the project, returning a
+[`ProjectDataset`](@ref) object, or throwing an [`InvalidRequestError`](@ref) if the project
+does not have the dataset attached.
 
-Looks up a dataset in the context of a project.
+$(_DOCS_nondynamic_datasets_object_warning)
 """
 function project_dataset end
 
 function project_dataset(
-    dataset::Dataset;
+    dataset::Union{Dataset, ProjectDataset};
     project::Union{ProjectReference, Nothing}=nothing,
     auth::Authentication=__auth__(),
 )
+    _assert_projects_enabled(auth)
     project_uuid = _project_uuid(auth, project)
     datasets = _project_datasets(auth, project_uuid)
     for project_dataset in datasets
@@ -142,9 +168,10 @@ function project_dataset(
 end
 
 """
-    JuliaHub.project_datasets([project::Union{AbstractString, UUID}]; [auth::Authentication]) -> Vector{Dataset}
+    JuliaHub.project_datasets([project::ProjectReference]; [auth::Authentication]) -> Vector{Dataset}
 
-Returns the list of datasets linked to the given project.
+Returns the list of datasets attached to the project, as a list of [`ProjectDataset`](@ref) objects.
+If the project is not explicitly specified, it uses the project of the authentication object.
 """
 function project_datasets end
 
@@ -239,7 +266,7 @@ Uploads a new version of a project-linked dataset.
 function upload_project_dataset end
 
 function upload_project_dataset(
-    ds::Dataset,
+    ds::Union{Dataset, ProjectDataset},
     local_path::AbstractString;
     progress::Bool=true,
     project::Union{ProjectReference, Nothing}=nothing,
@@ -281,8 +308,16 @@ function upload_project_dataset(
 end
 
 function upload_project_dataset(
-    ::Union{_DatasetRefTuple, AbstractString}
+    dataset::Union{_DatasetRefTuple, AbstractString},
+    local_path::AbstractString;
+    progress::Bool=true,
+    project::Union{ProjectReference, Nothing}=nothing,
+    # Authentication
+    auth::Authentication=__auth__(),
 )
+    project_uuid = _project_uuid(auth, project)
+    dataset = project_dataset(dataset; project=project_uuid, auth)
+    return upload_project_dataset(dataset, local_path; progress, project=project_uuid, auth)
 end
 
 # This calls the /datasets/{uuid}/versions?project={uuid} endpoint,

src/utils.jl

@@ -94,6 +94,25 @@ function Base.showerror(io::IO, e::PermissionError)
     isnothing(e.response) || print(io, '\n', e.response)
 end
 
+"""
+    struct InvalidJuliaHubVersion <: JuliaHubException
+
+Thrown if the requested operation is not supported by the JuliaHub instance.
+`.msg` contains a more detailed error message.
+
+!!! tip
+
+    This generally means that the functionality you are attempting to use requires a
+    newer JuliaHub version.
+"""
+struct InvalidJuliaHubVersion <: JuliaHubException
+    msg::String
+end
+
+function Base.showerror(io::IO, e::InvalidJuliaHubVersion)
+    print(io, "InvalidJuliaHubVersion: $(e.msg)")
+end
+
 _takebody!(r::HTTP.Response)::Vector{UInt8} = isa(r.body, IO) ? take!(r.body) : r.body
 _takebody!(r::HTTP.Response, ::Type{T}) where {T} = T(_takebody!(r))