Metadata-Version: 2.1
Name: querystringsafe-base64
Version: 1.2.0
Summary: Encoding and decoding arbitrary strings into strings that are safe to put into a URL query param.
Home-page: https://github.com/ClearcodeHQ/querystringsafe_base64
Author: Clearcode - The A Room
Author-email: thearoom@clearcode.cc
License: LGPL
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Environment :: Web Environment
Provides-Extra: tests
Requires-Dist: pytest ; extra == 'tests'
Requires-Dist: pytest-cov ; extra == 'tests'
Requires-Dist: pylama ; extra == 'tests'

.. image:: https://travis-ci.org/ClearcodeHQ/querystringsafe_base64.svg?branch=v1.2.0
    :target: https://travis-ci.org/ClearcodeHQ/querystringsafe_base64
    :alt: Tests

.. image:: https://coveralls.io/repos/ClearcodeHQ/querystringsafe_base64/badge.png?branch=v1.2.0
    :target: https://coveralls.io/r/ClearcodeHQ/querystringsafe_base64?branch=v1.2.0
    :alt: Coverage Status

Query string safe Base64
========================

Encoding and decoding arbitrary strings into strings that are safe to put into a URL query param.

The problem
-----------

`urlsafe_b64encode` and `urlsafe_b64decode` from base64 are not enough because they leave `=` used for padding chars unquoted:

.. code-block:: python

    import base64

    base64.urlsafe_b64encode('a')
    'YQ=='

And there are 2 problems with that

I. `=` sign gets quoted:

.. code-block:: python

    import urllib

    urllib.quote('=')
    '%3D'

II. Some libraries tolerate the `=` in query string values:

.. code-block:: python

    from urlparse import urlsplit, parse_qs

    parse_qs(urlsplit('http://aaa.com/asa?q=AAAA=BBBB=CCCC').query)
    {'q': ['AAAA=BBBB=CCCC']}

but the RFC 3986 underspecifies the query string so we cannot rely on `=` chars being handled by all web applications as it is done by urlparse.

Therefore we consider chars: `['+', '/', '=']` unsafe and we replace them with `['-', '_', '.']`.
Characters `+` and `/` are already handled by `urlsafe_*` functions from base64 so only `=` is left.
Since the `=` is used exclusively for padding, we simply remove it, and re-attach the padding during decoding.
Because of that, `querystringsafe_base64` is able to decode padded and unpadded string.

The solution
------------

.. code-block:: python

    import querystringsafe_base64

    querystringsafe_base64.encode(b'foo-bar')
    b'Zm9vLWJhcg'

    querystringsafe_base64.decode(b'Zm9vLWJhcg..')
    b'foo-bar'

    querystringsafe_base64.decode(b'Zm9vLWJhcg')
    b'foo-bar'


CHANGELOG
=========

1.2.0
-------

* Remove padding characters from encoded string.

1.1.1
-------

* Fixed packaging

1.1.0
-------

* Always expect bytes
* Add type annotations

1.0.0
-------

* support for restore missing padding during decode process

0.2.0
-------

* Support for python3

0.1.5
-------

* Move querystringsafe_base64 module to the root
* Use install instead of develop during tests

0.1.4
-------

* Remove bdist_wheel from distributons

0.1.3
-------

* Install pandoc (travis)

0.1.2
-------

* Add setup.cfg and pypandoc to tests

0.1.1
-------

* add MANIFEST.in file

0.1.0
-------

* package structure
* tests


