diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 7fa9b93..2768c90 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.11.0","generation_timestamp":"2024-10-10T14:23:03","documenter_version":"1.7.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.11.0","generation_timestamp":"2024-10-10T14:33:44","documenter_version":"1.7.0"}} \ No newline at end of file diff --git a/dev/ambiguities/index.html b/dev/ambiguities/index.html index c574fdd..99228f9 100644 --- a/dev/ambiguities/index.html +++ b/dev/ambiguities/index.html @@ -9,4 +9,4 @@ Possible fix, define f(::Int64, ::Int64)

This will throw an MethodError because both methods are equally specific. The solution is to add a third method:

f(x::Int, y::Int) = ? # `?` is dependent on the use case, most times it will be `1` or `2`

Test function

Aqua.test_ambiguities — Function
test_ambiguities(package::Union{Module, PkgId})
-test_ambiguities(packages::Vector{Union{Module, PkgId}})

Test that there is no method ambiguities in given package(s). It calls Test.detect_ambiguities in a separated clean process to avoid false-positives.

Keyword Arguments

  • broken::Bool = false: If true, it uses @test_broken instead of @test and shortens the error message.
  • color::Union{Bool, Nothing} = nothing: Enable/disable colorful output if a Bool. nothing (default) means to inherit the setting in the current process.
  • exclude::AbstractVector = []: A vector of functions or types to be excluded from ambiguity testing. A function means to exclude all its methods. A type means to exclude all its methods of the callable (sometimes also called "functor") and the constructor. That is to say, MyModule.MyType means to ignore ambiguities between (::MyType)(x, y::Int) and (::MyType)(x::Int, y).
  • recursive::Bool = true: Passed to Test.detect_ambiguities. Note that the default here (true) is different from detect_ambiguities. This is for testing ambiguities in methods defined in all sub-modules.
  • Other keyword arguments such as imported and ambiguous_bottom are passed to Test.detect_ambiguities as-is.
source
+test_ambiguities(packages::Vector{Union{Module, PkgId}})

Test that there is no method ambiguities in given package(s). It calls Test.detect_ambiguities in a separated clean process to avoid false-positives.

Keyword Arguments

source diff --git a/dev/deps_compat/index.html b/dev/deps_compat/index.html index 00e9e5f..de52bcd 100644 --- a/dev/deps_compat/index.html +++ b/dev/deps_compat/index.html @@ -1,2 +1,2 @@ -Compat entries · Aqua.jl
GitHub

Compat entries

In your Project.toml you can (and should) use compat entries to specify with which versions of Julia and your dependencies your package is compatible with. This is important to ease the installation and upgrade of your package for users, and to keep everything working in the case of breaking changes in Julia or your dependencies.

For more details, see the Pkg docs.

Test function

Aqua.test_deps_compat — Function
Aqua.test_deps_compat(package)

Test that the Project.toml of package has a compat entry for each package listed under deps and for julia.

Arguments

  • packages: a top-level Module, a Base.PkgId, or a collection of them.

Keyword Arguments

Test choosers

  • check_julia = true: If true, additionally check for a compat entry for "julia".
  • check_extras = true: If true, additionally check "extras". A NamedTuple can be used to pass keyword arguments with test options (see below).
  • check_weakdeps = true: If true, additionally check "weakdeps". A NamedTuple can be used to pass keyword arguments with test options (see below).

Test options

If these keyword arguments are set directly, they only apply to the standard test for "deps". To apply them to "extras" and "weakdeps", pass them as a NamedTuple to the corresponding check_$x keyword argument.

  • broken::Bool = false: If true, it uses @test_broken instead of @test for "deps".
  • ignore::Vector{Symbol}: names of dependent packages to be ignored.
source
+Compat entries · Aqua.jl
GitHub

Compat entries

In your Project.toml you can (and should) use compat entries to specify with which versions of Julia and your dependencies your package is compatible with. This is important to ease the installation and upgrade of your package for users, and to keep everything working in the case of breaking changes in Julia or your dependencies.

For more details, see the Pkg docs.

Test function

Aqua.test_deps_compat — Function
Aqua.test_deps_compat(package)

Test that the Project.toml of package has a compat entry for each package listed under deps and for julia.

Arguments

  • packages: a top-level Module, a Base.PkgId, or a collection of them.

Keyword Arguments

