Feature implementation, code refactoring, new test suite and increasing code coverage (#27)

* uploading refactoring; implementing and separating test cases

* general searchrun tests and code formatting

* empty commit to test

* Adding coverage and improving test suite

* Adding new features, test reimplementation and code coverage increase

* fix to test, removing unused implementation, and updates to get documenter working

* changed Project.toml entries and fixed a test to work with all kind of exceptions

* up corrections

Author: pebeto

.gitignore

@@ -4,3 +4,4 @@
 Manifest.toml
 /docs/build/
 mlruns
+coverage

Project.toml

@@ -14,11 +14,11 @@ UUIDs = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
 
 [compat]
 FilePathsBase = "0.9"
-HTTP = "0.9,1.2"
+HTTP = "1.9"
 JSON = "0.21"
 ShowCases = "0.1"
-URIs = "1"
-julia = "1"
+URIs = "1.0"
+julia = "1.0"
 
 [extras]
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

docs/make.jl

@@ -11,16 +11,16 @@ makedocs(;
     format=Documenter.HTML(;
         prettyurls=get(ENV, "CI", "false") == "true",
         canonical="https://juliaai.github.io/MLFlowClient.jl",
-        assets=String[],
+        assets=String[]
     ),
     pages=[
         "Home" => "index.md",
         "Tutorial" => "tutorial.md",
         "Reference" => "reference.md"
-    ],
+    ]
 )
 
 deploydocs(;
     repo="github.com/JuliaAI/MLFlowClient.jl",
-    devbranch="main",
+    devbranch="main"
 )

docs/src/reference.md

@@ -26,8 +26,9 @@ MLFlowArtifactDirInfo
 createexperiment
 getexperiment
 getorcreateexperiment
-listexperiments
 deleteexperiment
+searchexperiments
+listexperiments
 ```
 
 # Runs
@@ -50,5 +51,8 @@ listartifacts
 mlfget
 mlfpost
 uri
+generatefilterfromentity_type
 generatefilterfromparams
+generatefilterfromattributes
+
 ```

src/MLFlowClient.jl

@@ -20,19 +20,25 @@ using JSON
 using ShowCases
 using FilePathsBase: AbstractPath
 
-include("types.jl")
+include("types/core.jl")
 export
     MLFlow,
-    MLFlowExperiment,
+    MLFlowExperiment
+
+include("types/runs.jl")
+export
     MLFlowRunStatus,
     MLFlowRunInfo,
-    get_run_id,
-    MLFlowRunData,
-    get_params,
     MLFlowRunDataMetric,
+    MLFlowRunData,
     MLFlowRun,
     get_info,
     get_data,
+    get_run_id,
+    get_params
+
+include("types/artifacts.jl")
+export
     MLFlowArtifactFileInfo,
     MLFlowArtifactDirInfo,
     get_path,
@@ -41,25 +47,29 @@ export
 include("utils.jl")
 export
     generatefilterfromparams
+    generatefilterfromattributes
+    generatefilterfromentity_type
 
 include("experiments.jl")
 export
     createexperiment,
     getexperiment,
     getorcreateexperiment,
     deleteexperiment,
-    listexperiments
+    searchexperiments
 
 include("runs.jl")
 export
     createrun,
     getrun,
     updaterun,
     deleterun,
-    searchruns,
+    searchruns
+
+include("loggers.jl")
+export
     logparam,
     logmetric,
     logartifact,
     listartifacts
-
 end

src/deprecated.jl

@@ -0,0 +1,12 @@
+"""
+    listexperiments(mlf::MLFlow)
+
+Returns a list of MLFlow experiments.
+
+Deprecated (last MLFlow version: 1.30.1) in favor of [`searchexperiments`](@ref).
+"""
+
+function listexperiments(mlf::MLFlow)
+endpoint = "experiments/list"
+    mlfget(mlf, endpoint)
+end

src/experiments.jl

@@ -73,12 +73,12 @@ function getexperiment(mlf::MLFlow, experiment_name::String)
 end
 function _getexperimentbyid(mlf::MLFlow, experiment_id::Integer)
     endpoint = "experiments/get"
-    arguments = (:experiment_id => experiment_id, )
+    arguments = (:experiment_id => experiment_id,)
     mlfget(mlf, endpoint; arguments...)["experiment"]
 end
 function _getexperimentbyname(mlf::MLFlow, experiment_name::String)
     endpoint = "experiments/get-by-name"
-    arguments = (:experiment_name => experiment_name, )
+    arguments = (:experiment_name => experiment_name,)
     mlfget(mlf, endpoint; arguments...)["experiment"]
 end
 
@@ -147,13 +147,59 @@ deleteexperiment(mlf::MLFlow, experiment::MLFlowExperiment) =
     deleteexperiment(mlf, experiment.experiment_id)
 
 """
-    listexperiments(mlf::MLFlow)
+    searchexperiments(mlf::MLFlow)
 
-Returns a list of MLFlow experiments.
+Searches for experiments in an MLFlow instance.
+
+# Arguments
+- `mlf`: [`MLFlow`](@ref) configuration.
+
+# Keywords
+- `filter::String`: filter as defined in [MLFlow documentation](https://mlflow.org/docs/latest/rest-api.html#search-experiments)
+- `filter_attributes::AbstractDict{K,V}`: if provided, `filter` is automatically generated based on `filter_attributes` using [`generatefilterfromattributes`](@ref). One can only provide either `filter` or `filter_attributes`, but not both.
+- `run_view_type::String`: one of `ACTIVE_ONLY`, `DELETED_ONLY`, or `ALL`.
+- `max_results::Integer`: 50,000 by default.
+- `order_by::String`: as defined in [MLFlow documentation](https://mlflow.org/docs/latest/rest-api.html#search-experiments)
+- `page_token::String`: paging functionality, handled automatically. Not meant to be passed by the user.
+
+# Returns
+- vector of [`MLFlowExperiment`](@ref) experiments that were found in the MLFlow instance
 
-TODO: not yet entirely implemented
 """
-function listexperiments(mlf::MLFlow)
-    endpoint = "experiments/list"
-    mlfget(mlf, endpoint)
+function searchexperiments(mlf::MLFlow;
+    filter::String="",
+    filter_attributes::AbstractDict{K,V}=Dict{}(),
+    run_view_type::String="ACTIVE_ONLY",
+    max_results::Int64=50000,
+    order_by::AbstractVector{<:String}=["attribute.last_update_time"],
+    page_token::String=""
+) where {K,V}
+    endpoint = "experiments/search"
+    run_view_type ∈ ["ACTIVE_ONLY", "DELETED_ONLY", "ALL"] || error("Unsupported run_view_type = $run_view_type")
+
+    if length(filter_attributes) > 0 && length(filter) > 0
+        error("Cannot specify both filter and filter_attributes")
+    end
+
+    if length(filter_attributes) > 0
+        filter = generatefilterfromattributes(filter_attributes)
+    end
+
+    kwargs = (; filter, run_view_type, max_results, order_by)
+    if !isempty(page_token)
+        kwargs = (; kwargs..., page_token=page_token)
+    end
+
+    result = mlfpost(mlf, endpoint; kwargs...)
+    haskey(result, "experiments") || return MLFlowExperiment[]
+
+    experiments = map(x -> MLFlowExperiment(x), result["experiments"])
+
+    if haskey(result, "next_page_token") && !isempty(result["next_page_token"])
+        kwargs = (; filter, run_view_type, max_results, order_by, page_token=result["next_page_token"])
+        next_experiments = searchexperiments(mlf; kwargs...)
+        return vcat(experiments, next_experiments)
+    end
+
+    experiments
 end