base62
======
|Build Status| |Coveralls| |PyPI|
A Python module for ``base62`` encoding. Ported from PHP code that I wrote
in mid-2000, which can be found
`here <http://philosophical.one/posts/base62>`__.
.. |Build Status| image:: https://github.com/suminb/base62/actions/workflows/ci.yml/badge.svg
:target: https://github.com/suminb/base62/actions/workflows/ci.yml?query=branch%3Adevelop
.. |PyPI| image:: https://img.shields.io/pypi/v/pybase62.svg
:target: https://pypi.python.org/pypi/pybase62
.. |Coveralls| image:: https://coveralls.io/repos/github/suminb/base62/badge.svg?branch=master
:target: https://coveralls.io/github/suminb/base62?branch=develop
Rationale
---------
When writing a web application, often times we would like to keep the URLs
short.
::
http://localhost/posts/V1Biicwt
This certainly gives a more concise look than the following.
::
http://localhost/posts/109237591284123
This was the original motivation to write this module, but there shall be much
more broader potential use cases of this module. The main advantage of
``base62`` is that it is URL-safe (as opposed to ``base64``) due to the lack of
special characters such as '``/``' or '``=``'. Another key aspect is that the
alphabetical orders of the original (unencoded) data is preserved when encoded.
In other words, encoded data can be sorted without being decoded at all.
Installation
============
``base62`` can be installed via ``pypi``. Unfortunately, the package name
``base62`` on ``pypi`` had already been occupied by someone else, so we had to
go by ``pybase62``.
::
pip install pybase62
Alternatively, you may clone the code to manually install it.
::
git clone https://github.com/suminb/base62
cd base62 && python setup.py install
Usage
=====
The following section describes a basic usage of ``base62``.
.. code:: python
>>> import base62
>>> base62.encode(34441886726)
'base62'
>>> base62.decode('base62')
34441886726
From version ``0.2.0``, ``base62`` supports ``bytes`` array encoding as well.
.. code:: python
>>> base62.encodebytes(b'\0')
0
>>> base62.encodebytes(b'\xff\xff')
H31
>>> base62.decodebytes('0')
b''
>>> base62.decodebytes('1')
b'\x01'
Some may be inclined to assume that they both take ``bytes`` types as input
due to their namings. However, ``encodebytes()`` takes ``bytes`` types
whereas ``decodebytes()`` takes ``str`` types as an input. They are intended
to be commutative, so that a *roundtrip* between both functions yields the
original value.
Formally speaking, we say function *f* and *g* commute if *f∘g* = *g∘f* where
*f(g(x))* = *(f∘g)(x)*.
Therefore, we may expect the following relationships:
* ``value == encodebytes(decodebytes(value))``
* ``value == decodebytes(encodebytes(value))``
Tests
=====
You may run some test cases to ensure all functionalities are operational.
::
pytest -v
If ``pytest`` is not installed, you may want to run the following command:
::
pip install -r tests/requirements.txt
Deployment
==========
Deploy a source package (to `pypi <https://pypi.org>`_) as follows:
::
python setup.py sdist upload
Raw data
{
"_id": null,
"home_page": "http://github.com/suminb/base62",
"name": "pybase62",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Sumin Byeon",
"author_email": "suminb@gmail.com",
"download_url": "",
"platform": null,
"description": "base62\n======\n\n|Build Status| |Coveralls| |PyPI|\n\nA Python module for ``base62`` encoding. Ported from PHP code that I wrote\nin mid-2000, which can be found\n`here <http://philosophical.one/posts/base62>`__.\n\n.. |Build Status| image:: https://github.com/suminb/base62/actions/workflows/ci.yml/badge.svg\n :target: https://github.com/suminb/base62/actions/workflows/ci.yml?query=branch%3Adevelop\n.. |PyPI| image:: https://img.shields.io/pypi/v/pybase62.svg\n :target: https://pypi.python.org/pypi/pybase62\n.. |Coveralls| image:: https://coveralls.io/repos/github/suminb/base62/badge.svg?branch=master\n :target: https://coveralls.io/github/suminb/base62?branch=develop\n\n\nRationale\n---------\n\nWhen writing a web application, often times we would like to keep the URLs\nshort.\n\n::\n\n http://localhost/posts/V1Biicwt\n\nThis certainly gives a more concise look than the following.\n\n::\n\n http://localhost/posts/109237591284123\n\nThis was the original motivation to write this module, but there shall be much\nmore broader potential use cases of this module. The main advantage of\n``base62`` is that it is URL-safe (as opposed to ``base64``) due to the lack of\nspecial characters such as '``/``' or '``=``'. Another key aspect is that the\nalphabetical orders of the original (unencoded) data is preserved when encoded.\nIn other words, encoded data can be sorted without being decoded at all.\n\nInstallation\n============\n\n``base62`` can be installed via ``pypi``. Unfortunately, the package name\n``base62`` on ``pypi`` had already been occupied by someone else, so we had to\ngo by ``pybase62``.\n\n::\n\n pip install pybase62\n\nAlternatively, you may clone the code to manually install it.\n\n::\n\n git clone https://github.com/suminb/base62\n cd base62 && python setup.py install\n\nUsage\n=====\n\nThe following section describes a basic usage of ``base62``.\n\n.. code:: python\n\n >>> import base62\n\n >>> base62.encode(34441886726)\n 'base62'\n\n >>> base62.decode('base62')\n 34441886726\n\nFrom version ``0.2.0``, ``base62`` supports ``bytes`` array encoding as well.\n\n.. code:: python\n\n >>> base62.encodebytes(b'\\0')\n 0\n\n >>> base62.encodebytes(b'\\xff\\xff')\n H31\n\n >>> base62.decodebytes('0')\n b''\n\n >>> base62.decodebytes('1')\n b'\\x01'\n\nSome may be inclined to assume that they both take ``bytes`` types as input\ndue to their namings. However, ``encodebytes()`` takes ``bytes`` types\nwhereas ``decodebytes()`` takes ``str`` types as an input. They are intended\nto be commutative, so that a *roundtrip* between both functions yields the\noriginal value.\n\nFormally speaking, we say function *f* and *g* commute if *f\u2218g* = *g\u2218f* where\n*f(g(x))* = *(f\u2218g)(x)*.\n\nTherefore, we may expect the following relationships:\n\n* ``value == encodebytes(decodebytes(value))``\n* ``value == decodebytes(encodebytes(value))``\n\nTests\n=====\n\nYou may run some test cases to ensure all functionalities are operational.\n\n::\n\n pytest -v\n\nIf ``pytest`` is not installed, you may want to run the following command:\n\n::\n\n pip install -r tests/requirements.txt\n\n\nDeployment\n==========\n\nDeploy a source package (to `pypi <https://pypi.org>`_) as follows:\n\n::\n\n python setup.py sdist upload\n",
"bugtrack_url": null,
"license": "",
"summary": "Python module for base62 encoding",
"version": "1.0.0",
"project_urls": {
"Homepage": "http://github.com/suminb/base62"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "11078fe498201daece90af1725cf48d5de9d1a87ea8d457df52c986ef926ff33",
"md5": "16985fa217b8c7e43441d173f6d5b437",
"sha256": "60539ad956ec9e9de091bc7ae88c9550bc2fa17f503050cf34d021b75e73cb27"
},
"downloads": -1,
"filename": "pybase62-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "16985fa217b8c7e43441d173f6d5b437",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 4913,
"upload_time": "2023-05-29T08:43:05",
"upload_time_iso_8601": "2023-05-29T08:43:05.677716Z",
"url": "https://files.pythonhosted.org/packages/11/07/8fe498201daece90af1725cf48d5de9d1a87ea8d457df52c986ef926ff33/pybase62-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-29 08:43:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "suminb",
"github_project": "base62",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pybase62"
}
JSON