Test choosers

  • check_julia = true: If true, additionally check for a compat entry for "julia".
  • check_extras = true: If true, additionally check "extras". A NamedTuple can be used to pass keyword arguments with test options (see below).
  • check_weakdeps = true: If true, additionally check "weakdeps". A NamedTuple can be used to pass keyword arguments with test options (see below).

Test options

If these keyword arguments are set directly, they only apply to the standard test for "deps". To apply them to "extras" and "weakdeps", pass them as a NamedTuple to the corresponding check_$x keyword argument.

  • broken::Bool = false: If true, it uses @test_broken instead of @test for "deps".
  • ignore::Vector{Symbol}: names of dependent packages to be ignored.
source
diff --git a/dev/exports/index.html b/dev/exports/index.html index 90bde24..bfa5621 100644 --- a/dev/exports/index.html +++ b/dev/exports/index.html @@ -1,2 +1,2 @@ -Undefined exports · Aqua.jl
GitHub
+Undefined exports · Aqua.jl
GitHub
diff --git a/dev/index.html b/dev/index.html index 90c3362..f212f65 100644 --- a/dev/index.html +++ b/dev/index.html @@ -25,4 +25,4 @@ deps_compat=(ignore=[:SomeOtherPackage],), piracies=false, ) -end

Note, that for all tests with no explicit options provided, the default options are used.

For more details on the options, see the respective functions here.

Examples

The following is a small selection of packages that use Aqua.jl:

+end

Note, that for all tests with no explicit options provided, the default options are used.

For more details on the options, see the respective functions here.

Examples

The following is a small selection of packages that use Aqua.jl:

diff --git a/dev/persistent_tasks/index.html b/dev/persistent_tasks/index.html index dd9d411..364cecb 100644 --- a/dev/persistent_tasks/index.html +++ b/dev/persistent_tasks/index.html @@ -18,4 +18,4 @@ if ccall(:jl_generating_output, Cint, ()) == 0 # if we're not precompiling... # launch persistent tasks here end -end

In more complex cases, you may need to set up independently-callable functions to launch the tasks and set conditions that allow them to cleanly exit.

Test functions

Aqua.test_persistent_tasks — Function
Aqua.test_persistent_tasks(package)

Test whether loading package creates persistent Tasks which may block precompilation of dependent packages. See also Aqua.find_persistent_tasks_deps.

If you provide an optional expr, this tests whether loading package and running expr creates persistent Tasks. For example, you might start and shutdown a web server, and this will test that there aren't any persistent Tasks.

On Julia version 1.9 and before, this test always succeeds.

Arguments

  • package: a top-level Module or Base.PkgId.

Keyword Arguments

  • broken::Bool = false: If true, it uses @test_broken instead of @test.
  • tmax::Real = 5: the maximum time (in seconds) to wait after loading the package before forcibly shutting down the precompilation process (triggering a test failure).
  • expr::Expr = quote end: An expression to run in the precompile package.
Note

Aqua.test_persistent_tasks(package) creates a package with package as a dependency and runs the precompilation process. This requires that package is instantiable with the information in the Project.toml file alone. In particular, this will not work if some of package's dependencies are deved packages or are given as a local path or a git repository in the Manifest.toml.

source
Aqua.find_persistent_tasks_deps — Function
Aqua.find_persistent_tasks_deps(package; broken = Dict{String,Bool}(), kwargs...)

Test all the dependencies of package with Aqua.test_persistent_tasks. On Julia 1.10 and higher, it returns a list of all dependencies failing the test. These are likely the ones blocking precompilation of your package.

Any additional kwargs (e.g., tmax) are passed to Aqua.test_persistent_tasks.

source
+end

In more complex cases, you may need to set up independently-callable functions to launch the tasks and set conditions that allow them to cleanly exit.

Test functions

Aqua.test_persistent_tasks — Function
Aqua.test_persistent_tasks(package)

Test whether loading package creates persistent Tasks which may block precompilation of dependent packages. See also Aqua.find_persistent_tasks_deps.

If you provide an optional expr, this tests whether loading package and running expr creates persistent Tasks. For example, you might start and shutdown a web server, and this will test that there aren't any persistent Tasks.

On Julia version 1.9 and before, this test always succeeds.

Arguments

  • package: a top-level Module or Base.PkgId.

