Group some os functions in submodules

[ezio-melotti]

BPO	13263
Nosy	@loewis, @birkenfeld, @rhettinger, @pitrou, @vstinner, @benjaminp, @ezio-melotti, @merwok, @akheron

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2012-09-26.14:58:15.652>
created_at = <Date 2011-10-25.12:06:16.549>
labels = ['extension-modules', 'type-feature']
title = 'Group some os functions in submodules'
updated_at = <Date 2012-09-26.14:58:15.651>
user = 'https://github.com/ezio-melotti'

bugs.python.org fields:

activity = <Date 2012-09-26.14:58:15.651>
actor = 'ezio.melotti'
assignee = 'none'
closed = True
closed_date = <Date 2012-09-26.14:58:15.652>
closer = 'ezio.melotti'
components = ['Extension Modules']
creation = <Date 2011-10-25.12:06:16.549>
creator = 'ezio.melotti'
dependencies = []
files = []
hgrepos = []
issue_num = 13263
keywords = []
message_count = 13.0
messages = ['146363', '146386', '146390', '146392', '146393', '146399', '146417', '146419', '146509', '146512', '146513', '163645', '171343']
nosy_count = 12.0
nosy_names = ['loewis', 'georg.brandl', 'rhettinger', 'pitrou', 'vstinner', 'benjamin.peterson', 'ezio.melotti', 'eric.araujo', 'Arfrever', 'neologix', 'rosslagerwall', 'petri.lehtinen']
pr_nums = []
priority = 'normal'
resolution = 'out of date'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue13263'
versions = ['Python 3.3']

[ezio-melotti]

In Python 3.3 the os module gained a few new functions and constants:

Python 3.2.2+ (3.2:58a75eeb5c8e, Sep 29 2011, 02:11:05) 
>>> import os; len(dir(os))
232

Python 3.3.0a0 (default:a50f080c22ca+, Oct 25 2011, 09:56:01) 
>>> import os; len(dir(os))
332

http://docs.python.org/dev/py3k/whatsnew/3.3.html#os lists some of these additions, and they are already grouped (e.g. the sched_* functions, the "at" functions, ...).

Before the os API gets even more bloated, maybe we should group some of these functions in new submodules, like os.sched.*.

[loewis]

I think there is a value to use the very same function names in the posix module as in the posix API. The posix API (and C in general) is also flat, and uses the prefix convention. People who look at the function lists will know to ignore blocks of functions by prefix if they don't need them.

[ezio-melotti]

Of the new ones, only the sched_* ones share a common prefix, the *xattr and *at functions share a common suffix, and it's difficult to find them e.g. in dir() (also it's difficult to find other common os functions among all the names). The fact that the Posix API and C in general use a flat API doesn't seem to me a valid reason to do the same in Python. Having the same name is a good reason to avoid sched.*, even if I don't think that having sched.* will make finding/recognizing these functions much more difficult.

[neologix]

I think there is a value to use the very same function names in the
posix module as in the posix API.

It would still be the case, except that they'd live in distinct submodule.

The posix API (and C in general) is also flat, and uses the prefix
convention.

That's because C doesn't have namespaces: it's certainly due to this limitation, and not a design choice (and when you think about it, there is a namespace hierarchy, in the header files: <sys/sched.h>, <attr/xatr.h>, etc.).

[rosslagerwall]

Some functions would be easy to split off into separate modules conceptually like the sched_* functions and the cap_* functions (see bpo-1615158).

However, certain groups of functions like the *at functions cover a lot of different functionality and don't really belong together.

Perhaps the only grouping that should be done is for functions that start with a common prefix like sched_* since they are basically in a C "namespace".

[vstinner]

I would prefer to keep the shared prefix even if we move functions to a new module. Python refers usually to the C documentation for the details of a function. If we rename a function, it becomes more difficult to get the manual of the function.

[neologix]

I would prefer to keep the shared prefix even if we move functions to a new module. Python refers usually to the C documentation for the details of a function. If we rename a function, it becomes more difficult to get the manual of the function.

Indeed.
But that's what I understood from Ezio's proposal, I don't think he's
suggesting to rename them.

[ezio-melotti]

It would be fine for me to rename os.sched_get_priority_max() to os.sched.get_priority_max().
os.sched.sched_get_priority_max() is a bit redundant, and I think it's not to difficult to figure out that os.sched.get_priority_max() corresponds to the posix sched_get_priority_max() function, especially if we add a note to the doc (I'm only -0 about keeping the original name though).
Regarding the other functions that don't share a common prefix it's certainty better to keep the original name.

[pitrou]

I don't think submodules are a good idea. In practice, for example, urllib.request.urlopen is more painful to use than good old urllib.urlopen.

If it's a matter of documentation, it can be split in several subchapters.
If it's a matter of organizing source code, it can also be split in several C files: see the _io module for an example.

[ezio-melotti]

I agree about urllib.request.urlopen, but os.sched.get_priority_max() is not longer than os.sched_get_priority_max().
I also agree about the documentation -- that should be organized in several sections, regardless of what happens with the module.

[pitrou]

I agree about urllib.request.urlopen, but os.sched.get_priority_max()
is not longer than os.sched_get_priority_max().

Agreed. There are not many functions which could get this treatment,
though.

[ezio-melotti]

FWIW we have 12 functions less since 3.3.0a0 (probably after bpo-14626):

Python 3.3.0a4+ (default:8dd2f5754b2f, Jun 23 2012, 16:50:40) 
>>> import os; len(dir(os))
320

[ezio-melotti]

Now it's too late to fix this, so I'm closing it.