bidict/README.rst

bidict
======
 
Efficient, Pythonic bidirectional map implementation and related functionality.

.. image:: https://raw.githubusercontent.com/jab/bidict/master/_static/logo-256.png
    :target: https://bidict.readthedocs.io/
    :alt: bidict logo


Status
------

.. Hide until https://github.com/badges/shields/issues/716 is fixed
.. .. image:: https://img.shields.io/pypi/dm/bidict.svg
..     :target: https://pypi.python.org/pypi/bidict
..     :alt: Downloads per month

.. image:: https://img.shields.io/pypi/v/bidict.svg
    :target: https://pypi.python.org/pypi/bidict
    :alt: Latest release

.. image:: https://readthedocs.org/projects/bidict/badge/?version=master
    :target: https://bidict.readthedocs.io/en/master/
    :alt: Documentation

.. image:: https://travis-ci.org/jab/bidict.svg?branch=master
    :target: https://travis-ci.org/jab/bidict
    :alt: Build status

.. image:: https://coveralls.io/repos/jab/bidict/badge.svg?branch=master
    :target: https://coveralls.io/github/jab/bidict
    :alt: Test coverage

.. Hide to reduce clutter
.. .. image:: https://img.shields.io/pypi/pyversions/bidict.svg
..     :target: https://pypi.python.org/pypi/bidict
..     :alt: Supported Python versions

.. image:: https://img.shields.io/pypi/implementation/bidict.svg
    :target: https://pypi.python.org/pypi/bidict
    :alt: Supported Python implementations

.. image:: https://img.shields.io/pypi/l/bidict.svg
    :target: https://raw.githubusercontent.com/jab/bidict/master/LICENSE
    :alt: License

.. image:: https://badges.gitter.im/join%20chat.svg
    :target: https://gitter.im/jab/bidict
    :alt: Chat

The bidict codebase is mature, well-tested, and well-reviewed.
It is in use by several teams at Google, Bank of America Merill Lynch,
and other developers all over the world.

If you are thinking of using bidict in your work,
or if you have any questions, comments, or suggested improvements,
`please let me know <https://gitter.im/jab/bidict>`_!
I'd love to know about and be able to support
your use case as much as possible.

Please also feel free to
file an issue or submit a pull request.
All contributions are gratefully received:)
(See contributing_ below.)

.. copy/paste rather than `include` so this renders on GitHub:
.. .. include:: release-notifications.rst.inc

Release Notifications
^^^^^^^^^^^^^^^^^^^^^

.. image:: https://img.shields.io/badge/VersionEye-follow-brightgreen.svg
    :target: https://www.versioneye.com/python/bidict
    :alt: Follow on VersionEye


Tip: `Follow bidict on VersionEye <https://www.versioneye.com/python/bidict>`_
to automatically be notified via email
when a new version of bidict is released.

.. end pasted release-notifications.rst.inc content


Installation
------------

``pip install bidict``


Usage Documentation
-------------------

For usage documentation, please start at the :doc:`intro`
and proceed from there.

.. NOTE::
   If you're reading this on GitHub, PyPI, in your code editor,
   or in some other place that can't render/link the full docs properly,
   you can find the bidict documentation on Read the Docs at:

       `<https://bidict.readthedocs.io>`_

   Also note: multiple versions of the documentation are published on Read the Docs,
   and by default you will be taken to the version built from the master branch.
   You can choose different versions from the pop-up menu in the lower-right.

   If you have the `bidict source code <https://github.com/jab/bidict>`_  handy,
   you can also browse the docs inside the ``docs`` directory,
   and build them yourself by running ``make html`` from within that directory
   (requires `Sphinx <https://pypi.python.org/pypi/Sphinx>`_).


Contributing
------------

For information about contributing,
please see the :doc:`contributors-guide`
(`<CONTRIBUTING.rst>`_ |
`<https://bidict.readthedocs.io/contributors-guide.html>`_)

If bidict has helped you accomplish your work,
especially work you've been paid for,
please consider supporting bidict's maintenance and development.

.. image:: https://raw.githubusercontent.com/jab/bidict/master/_static/support-on-gumroad.png
    :target: https://gumroad.com/l/bidict
    :alt: Support bidict


Changelog
---------

For a history of notable changes to bidict,
check out the :doc:`changelog`
(`<CHANGELOG.rst>`_ |
`<https://bidict.readthedocs.io/changelog.html>`_).