Keyword Arguments

  • broken::Bool = false: If true, it uses @test_broken instead of @test.
  • tmax::Real = 5: the maximum time (in seconds) to wait after loading the package before forcibly shutting down the precompilation process (triggering a test failure).
  • expr::Expr = quote end: An expression to run in the precompile package.
Note

Aqua.test_persistent_tasks(package) creates a package with package as a dependency and runs the precompilation process. This requires that package is instantiable with the information in the Project.toml file alone. In particular, this will not work if some of package's dependencies are deved packages or are given as a local path or a git repository in the Manifest.toml.

source
Aqua.find_persistent_tasks_deps — Function
Aqua.find_persistent_tasks_deps(package; broken = Dict{String,Bool}(), kwargs...)

Test all the dependencies of package with Aqua.test_persistent_tasks. On Julia 1.10 and higher, it returns a list of all dependencies failing the test. These are likely the ones blocking precompilation of your package.

Any additional kwargs (e.g., tmax) are passed to Aqua.test_persistent_tasks.

source
diff --git a/dev/piracies/index.html b/dev/piracies/index.html index c0b1930..2e3d66e 100644 --- a/dev/piracies/index.html +++ b/dev/piracies/index.html @@ -14,4 +14,4 @@ bar(x::Vector{D}) = 4 # slightly bad (may cause invalidations) bar(x::Union{C,D}) = 5 # slightly bad (a change in PkgA may turn it into piracy) # (for example changing bar(x::C) = 1 to bar(x::Union{C,Int}) = 1) -end

The following cases are enumerated by the return values in the example above:

  1. This is the worst case of type piracy. The value of bar(C()) can be either 1 or 42 and will depend on whether PkgB is loaded or not.
  2. This is also a bad case of type piracy. bar() throws a MethodError with only PkgA available, and returns 2 with PkgB loaded. PkgA may add a method for bar() that takes no arguments in the future, and then this is equivalent to case 1.
  3. This is a moderately bad case of type piracy. bar(Union{}[]) returns 3 when PkgB is loaded, and 43 when PkgB is not loaded, although neither of the occurring types are defined in PkgB. This case is not as bad as cases 1 and 2, because it is only about behavior around Union{}, which has no instances.
  4. Depending on ones understanding of type piracy, this could be considered piracy as well. In particular, this may cause invalidations.
  5. This is a slightly bad case of type piracy. In the current form, bar(C()) returns 42 as the dispatch on Union{C,D} is less specific. However, a future change in PkgA may change this behavior, e.g. by changing bar(x::C) to bar(x::Union{C,Int}) the call bar(C()) would become ambiguous.
Note

The test function below currently only checks for cases 1 and 2.

Test function

Aqua.test_piracies — Function
test_piracies(m::Module)

Test that m does not commit type piracies.

Keyword Arguments

  • broken::Bool = false: If true, it uses @test_broken instead of @test and shortens the error message.
  • skip_deprecated::Bool = true: If true, it does not check deprecated methods.
  • treat_as_own = Union{Function, Type}[]: The types in this container are considered to be "owned" by the module m. This is useful for testing packages that deliberately commit some type piracies, e.g. modules adding higher-level functionality to a lightweight C-wrapper, or packages that are extending StatsAPI.jl.
source
+end

The following cases are enumerated by the return values in the example above:

  1. This is the worst case of type piracy. The value of bar(C()) can be either 1 or 42 and will depend on whether PkgB is loaded or not.
  2. This is also a bad case of type piracy. bar() throws a MethodError with only PkgA available, and returns 2 with PkgB loaded. PkgA may add a method for bar() that takes no arguments in the future, and then this is equivalent to case 1.
  3. This is a moderately bad case of type piracy. bar(Union{}[]) returns 3 when PkgB is loaded, and 43 when PkgB is not loaded, although neither of the occurring types are defined in PkgB. This case is not as bad as cases 1 and 2, because it is only about behavior around Union{}, which has no instances.
  4. Depending on ones understanding of type piracy, this could be considered piracy as well. In particular, this may cause invalidations.
  5. This is a slightly bad case of type piracy. In the current form, bar(C()) returns 42 as the dispatch on Union{C,D} is less specific. However, a future change in PkgA may change this behavior, e.g. by changing bar(x::C) to bar(x::Union{C,Int}) the call bar(C()) would become ambiguous.
Note

The test function below currently only checks for cases 1 and 2.

Test function

Aqua.test_piracies — Function
test_piracies(m::Module)

