While @rcollyer has answered the "what", I feel that this question still deserves an additional answer because no less important is IMO the why.
Public and private package import
The first form (contexts in BeginPackage
) is called the public import. What this means is that, in addition to making the public symbols of those contexts available for the implementation of your package, you also make them available for the code that loads your package, be it some top-level code or another package. The two typical use cases when you may want to do this are:
- You want at least some of the functionality of the packages you use in your package to be also available to the end user
- Your package is actually an extension of some other package, much like a subclass extends its parent class in OOP.
The difference between these two scenarios is sometimes blurred.
The second form is called private import, and is recommended for most cases when you import some functions from other packages into yours. Most of the time, you want it this way, since you only use those functions in implementation of your package's functions, and otherwise the end user could not care less what they are.
How it works
Technically, the encapsulation is realized by the way how BeginPackage
and EndPackage
functions manipulate the $ContextPath
. What happens is that BeginPackage
calls Needs
on all contexts indicated in its second argument (which is why the ordering is different, as @rcollyer indicated), so that the corresponding packages are loaded (if necessary) and the contexts added to the $ContextPath
in such a way that they will not be removed by EndPackage
. OTOH, all the modifications of $ContextPath
in the body of the package between BeginPackage
and EndPackage
are undone by EndPackage
, which makes the packages imported by calls to Needs
in the package body to be privately imported.
An additional subtlety
There is one additional subtlety related to the use of BeginPackage
, which is not widely known and can be puzzling at first. Consider some package A`
, which imports packages B`
and C`
publicly (in other words, it starts with BeginPackage["A`",{"B`","C`"}]
). Imagine that A`
has been loaded, but is not on the $ContextPath
at the moment (for example, it was privately imported by another package). Then, if you call Needs["A`"]
, not only will A`
be added to the $ContextPath
, but also B`
and C`
.
This is a rather natural behavior when we think about it, but back in the day it took me a while to figure out why calling Needs
on a single context brings many contexts to the $ContextPath
. What this means is that the public dependencies declared through BeginPackage
are cached. This does not happen for private package imports.
Further information
A much better and more complete description of these mechanisms can be found in the book of Roman Maeder "Programming in Mathematica", which IMO remains to this day the best reference for package mechanics in Mathematica.