[PEP] Standardizing Pyomo Imports in examples as "import pyomo.environ as pyo"

[whart222]

(Edited by @carldlaird) This PEP advocates use of the "pyo" alias throughout the documentation, pyomo examples, and tutorials.

Motivation

Users find it confusing that we have not "standardized" on a particular approach for imports (some use from pyomo.environ import *, some use import pyomo.environ as pe, and some use import pyomo.environ as pyo). We also agree that it is generally bad practice to import *, and would prefer to use advocate the use of a named alias when importing pyomo.environ.

Implementation

Standardize on "import pyomo.environ as pyo".

This will need to be done for:

• [ ] examples in read-the-docs
• [ ] examples in the pyomo repository (examples directory)
• [x] exercises and slides for Pyomo workshops

@carldlaird has agreed to implement this PEP.

Original Introduction from @whart222 included below:

Currently, three conventions are used in the Pyomo online documentation for importing Pyomo:

• Symbols are imported from pyomo.environ """ from pyomo.environ import * """
• The pyomo.environ module is imported to an alias """ import pyomo.environ as pyo """
• The environment is imported, and symbols are referenced directly from the pyomo library """ import pyomo.environ from pyomo.opt import SolverFactory """

A brand new user recently noted how confusing this made the online documentation. The fact that 'pyo' was used was particularly confusing because that alias is not included in most examples.

We need to standardize documentation to avoid such confusion, and provide more complete examples if we use an alias like 'pyo'. I think this PEP should include a specific recommendation to either use 'pyo' or not. Let's include comments for/against.

[blnicho]

We should also propagate whatever import convention we choose to the workshop slides, examples, and exercises.

I personally use from pyomo.environ import * however my vote for standardization would be for import pyomo.environ as pyo (or I think some folks use import pyomo.environ as pe). I think importing to an alias is more Pythonic and it makes the code very explicit as to which classes/functions are coming from Pyomo.

[jwatsonnm]

I concur with @blnicho - and prefer to adopt "import pyomo.environ as pro" following our colleagues at NPS and elsewhere.

[carldlaird]

Assuming you meant "pyo" instead of "pro", I agree as well.

[jwatsonnm]

Whoops - yes. Stupid autocorrect. Or neurons.

[carldlaird]

Bill above asked us to list comments against the use of an alias. The only one I can think about is that it adds some additional "pyo." to our code - that might not look as nice in examples. (maybe). This could be overcome with explicit imports (e.g., from pyomo.environ import ConcreteModel, Constraint, Objective, ...). But that list would get extensive, and I don't favor that approach over the pyo approach.

[jwatsonnm]

We could ask everyone if they like "std::endl" or "endl" better - I bet the survey would predict who does and doesn't like aliases almost perfectly. For the record, I personally believe that "using namespace std" is evil. Sure, the alias makes short examples slightly longer. But the clarity has to outweigh the conciseness.

[DLWoodruff]

I agree with standardizing to pyo; however, an interesting debate is based on the following: When Bill says "and provide more complete examples if we use an alias like 'pyo'" he seems to imply that every code snippet that uses pyo would , at a minimum, need to include import pyomo.environ as pyo

There are many python packages that do that sort of thing, but our situation is a little different. Many of our code snippets rely on lots of things that are not rendered to the screen. These snippets are not intended to serve as a tutorial, but rather to let a user remember, or learn, a particular syntax.

[whart222]

@DLWoodruff FWIW, I'm OK not adding the import alias in every example, but per a user suggestion we should include a simple example at the beginning of our documentation to establish this convention.