Test that m does not commit type piracies.

Keyword Arguments

  • broken::Bool = false: If true, it uses @test_broken instead of @test and shortens the error message.
  • skip_deprecated::Bool = true: If true, it does not check deprecated methods.
  • treat_as_own = Union{Function, Type}[]: The types in this container are considered to be "owned" by the module m. This is useful for testing packages that deliberately commit some type piracies, e.g. modules adding higher-level functionality to a lightweight C-wrapper, or packages that are extending StatsAPI.jl.
source
diff --git a/dev/project_extras/index.html b/dev/project_extras/index.html index 125a925..4611c47 100644 --- a/dev/project_extras/index.html +++ b/dev/project_extras/index.html @@ -1,3 +1,3 @@ Project.toml extras · Aqua.jl
GitHub

Project.toml extras

There are two different ways to specify test-only dependencies (see the Pkg docs):

  1. Add the test-only dependencies to the [extras] section of your Project.toml file and use a test target.
  2. Add the test-only dependencies to the [deps] section of your test/Project.toml file. This is only available in Julia 1.2 and later.

This test checks checks that, in case you use both methods, the set of test-only dependencies is the same in both ways.

Test function

Aqua.test_project_extras — Function
test_project_extras(package::Union{Module, PkgId})
-test_project_extras(packages::Vector{Union{Module, PkgId}})

Check that test target of the root project and test project (test/Project.toml) are consistent. This is useful for supporting Julia < 1.2 while recording test-only dependency compatibility in test/Project.toml.

source
+test_project_extras(packages::Vector{Union{Module, PkgId}})

Check that test target of the root project and test project (test/Project.toml) are consistent. This is useful for supporting Julia < 1.2 while recording test-only dependency compatibility in test/Project.toml.

source diff --git a/dev/release-notes/index.html b/dev/release-notes/index.html index 0e23ce2..4ea615b 100644 --- a/dev/release-notes/index.html +++ b/dev/release-notes/index.html @@ -1,2 +1,2 @@ -Release notes · Aqua.jl
GitHub

Release notes

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Version v0.8.7 - 2024-04-09

  • Reverted #285, which was originally released in v0.8.6, but caused a regression. (#287, #288)

Version v0.8.6 - 2024-04-09

