Merge pull request #129 from drbergman/deprecate-kwargs

deprecate kwargs in connectedComponents

Author: drbergman

.github/workflows/CI.yml

@@ -113,6 +113,8 @@ jobs:
         PCVCT_PUBLIC_REPO_AUTH: ${{ secrets.PUBLIC_REPO_AUTH }}
 
     - uses: julia-actions/julia-processcoverage@v1
+      with:
+        directories: src,deps
 
     - uses: codecov/codecov-action@v5
       with:

.gitignore

@@ -4,6 +4,7 @@ test.jl
 *.db
 .vscode
 studio_debug.log
+/temp
 
 # from PkgTemplate.jl
 *.jl.*.cov

Project.toml

@@ -20,6 +20,7 @@ LazyGrids = "7031d0ef-c40d-4431-b2f8-61a8d2f650db"
 LightXML = "9c8b4983-aa76-5018-a973-4c85ecc9e179"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 MAT = "23992714-dd62-5051-b70f-ba57cb901cac"
+MacroTools = "1914dd2f-81c6-5fcd-8719-6d5c9610ff09"
 MetaGraphsNext = "fa8bd995-216d-47f1-8a91-f3b68fbeb377"
 PairCorrelationFunction = "1da3c5ec-5de6-497d-83f1-8bbf7fdc92ec"
 Parameters = "d96e819e-fc66-5662-9728-84c9c7592b0a"
@@ -52,6 +53,7 @@ LazyGrids = "1"
 LightXML = "0.9"
 LinearAlgebra = "1.10 - 1"
 MAT = "0.10"
+MacroTools = "0.5.16"
 MetaGraphsNext = "0.7.2"
 PairCorrelationFunction = "0.0.11"
 Parameters = "0.12"

codecov.yml

@@ -1,3 +1,2 @@
 ignore:
-  - "src/public.jl"
-  - "src/up.jl"
+  - "src/up.jl"

deps/DeprecateKeywords.jl

