Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #109214 > unrolled thread

Package setup best practice style question

Back to article view | Back to comp.lang.python

This discussion starts older than the indexed window; earlier articles aren't shown. The article labeled Started by below is the oldest one visible, not the original post.

Contents

  Package setup best practice style question Gerald Britton <gerald.britton@gmail.com> - 2016-05-28 12:15 -0400
    Re: Package setup best practice style question Steven D'Aprano <steve@pearwood.info> - 2016-05-29 03:00 +1000
      Re: Package setup best practice style question Steven D'Aprano <steve@pearwood.info> - 2016-05-29 13:02 +1000

#109214 — Package setup best practice style question

suppose I have a simple python project setup like this:

Project diectory
     prog.py
     pkg directory
          __init__.py
          mod1.py
               class A:

In order to have class A (unqualified) available from prog.py, there are a
few options that I know about.  I'm currently considering two of them and
would like some feedback on best practices.

1. in pkg.__init__.py add:

       from pkg.mod1 import A

    in prog.py add:

       from pkg import A

2. leave __init__.py empty
    in prog.py add:

         from pkg.mod1 import A


Is there a preference or best practice that would indicate to prefer method
1 or method 2?  Are there methods 3, 4, 5, ... that I should consider that
are even better?
-- 
Gerald Britton, MCSE-DP, MVP
LinkedIn Profile: http://ca.linkedin.com/in/geraldbritton

[toc] | [next] | [standalone]

#109217

On Sun, 29 May 2016 02:15 am, Gerald Britton wrote:

> suppose I have a simple python project setup like this:
> 
> Project diectory
>      prog.py
>      pkg directory
>           __init__.py
>           mod1.py
>                class A:

If this is a single project, why do you set it up like this? Is there a
reason why you don't just have:

prog.py  # contains class A

or even:

prog.py
mod1.py  # contains class A


Or if the project is so big it needs to be a package, make it executable:

prog/
    __init__.py
    mod1.py
    __main__.py


This layout is now executable using:

python -m prog

which automatically calls __main__.py.


But if you don't have a good reason for using a package, don't use a
package. Use the simplest project layout that solves your problem.

But for the rest of my comments, I'm going to assume that you DO have a good
reason.



> In order to have class A (unqualified) available from prog.py, there are a
> few options that I know about.  I'm currently considering two of them and
> would like some feedback on best practices.
> 
> 1. in pkg.__init__.py add:
> 
>        from pkg.mod1 import A

This kinda-sorta defeats the purpose, or at least one purpose, of using a
package. Which is fine, so long as you understand that's what you are
doing.

Generally speaking, one of the purposes of using a package layout is to
allow unused sub-modules to be left unloaded unless needed. So pkg.mod1
doesn't get loaded unless you need it, in which case you explicitly call 

import pkg.mod1

or 

from pkg.mod1 import A

as you prefer. By putting that import in the pkg __init__ file, you're
making it automatically occur as soon as pkg is imported. Is that what you
intend? If so, then it is fine, and feel free to do it.

But in that case, why not just move class A into pkg/__init__.py?


>     in prog.py add:
> 
>        from pkg import A

*shrug* This entirely depends on the purpose and use of pkg. When you give
generic, meaningless names, I can only respond with wishy-washy, sit-on-
the-fence generic advice.

If the appropriate API is for callers to say:

from pkg import A

then this is the right way to design your package. But if the right API is:

from pkg.mod1 import A

then don't do it this way, instead do it as follows.


> 2. leave __init__.py empty
>     in prog.py add:
> 
>          from pkg.mod1 import A
> 
> 
> Is there a preference or best practice that would indicate to prefer
> method
> 1 or method 2?  Are there methods 3, 4, 5, ... that I should consider that
> are even better?

One purpose of using a package is to have alternative implementations. For
instance I have a package which has to support Python 2.4 where the "with"
statement is not available, so I design it like this:

package/
    __init__.py
    module.py
    module24.py

Since the user doesn't choose which implementation to use, I have this in
the init file:


try:
    from module import thing
except SyntaxError:
    from module24 import thing


and then the caller uses:

from package import thing

and is none the wiser.

On the other hand, if the user was supposed to choose, then I would have
then call:

from package.redblack import Tree
from package.avl import Tree
from package.scapegoat import Tree

and let the user choose which implementation they wanted.


-- 
Steven

[toc] | [prev] | [next] | [standalone]

#109224

On Sun, 29 May 2016 03:00 am, Steven D'Aprano wrote:

> On Sun, 29 May 2016 02:15 am, Gerald Britton wrote:
> 
>> suppose I have a simple python project setup like this:
[...]

To which I responded:

> If this is a single project, why do you set it up like this? Is there a
> reason why you don't just have:
[...]


I'm sorry, on re-reading my post I realise that it might come across as a
bit confrontational. Sorry Gerald, it wasn't intended that way. I was just
intending to point out that we aren't forced to use a package structure at
all, unless it brings actual advantages to the project.



-- 
Steven

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.python

csiph-web