## Package Description
[](https://dl.circleci.com/status-badge/redirect/gh/sfkleach/pushable/tree/main) [](https://pushable.readthedocs.io/en/latest/?badge=latest)
This is a Python package that provides a simple class Pushable that creates "pushable" iterators by wrapping an inner iterator/iterable. Pushable iterators act like dynamically expanding queues, allowing you to peek ahead or push items back onto the queue.
## Basic Usage
We can turn any iterable/iterator into a pushable iterator using the constructor.
```
count_up = Pushable( range( 0, 5 ) )
```
We can use it like an ordinary iterator:
```
print( next( count_up ) )
# Prints 0
```
Or we can look-ahead to see what is coming:
```
whats_up_next = count_up.peek()
print( whats_up_next )
# Print 1
print( next( count_up ) )
# Also prints 1 because peek does not remove the item from the internal queue.
```
We can even push back items onto it:
```
count_up.push("cat")
count_up.push("dog")
print( list( count_up ) )
# Prints 'dog', 'cat', 2, 3, 4
```
## Examples
From an iterator such as a file-object, which will iterate over the lines in a file, create a peekable/pushable iterator. This can be useful for example when we want to know if the iterator still has contents or want a sneak peek at what is coming.
```py
from pushable import Pushable
def read_upto_two_blank_lines( filename ):
with open( filename ) as file:
plines = Pushable( file )
# Pushable iterators can be used as booleans in the natural way.
while plines:
line = next( plines )
# peekOr makes it safe to look ahead.
if line == '\n' and plines.peekOr() == '\n':
# Two blank lines encountered.
break
else:
yield line
```
It is also useful to perform "macro-like" transformation.
```py
from pushable import Pushable
def translate( text, translations ):
ptokens = Pushable( text.split() )
while ptokens:
token = next(ptokens)
if token in translations:
ptokens.multiPush( *translations[token].split() )
else:
yield token
print( ' '.join( translate( 'My name is MYNAME', {'MYNAME':'Fred Bloggs'} ) ) )
# Prints: My name is Fred Bloggs
```
### More Complex Uses
In addition to peeking and popping items, which risks raising a
`StopIteration` exception if there's nothing left on the internal queue, we
can utilise `peekOr` and `popOr` to deliver a default value instead. The
default value is passed as an optional parameter and falls back to None.
We can also peek and pop multiple values using `multiPeekOr` and `multiPopOr`,
which return generators. These support skipping over values so that you can
get the 2nd and 3rd value without getting the first e.g.
```py
(second, third) = Pushable("pqr").multiPop(skip=1, count=2)
print( second, third )
# Prints: q r
```
Lastly, we can push multiple items with `multiPush`:
```py
count_up.multiPush("cat", "dog", "rabbit")
print( list( count_up ) )
# Prints: ['cat', 'dog', 'rabbit']
```
For a full set of available methods see [the documentation](https://pushable.readthedocs.io/en/latest/pushable.html).
Raw data
{
"_id": null,
"home_page": "https://pushable.readthedocs.io/en/latest/",
"name": "pushable",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "iterators, pushable, peekable",
"author": "Stephen Leach",
"author_email": "sfkleach@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/73/96/e57513e72bb25779f90a99dd42b536b303b6e2972655ce1e8fafe9a510f1/pushable-0.1.7.tar.gz",
"platform": null,
"description": "## Package Description\n\n[](https://dl.circleci.com/status-badge/redirect/gh/sfkleach/pushable/tree/main) [](https://pushable.readthedocs.io/en/latest/?badge=latest)\n\nThis is a Python package that provides a simple class Pushable that creates \"pushable\" iterators by wrapping an inner iterator/iterable. Pushable iterators act like dynamically expanding queues, allowing you to peek ahead or push items back onto the queue.\n\n\n## Basic Usage\n\nWe can turn any iterable/iterator into a pushable iterator using the constructor.\n```\ncount_up = Pushable( range( 0, 5 ) )\n```\n\nWe can use it like an ordinary iterator:\n```\nprint( next( count_up ) )\n# Prints 0\n```\n\nOr we can look-ahead to see what is coming:\n```\nwhats_up_next = count_up.peek()\nprint( whats_up_next )\n# Print 1\nprint( next( count_up ) )\n# Also prints 1 because peek does not remove the item from the internal queue.\n```\n\nWe can even push back items onto it:\n```\ncount_up.push(\"cat\")\ncount_up.push(\"dog\")\nprint( list( count_up ) )\n# Prints 'dog', 'cat', 2, 3, 4\n```\n\n## Examples\n\nFrom an iterator such as a file-object, which will iterate over the lines in a file, create a peekable/pushable iterator. This can be useful for example when we want to know if the iterator still has contents or want a sneak peek at what is coming.\n\n```py\nfrom pushable import Pushable\n\ndef read_upto_two_blank_lines( filename ):\n with open( filename ) as file:\n plines = Pushable( file )\n # Pushable iterators can be used as booleans in the natural way.\n while plines:\n line = next( plines )\n # peekOr makes it safe to look ahead.\n if line == '\\n' and plines.peekOr() == '\\n':\n # Two blank lines encountered.\n break\n else:\n yield line \n```\n\nIt is also useful to perform \"macro-like\" transformation.\n\n```py\nfrom pushable import Pushable\n\ndef translate( text, translations ):\n ptokens = Pushable( text.split() )\n while ptokens:\n token = next(ptokens)\n if token in translations:\n ptokens.multiPush( *translations[token].split() )\n else:\n yield token\n\nprint( ' '.join( translate( 'My name is MYNAME', {'MYNAME':'Fred Bloggs'} ) ) ) \n# Prints: My name is Fred Bloggs\n```\n\n### More Complex Uses\n\nIn addition to peeking and popping items, which risks raising a\n`StopIteration` exception if there's nothing left on the internal queue, we\ncan utilise `peekOr` and `popOr` to deliver a default value instead. The \ndefault value is passed as an optional parameter and falls back to None.\n\nWe can also peek and pop multiple values using `multiPeekOr` and `multiPopOr`, \nwhich return generators. These support skipping over values so that you can\nget the 2nd and 3rd value without getting the first e.g.\n\n```py\n(second, third) = Pushable(\"pqr\").multiPop(skip=1, count=2)\nprint( second, third )\n# Prints: q r\n```\n\nLastly, we can push multiple items with `multiPush`:\n```py\ncount_up.multiPush(\"cat\", \"dog\", \"rabbit\")\nprint( list( count_up ) )\n# Prints: ['cat', 'dog', 'rabbit']\n```\n\nFor a full set of available methods see [the documentation](https://pushable.readthedocs.io/en/latest/pushable.html).\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "Convert iterators into peekable, pushable iterators",
"version": "0.1.7",
"project_urls": {
"Documentation": "https://pushable.readthedocs.io/en/latest/",
"Homepage": "https://pushable.readthedocs.io/en/latest/",
"Repository": "https://github.com/sfkleach/pushable"
},
"split_keywords": [
"iterators",
" pushable",
" peekable"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bf6c9e901461db64f2e34e20b9f3eb45de5c870674f245423364b55fea643a62",
"md5": "54273d1949e2fece390a43ebe0b5d297",
"sha256": "ce98acb81be40e13992540d52e79c1a90b5953979accc3e5026d2597de04de69"
},
"downloads": -1,
"filename": "pushable-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "54273d1949e2fece390a43ebe0b5d297",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 17146,
"upload_time": "2024-04-23T19:27:42",
"upload_time_iso_8601": "2024-04-23T19:27:42.612850Z",
"url": "https://files.pythonhosted.org/packages/bf/6c/9e901461db64f2e34e20b9f3eb45de5c870674f245423364b55fea643a62/pushable-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7396e57513e72bb25779f90a99dd42b536b303b6e2972655ce1e8fafe9a510f1",
"md5": "9edc3038e3580a2b7a252b8ceaef1324",
"sha256": "757fbd5754f3e0f20bdfba4f92efdb9c12860aa0e8579fca665e736df9b66017"
},
"downloads": -1,
"filename": "pushable-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "9edc3038e3580a2b7a252b8ceaef1324",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 16474,
"upload_time": "2024-04-23T19:27:44",
"upload_time_iso_8601": "2024-04-23T19:27:44.192653Z",
"url": "https://files.pythonhosted.org/packages/73/96/e57513e72bb25779f90a99dd42b536b303b6e2972655ce1e8fafe9a510f1/pushable-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-23 19:27:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sfkleach",
"github_project": "pushable",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"lcname": "pushable"
}
JSON