@@ -0,0 +1,154 @@
+module DeprecateKeywords
+
+using MacroTools
+
+"""
+    @depkws [force=false] def
+
+Macro to deprecate keyword arguments. Use by wrapping a function signature,
+while using `@deprecate(old_kw, new_kw)` within the function signature to deprecate.
+
+# Examples
+
+```julia
+@depkws function f(; a=2, @deprecate(b, a))
+    a
+end
+```
+
+```julia
+# force the deprecation warning to be emitted
+@depkws force=true function f(; a=2, @deprecate(b, a))
+    a
+end
+```
+"""
+macro depkws(args...)
+    options = parse_options(args[1:end-1])
+    return esc(_depkws(args[end], options))
+end
+
+function parse_options(args)
+    options = default_options()
+    for arg in args
+        if isa(arg, Expr) && arg.head == :(=)
+            @assert arg.args[1] ∈ keys(options) "Unknown option: $(arg.args[1])"
+            options[arg.args[1]] = arg.args[2]
+        else
+            error("Invalid option: $arg")
+        end
+    end
+    return options
+end
+
+function default_options()
+    return Dict{Symbol, Any}(:force => false)
+end
+
+abstract type DeprecatedDefault end
+
+function _depkws(def, options)
+    sdef = splitdef(def)
+    func_symbol = Expr(:quote, sdef[:name])  # Double quote for expansion
+
+    new_symbols = Symbol[]
+    deprecated_symbols = Symbol[]
+    kwargs_to_remove = Int[]
+    for (i, param) in enumerate(sdef[:kwargs])
+        isa(param, Symbol) && continue
+        # Look for @deprecated macro:
+        if param.head == :macrocall && param.args[1] == Symbol("@deprecate")
+            # e.g., params.args[2] is the line number
+            deprecated_symbol = param.args[end-1]
+            new_symbol = param.args[end]
+            if !isa(new_symbol, Symbol)
+                # Remove line numbers nodes:
+                clean_param = deepcopy(param)
+                filter!(x -> !isa(x, LineNumberNode), clean_param.args)
+                error(
+                    "The expression\n    $(clean_param)\ndoes not appear to be two symbols in a `@deprecate`. This can happen if you use `@deprecate` in a function " *
+                    "definition without " *
+                    "parentheses, such as `f(; @deprecate a b, c=2)`. Instead, you should write `f(; (@deprecate a b), c=2)` or alternatively " *
+                    "`f(; @deprecate(a, b), c=2)`.)"
+                )
+            end
+            push!(deprecated_symbols, deprecated_symbol)
+            push!(new_symbols, new_symbol)
+            push!(kwargs_to_remove, i)
+        end
+    end
+    deleteat!(sdef[:kwargs], kwargs_to_remove)
+
+    # Add deprecated kws:
+    for deprecated_symbol in deprecated_symbols
+        pushfirst!(sdef[:kwargs], Expr(:kw, deprecated_symbol, DeprecatedDefault))
+    end
+
+    symbol_mapping = Dict(new_symbols .=> deprecated_symbols)
+
+    # Update new symbols to use deprecated kws if passed:
+    for (i, kw) in enumerate(sdef[:kwargs])
+        no_default_type_assertion = !isa(kw, Symbol) && kw.head != :kw
+        no_default_naked = isa(kw, Symbol)
+        no_default = no_default_naked || no_default_type_assertion
+
+        (kw, type_assertion) = if no_default_type_assertion
+            @assert kw.head == :(::)
+            # Remove type assertion from keyword; we will
+            # assert it later.
+            kw.args
+        else
+            (kw, Nothing)
+        end
+
+        new_kw, default = if no_default
+            (kw, DeprecatedDefault)
+        else
+            (kw.args[1], kw.args[2])
+        end
+
+
+        _get_symbol(new_kw) in deprecated_symbols && continue
+        !(_get_symbol(new_kw) in new_symbols) && continue
+
+        deprecated_symbol = symbol_mapping[_get_symbol(new_kw)]
+        depwarn_string = "Keyword argument `$(deprecated_symbol)` is deprecated. Use `$(_get_symbol(new_kw))` instead."
+        new_kwcall = quote
+            if $deprecated_symbol !== $(DeprecatedDefault)
+                Base.depwarn($depwarn_string, $func_symbol; force=$(options[:force]))
+                $deprecated_symbol
+            else
+                $default
+            end
+        end
+        sdef[:kwargs][i] = Expr(:kw, new_kw, new_kwcall)
+
+        if no_default_type_assertion
+            pushfirst!(
+                sdef[:body].args,
+                Expr(:(::), _get_symbol(new_kw), type_assertion)
+            )
+        end
+
+        if no_default
+            # Propagate UndefKeywordError
+            pushfirst!(
+                sdef[:body].args,
+                Expr(:if,
+                    Expr(:call, :(===), _get_symbol(new_kw), DeprecatedDefault),
+                    Expr(:call, :throw,
+                        Expr(:call, :UndefKeywordError, QuoteNode(_get_symbol(new_kw)))
+                    )
+                )
+            )
+        end
+    end
+
+    return combinedef(sdef)
+end
+
+# This is used to go from a::Int to a
+_get_symbol(e::Expr) = first(map(_get_symbol, e.args))
+_get_symbol(e::Symbol) = e
+
+end

docs/src/lib/deprecate_keywords.md

