From c2e519beafc47aff1621c6fc9a311d8b18fc34ff Mon Sep 17 00:00:00 2001 From: Kristoffer Date: Wed, 1 Sep 2021 18:49:47 +0200 Subject: [PATCH 1/6] warn against `using Foo` in package code --- base/docs/basedocs.jl | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/base/docs/basedocs.jl b/base/docs/basedocs.jl index d9625c914633b..3c5f6d2e86282 100644 --- a/base/docs/basedocs.jl +++ b/base/docs/basedocs.jl @@ -33,6 +33,15 @@ kw"help", kw"Julia", kw"julia", kw"" available for direct use. Names can also be used via dot syntax (e.g. `Foo.foo` to access the name `foo`), whether they are `export`ed or not. See the [manual section about modules](@ref modules) for details. + +!!! note + Doing `using Foo` in packages or code that you want to keep working with + updated dependencies is not recommended. The reason for this is if another + dependency starts to export one of the same names as `Foo` the code will + error due to an ambiguity in which package the name should be taken from. + Instead, explicitly list what names you want to use from Foo, for example: + `using Foo: Foo, parsefile, readfile` to get access bring `Foo` and two + functions `parsefile` and `readfile` into scope. """ kw"using" From 5a497c8c814d22c58deaac550eb31daa5dafe036 Mon Sep 17 00:00:00 2001 From: Mason Protter Date: Mon, 3 Jun 2024 23:06:08 +0200 Subject: [PATCH 2/6] Add guidance for using qualified names in packages (#53428) Note: the base branch (target branch) of this PR is `kc/warn_using` (#42080), NOT `master`. --- This is additive to https://github.com/JuliaLang/julia/pull/42080 which adds advice to the docstring of `using` . The wording here is a tweaked version of @IanButterworth's suggestion here: https://github.com/JuliaLang/julia/pull/42080#discussion_r1340812119 --------- Co-authored-by: Max Horn Co-authored-by: Dilum Aluthge --- doc/src/manual/modules.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/doc/src/manual/modules.md b/doc/src/manual/modules.md index 64befb03c1ad5..aecff0eb8c88e 100644 --- a/doc/src/manual/modules.md +++ b/doc/src/manual/modules.md @@ -112,7 +112,7 @@ and above. To maintain compatibility with Julia 1.10 and below, use the `@compat ### Standalone `using` and `import` -Possibly the most common way of loading a module is `using ModuleName`. This [loads](@ref +For interactive use, the most common way of loading a module is `using ModuleName`. This [loads](@ref code-loading) the code associated with `ModuleName`, and brings 1. the module name @@ -168,6 +168,26 @@ Importantly, the module name `NiceStuff` will *not* be in the namespace. If you julia> using .NiceStuff: nice, DOG, NiceStuff ``` +!!! note + Qualifying the names being used as in `using Foo: Foo, f` is + recommended over plain `using Foo` for released packages, and other + code which is meant to be re-used in the future with updated dependencies + or future versions of julia. + + The reason for this is if another dependency starts to export one of the + same names as `Foo` and you attempt to use that name, then previously working + code will error due to an ambiguity in which package the name should be + taken from. This is especially problematic in released packages which needs + to be forward-compatible with the future releases. + + For example, if your package has dependencies `Foo` version `1` and `Bar` + version `2`, and you write `using Foo, Bar` the current versions may not + have any conflicting names, but if in a minor non-breaking release of `Bar` + version 2.x it also exports the name `f`, then suddenly calling the function + `f` will error because the name has become ambiguous. This issue can be + avoided by explicitly listing what names you want to use from which modules. + + Julia has two forms for seemingly the same thing because only `import ModuleName: f` allows adding methods to `f` *without a module path*. That is to say, the following example will give an error: From aa0ce07358255dad7a50b2932a090c702dd65149 Mon Sep 17 00:00:00 2001 From: Matt Bauman Date: Tue, 4 Jun 2024 09:59:45 -0400 Subject: [PATCH 3/6] Unify some of the language from #53428 --- base/docs/basedocs.jl | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/base/docs/basedocs.jl b/base/docs/basedocs.jl index 6268274f0e9ec..17b14cedea952 100644 --- a/base/docs/basedocs.jl +++ b/base/docs/basedocs.jl @@ -39,13 +39,13 @@ the name `foo`), whether they are `export`ed or not. See the [manual section about modules](@ref modules) for details. !!! note - Doing `using Foo` in packages or code that you want to keep working with - updated dependencies is not recommended. The reason for this is if another - dependency starts to export one of the same names as `Foo` the code will - error due to an ambiguity in which package the name should be taken from. - Instead, explicitly list what names you want to use from Foo, for example: - `using Foo: Foo, parsefile, readfile` to get access bring `Foo` and two - functions `parsefile` and `readfile` into scope. + Qualifying the names being used as in `using Foo: Foo, f` is + recommended over plain `using Foo` for released packages and other + code which is meant to be re-used in the future with updated dependencies + or future versions of julia. When two modules or packages export the same name + and both are loaded with `using` (without the explicit list), it is an error to use + that name without qualification. Using an explicit list ensures that new exports + in updated dependencies do not break the forward compatibility of the code. """ kw"using" From ca82f8b022245d3a454fd8229ffe2d96854eea8e Mon Sep 17 00:00:00 2001 From: Kristoffer Carlsson Date: Wed, 5 Jun 2024 13:35:50 +0200 Subject: [PATCH 4/6] make shorter --- doc/src/manual/modules.md | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) diff --git a/doc/src/manual/modules.md b/doc/src/manual/modules.md index fc93f63fa7630..1eae3fd88fa76 100644 --- a/doc/src/manual/modules.md +++ b/doc/src/manual/modules.md @@ -177,16 +177,7 @@ julia> using .NiceStuff: nice, DOG, NiceStuff The reason for this is if another dependency starts to export one of the same names as `Foo` and you attempt to use that name, then previously working code will error due to an ambiguity in which package the name should be - taken from. This is especially problematic in released packages which needs - to be forward-compatible with the future releases. - - For example, if your package has dependencies `Foo` version `1` and `Bar` - version `2`, and you write `using Foo, Bar` the current versions may not - have any conflicting names, but if in a minor non-breaking release of `Bar` - version 2.x it also exports the name `f`, then suddenly calling the function - `f` will error because the name has become ambiguous. This issue can be - avoided by explicitly listing what names you want to use from which modules. - + taken from. Julia has two forms for seemingly the same thing because only `import ModuleName: f` allows adding methods to `f` *without a module path*. From d99b8d11919df888d20ba4495337361684f4822a Mon Sep 17 00:00:00 2001 From: Kristoffer Carlsson Date: Fri, 7 Jun 2024 15:08:26 +0200 Subject: [PATCH 5/6] Update base/docs/basedocs.jl Co-authored-by: Alex Arslan --- base/docs/basedocs.jl | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/base/docs/basedocs.jl b/base/docs/basedocs.jl index 17b14cedea952..dfa85552b7181 100644 --- a/base/docs/basedocs.jl +++ b/base/docs/basedocs.jl @@ -39,13 +39,12 @@ the name `foo`), whether they are `export`ed or not. See the [manual section about modules](@ref modules) for details. !!! note - Qualifying the names being used as in `using Foo: Foo, f` is - recommended over plain `using Foo` for released packages and other - code which is meant to be re-used in the future with updated dependencies - or future versions of julia. When two modules or packages export the same name - and both are loaded with `using` (without the explicit list), it is an error to use - that name without qualification. Using an explicit list ensures that new exports - in updated dependencies do not break the forward compatibility of the code. + When two or more packages/modules export a name and that name does not refer to the + same thing in each of the packages, and the packages are loaded via `using` without + an explicit list of names, it is an error to reference that name without qualification. + It is thus recommended that code intended to be forward-compatible with future versions + of its dependencies and of Julia, e.g. code in released packages, list the names it + uses from each loaded package, e.g. `using Foo: Foo, f` rather than `using Foo`. """ kw"using" From 990cd5c3b634bb43a062745b6311ebee738b3814 Mon Sep 17 00:00:00 2001 From: Kristoffer Carlsson Date: Fri, 7 Jun 2024 15:44:33 +0200 Subject: [PATCH 6/6] Update doc/src/manual/modules.md Co-authored-by: Alex Arslan --- doc/src/manual/modules.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/doc/src/manual/modules.md b/doc/src/manual/modules.md index 1eae3fd88fa76..b75ceb27a4901 100644 --- a/doc/src/manual/modules.md +++ b/doc/src/manual/modules.md @@ -168,16 +168,15 @@ Importantly, the module name `NiceStuff` will *not* be in the namespace. If you julia> using .NiceStuff: nice, DOG, NiceStuff ``` -!!! note - Qualifying the names being used as in `using Foo: Foo, f` is - recommended over plain `using Foo` for released packages, and other - code which is meant to be re-used in the future with updated dependencies - or future versions of julia. - - The reason for this is if another dependency starts to export one of the - same names as `Foo` and you attempt to use that name, then previously working - code will error due to an ambiguity in which package the name should be - taken from. +Qualifying the names being used as in `using Foo: Foo, f` is +recommended over plain `using Foo` for released packages, and other +code which is meant to be re-used in the future with updated dependencies +or future versions of julia. + +The reason for this is if another dependency starts to export one of the +same names as `Foo` and you attempt to use that name, then previously working +code will error due to an ambiguity in which package the name should be +taken from. Julia has two forms for seemingly the same thing because only `import ModuleName: f` allows adding methods to `f` *without a module path*.