Melhor explicação de quando usar Imports / Depends

O manual " Writing R Extensions " fornece as seguintes orientações sobre quando usar Imports ou Depends:

As regras gerais são

• Pacotes cujo espaço para nome é necessário apenas para carregar o pacote usando a biblioteca (pkgname) devem ser listados no campo 'Importações' e não no campo 'Depends'.
• Os pacotes que precisam ser anexados para carregar o pacote com sucesso usando a biblioteca (pkgname) devem ser listados apenas no campo 'Depends'.

Alguém pode fornecer um pouco mais de clareza sobre isso? Como sei quando meu pacote precisa apenas de namespaces carregados e quando preciso que um pacote seja anexado? Quais são os exemplos de ambos? Eu acho que o pacote típico é apenas uma coleção de funções que às vezes chamam funções em outros pacotes (onde algum trabalho já foi codificado). Este cenário é 1 ou 2 acima?

Editar

Eu escrevi uma postagem no blog com uma seção sobre esse tópico específico (procure por 'Importações v Depends'). O visual facilita muito a compreensão.

"Imports"é mais seguro do que "Depends"(e também torna um pacote usá-lo um 'cidadão melhor' em relação a outros pacotes que o utilizam "Depends").

Uma "Depends"diretiva tenta garantir que uma função de outro pacote esteja disponível anexando o outro pacote ao caminho de pesquisa principal (ou seja, a lista de ambientes retornados por search()). Essa estratégia pode, no entanto, ser frustrada se outro pacote, carregado posteriormente, colocar uma função com nome idêntico anteriormente no caminho da pesquisa. Chambers ( no SoDA ) usa o exemplo da função "gam", encontrada nos pacotes game mgcv. Se dois outros pacotes fossem carregados, um deles dependendo game um dependendo mgcv, a função encontrada pelas chamadas gam()dependeria da ordem em que esses dois pacotes foram anexados. Não é bom.

Uma "Imports"diretiva deve ser usada para qualquer pacote de suporte cujas funções sejam colocadas <imports:packageName>(pesquisadas imediatamente após <namespace:packageName>), em vez de no caminho de pesquisa regular. Se um dos pacotes no exemplo acima usasse o "Imports"mecanismo (que também requer importou importFromdiretivas no NAMESPACEarquivo), as questões seriam melhoradas de duas maneiras. (1) O pacote ganharia controle sobre qual mgcvfunção é usada. (2) Ao manter o caminho de pesquisa principal livre dos objetos importados, ele nem sequer quebraria a dependência do outro pacote em relação à outra mgcvfunção.

É por isso que usar namespaces é uma prática tão boa, agora é aplicada pelo CRAN e (em particular) por que usar "Imports"é mais seguro do que usar "Depends".

Editado para adicionar uma ressalva importante:

Há uma exceção, infelizmente, comuns ao conselho acima: se o seu pacote depende de um pacote Aque se "Depends"em outro pacote B, o pacote provavelmente precisará anexar Acom uma "Dependsdirectiva.

Isso ocorre porque as funções no pacote Aforam escritas com a expectativa de que o pacote Be suas funções sejam anexadas ao search()caminho .

Uma "Depends"diretiva carregará e anexará o pacote A; nesse momento, Aa "Depends"diretiva do próprio pacote , em uma reação em cadeia, fará com que o pacote Bseja carregado e anexado também. As funções no pacote Apoderão encontrar as funções no pacote Bnas quais elas dependem.

Uma "Imports"diretiva carregará, mas não anexará o pacote A, nem carregará nem anexará o pacote B. ( "Imports"afinal de contas, espera que os gravadores de pacotes estejam usando o mecanismo de namespace e esse pacote Aesteja usando "Imports"para apontar para quaisquer funções nas Bquais precise acessar.) Chamadas pelas suas funções para quaisquer funções no pacote Aque dependam de funções no pacote B. consequentemente falhar.

As duas únicas soluções são:

1. Faça seu pacote anexar pacote Ausando uma "Depends"diretiva.
2. Melhor a longo prazo, entre em contato com o mantenedor do pacote Ae peça que ele faça um trabalho mais cuidadoso na construção de seu espaço para nome (nas palavras de Martin Morgan nesta resposta relacionada ).

Hadley Wickham dá uma explicação fácil ( http://r-pkgs.had.co.nz/namespace.html ):

Listar um pacote em Dependsou Importsgarante que ele seja instalado quando necessário. A principal diferença é que, onde Importsapenas carrega o pacote, o Dependsanexa. Não há outras diferenças. [...]

A menos que exista uma boa razão, você deve sempre listar os pacotes Importsnão Depends. Isso ocorre porque um bom pacote é independente e minimiza as alterações no ambiente global (incluindo o caminho de pesquisa). A única exceção é se o seu pacote foi projetado para ser usado em conjunto com outro pacote. Por exemplo, o pacote analógico se baseia em produtos veganos. Não é útil sem veganos, por isso é vegano em Dependsvez de Imports. Da mesma forma, o ggplot2 deve realmente depender de escalas, em vez de importá-lo.

Chambers no SfDA diz usar 'Imports' quando este pacote usa um mecanismo de 'namespace' e como todos os pacotes agora precisam deles, a resposta agora pode ser sempre usar 'Imports'. No passado, os pacotes podiam ter sido carregados sem ter espaços para nome e, nesse caso, você precisaria usar o Depends.

Aqui está uma pergunta simples para ajudá-lo a decidir qual usar:

Seu pacote exige que o usuário final tenha acesso direto às funções de outro pacote?

• NÃO -> Importações (resposta mais comum)
• SIM -> Depende

O único momento em que você deve usar 'Depends' é quando o seu pacote é um complemento ou acessório para outro pacote, em que o usuário final utilizará funções do seu pacote e do pacote 'Depends' no código. Se o seu usuário final estiver interagindo apenas com as suas funções e o outro pacote apenas estiver trabalhando nos bastidores, use 'Importações'.

A ressalva disso é que, se você adicionar um pacote a 'Importações', como normalmente deveria, seu código precisará se referir às funções desse pacote, usando a sintaxe completa do espaço para nome, por exemplo dplyr::mutate(), em vez de apenas mutate(). Isso torna o código um pouco mais complicado de ler, mas é um preço pequeno a pagar por uma melhor higiene das embalagens.