R devel - Jul 2013 - Depends vs Imports

I am being asked to modernize the Depends line in the DESCRIPTION file 
of some packages. Writing R Extensions says:

   The general rules are

      Packages whose namespace only is needed to load the package using
    library(pkgname) must be listed in the ?Imports? field and not in
    the ?Depends? field. Packages listed in imports or importFrom
    directives in the NAMESPACE file should almost always be in
    ?Imports? and not ?Depends?.

      Packages that need to be attached to successfully load the
     package using library(pkgname) must be listed in the
     ?Depends? field, only.

Could someone please explain a few points I thought I understood but 
obviously do not, or point to where these are explained:

    -What does it mean for the namespace only to be needed? I thought 
the namespace was needed if the package or some of its functions were 
mentioned in the NAMESPACE file, and that only the namespace was needed 
if only the generics were called, and not other functions. The above 
suggests that I may be wrong about this. If so, that is, Imports will 
usually suffice, then when would Depends ever be needed when a package 
is mentioned in the NAMESPACE file?

   -Should the package DESCRIPTION make any accommodation for the 
situation where users will probably need to directly call functions in 
the imported package, even though the package itself does not?

    -What does "need to be attached" mean? Is there a distinction 
between a package being attached and a namespace being attached.

    -Does "successfully load" mean something different from actually 
using the package? That is, can we assume that if the package loads then 
all the functions to run things will actually be found?

    -If pkg1 uses a function foo in pkg3 indirectly, by a call to a 
function in  pkg2 which then uses foo, how should pkg1 indicate the 
relationship with foo's pkg3, or is there no need to indicate any 
relationship with pkg3 because that is all looked after by pkg2?

Thanks,
Paul

On Jul 31, 2013, at 7:14 PM, Paul Gilbert wrote:
> I am being asked to modernize the Depends line in the DESCRIPTION file of
some packages. Writing R Extensions says:
> 
>  The general rules are
> 
>     Packages whose namespace only is needed to load the package using
>   library(pkgname) must be listed in the ?Imports? field and not in
>   the ?Depends? field. Packages listed in imports or importFrom
>   directives in the NAMESPACE file should almost always be in
>   ?Imports? and not ?Depends?.
> 
>     Packages that need to be attached to successfully load the
>    package using library(pkgname) must be listed in the
>    ?Depends? field, only.
> 
> Could someone please explain a few points I thought I understood but
obviously do not, or point to where these are explained:
> 
>   -What does it mean for the namespace only to be needed? I thought the
namespace was needed if the package or some of its functions were mentioned in
the NAMESPACE file, and that only the namespace was needed if only the generics
were called, and not other functions. The above suggests that I may be wrong
about this. If so, that is, Imports will usually suffice, then when would
Depends ever be needed when a package is mentioned in the NAMESPACE file?
> 
In the namespace era Depends is never really needed. All modern packages have no
technical need for Depends anymore. Loosely speaking the only purpose of Depends
today is to expose other package's functions to the user without
re-exporting them.

>  -Should the package DESCRIPTION make any accommodation for the situation
where users will probably need to directly call functions in the imported
package, even though the package itself does not?
> 
>   -What does "need to be attached" mean? Is there a distinction
between a package being attached and a namespace being attached.
> 
No, the distinction is between loaded and attached (namespace/package is
synonymous here).

>   -Does "successfully load" mean something different from
actually using the package? That is, can we assume that if the package loads
then all the functions to run things will actually be found?
> 
Define "found" - they will not be attached to the search path, so they
will be found if you address them fully via myPackage::myFn but not just via
myFn (except for another package that imports myPackage).

>   -If pkg1 uses a function foo in pkg3 indirectly, by a call to a function
in  pkg2 which then uses foo, how should pkg1 indicate the relationship with
foo's pkg3, or is there no need to indicate any relationship with pkg3
because that is all looked after by pkg2?
> 
There is no need - how would you imagine being responsible for code that you did
not write? pkg2 will import function from pkg1, but you're not importing
them in pkg3, you don't even care about them so you have no direct
relationship with pkg1 (imagine pkg2 switched to use pkg4 instead of pkg1).


IMHO it's all really simple:

load = functions exported in myPkg are available to interested parties as
myPkg::foo or via direct imports - essentially this means the package can now be
used

attach = the namespace (and thus all exported functions) is attached to the
search path - the only effect is that you have now added the exported functions
to the global pool of functions - sort of like dumping them in the workspace
(for all practical purposes, not technically)

import a function into a package = make sure that this function works in my
package regardless of the search path (so I can write fn1 instead of pkg1::fn1
and still know it will come from pkg1 and not someone's workspace or other
package that chose the same name)

Cheers,
Simon