v1.4.0 (BREAKING) - Added inject_items + cleanup

Notable Changes
===============

**New Features**

 - Added `common.inject_items` - a small function for injecting a list into another list
   at an arbitrary position.

**General Improvements/Fixes**

 - Fixed `net.asn_to_name` so that it correctly raises `KeyError` or returns
   `'Unknown ASN'` when dnspython raises `NoAnswer`
 - Added `plugin.HAS_DNSPYTHON` attribute, for checking whether the dnspython dependent
   functions/classes were loaded or not
 - (POTENTIALLY BREAKING CHANGE) `__init__.py` no longer loads the `django` module,
   as it was causing endless issues related to Django not being configured, or
   not being ready for accessing certain modules.

**Documentation**

 - Fixed small typo in `cache.RedisCache` pydoc block
 - Re-organised Unit Tests section to make it more readable
 - Re-named the cache module into "Cache Abstraction Layer", as the module page contains
   a lot of hand written documentation about it.
 - Re-organised the code documentation to be top level
 - Added **Usage Examples** section
 - Fleshed out the index page of the docs

**Unit Test updates**

 - Extracted tests from `tests.py` into individual files in `tests` folder, as tests.py
   was close to 500 lines long and growing...
 - Added unit tests for `net.asn_to_name`
 - Added unit tests for `common.inject_items`

.gitignore

@@ -9,4 +9,5 @@ __pycache__
 build
 dist
 *.egg-info
+venv/
 

.travis.yml

@@ -13,6 +13,6 @@ python:
 install:
   - pip install -r docs/requirements.txt
   - pip install .
-script: pytest --cov=./privex tests.py
+script: pytest --cov=./privex -v
 after_success:
   - codecov

README.md

