PDicts - immutable dictionaries
==================================

Introduction
--------------

A PDict is a dictionary that is mostly like the built-in Python dictionary
type::

    >>> from pysistence import make_dict
    >>> d = make_dict(foo='bar')
    >>> d
    {'foo': 'bar'}

The main difference is that this dictionary is immutable::

    >>> d['asdf'] = 'jkl;'
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
      File "persistent_dict.py", line 22, in not_implemented_method
        raise NotImplementedError, 'Cannot set values in a PDict'    
    NotImplementedError: Cannot set values in a PDict
    >>> del d['foo']
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
      File "persistent_dict.py", line 22, in not_implemented_method
        raise NotImplementedError, 'Cannot set values in a PDict'    
    NotImplementedError: Cannot set values in a PDict

Just like the :class:`~pysistence.expando.Expando`, you can make copies using
the **without** and **using**
methods::

    >>> d2 = d.using(asdf='jkl;')
    >>> d2
    {'foo': 'bar', 'asdf': 'jkl;'}
    >>> d3 = d2.without('foo')
    >>> d3
    {'asdf': 'jkl;'}

.. seealso::
  
    :doc:`expando`
        A semi-persistent object type that is similar to the PDict.

Reference
------------

.. module:: pysistence.persistent_dict
    :synopsis: Immutable dictionaries
.. moduleauthor:: Jason Baker <amnorvend@gmail.com>

.. function:: make_dict(mapping, **kwargs)

    This function works the same as the builtin **dict** function.  You may
    build a :class:`~pysistence.persistent_dict.PDict` using a pre-existing 
    dictionary, a sequence of two-item sequences, or using keyword arguments. 
    This is essentially a binding to :class:`~pysistence.persistent_dict.PDict`'s constructor.
    
.. class:: PDict(mapping, **kwargs)

    Build a PDict instance.  See the documentation for 
    :func:`~pysistence.persistent_dict.make_dict` for more information.

    .. method:: copy()

        Get a new PDict that is the same as the current one.

    .. method:: using(**kwargs)

        Get a new PDict that's the same as the current one, but with extra
        items defined by *kwargs*.

    .. method:: without(*args)

        Get a new PDict that's the same as the current one, but without the
        keys named by *args*.