93

I'm trying to put together a really simple module with one .py source file in it, and have already run into a roadblock. I was going to call it scons-config but import scons-config doesn't work in Python. I found this SO question and looked at PEP8 style guide but am kind of bewildered, it doesn't talk about two-word-name conventions.

What's the right way to deal with this?

  • module name: SconsConfig? scons_config? sconsconfig? scons.config?
  • name of the single .py file in it: scons-config.py? scons_config.py?

edit: I did see "the use of underscores is discouraged" and that left me at a dead end: should I use "sconsconfig" or "scons_config" (I guess the other ones are out)?

Community
  • 1
  • 1
Jason S
  • 184,598
  • 164
  • 608
  • 970

4 Answers4

99

If you have to, always use underscores _.

Using a dot . would not even work, otherwise 

from scons.config import whatever

would break.

But PEP 8 clearly describes it:

Package and Module Names

Modules should have short, all-lowercase names. Underscores can be used in the module name if it improves readability. Python packages should also have short, all-lowercase names, although the use of underscores is discouraged.

UPDATE:

To directly target your question: I think sconsconfig is fine. It is not too long and quite readable.

But honestly, I don't think anyone will blame you if you use underscores and your code will run with either decision. There is always a certain level where you should not care that much anymore.

Asclepius
  • 57,944
  • 17
  • 167
  • 143
Felix Kling
  • 795,719
  • 175
  • 1,089
  • 1,143
  • 13
    I saw "use of underscores is discouraged" and it left me at a dead end. – Jason S May 17 '10 at 20:07
  • 9
    @Jason S: Well, use it if readability really suffers or think about another name ;) It is *only* discouraged, not forbidden. – Felix Kling May 17 '10 at 20:09
  • 6
    "There is always a certain level where you should not care that much anymore." True but there are almost always consequences for these kinds of decisions and if you're a beginner like me it's daunting. Thanks! – Jason S May 17 '10 at 20:16
  • 1
    It is worth noting that the first example - using the dot - isn't terrible. It'd be an example of a namespace package as described in [PEP 420](http://www.python.org/dev/peps/pep-0420/). It isn't exactly what the author is trying to achieve though with a simple module. – Mark Embling Jul 21 '13 at 17:03
  • 6
    Example: app_pool VS apppool – Rockallite Mar 20 '14 at 18:06
  • 6
    To clarify, underscores are NOT discouraged for python MODULES. Underscores ARE discouraged for python PACKAGES. – cowlinator Jun 13 '19 at 00:30
24

First, the module name is the same as the name of the single .py file. In Python-speak, a collection of several .py files is a package.

PEP-8 discourages breaking up package names with underscores. A quick peak at my site-packages directory shows that multiword names are commonly just run together (e.g., setuptools, sqlalchemy)

Module names (that is, file names) may be broken up by underscores (and I usually do this, because I hate namesthatruntogethersoyoucanhardlyreadthem).

Stick with lower-case only (per PEP-8). This avoids problems when going from case-sensitive to case-insensitive filesystems and vice versa.

Dan Menes
  • 6,667
  • 1
  • 33
  • 35
11

Aside from PEP-8, you can also check out how the native Python modules deal with this issue.

If you were to compare the native modules of Python 2 to that of Python 3, you would see that the new tendency with the official devs is to avoid uppercase and underscores. For example, ConfigParser in Python 2 becomes configparser in Python 3.

Looking at this, the best course of action would be to avoid uppercase and underscores, and just join the words together, i.e. sconsconfig.

osolmaz
  • 1,873
  • 2
  • 24
  • 41
4

- is a no go. The symbol is used for minus operator. The same is true in most programming languages. Use _ or otherwise nothing at all.

Asclepius
  • 57,944
  • 17
  • 167
  • 143
Wai Yip Tung
  • 18,106
  • 10
  • 43
  • 47