@@ -2,7 +2,7 @@
 
 [![Documentation Status](https://readthedocs.org/projects/python-helpers/badge/?version=latest)](https://python-helpers.readthedocs.io/en/latest/?badge=latest) 
 [![Build Status](https://travis-ci.com/Privex/python-helpers.svg?branch=master)](https://travis-ci.com/Privex/python-helpers) 
-[![Codecov](https://img.shields.io/codecov/c/github/Privex/python-helpers)](https://codecov.io/gh/Privex/python-helpers)  
+[![Codecov](https://img.shields.io/codecov/c/github/Privex/python-helpers)](https://codecov.io/gh/Privex/python-helpers)
 [![PyPi Version](https://img.shields.io/pypi/v/privex-helpers.svg)](https://pypi.org/project/privex-helpers/)
 ![License Button](https://img.shields.io/pypi/l/privex-helpers) 
 ![PyPI - Downloads](https://img.shields.io/pypi/dm/privex-helpers)
@@ -12,7 +12,7 @@
 This small Python 3 module is comprised of various small functions and classes that were often
 copied and pasted across our projects.
 
-Each of these "helper" functions, decorators or classes are otherwise too small to be independantly
+Each of these "helper" functions, decorators or classes are otherwise too small to be independently
 packaged, and so we've amalgamated them into this PyPi package, `privex-helpers`.
 
 
@@ -34,7 +34,15 @@ packaged, and so we've amalgamated them into this PyPi package, `privex-helpers`
 
 # Install
 
-### Download and install from PyPi using pip (recommended)
+### Download and install from PyPi 
+
+**Using [Pipenv](https://pipenv.kennethreitz.org/en/latest/) (recommended)**
+
+```sh
+pipenv install privex-helpers
+```
+
+**Using standard Python pip** 
 
 ```sh
 pip3 install privex-helpers

docs/source/examples.rst

@@ -0,0 +1,101 @@
+##############
+Example Usages
+##############
+
+Boolean testing
+===============
+
+The ``empty`` function
+-----------------------
+
+The :func:`empty` function in our opinion, is one of most useful functions in this library. It allows for a clean,
+readable method of checking if a variable is "empty", e.g. when checking keyword arguments to a function.
+
+With a single argument, it simply tests if a variable is ``""`` (empty string) or ``None``.
+
+The argument ``itr`` can be set to ``True`` if you consider an empty iterable such as ``[]`` or ``{}`` as "empty". This
+functionality also supports objects which implement ``__len__``, and also checks to ensure ``__len__`` is available,
+avoiding an exception if an object doesn't support it.
+
+The argument ``zero`` can be set to ``True`` if you want to consider ``0`` (integer) and ``'0'`` (string) as "empty".
+
+.. code-block:: python
+
+    from privex.helpers import empty
+
+    x, y = "", None
+    z, a = [], 0
+
+    empty(x) # True
+    empty(y) # True
+    empty(z) # False
+    empty(z, itr=True) # True
+    empty(a) # False
+    empty(a, zero=True) # True
+
+
+The ``is_true`` and ``is_false`` functions
+------------------------------------------
+
+When handling user input, whether from an environment file (``.env``), or from data passed to a web API, it can be
+a pain attempting to check for booleans.
+
+A boolean ``True`` could be represented as the string ``'true'``, ``'1'``, ``'YES'``, as an integer ``1``, or even
+an actual boolean ``True``. Trying to test for all of those cases requires a rather long ``if`` statement...
+
+Thus :func:`.is_true` and :func:`.is_false` were created.
+
+.. code-block:: python
+
+    from privex.helpers import is_true, is_false
+
+    is_true(0)          # False
+    is_true(1)          # True
+    is_true('1')        # True
+    is_true('true')     # True
+    is_true('false')    # False
+    is_true('orange')   # False
+    is_true('YeS')      # True
+
+    is_false(0)         # True
+    is_false('false')   # True
+    is_false('true')    # False
+    is_false(False)     # True
+
+
+Handling environmental variables in different formats
+=====================================================
+
+Using ``env_csv`` to support lists contained within an env var
+---------------------------------------------------------------
+
+The function :func:`.env_csv` parses a CSV-like environment variable into a list
+
+.. code-block:: python
+
+    from privex.helpers import env_csv
+    import os
+    os.environ['EXAMPLE'] = "this,   is, an,example   "
+
+    env_csv('EXAMPLE', ['error'])
+    # returns: ['this', 'is', 'an', 'example']
+    env_csv('NOEXIST', ['non-existent'])
+    # returns: ['non-existent']
+
+Using ``env_keyval`` to support dictionaries contained within an env var
+------------------------------------------------------------------------
+
+The function :func:`.env_keyval` parses an environment variable into a ordered list of tuple pairs, which can be
+easily converted into a dictionary using ``dict()``.
+
+.. code-block:: python
+
+    from privex.helpers import env_keyval
+    import os
+    os.environ['EXAMPLE'] = "John:  Doe , Jane   : Doe, Aaron:Smith"
+
+    env_keyval('EXAMPLE')
+    # returns: [('John', 'Doe'), ('Jane', 'Doe'), ('Aaron', 'Smith')]
+    env_keyval('NOEXIST', {})
+    # returns: {}
+

docs/source/helpers/common/privex.helpers.common.Dictable.rst

@@ -0,0 +1,23 @@
+Dictable
+========
+
+.. currentmodule:: privex.helpers.common
+
+.. autoclass:: Dictable
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~Dictable.__init__
+      ~Dictable.from_dict
+
+
+
+
+
+

docs/source/helpers/common/privex.helpers.common.ErrHelpParser.rst

@@ -0,0 +1,40 @@
+ErrHelpParser
+=============
+
+.. currentmodule:: privex.helpers.common
+
+.. autoclass:: ErrHelpParser
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~ErrHelpParser.__init__
+      ~ErrHelpParser.add_argument
+      ~ErrHelpParser.add_argument_group
+      ~ErrHelpParser.add_mutually_exclusive_group
+      ~ErrHelpParser.add_subparsers
+      ~ErrHelpParser.convert_arg_line_to_args
+      ~ErrHelpParser.error
+      ~ErrHelpParser.exit
+      ~ErrHelpParser.format_help
+      ~ErrHelpParser.format_usage
+      ~ErrHelpParser.get_default
+      ~ErrHelpParser.parse_args
+      ~ErrHelpParser.parse_intermixed_args
+      ~ErrHelpParser.parse_known_args
+      ~ErrHelpParser.parse_known_intermixed_args
+      ~ErrHelpParser.print_help
+      ~ErrHelpParser.print_usage
+      ~ErrHelpParser.register
+      ~ErrHelpParser.set_defaults
+
+
+
+
+
+

docs/source/helpers/common/privex.helpers.common.inject_items.rst

@@ -0,0 +1,6 @@
+inject\_items
+=============
+
+.. currentmodule:: privex.helpers.common
+
+.. autofunction:: inject_items

docs/source/helpers/index.rst

@@ -1,5 +1,3 @@
-Code Docs for each helper module
-=================================
 
 .. autosummary::
     :toctree:
@@ -14,10 +12,4 @@ Code Docs for each helper module
     privex.helpers.plugin
     privex.helpers.settings
 
-Unit Tests
-==========
 
-.. autosummary::
-    :toctree:
-
-    tests

docs/source/helpers/privex.helpers.cache.rst

@@ -1,5 +1,10 @@
-privex.helpers.cache
-====================
+Cache Abstraction Layer
+=======================
+
+**Module:** ``privex.helpers.cache``
+
+Classes
+^^^^^^^
 
 .. autosummary::
     :toctree: cache
@@ -10,7 +15,7 @@ privex.helpers.cache
 
 
 Functions
----------
+^^^^^^^^^
 
 .. automodule:: privex.helpers.cache
 

docs/source/helpers/privex.helpers.common.rst

@@ -21,6 +21,7 @@ privex.helpers.common
       env_keyval
       is_false
       is_true
+      inject_items
       parse_csv
       parse_keyval
       random_str
@@ -32,7 +33,8 @@ privex.helpers.common
    .. rubric:: Classes
 
    .. autosummary::
-
+      :toctree: common
+
       ErrHelpParser
       Dictable