classification
Title: Add peek() or first() method in queue
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.8
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: Ark-kun, Windson Yang, docs@python, rhettinger
Priority: low Keywords: patch

Created on 2018-10-31 03:20 by Windson Yang, last changed 2021-03-23 01:31 by rhettinger. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 10265 merged Windson Yang, 2018-10-31 20:14
Messages (9)
msg328963 - (view) Author: Windson Yang (Windson Yang) * Date: 2018-10-31 03:20
I found other languages like Java and C++ have the method to access the first value in Queue like first() and peek(). Since we use deque_ to create Queue now, it's easy to implement in python using the index. Otherwise, we can add this to the document? I also found some discussion_ here.


.. _deque: 
 https://github.com/python/cpython/blob/master/Lib/queue.py#L205

.. _discussion https://mail.python.org/pipermail/python-list/2010-March/569930.html
msg328965 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2018-10-31 04:06
For deque, we have d[0].  Is anything more needed?  Even lists don't require a peek.

For Queue, I'm not sure I've ever seen any use case for peek.  What do you have in mind?  

* https://docs.oracle.com/javase/7/docs/api/java/util/Queue.html#peek()
msg328967 - (view) Author: Windson Yang (Windson Yang) * Date: 2018-10-31 05:23
For deque, we can add peek() function to deque or just make it clear in the document that we can use deque[0] to access the first element(I can only find index method in the document)

For Queue, I found Java and C++ has the function like first() or peek(), I'm not sure should we also implement a method like this.


* http://www.cplusplus.com/reference/queue/queue/
msg328969 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2018-10-31 05:38
In the absence of good use cases, I'll decline the API expansion.

Feel free to post a PR to have the deque documentation to mention d[0] indexing more prominently.  Am not really sure that is needed though, we don't have to point out the same thing for lists and I haven't encountered any misunderstandings on the topic.  This would be just a minor usage note.
msg329271 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2018-11-04 22:34
New changeset 98b85354153883b0a080f678f213729cd0764fee by Raymond Hettinger (Windson yang) in branch 'master':
bpo-35118: Improve docs regarding indexing (GH-10265)
https://github.com/python/cpython/commit/98b85354153883b0a080f678f213729cd0764fee
msg388195 - (view) Author: Alexey Volkov (Ark-kun) Date: 2021-03-06 06:22
>For Queue, I'm not sure I've ever seen any use case for peek.  What do you have in mind?

I want to examine the first (oldest) element in queue and remove it if it's too old.

The queue should not be modified unless the oldest element is too old.
msg388324 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2021-03-09 02:30
> I want to examine the first (oldest) element in queue and 
> remove it if it's too old.

Why not just dismiss older queue entries during a normal get() operation?  Or just use a plain deque with access guarded by a lock.

FWIW, the standard library queue module doesn't have a straight-forward way to implement a peek() method.  The module guarantees that the underlying data structure is only accessed with _init, _qsize, _get, and _put.


That would be difficult to do atomically with a Queue object.
msg388824 - (view) Author: Alexey Volkov (Ark-kun) Date: 2021-03-16 08:39
>Why not just dismiss older queue entries during a normal get() operation?  Or just use a plain deque with access guarded by a lock.

You do not know whether the item needs to be removed until you see it. And to see it you need to get it. And if you get it, you cannot push it back to the start of the queue.

>FWIW, the standard library queue module doesn't have a straight-forward way to implement a peek() method.

I currently use `q.deque[0]`

>Or just use a plain deque with access guarded by a lock.

I can. But technically the same applies to almost any queue usage.
msg389362 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2021-03-23 01:31
>> FWIW, the standard library queue module doesn't have 
>> a straight-forward way to implement a peek() method.

> I currently use `q.deque[0]`

The Queue class is only allowed to call _init, _qsize, _put, and _get.  It is not allowed to directly touch the underlying data structure.  Otherwise, subclasses relying on the abstraction would fail.
History
Date User Action Args
2021-03-23 01:31:51rhettingersetmessages: + msg389362
2021-03-16 08:39:13Ark-kunsetmessages: + msg388824
2021-03-09 02:30:54rhettingersetmessages: + msg388324
2021-03-06 06:22:10Ark-kunsetnosy: + Ark-kun
messages: + msg388195
2018-11-04 22:34:54rhettingersetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2018-11-04 22:34:24rhettingersetmessages: + msg329271
2018-10-31 20:14:01Windson Yangsetkeywords: + patch
stage: patch review
pull_requests: + pull_request9576
2018-10-31 05:38:13rhettingersetpriority: normal -> low

messages: + msg328969
2018-10-31 05:23:49Windson Yangsetmessages: + msg328967
2018-10-31 04:06:35rhettingersetmessages: + msg328965
versions: - Python 2.7, Python 3.4, Python 3.5, Python 3.6, Python 3.7
2018-10-31 03:38:13rhettingersetassignee: docs@python -> rhettinger

nosy: + rhettinger
2018-10-31 03:20:18Windson Yangcreate