immutable-views - Immutable views on other collection objects
=============================================================
.. image:: https://badge.fury.io/py/immutable-views.svg
:target: https://pypi.python.org/pypi/immutable-views/
:alt: Version on Pypi
.. image:: https://github.com/andy-maier/immutable-views/workflows/test/badge.svg?branch=master
:target: https://github.com/andy-maier/immutable-views/actions/
:alt: Actions status
.. image:: https://readthedocs.org/projects/immutable-views/badge/?version=latest
:target: https://readthedocs.org/projects/immutable-views/builds/
:alt: Docs build status (master)
.. image:: https://coveralls.io/repos/github/andy-maier/immutable-views/badge.svg?branch=master
:target: https://coveralls.io/github/andy-maier/immutable-views?branch=master
:alt: Test coverage (master)
Overview
--------
The **immutable-views** package provides collection classes that are immutable
views on other (mutable) collection objects:
* `DictView <https://immutable-views.readthedocs.io/en/latest/api_dict_view.html>`_ -
immutable view on another mapping (dictionary) object.
* `ListView <https://immutable-views.readthedocs.io/en/latest/api_list_view.html>`_ -
immutable view on another sequence (list) object.
* `SetView <https://immutable-views.readthedocs.io/en/latest/api_set_view.html>`_ -
immutable view on another set object.
An important behavior of views is that they are "live": Since the view classes
delegate to the underlying collection, any modification of the underlying
collection object will be visible in the view object.
Creating an immutable view on a collection does not copy the collection and
is therefore much faster than creating an immutable copy of the collection.
The memory overhead of using immutable views is very small: An object
of any of the view classes in the **immutable-views** package occupies 40 Bytes
(measured in CPython 3.9 on macOS), and because the view object only has a
reference to its underlying collection object, that size is independent of the
number of items in the collection.
The compute overhead is also very small, it is basically an additional function
call to the corresponding function of the underlying collection.
Immutable views are useful if a method or function maintains data in form of a
mutable collection and is intended to return that data but users should not be
able to modify the data. The underlying collection can be updated by the method
or function as needed, but the caller only gets an immutable view on it.
The view classes in the **immutable-views** package implement the complete
behavior of the corresponding Python collection types except for any
operations that would modify the underlying collection object.
The view classes delegate all operations to the underlying collection object
they are a view of. Therefore, the underlying collection can be any kind of
collection implementation (i.e. not just the standard Python collection
classes).
Note that the immutability of the view objects only applies to the view object
itself and to its underlying collection, but not to the items in the underlying
collection. So if the underlying collection contains mutable objects, they will
still be mutable when accessed through the view objects.
The standard Python class
`types.MappingProxyType <https://docs.python.org/3/library/types.html#types.MappingProxyType>`_
serves the same purpose as the
`DictView <https://immutable-views.readthedocs.io/en/latest/api_dict_view.html>`_
class but it does not support pickling or hashing and was added only in
Python 3.3.
The ``dictproxy`` class from the
`dictproxyhack <https://pypi.org/project/dictproxyhack/>`_
package on Pypi supports Python 2 and Python 3 and uses Python classes where
available (e.g. ``MappingProxyType`` on Python 3.3 and later, and the internal
``mappingproxy`` class used for ``__dict__`` on CPython) but also does not
support pickling or hashing.
The lack of support for standard dictionary behaviors prevents their use in
cases where the view class is used as a read-only replacement for the standard
dictionary.
Note that there are several packages on Pypi that provide immutable
collections, but they all are collections on their own, and not views on
other collections. Here is a notable subset of such packages:
* `immutables <https://pypi.org/project/immutables/>`_
* `pyimmutable <https://pypi.org/project/pyimmutable/>`_
* `frozenordereddict <https://pypi.org/project/frozenordereddict/>`_
* `immutabledict <https://pypi.org/project/immutabledict/>`_
* `frozendict <https://pypi.org/project/immutabledict/>`_
* `itypes <https://pypi.org/project/itypes/>`_
* `HashableDict <https://pypi.org/project/HashableDict/>`_
* `shoobx.immutable <https://pypi.org/project/shoobx.immutable/>`_
* `immutable-collection <https://pypi.org/project/immutable-collection/>`_
* `Dict-Path-Immutable <https://pypi.org/project/Dict-Path-Immutable/>`_
.. _`Examples`:
Examples
--------
Example with dictionaries:
.. code-block:: bash
$ python
>>> from immutable_views import DictView
>>> dict1 = {'a': 1, 'b': 2}
>>> dictview1 = DictView(dict1)
# Read-only access to the underlying collection through the view is supported:
>>> dictview1['a']
1
# Modifying the underlying collection through the view is rejected:
>>> dictview1['a'] = 2
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: 'DictView' object does not support item assignment
# Modifications of the underlying collection are visible in the view:
>>> dict1['a'] = 2
>>> dictview1['a']
2
Example with lists:
.. code-block:: bash
$ python
>>> from immutable_views import ListView
>>> list1 = ['a', 'b']
>>> listview1 = ListView(list1)
# Read-only access to the underlying collection through the view is supported:
>>> listview1[0]
'a'
# Modifying the underlying collection through the view is rejected:
>>> listview1[0] = 'c'
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: 'ListView' object does not support item assignment
# Modifications of the underlying collection are visible in the view:
>>> list1[0] = 'c'
>>> listview1[0]
'c'
Example with sets:
.. code-block:: bash
$ python
>>> from immutable_views import SetView
>>> set1 = {'a', 'b'}
>>> setview1 = SetView(set1)
# Read-only access to the underlying collection through the view is supported:
>>> 'a' in setview1
True
# Modifying the underlying collection through the view is rejected:
>>> setview1.add('c')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
AttributeError: 'SetView' object has no attribute 'add'
# Modifications of the underlying collection are visible in the view:
>>> set1.add('c')
>>> 'c' in setview1
True
Documentation and change log
----------------------------
* `Documentation <https://immutable-views.readthedocs.io/en/latest/>`_
* `Change log <https://immutable-views.readthedocs.io/en/latest/changes.html>`_
License
-------
The **immutable-views** project is provided under the
`Apache Software License 2.0 <https://raw.githubusercontent.com/andy-maier/immutable-views/master/LICENSE>`_.
Raw data
{
"_id": null,
"home_page": "https://github.com/andy-maier/immutable-views",
"name": "immutable-views",
"maintainer": "Andreas Maier",
"docs_url": null,
"requires_python": ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*",
"maintainer_email": "andreas.r.maier@gmx.de",
"keywords": "",
"author": "Andreas Maier",
"author_email": "andreas.r.maier@gmx.de",
"download_url": "https://files.pythonhosted.org/packages/ce/05/6c84a56d52ad8e838389651a59e7e71d175ca26656605883b79fe3a734e2/immutable-views-0.6.1.tar.gz",
"platform": "any",
"description": "immutable-views - Immutable views on other collection objects\n=============================================================\n\n.. image:: https://badge.fury.io/py/immutable-views.svg\n :target: https://pypi.python.org/pypi/immutable-views/\n :alt: Version on Pypi\n\n.. image:: https://github.com/andy-maier/immutable-views/workflows/test/badge.svg?branch=master\n :target: https://github.com/andy-maier/immutable-views/actions/\n :alt: Actions status\n\n.. image:: https://readthedocs.org/projects/immutable-views/badge/?version=latest\n :target: https://readthedocs.org/projects/immutable-views/builds/\n :alt: Docs build status (master)\n\n.. image:: https://coveralls.io/repos/github/andy-maier/immutable-views/badge.svg?branch=master\n :target: https://coveralls.io/github/andy-maier/immutable-views?branch=master\n :alt: Test coverage (master)\n\n\nOverview\n--------\n\nThe **immutable-views** package provides collection classes that are immutable\nviews on other (mutable) collection objects:\n\n* `DictView <https://immutable-views.readthedocs.io/en/latest/api_dict_view.html>`_ -\n immutable view on another mapping (dictionary) object.\n* `ListView <https://immutable-views.readthedocs.io/en/latest/api_list_view.html>`_ -\n immutable view on another sequence (list) object.\n* `SetView <https://immutable-views.readthedocs.io/en/latest/api_set_view.html>`_ -\n immutable view on another set object.\n\nAn important behavior of views is that they are \"live\": Since the view classes\ndelegate to the underlying collection, any modification of the underlying\ncollection object will be visible in the view object.\n\nCreating an immutable view on a collection does not copy the collection and\nis therefore much faster than creating an immutable copy of the collection.\n\nThe memory overhead of using immutable views is very small: An object\nof any of the view classes in the **immutable-views** package occupies 40 Bytes\n(measured in CPython 3.9 on macOS), and because the view object only has a\nreference to its underlying collection object, that size is independent of the\nnumber of items in the collection.\n\nThe compute overhead is also very small, it is basically an additional function\ncall to the corresponding function of the underlying collection.\n\nImmutable views are useful if a method or function maintains data in form of a\nmutable collection and is intended to return that data but users should not be\nable to modify the data. The underlying collection can be updated by the method\nor function as needed, but the caller only gets an immutable view on it.\n\nThe view classes in the **immutable-views** package implement the complete\nbehavior of the corresponding Python collection types except for any\noperations that would modify the underlying collection object.\n\nThe view classes delegate all operations to the underlying collection object\nthey are a view of. Therefore, the underlying collection can be any kind of\ncollection implementation (i.e. not just the standard Python collection\nclasses).\n\nNote that the immutability of the view objects only applies to the view object\nitself and to its underlying collection, but not to the items in the underlying\ncollection. So if the underlying collection contains mutable objects, they will\nstill be mutable when accessed through the view objects.\n\nThe standard Python class\n`types.MappingProxyType <https://docs.python.org/3/library/types.html#types.MappingProxyType>`_\nserves the same purpose as the\n`DictView <https://immutable-views.readthedocs.io/en/latest/api_dict_view.html>`_\nclass but it does not support pickling or hashing and was added only in\nPython 3.3.\nThe ``dictproxy`` class from the\n`dictproxyhack <https://pypi.org/project/dictproxyhack/>`_\npackage on Pypi supports Python 2 and Python 3 and uses Python classes where\navailable (e.g. ``MappingProxyType`` on Python 3.3 and later, and the internal\n``mappingproxy`` class used for ``__dict__`` on CPython) but also does not\nsupport pickling or hashing.\nThe lack of support for standard dictionary behaviors prevents their use in\ncases where the view class is used as a read-only replacement for the standard\ndictionary.\n\nNote that there are several packages on Pypi that provide immutable\ncollections, but they all are collections on their own, and not views on\nother collections. Here is a notable subset of such packages:\n\n* `immutables <https://pypi.org/project/immutables/>`_\n* `pyimmutable <https://pypi.org/project/pyimmutable/>`_\n* `frozenordereddict <https://pypi.org/project/frozenordereddict/>`_\n* `immutabledict <https://pypi.org/project/immutabledict/>`_\n* `frozendict <https://pypi.org/project/immutabledict/>`_\n* `itypes <https://pypi.org/project/itypes/>`_\n* `HashableDict <https://pypi.org/project/HashableDict/>`_\n* `shoobx.immutable <https://pypi.org/project/shoobx.immutable/>`_\n* `immutable-collection <https://pypi.org/project/immutable-collection/>`_\n* `Dict-Path-Immutable <https://pypi.org/project/Dict-Path-Immutable/>`_\n\n\n.. _`Examples`:\n\nExamples\n--------\n\nExample with dictionaries:\n\n.. code-block:: bash\n\n $ python\n >>> from immutable_views import DictView\n >>> dict1 = {'a': 1, 'b': 2}\n >>> dictview1 = DictView(dict1)\n\n # Read-only access to the underlying collection through the view is supported:\n >>> dictview1['a']\n 1\n\n # Modifying the underlying collection through the view is rejected:\n >>> dictview1['a'] = 2\n Traceback (most recent call last):\n File \"<stdin>\", line 1, in <module>\n TypeError: 'DictView' object does not support item assignment\n\n # Modifications of the underlying collection are visible in the view:\n >>> dict1['a'] = 2\n >>> dictview1['a']\n 2\n\nExample with lists:\n\n.. code-block:: bash\n\n $ python\n >>> from immutable_views import ListView\n >>> list1 = ['a', 'b']\n >>> listview1 = ListView(list1)\n\n # Read-only access to the underlying collection through the view is supported:\n >>> listview1[0]\n 'a'\n\n # Modifying the underlying collection through the view is rejected:\n >>> listview1[0] = 'c'\n Traceback (most recent call last):\n File \"<stdin>\", line 1, in <module>\n TypeError: 'ListView' object does not support item assignment\n\n # Modifications of the underlying collection are visible in the view:\n >>> list1[0] = 'c'\n >>> listview1[0]\n 'c'\n\nExample with sets:\n\n.. code-block:: bash\n\n $ python\n >>> from immutable_views import SetView\n >>> set1 = {'a', 'b'}\n >>> setview1 = SetView(set1)\n\n # Read-only access to the underlying collection through the view is supported:\n >>> 'a' in setview1\n True\n\n # Modifying the underlying collection through the view is rejected:\n >>> setview1.add('c')\n Traceback (most recent call last):\n File \"<stdin>\", line 1, in <module>\n AttributeError: 'SetView' object has no attribute 'add'\n\n # Modifications of the underlying collection are visible in the view:\n >>> set1.add('c')\n >>> 'c' in setview1\n True\n\n\nDocumentation and change log\n----------------------------\n\n* `Documentation <https://immutable-views.readthedocs.io/en/latest/>`_\n* `Change log <https://immutable-views.readthedocs.io/en/latest/changes.html>`_\n\n\nLicense\n-------\n\nThe **immutable-views** project is provided under the\n`Apache Software License 2.0 <https://raw.githubusercontent.com/andy-maier/immutable-views/master/LICENSE>`_.\n\n\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "Immutable views on other collection objects",
"version": "0.6.1",
"project_urls": {
"Bug Tracker": "https://github.com/andy-maier/immutable-views/issues",
"Change Log": "https://immutable-views.readthedocs.io/en/stable/changes.html",
"Documentation": "https://immutable-views.readthedocs.io/en/stable/",
"Homepage": "https://github.com/andy-maier/immutable-views"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "87cc003c1a4965e2499fdf9bde2543d3d55205fdd7c47b11d5b52be94ef4c535",
"md5": "730a678de0f25b4cbc145d73d02cd29a",
"sha256": "549dbe1106c53e26da28e1ab0f19f54ff20592cc6590f791ffd060de140c1aff"
},
"downloads": -1,
"filename": "immutable_views-0.6.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "730a678de0f25b4cbc145d73d02cd29a",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*",
"size": 19985,
"upload_time": "2021-06-30T08:28:53",
"upload_time_iso_8601": "2021-06-30T08:28:53.671246Z",
"url": "https://files.pythonhosted.org/packages/87/cc/003c1a4965e2499fdf9bde2543d3d55205fdd7c47b11d5b52be94ef4c535/immutable_views-0.6.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ce056c84a56d52ad8e838389651a59e7e71d175ca26656605883b79fe3a734e2",
"md5": "ff0b14e1578ad644cc1b12b977d18921",
"sha256": "48e0543786e8a196667fb8412ce35c4f555ce08f39eab21dcf4b0a23d8d19295"
},
"downloads": -1,
"filename": "immutable-views-0.6.1.tar.gz",
"has_sig": false,
"md5_digest": "ff0b14e1578ad644cc1b12b977d18921",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*",
"size": 45599,
"upload_time": "2021-06-30T08:28:55",
"upload_time_iso_8601": "2021-06-30T08:28:55.438648Z",
"url": "https://files.pythonhosted.org/packages/ce/05/6c84a56d52ad8e838389651a59e7e71d175ca26656605883b79fe3a734e2/immutable-views-0.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-06-30 08:28:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "andy-maier",
"github_project": "immutable-views",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [],
"lcname": "immutable-views"
}
JSON
