[issue35123] Add style guide for sentinel usage

[Serhiy Storchaka]

Serhiy Storchaka  added the comment:

I agree that there are not any problems that need solving.

--
nosy: +serhiy.storchaka
resolution:  -> not a bug
stage:  -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue35123] Add style guide for sentinel usage

[Robert Wright]

Robert Wright  added the comment:

Perhaps there's confusion over what I mean by "style guide". I'd happily take 
Steven's message *as* the style guide. Or, at the very least, the clarification 
that sentinels are to be thought of as constants.

It's one of those things that's obvious once mentioned, but might not be 
thought of when you're using them.

Though Eric does raise an interesting point about C sentinels. Something like:

kwargs = {}

if mode is not _MISSING:
  kwargs.update(mode=mode)

return open(name, "foo", **kwargs)

would work a bit better with multiple arguments, but it's still not great.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue35123] Add style guide for sentinel usage

[Eric V. Smith]

Eric V. Smith  added the comment:

I don't see any problems that need solving.

My only interest in this is that I tend to think sentinels that are used for 
missing parameters should be exposed, and this isn't always an obvious 
consideration when designing an API.

For example, say there's a library that has a function:
open(name, type, [mode])

That is, mode is optional. I realize that in pure Python, I could find out what 
sentinel value they're using, unless they're playing tricks with args and 
kwargs. But maybe this is written in C.

Now, say I want to write a wrapper around this, called myopen, and always pass 
in "foo" for type.

I'd need to use my own sentinel:
_MISSING= object()
def myopen(name, mode=_MISSING)

But, how do I call open? In the past, I've done things like:
if mode is _MISSING:
  return open(name, "foo")
else:
  return open(name, "foo", mode)

That doesn't scale well if there are multiple optional parameters.

In any event, this just seems like a guideline we should be aware of when 
adding APIs.

Absent any concrete proposals for a "sentinel style guide", I don't think 
there's anything actionable here. I agree with Steven that it's a case-by-case 
thing. One size need not fit all.

As to the issue referenced by Victor: I'm not sure what a style guide would 
bring to the table. I think the issue of whether to use a second sentinel or 
not could be decided in this file alone, without needed a global decision.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue35123] Add style guide for sentinel usage

[Steven D'Aprano]

Steven D'Aprano  added the comment:

I was not aware that there currently were arguments about the use of sentinels 
in future code. I feel that you are being excessively prescriptive here:

"we should nip it in the bud"

is good advice for gardening, but for programming it just results in a lot of 
pre-emptive arguments about prescriptive rules that aren't needed.

What makes a sentinel a sentinel is *how it is used*, not what it is. As such, 
sentinels are just another type of (pseudo-)constant, and the same style guides 
should apply: in general, they should be in UPPER case, at the top of the 
module. (But remember the rule about foolish consistency.)

And each sentinel should be reused exactly as often as is appropriate. The same 
as any other constant.

As for exposing sentinels, the same applies to any part of the implementation. 
Should we make this a public part of the API or a private implementation 
detail? That has to be judged on a case-by-case basis. Making a rule or even a 
guideline that just because something is a sentinel is "should be" public (or 
private) is precisely the sort of thing I don't want to see. Sentinels should 
be public when it makes sense to make them public and private when it makes 
sense to keep them as private implementation details.

The bottom line is, I don't think we need sentinel-specific rules in the style 
guide. That would be like adding specific rules for "numeric constants", or 
specific rules for "constants used by decorators".

--
nosy: +steven.daprano

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue35123] Add style guide for sentinel usage

[STINNER Victor]

STINNER Victor  added the comment:

Context: https://github.com/python/cpython/pull/8548#pullrequestreview-166711603

--
nosy: +vstinner

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue35123] Add style guide for sentinel usage

[Robert Wright]

Robert Wright  added the comment:

Just the classic problems caused by inconsistency in code - confusion when 
reading, and disagreements when writing.

For reading: Where should I look in a file for the sentinels? Is this value a 
sentinel, or is it some other type of variable?

For writing, there will always be disagreements in PRs, so we should nip it in 
the bud.

You raise a good point about exposing sentinel values. I was previously on the 
fence about whether sentinels should (in general) be private, or public.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue35123] Add style guide for sentinel usage

[Eric V. Smith]

Eric V. Smith  added the comment:

Could you give some examples of problems caused by inconsistent usage of 
sentinels?

I do often wish modules exposed their sentinel values, since it makes writing 
wrappers easier. It's one of the reasons I ended up exposing 
dataclasses.MISSING.

--
nosy: +eric.smith

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue35123] Add style guide for sentinel usage

[Robert Wright]

New submission from Robert Wright :

Sentinel values are used inconsistently in the Python code base.

It would be helpful to have a style guide (about eg. casing, placement, and 
sentinel reuse) to prevent arguments about their use in future code.

--
messages: 328984
nosy: madman bob
priority: normal
severity: normal
status: open
title: Add style guide for sentinel usage

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com