@@ -0,0 +1,21 @@
+```@meta
+CollapsedDocStrings = true
+```
+
+# Deprecate Keywords
+
+A light edit of the [DeprecateKeywords.jl](https://github.com/MilesCranmer/DeprecateKeywords.jl) package to enable the deprecation warnings for users.
+
+## Public API
+```@autodocs
+Modules = [pcvct.DeprecateKeywords]
+Pages = ["DeprecateKeywords.jl"]
+Private = false
+```
+
+## Private API
+```@autodocs
+Modules = [pcvct.DeprecateKeywords]
+Pages = ["DeprecateKeywords.jl"]
+Public = false
+```

docs/src/man/covariations.md

@@ -44,8 +44,7 @@ using pcvct
 timing_1_path = configPath("user_parameters", "event_1_time")
 timing_2_path = configPath("user_parameters", "event_2_time")
 dv1 = UniformDistributedVariation(timing_1_path, 100.0, 200.0)
-flip = true
-dv2 = UniformDistributedVariation(timing_2_path, 100.0, 200.0, flip)
+dv2 = UniformDistributedVariation(timing_2_path, 100.0, 200.0; flip=true)
 covariation = CoVariation(dv1, dv2)
 cdf = 0.1
 pcvct.variationValues.(covariation.variations, cdf) # pcvct internal for getting values for an ElementaryVariation

src/analysis/graphs.jl

@@ -1,5 +1,8 @@
 using Graphs, MetaGraphsNext
 
+include(joinpath(@__DIR__, "..", "..", "deps", "DeprecateKeywords.jl"))
+import .DeprecateKeywords: @depkws
+
 export connectedComponents
 
 """
@@ -34,25 +37,15 @@ For each key, the value is a list of connected components in the graph.
 Each component is represented as a vector of vertex labels.
 As of this writing, the vertex labels are the simple `AgentID` class that wraps the cell ID.
 """
-function connectedComponents(snapshot::PhysiCellSnapshot, graph::Symbol=:neighbors; include_cell_type_names=:all_in_one, exclude_cell_type_names=String[], include_dead::Bool=false,
-                             include_cell_types=nothing, exclude_cell_types=nothing)
+@depkws force=true function connectedComponents(snapshot::PhysiCellSnapshot, graph::Symbol=:neighbors; include_cell_type_names=:all_in_one, exclude_cell_type_names=String[], include_dead::Bool=false,
+    @deprecate(include_cell_types, include_cell_type_names), @deprecate(exclude_cell_types, exclude_cell_type_names))
     is_all_in_one = include_cell_type_names == :all_in_one
     cell_type_to_name_dict = cellTypeToNameDict(snapshot)
     cell_type_names = values(cell_type_to_name_dict) |> collect
 
-    if !isnothing(include_cell_types)
-        @assert include_cell_type_names == :all_in_one "Do not use both `include_cell_types` and `include_cell_type_names` as keyword arguments. Use `include_cell_type_names` instead."
-        Base.depwarn("`include_cell_types` is deprecated as a keyword. Use `include_cell_type_names` instead.", :connectedComponents, force=true)
-        include_cell_type_names = include_cell_types
-    end
     include_cell_type_names = processIncludeCellTypes(include_cell_type_names, cell_type_names)
-
-    if !isnothing(exclude_cell_types)
-        @assert exclude_cell_type_names == String[] "Do not use both `exclude_cell_types` and `exclude_cell_type_names` as keyword arguments. Use `exclude_cell_type_names` instead."
-        Base.depwarn("`exclude_cell_types` is deprecated as a keyword. Use `exclude_cell_type_names` instead.", :connectedComponents, force=true)
-        exclude_cell_type_names = exclude_cell_types
-    end
     exclude_cell_type_names = processExcludeCellTypes(exclude_cell_type_names)
+
     loadGraph!(snapshot, graph)
     if is_all_in_one
         G = getfield(snapshot, graph) |> deepcopy

src/analysis/substrate.jl

@@ -77,6 +77,7 @@ asts = pcvct.AverageSubstrateTimeSeries(1) # Load average substrate time series
 asts.time # Get the time points
 asts["time"] # alternative way to get the time points
 asts["oxygen"] # Get the oxygen concentration over time
+```
 """
 struct AverageSubstrateTimeSeries
     simulation_id::Int

src/configuration.jl

@@ -998,7 +998,7 @@ function rulePath(cell_definition::AbstractString, behavior::AbstractString, pat
 end
 
 """
-    icCellsPath(cell_definition::AbstractString, patch_type::AbstractString, patch_id, path_elements::Vararg{<:Union{Integer,AbstractString}})
+    icCellsPath(cell_definition::AbstractString, patch_type::AbstractString, patch_id, path_elements::Vararg{Union{Integer,AbstractString}})
 
 Return the XML path to the IC cell patch for the given cell type, patch type, and patch ID.
 The remaining arguments are either just the tag for the patch parameter or the carveout patch type, ID, and tag.
@@ -1024,7 +1024,7 @@ julia> icCellsPath("default", "annulus", 1, "rectangle", 1, "width")
  "width"
 ```
 """
-function icCellsPath(cell_definition::AbstractString, patch_type::AbstractString, patch_id, path_elements::Vararg{<:Union{Integer,AbstractString}})
+function icCellsPath(cell_definition::AbstractString, patch_type::AbstractString, patch_id, path_elements::Vararg{Union{Integer,AbstractString}})
     supported_patch_types = PhysiCellCellCreator.supportedPatchTypes()
     @assert patch_type in supported_patch_types "IC Cell patch_type must be one of the available patch types, i.e., in $(supported_patch_types). Got $(patch_type)"
     xml_path = ["cell_patches:name:$(cell_definition)"; "patch_collection:type:$(patch_type)"; "patch:ID:$(patch_id)"]