Changed

  • The output of test_ambiguities now gets printed to stderr instead of stdout. (#281)

Version v0.8.5 - 2024-04-03

Changed

  • When supplying broken = true to test_ambiguities, test_undefined_exports, test_piracies, or test_unbound_args, the output is shortened. In particular, the list of offending instances is no longer printed. To get the full output, set broken = false. (#272)
  • Use Changelog.jl to generate the changelog, and add it to the documentation. (#277, #279)
  • test_project_extras prints failures the same on all julia versions. In particular, 1.11 and nightly are no outliers. (#275)

Version v0.8.4 - 2023-12-01

Added

  • test_persistent_tasks now accepts an optional expr to run in the precompile package. (#255)
    • The expr option lets you test whether your precompile script leaves any dangling Tasks
    or Timers, which would make it unsafe to use as a dependency for downstream packages.

Version v0.8.3 - 2023-11-29

Changed

  • test_persistent_tasks is now less noisy. (#256)
  • Completely overhauled the documentation. Every test now has its dedicated page. (#250)

Version v0.8.2 - 2023-11-16

Changed

  • test_persistent_tasks no longer clears the environment of the subtask. Instead, it modifies LOAD_PATH directly to make stdlibs work. (#241)

Version v0.8.1 - 2023-11-16

Changed

  • test_persistent_tasks now redirects stdout and stderr of the created subtask. Furthermore, the environment of the subtask gets cleared to allow default values for JULIA_LOAD_PATH to work. (#240)

Version v0.8.0 - 2023-11-15

Added

  • Two additions check whether packages might block precompilation on Julia 1.10 or higher: (#174)
    • test_persistent_tasks tests whether "your" package can safely be used as a dependency for downstream packages. This test is enabled for the default testsuite test_all, but you can opt-out by supplying persistent_tasks=false to test_all. [BREAKING]
    • find_persistent_tasks_deps is useful if "your" package hangs upon precompilation: it runs test_persistent_tasks on all the things you depend on, and may help isolate the culprit(s).

Changed

  • In test_deps_compat, the two subtests check_extras and check_weakdeps are now run by default. (#202) [BREAKING]
  • test_deps_compat now requires compat entries for all dependencies. Stdlibs no longer get ignored. This change is motivated by similar changes in the General registry. (#215) [BREAKING]
  • test_ambiguities now excludes the keyword sorter of all excluded functions with keyword arguments as well. (#203)
  • test_piracy is renamed to test_piracies. (#230) [BREAKING]
  • test_ambiguities and test_piracies now return issues in a defined order. This order may change in a patch release of Aqua.jl. (#233)
  • Improved the message for test_project_extras failures. (#234)
  • test_deps_compat now requires a compat entry for julia This can be disabling by setting compat_julia = false. (#236) [BREAKING]

Removed

  • test_project_toml_formatting has been removed. Thus, the kwarg project_toml_formatting to test_all no longer exists. (#209) [BREAKING]

Version v0.7.4 - 2023-10-24

Added

  • test_deps_compat has two new kwargs check_extras and check_weakdeps to extend the test to these dependency categories. They are not run by default. (#200)

Changed

  • The docstring for test_stale_deps explains the situation with package extensions. (#203)
  • The logo of Aqua.jl has been updated. (#128)

Version v0.7.3 - 2023-09-25

Added

  • test_deps_compat has a new kwarg broken to mark the test as broken using Test.@test_broken. (#193)

Fixed

  • test_piracy no longer prints warnings for methods where the third argument is a TypeVar. (#188)

Version v0.7.2 - 2023-09-19

Changed

  • test_undefined_exports additionally prints the modules of the undefined exports in the failure report. (#177)

Version v0.7.1 - 2023-09-05

Fixed

  • test_piracy no longer reports type piracy in the kwsorter, i.e. kwcall should no longer appear in the report. (#171)

Version v0.7.0 - 2023-08-29

Added

  • Installation and usage instructions to the documentation. (#159)

Changed

  • test_ambiguities now allows to exclude non-singleton callables. Excluding a type means to exclude all methods of the callable (sometimes also called "functor") and the constructor. (#144) [BREAKING]
  • test_piracy considers more functions. Callables and qualified names are now also checked. (#156) [BREAKING]

Fixed

  • test_ambiguities prints less unnecessary whitespace. (#158)
  • test_ambiguities no longer hangs indefinitely when there are many ambiguities. (#166)

Version v0.6.7 - 2023-09-19

Changed

  • test_undefined_exports additionally prints the modules of the undefined exports in the failure report. (#177)

Fixed

  • test_ambiguities prints less unnecessary whitespace. (#158)
  • Fix test_piracy for some methods with arguments of custom subtypes of Function. (#170)

Version v0.6.6 - 2023-08-24

Fixed

  • test_ambiguities no longer hangs indefinitely when there are many ambiguities. (#166)

Version v0.6.5 - 2023-06-26

Fixed

  • Typo when calling kwargs. (#153)

Version v0.6.4 - 2023-06-25

Added

  • test_piracy has a new kwarg treat_as_own. It is useful for testing packages that deliberately commit some type piracy, e.g. modules adding higher-level functionality to a lightweight C-wrapper, or packages that are extending StatsAPI.jl. (#140)

Changed

  • Explanation of test_unbound_args in the docstring. (#146)

Fixed

  • Callable objects with type parameters no longer error in test_ambiguities' kwarg exclude. (#142)

Version v0.6.3 - 2023-06-05

Changed

  • When installing a method for a union type, it is only reported by test_piracy if all types in the union are foreign (instead of any for arguments). (#131)

Fixed

  • test_deps_compat's kwarg ignore now works as intended. (#130)
  • Weakdeps are not reported as stale by test_stale_deps anymore. (#135)

Version v0.6.2 - 2023-06-02

Added

  • test_ambiguities, test_undefined_exports, test_piracy, and test_unbound_args each have a new kwarg broken to mark the test as broken using Test.@test_broken. (#124)

Changed

  • test_piracy now prints the offending methods in a more readable way. (#93)
  • Extend test_project_toml_formatting to docs/Project.toml. (#115)

Fixed

  • test_stale_deps no longer fails if any of the loaded packages prints during loading. (#113)
  • Clarified the error message of test_unbound_args. (#103)
  • Clarified the error message of test_project_toml_formatting. (#122)
+Release notes · Aqua.jl
GitHub

Release notes

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Version v0.8.7 - 2024-04-09

  • Reverted #285, which was originally released in v0.8.6, but caused a regression. (#287, #288)

Version v0.8.6 - 2024-04-09

Changed

  • The output of test_ambiguities now gets printed to stderr instead of stdout. (#281)

Version v0.8.5 - 2024-04-03

Changed

  • When supplying broken = true to test_ambiguities, test_undefined_exports, test_piracies, or test_unbound_args, the output is shortened. In particular, the list of offending instances is no longer printed. To get the full output, set broken = false. (#272)
  • Use Changelog.jl to generate the changelog, and add it to the documentation. (#277, #279)
  • test_project_extras prints failures the same on all julia versions. In particular, 1.11 and nightly are no outliers. (#275)

Version v0.8.4 - 2023-12-01

Added

  • test_persistent_tasks now accepts an optional expr to run in the precompile package. (#255)
    • The expr option lets you test whether your precompile script leaves any dangling Tasks
    or Timers, which would make it unsafe to use as a dependency for downstream packages.

Version v0.8.3 - 2023-11-29

Changed

  • test_persistent_tasks is now less noisy. (#256)
  • Completely overhauled the documentation. Every test now has its dedicated page. (#250)

Version v0.8.2 - 2023-11-16

Changed

  • test_persistent_tasks no longer clears the environment of the subtask. Instead, it modifies LOAD_PATH directly to make stdlibs work. (#241)

Version v0.8.1 - 2023-11-16

Changed

  • test_persistent_tasks now redirects stdout and stderr of the created subtask. Furthermore, the environment of the subtask gets cleared to allow default values for JULIA_LOAD_PATH to work. (#240)

Version v0.8.0 - 2023-11-15

Added

  • Two additions check whether packages might block precompilation on Julia 1.10 or higher: (#174)
    • test_persistent_tasks tests whether "your" package can safely be used as a dependency for downstream packages. This test is enabled for the default testsuite test_all, but you can opt-out by supplying persistent_tasks=false to test_all. [BREAKING]
    • find_persistent_tasks_deps is useful if "your" package hangs upon precompilation: it runs test_persistent_tasks on all the things you depend on, and may help isolate the culprit(s).

Changed

  • In test_deps_compat, the two subtests check_extras and check_weakdeps are now run by default. (#202) [BREAKING]
  • test_deps_compat now requires compat entries for all dependencies. Stdlibs no longer get ignored. This change is motivated by similar changes in the General registry. (#215) [BREAKING]
  • test_ambiguities now excludes the keyword sorter of all excluded functions with keyword arguments as well. (#203)
  • test_piracy is renamed to test_piracies. (#230) [BREAKING]
  • test_ambiguities and test_piracies now return issues in a defined order. This order may change in a patch release of Aqua.jl. (#233)
  • Improved the message for test_project_extras failures. (#234)
  • test_deps_compat now requires a compat entry for julia This can be disabling by setting compat_julia = false. (#236) [BREAKING]

Removed

  • test_project_toml_formatting has been removed. Thus, the kwarg project_toml_formatting to test_all no longer exists. (#209) [BREAKING]

Version v0.7.4 - 2023-10-24

Added

  • test_deps_compat has two new kwargs check_extras and check_weakdeps to extend the test to these dependency categories. They are not run by default. (#200)

Changed

  • The docstring for test_stale_deps explains the situation with package extensions. (#203)
  • The logo of Aqua.jl has been updated. (#128)

Version v0.7.3 - 2023-09-25

Added

  • test_deps_compat has a new kwarg broken to mark the test as broken using Test.@test_broken. (#193)

Fixed

  • test_piracy no longer prints warnings for methods where the third argument is a TypeVar. (#188)

Version v0.7.2 - 2023-09-19

Changed

  • test_undefined_exports additionally prints the modules of the undefined exports in the failure report. (#177)

Version v0.7.1 - 2023-09-05

Fixed

  • test_piracy no longer reports type piracy in the kwsorter, i.e. kwcall should no longer appear in the report. (#171)

Version v0.7.0 - 2023-08-29

Added

  • Installation and usage instructions to the documentation. (#159)

Changed

  • test_ambiguities now allows to exclude non-singleton callables. Excluding a type means to exclude all methods of the callable (sometimes also called "functor") and the constructor. (#144) [BREAKING]
  • test_piracy considers more functions. Callables and qualified names are now also checked. (#156) [BREAKING]

Fixed

  • test_ambiguities prints less unnecessary whitespace. (#158)
  • test_ambiguities no longer hangs indefinitely when there are many ambiguities. (#166)

Version v0.6.7 - 2023-09-19

Changed

  • test_undefined_exports additionally prints the modules of the undefined exports in the failure report. (#177)

Fixed

  • test_ambiguities prints less unnecessary whitespace. (#158)
  • Fix test_piracy for some methods with arguments of custom subtypes of Function. (#170)

Version v0.6.6 - 2023-08-24

Fixed

  • test_ambiguities no longer hangs indefinitely when there are many ambiguities. (#166)

Version v0.6.5 - 2023-06-26

Fixed

  • Typo when calling kwargs. (#153)

Version v0.6.4 - 2023-06-25

Added

  • test_piracy has a new kwarg treat_as_own. It is useful for testing packages that deliberately commit some type piracy, e.g. modules adding higher-level functionality to a lightweight C-wrapper, or packages that are extending StatsAPI.jl. (#140)

Changed

  • Explanation of test_unbound_args in the docstring. (#146)

Fixed

  • Callable objects with type parameters no longer error in test_ambiguities' kwarg exclude. (#142)

Version v0.6.3 - 2023-06-05

Changed

  • When installing a method for a union type, it is only reported by test_piracy if all types in the union are foreign (instead of any for arguments). (#131)

Fixed

  • test_deps_compat's kwarg ignore now works as intended. (#130)
  • Weakdeps are not reported as stale by test_stale_deps anymore. (#135)

Version v0.6.2 - 2023-06-02

Added

  • test_ambiguities, test_undefined_exports, test_piracy, and test_unbound_args each have a new kwarg broken to mark the test as broken using Test.@test_broken. (#124)

Changed

  • test_piracy now prints the offending methods in a more readable way. (#93)
  • Extend test_project_toml_formatting to docs/Project.toml. (#115)

Fixed

  • test_stale_deps no longer fails if any of the loaded packages prints during loading. (#113)
  • Clarified the error message of test_unbound_args. (#103)
  • Clarified the error message of test_project_toml_formatting. (#122)
diff --git a/dev/stale_deps/index.html b/dev/stale_deps/index.html index cfa9830..700d7f2 100644 --- a/dev/stale_deps/index.html +++ b/dev/stale_deps/index.html @@ -1,2 +1,2 @@ -Stale dependencies · Aqua.jl
GitHub

Stale dependencies

Test function

Aqua.test_stale_deps — Function
Aqua.test_stale_deps(package; [ignore])

Test that package loads all dependencies listed in Project.toml. Note that this does not imply that package loads the dependencies directly, this can be achieved via transitivity as well.

Weak dependencies and extensions

Due to the automatic loading of package extensions once all of their trigger dependencies are loaded, Aqua.jl can, by design of julia, not check if a package extension indeed loads all of its trigger dependencies using import or using.

Known bug

Currently, Aqua.test_stale_deps does not detect stale dependencies when they are in the sysimage. This is considered a bug and may be fixed in the future. Such a release is considered non-breaking.

Arguments

  • packages: a top-level Module, a Base.PkgId, or a collection of them.

Keyword Arguments

  • ignore::Vector{Symbol}: names of dependent packages to be ignored.
source
+Stale dependencies · Aqua.jl
GitHub

Stale dependencies

Test function

Aqua.test_stale_deps — Function
Aqua.test_stale_deps(package; [ignore])

Test that package loads all dependencies listed in Project.toml. Note that this does not imply that package loads the dependencies directly, this can be achieved via transitivity as well.

Weak dependencies and extensions

Due to the automatic loading of package extensions once all of their trigger dependencies are loaded, Aqua.jl can, by design of julia, not check if a package extension indeed loads all of its trigger dependencies using import or using.

Known bug

Currently, Aqua.test_stale_deps does not detect stale dependencies when they are in the sysimage. This is considered a bug and may be fixed in the future. Such a release is considered non-breaking.

Arguments

  • packages: a top-level Module, a Base.PkgId, or a collection of them.

Keyword Arguments

  • ignore::Vector{Symbol}: names of dependent packages to be ignored.
source
diff --git a/dev/test_all/index.html b/dev/test_all/index.html index 806c0ee..e86ecd4 100644 --- a/dev/test_all/index.html +++ b/dev/test_all/index.html @@ -1,2 +1,2 @@ -Test everything · Aqua.jl
GitHub

Test everything

This test runs most of the other tests in this module. The defaults should be fine for most packages. If you have a package that needs to customize the test, you can do so by providing appropriate keyword arguments to Aqua.test_all() (see below)

Aqua.test_all — Function
test_all(testtarget::Module)

Run the following tests:

The keyword argument $x (e.g., ambiguities) can be used to control whether or not to run test_$x (e.g., test_ambiguities). If test_$x supports keyword arguments, a NamedTuple can also be passed to $x to specify the keyword arguments for test_$x.

Keyword Arguments

  • ambiguities = true
  • unbound_args = true
  • undefined_exports = true
  • project_extras = true
  • stale_deps = true
  • deps_compat = true
  • piracies = true
  • persistent_tasks = true
source
+Test everything · Aqua.jl
GitHub

Test everything

This test runs most of the other tests in this module. The defaults should be fine for most packages. If you have a package that needs to customize the test, you can do so by providing appropriate keyword arguments to Aqua.test_all() (see below)

Aqua.test_all — Function
test_all(testtarget::Module)

Run the following tests:

The keyword argument $x (e.g., ambiguities) can be used to control whether or not to run test_$x (e.g., test_ambiguities). If test_$x supports keyword arguments, a NamedTuple can also be passed to $x to specify the keyword arguments for test_$x.

Keyword Arguments

  • ambiguities = true
  • unbound_args = true
  • undefined_exports = true
  • project_extras = true
  • stale_deps = true
  • deps_compat = true
  • piracies = true
  • persistent_tasks = true
source
diff --git a/dev/unbound_args/index.html b/dev/unbound_args/index.html index 84565d5..c2ce758 100644 --- a/dev/unbound_args/index.html +++ b/dev/unbound_args/index.html @@ -1,4 +1,4 @@ Unbound Type Parameters · Aqua.jl
GitHub

Unbound Type Parameters

An unbound type parameter is a type parameter with a where, that does not occur in the signature of some dispatch of the method.

Examples

The following methods each have T as an unbound type parameter:

julia> f(x::Int) where {T} = do_something(x)WARNING: method definition for f at REPL[1]:1 declares type variable T but does not use it.
 f (generic function with 1 method)
julia> g(x::T...) where {T} = println(T)g (generic function with 1 method)

In the cases of f above, the unbound type parameter T is neither present in the signature of the methods nor as a bound of another type parameter. Here, the type parameter T can be removed without changing any semantics.

For signatures with Vararg (cf. g above), the type parameter is unbound for the zero-argument case (e.g. g()).

julia> g(1.0, 2.0)Float64
julia> g(1)Int64
julia> g()ERROR: UndefVarError: `T` not defined in static parameter matching
-Suggestion: run Test.detect_unbound_args to detect method arguments that do not fully constrain a type parameter.

A possible fix would be to replace g by two methods.

julia> g() = println(Int)  # Defaults to `Int`g (generic function with 1 method)
julia> g(x1::T, x2::T...) where {T} = println(T)g (generic function with 2 methods)
julia> g(1.0, 2.0)Float64
julia> g(1)Int64
julia> g()Int64

Test function

Aqua.test_unbound_args — Function
test_unbound_args(module::Module)

Test that all methods in module and its submodules do not have unbound type parameters. An unbound type parameter is a type parameter with a where, that does not occur in the signature of some dispatch of the method.

Keyword Arguments

  • broken::Bool = false: If true, it uses @test_broken instead of @test and shortens the error message.
source
+Suggestion: run Test.detect_unbound_args to detect method arguments that do not fully constrain a type parameter.

A possible fix would be to replace g by two methods.

julia> g() = println(Int)  # Defaults to `Int`g (generic function with 1 method)
julia> g(x1::T, x2::T...) where {T} = println(T)g (generic function with 2 methods)
julia> g(1.0, 2.0)Float64
julia> g(1)Int64
julia> g()Int64

Test function

Aqua.test_unbound_args — Function
test_unbound_args(module::Module)

Test that all methods in module and its submodules do not have unbound type parameters. An unbound type parameter is a type parameter with a where, that does not occur in the signature of some dispatch of the method.

Keyword Arguments

  • broken::Bool = false: If true, it uses @test_broken instead of @test and shortens the error message.
source