6

I'm writing a custom sub-class of Queue.Queue and run into a situation where I need to acquire a queue-level lock when my custom put() is being called. I'd like to reuse the existing lock Queue has (Queue.mutex), but can't because its not an RLock.

In the source (python 2.6), it says:

# Override these methods [_put, _get, etc] to implement other queue organizations
# (e.g. stack or priority queue).
# These will only be called with appropriate locks held

But the online documentation doesn't mention overriding them. The other Queue implementations in that module override these. So, I'm kinda inclined to believe that the _put method is package-private and isn't really intended for use outside the Queue module.

Does anyone know how kosher it would be to use Queue._put and friends in my own subclass?

Richard Levasseur
  • 14,562
  • 6
  • 50
  • 63

1 Answers1

2

As far as I'm concerned, it would be completely kosher. In Python, the source is the documentation, or at least should be considered as a supplement to the published API documentation. This is largely a consequence of the enforced use of whitespace and coding conventions that emphasize clear, readable code: when you have questions that the documentation doesn't answer, you're supposed to be able to go to the source code and look up the answers.

In particular, details like this one are irrelevant to most clients of the Queue module (who are simply using the classes), so they wouldn't make it into the published docs. But if you want to subclass Queue, the developers expect you to be digging deeper, so the note is there in the source code for you to find.

I will also mention that Python doesn't really have a concept of "package-private." Semantically, there's no difference between a subclass which is in the same module and one which is in a different module, even one you write yourself. In fact, Python doesn't even have a concept of "private". Instead, it relies on a principle of responsible usage: as a developer you're expected to be smart enough not to use internal methods when you don't need to. Starting a member name with an underscore is simply a clue that it's an internal method, and that you probably shouldn't be accessing it if you are simply using the class - but if you're subclassing it, anything is fair game.

Community
  • 1
  • 1
David Z
  • 128,184
  • 27
  • 255
  • 279
  • Do you have a more authoritative source than your own answer for "the source is the documentation"? I've seen various discussions on python-dev about what visibility one should assume from the stdlib when there's no official documentation. Another point I hadn't considered is that Queue is essentially the same in 3.2, so I don't have to worry about upgrade issues. – Richard Levasseur Dec 13 '11 at 02:58
  • No I don't, it's just a sense I've picked up over a few years of programming with Python. In any case I didn't intended that link to be a source or to have any sort of authority; I just wanted to work it in somewhere since I remembered writing that answer recently and I thought it would be interesting further reading. – David Z Dec 13 '11 at 03:18
  • Actually: I think I may have read _somewhere_ more authoritative that the source should be considered a supplement to the documentation, or something to that effect. But I don't remember any details. – David Z Dec 13 '11 at 03:20