safe-cast 0.3.4
Safe casting of Python base types
License: MIT License
Keywords: safe casting tune

.. -*- mode: rst -*-


safe-cast
---------

Safe casting of Python base types.


Badges
------

.. start-badges

.. list-table::
    :stub-columns: 1

    * - docs
      - |docs| |license|
    * - info
      - |hits| |contributors|
    * - tests
      - |travis| |coveralls|
    * - package
      - |version| |supported-versions|
    * - other
      - |requires|


.. |docs| image:: https://readthedocs.org/projects/safe-cast/badge/?style=flat
    :target: http://safe-cast.readthedocs.io
    :alt: Documentation Status

.. |hits| image:: http://hits.dwyl.io/TuneLab/safe-cast.svg
    :target: http://hits.dwyl.io/TuneLab/safe-cast
    :alt: Hit Count

.. |contributors| image:: https://img.shields.io/github/contributors/TuneLab/safe-cast.svg
    :target: https://github.com/TuneLab/safe-cast/graphs/contributors
    :alt: Contributors

.. |license| image:: https://img.shields.io/badge/License-MIT-yellow.svg
    :alt: License Status
    :target: https://opensource.org/licenses/MIT

.. |travis| image:: https://travis-ci.org/TuneLab/safe-cast.svg?branch=master
    :target: https://travis-ci.org/TuneLab/safe-cast
    :alt: Travis

.. |coveralls| image:: https://coveralls.io/repos/github/TuneLab/safe-cast/badge.svg?branch=master
    :target: https://coveralls.io/github/TuneLab/safe-cast?branch=master
    :alt: Code Coverage Status

.. |requires| image:: https://requires.io/github/TuneLab/safe-cast/requirements.svg?branch=master
     :target: https://requires.io/github/TuneLab/safe-cast/requirements/?branch=master
     :alt: Requirements Status

.. |version| image:: https://img.shields.io/pypi/v/safe-cast.svg?style=flat
    :target: https://pypi.python.org/pypi/safe-cast
    :alt: PyPI Package latest release

.. |supported-versions| image:: https://img.shields.io/pypi/pyversions/safe-cast.svg?style=flat
    :target: https://pypi.python.org/pypi/safe-cast
    :alt: Supported versions

.. end-badges


Functions
---------

+-----------------------------------------------+------------------------------------------------------------------+
| Function                                      | Purpose                                                          |
+===============================================+==================================================================+
| ``safe_cast(val, to_type, default=None)``     | Cast value to requested type, if failed, then used default.      |
+-----------------------------------------------+------------------------------------------------------------------+
| ``safe_str(val, default=None)``               | Cast value to type string, if failed, then used default.         |
+-----------------------------------------------+------------------------------------------------------------------+
| ``safe_float(val, ndigits=2, default=None)``  | Cast value to type float, if failed, then used default.          |
+-----------------------------------------------+------------------------------------------------------------------+
| ``safe_int(val, default=None)``               | Cast value to type int, if failed, then used default.            |
+-----------------------------------------------+------------------------------------------------------------------+
| ``safe_dict(val, default=None)``              | Cast value to type dictionary, if failed, then used default.     |
+-----------------------------------------------+------------------------------------------------------------------+
| ``safe_smart_cast(val)``                      | Determine type based upon value, and cast to that type.          |
+-----------------------------------------------+------------------------------------------------------------------+
| ``safe_cost(val)``                            | Cast value to type float by 4 decimal points.                    |
+-----------------------------------------------+------------------------------------------------------------------+
| ``safe_fraction(val)``                        | Cast fraction to type float, if failed, then used default.       |
+-----------------------------------------------+------------------------------------------------------------------+


Usage
-----

``safe_cast(val, to_type, default=None)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Safely cast a value to type, and if failed, returned default if exists.

    Optional: Pass default value. Returned if casting fails.

    :param val: Value to be cast.
    :param to_type: Safely cast to a specific type.
    :param default: Default if casting fails.
    :return: Return casted value or default.

``safe_int(val, default=None)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Safely cast a value to an integer.

    Optional: Pass default value. Returned if casting fails.

    :param val: Value to be cast to int.
    :param default: Default if casting fails.
    :return: Return int casted value or default.

``safe_float(val, ndigits=2, default=None)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Safely cast a value to float, remove ',' if exists to ensure strings "1,234.5" are transformed to become "1234.5".

    Optional: Pass default value. Returned if casting fails.

    :param val: Value to be cast to float.
    :param ndigits: Number of digits in float.
    :param default: Default if casting fails.
    :return: Return float casted value or default.

``safe_str(val, default=None)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Safely cast a value to a string.

    Optional: Pass default value. Returned if casting fails.

    :param val: Value to be cast to string.
    :param default: Default if casting fails.
    :return: Return string casted value or default.

``safe_dict(val, default=None)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Safely cast a value to a dictionary.

    Optional: Pass default value. Returned if casting fails.

    :param val: Value to be cast to dictionary.
    :param default: Default if casting fails.
    :return: Return dictionary casted value or default.

``safe_smart_cast(val)``
~~~~~~~~~~~~~~~~~~~~~~~~
    Safely cast a value to the best matching type.
    Optional: Pass default value. Returned if casting fails.

    :param val: Value to be smartly cast.
    :return: Typed value

``safe_fraction(fraction, ndigits=2, default=None)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Safely cast a fraction string to float.

    Optional: Pass default value. Returned if casting fails.

    :param fraction: Value of fraction to be cast to float.
    :param ndigits: Number of digits in float.
    :param default: Default if casting fails.
    :return: Return float casted value or default.


.. :changelog:

Release History
===============

0.3.4 (2018-04-20)
------------------
* Update requirements.txt

0.3.2 (2018-02-16)
------------------
- Python 2.7 supported
- Travis CI testing both Python 2.7 and 3.6.

0.3.1 (2018-02-15)
------------------
- migrate to github/TuneLab.

0.3.0 (2018-02-05)
------------------
- Added safe_fraction.
- Verbose exceptions handling.
- More examples.
- More tests.

0.2.4 (2018-01-25)
------------------
- migrate to github/tuneinc.
- LICENSE: MIT

0.2.3 (2017-12-10)
------------------
- readthedocs.org

0.2.0 (2017-12-05)
-------------------
* README

0.1.3 (2017-10-31)
------------------
* Added comments.

0.1.2 (2017-10-19)
------------------
* Update requirements.txt

0.1.1 (2017-03-15)
------------------
* Handle empty string -> int/float/dict casting
* Added relevant testing

0.1.0 (2017-03-14)
------------------
* Production ready
* Cleanup

0.0.9 (2017-03-14)
------------------
* Handle None input

0.0.8 (2017-03-12)
------------------
* Rename package to 'safe-cast'

0.0.7 (2017-03-09)
------------------
* Renamed inner package folder to underscore: 'smart_cast. To comply with Python standard.
* Updated casting logic
* Updated testing
* Activate Continues deployment and testing with Travis.CI
* Activate coverage testing: Coveralls.io

0.0.6 (2017-03-08)
------------------
* Renamed from 'safecast' to 'smart-cast'

0.0.1 (2017-03-07)
------------------
* Conception