Package: privex-helpers
Privex's Python HelpersThis 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 independently
packaged, and so we've amalgamated them into this PyPi package,privex-helpers.+===================================================+
    |                 © 2019 Privex Inc.                |
    |               https://www.privex.io               |
    +===================================================+
    |                                                   |
    |        Originally Developed by Privex Inc.        |
    |                                                   |
    |        Core Developer(s):                         |
    |                                                   |
    |          (+)  Chris (@someguy123) [Privex]        |
    |          (+)  Kale (@kryogenic) [Privex]          |
    |                                                   |
    +===================================================+Tl;Dr; Install and use Privex HelpersInstall from PyPi (detailed install info atInstallandUsing package extras)pipenvinstallprivex-helpers# If you use pipenv (and you should!)pip3installprivex-helpers# Otherwise, standard pip installation# If you're using privex-helpers in a project, then you may want to install with the "full" extras# which installs all optional requirements (other than Django/tests), so you can use **everything** in privex-helperspipenvinstall'privex-helpers[full]'# If you use pipenv (and you should!)pip3install'privex-helpers[full]'# Otherwise, standard pip installationVery import and basic usage (detailed examples atExample Uses)fromprivex.helpersimportis_true,emptyifis_true('yes'):print('yes is truthful')ifempty(''):print("'' is empty")Table of Contents (Github README)NOTE:The below Table of Contents is designed to work on Github. The links do NOT work on PyPi's description,
and may not work if you're reading this README.md elsewhere.Why use Privex Helpers?1.1.Lightweight1.2.Keeps your code DRY (Don't repeat yourself!)1.3.Makes your life just plain easier1.4.Thorough unit tests1.5.Overview of what's includedInstall2.1Via PyPi (pip)2.2Manually via GitDocumentationLicenseExample UsesMinimal Dependencies / Using package extras6.1Modules with dependencies6.2Using Setuptools Extras6.3Installing extras when using the cloned repositoryUnit TestsContributingWhy use Privex Helpers?Privex helpers was created with a very simple goal in mind: make developing Python applications easy, fun, simple,
andpainless.LightweightWhether you're using it in a library, or in your project, you'll be pleased to know that theprivex-helpersand
all of it'srequired dependenciesmake up less than200kb total. For comparison, theDjangopackage alone
(that's excluding it's dependencies) is a whopping 26 MEGABYTES.Most ofprivex-helperscan be used without any additional dependencies. Some modules, or parts of modules
may require a certain dependency, but will cleanly disable themselves if the necessary dependency isn't available.SeeModules with dependenciesto see which modules only work if you have a certain
package installed, and modules which are dependency-free but enable additional functionality if you install
extra packages.Keeps your code DRY (Don't repeat yourself!)Tired of writing those same longifstatements to check if a user entered value was some sort-of boolean value?
Useis_trueandis_false- trim those long if statements into a single function call. Less typing, and more
readable.Makes your life just plain easierWriting a library and need caching? Not sure whether you should just force your users to use Redis, whether you
should just make this a Django plugin, or write some sort-of rudimentary caching system yourself?privex-helpersincludes a modular caching abstraction layer that Just Works™ out of the box, without forcing tons of dependencies on
your users.Maybe you just need to encrypt a string, or generate an RSA keypair. But you tried taking a look at the
popularcryptographypackage docs, and it looks like you're going to be writing
scaffolding code for hours just to do that... Say hello toprivex.helpers.crypto- whether you're dealing with
symmetric or asymmetric encryption, it's justone import line, a few lines of code and you're DONE.Thorough unit testsIncluded in thetests/folder, is a collection of over 70 individual unit tests, which is constantly
having more unit tests added over time.This project uses Travis for continuous integration (automatic testing with each commit), and CodeCov keeping
track of how much of the codebase is covered by unit tests. SeeUnit Testsfor more details.This ensures thatprivex-helpersis reliable and robust - if a part of the library is broken with a new update,
then we'll be alerted shortly after pushing out the update that our tests are failing, so we can fix the issue ASAP.Overview of what's includedThis is not an exhaustive list, and may sometimes be a little outdated. To see everything that's available inprivex-helpersthen check out theDocumentation.common- a melting pot of functions and classes that will generally just make developing python code 100x easier,
and make it 10x more readable. some of the most useful include:empty- checking if a value is "empty", e.g.None,'',0,'0',[]etc.is_true- fuzzy "true" testing, checks for common forms of true, e.g.True,"true","yes",1is_false- fuzzy "false" testing, checks for common forms of false, e.g.False,"false","no",0env_csv- load an environment variable like a CSV, allowing for list representation in env varsenv_keyval- load an environment variable like a key value map, allowing for tuple pair / dict
representation in env varsdec_round- round a pythonDecimalusing the built-in Quantize method, but without the hassle.Dictable- easily create your Python 3.7dataclassfrom a dictionary, plus enable them to be casted
into a plain dict usingdict(mydataclass)and MORE, check thedocumentation!cache- a dependency-free, framework agnostic caching layer, with support for:automatic timeoutsability to extend the timeout of a cache item (even after it's already "expired" on some cache adapters)get_or_set with callback function/method supportcan optionally use Redis if you'd prefer (requires an optional dependency)crypto- classes which make both symmetric and asymmetric encryption extremely easy to useEncryptHelper- for symmetric AES-128 encryption / decryption with a shared key, with the ability to generate
either a secure random shared key, or a shared key generated from a password + saltKeyManager- for asymmetric signing / verification, plus encryption/decryption if you use RSA. supports
generating/loading RSA, ECDSA, and Ed25519 keys, as well as outputting them in a variety of formats
and encodings.setuppy- a module with various functions to help with making python packages or dealing with
requirements.txt filescommon.extras_require- A helper function which allows you to generate anextras_requiresetting in
setup.py simply by passing a list of extras names, e.g.extras_require=extras_require(['cache', 'net']),bump.bump_version- Bumps a certain part of a package's semver version number and updates the file containing
the versioncommands.BumpCommand- A setup.py command class, which allows you to usebump.bump_versionwithin
your package, just by typing a command such as./setup.py bump --minor(bumps your package's minor 0.x.0
version and updates the file which contains the version)commands.ExtrasCommand- Exposes various functionality for managingextras_requirein your package,
including easily generating/saving requirements.txt files for your extras, installing the requirements,
and outputting a list of extras.decorators- various decorators to simplify your coderetry_on_err- automatically re-run a function/method when exceptions are thrown, with a variety of
customization availabler_cache- automatic caching of a function/property, with support for caching based on parameters or a lambdanet- various networking functions, including:handling IP addressesgenerating reverse DNS recordslooking up ASN names based on their numberchecking if an IP is up (via ping) - with both IPv4 and IPv6 supportasyncx- various async helper functions, to help synchronous code play nicely with async codedjangovarious Django helper functions, most of which you'll probably question "why is this not built into django?"exceptions- various exception classes, most of which are used by privex-helpers functions/classes, but can be
used in any python project to save you re-inventing an exception nameInstallDownload and install from PyPiUsingPipenv(recommended)pipenvinstallprivex-helpersUsing standard Python pippip3installprivex-helpers(Alternative) Manual install from GitOption 1 - Use pip to install straight from Githubpip3installgit+https://github.com/Privex/python-helpersOption 2 - Clone and install manually# Clone the repository from Githubgitclonehttps://github.com/Privex/python-helperscdpython-helpers# RECOMMENDED MANUAL INSTALL METHOD# Use pip to install the source codepip3install.# ALTERNATIVE MANUAL INSTALL METHOD# If you don't have pip, or have issues with installing using it, then you can use setuptools instead.python3setup.pyinstallDocumentationFull documentation for this project is available above (click the Read The Docs image), including:How to install the application and it's dependenciesHow to use the various functions and classesGeneral documentation of the modules and classes for contributorsTo build the documentation:gitclonehttps://github.com/Privex/python-helperscdpython-helpers/docs
pip3install-rrequirements.txt# It's recommended to run make clean to ensure old HTML files are removed# `make html` generates the .html and static files in docs/build for productionmakeclean&&makehtml# After the files are built, you can live develop the docs using `make live`# then browse to http://127.0.0.1:8100/# If you have issues with content not showing up correctly, try make clean && make html# then run make live again.makeliveLicenseThis Python module was created byPrivex Inc. of Belize City, and licensed under the X11/MIT License.
See the fileLICENSEfor the license text.TL;DR; license:We offer no warranty. You can copy it, modify it, use it in projects with a different license, and even in commercial (paid for) software.The most important rule is - youMUSTkeep the original license text visible (seeLICENSE) in any copies.Example usesWe export all of the submodule's contents inprivex/helpers/__init__.py, so you can import any
function/class/attribute straight fromprivex.helperwithout needing several import lines.Here are some of the most useful examples (part of our.commonmodule, no dependencies)fromprivex.helpersimportempty,is_true,random_str,ip_is_v4,ip_is_v6##### Our empty() helper is very convenient and easy to remember. It allows you to quick check if a variable is "empty"# (a blank string, None, zero, or an empty list/dict/tuple).##   empty(v, zero: bool = False, itr: bool = False) -> bool## For safety, it only returns True for empty iterables / integer zero (0) if you enable `zero` and/or `itr` respectively.####x=''ifempty(x):print('Var x is empty: either None or empty string')y=[]ifempty(y,itr=True):print('Var y is empty: either None, empty string, or empty iterable')##### Our is_true() / is_false() helpers are designed to ease checking boolean values from plain text config files# such as .env files, or values passed in an API call##### The strings 'true' / 'y' / 'yes' / '1' are all considered truthy, plus int 1 / bool Trueenable_x='YES'# String values are automatically cast to lowercase, so even 'YeS' and 'TrUe' are fine.ifis_true(enable_x):print('Enabling feature X')##### Need to generate a random alphanumeric string for a password / API key? Try random_str(), which uses SystemRandom()# for cryptographically secure randomness, and by default uses our SAFE_CHARS character set, removing look-alike# characters such as 1 and l, or o and 0##### Default random string - 50 character alphanum without easily mistaken charsrandom_str()# outputs: 'MrCWLYMYtT9A7bHc5ZNE4hn7PxHPmsWaT9GpfCkmZASK7ApN8r'# Customised random string - 12 characters using only the characters `abcdef12345`random_str(12,chars='abcdef12345')# outputs: 'aba4cc14a43d'##### As a server hosting provider, we deal with IP addresses a lot :)# The helper functions ip_is_v4 and ip_is_v6 do exactly as their name says, they return a boolean# if an IP is IPv4 or IPv6 respectively.####ip_is_v4('192.168.1.1')# Trueip_is_v4('2a07:e00::1')# Falseip_is_v6('192.168.1.1')# Falseip_is_v6('2a07:e00::1')# TrueMinimal dependenciesMost of our helper code is independent, and does not result in any extra dependencies being installed.Some of our helpers are dependant on external libraries or frameworks, such as Django or Flask. To avoid
large Python packages such as Django being installed needlessly, we programatically enable/disable some
of the helpers based on whether you have the required dependency installed.This package only requires (and automatically installs if needed) a single dependency - ourprivex-loghelperpackage, which itself is lightweight
and dependency free.Using Setuptools ExtrasAs of version 2.0.0 - Privex Helpers now supportsSetuptools Extras, allowing you
to specify extra dependencies related to privex-helpers in your requirements.txt, or when runningpip3 install.What is each extra for?Extras designed for using theprivex-helperspackage in a project/package:full- A meta-extra which includes most other extras required for full functionality of the library.It doesNOTinclude thedjangoextra, because theDjangopackage and it's sub-dependencies results in
a good 30-50mb of packages being installed, and those who would use thedjangomodule probably already
haveDjangoinstalled...It doesNOTinclude thedocsortestsextras, as those two are only required for building the
documentation, or running the unit tests.crypto- Install dependencies required to use thecryptomodulecache- Install optional dependencies to enable all cache backends incachedjango- Install dependencies related to thedjangomodule (includingDjangoitself)net- Install optional dependencies to enable full functionality of thenetmodulesetuppy- Install optional dependencies to enable full functionality of thesetuppymodulesExtras designed for use when developing, testing, documenting, or buildingprivex-helpers:dev- Includes everything required for development and related activities withprivex-helper.
Generally includes ALL extras, unlikefullthis includesdjango,docsandtestsdocs- This extra is not required for privex-helpers modules. It contains requirements for building the docs.tests- Not required for privex-helpers module usage. Contains requirements for running the unit tests.Using the extras with pip install# Example: Install privex-helpers AND all optional dependencies (excluding django), for full functionality
pip3 install 'privex-helpers[full]'

# Example: Install privex-helpers with only the crypto and cache module dependencies
pip3 install 'privex-helpers[cache,crypto]'

# Example: Install just privex-helpers and REQUIRED dependencies (i.e. critical to basic functionality)
pip3 install privex-helpersAlternatively, justpip3 installextra packages depending on the helpers you require:# For all Django-specific helpers in privex.helpers.django
Django
# For certain DNS dependant helpers in privex.helpers.net
dnspython>=1.16.0
# For using Redis with the privex.helpers.cache module
redis>=3.3.8
# For using the privex.helpers.crypto module
cryptography>=2.8Installing extras when using the cloned repositoryFirst, it's recommended to install the requirements inextras/setuppy.txtto ensure setup.py functions fully.pip3install-rextras/setuppy.txtAs of privex-helpers 2.1.0, you can use the handy setup.pyextrascommand to install individual extras requirements,
or all extra requirements painlessly:# Install ALL extras requirements (including Django and unit testing related)./setup.pyextras-i# Install an individual extras requirements, for example 'cache' or 'net'./setup.pyextras-i-ecacheIf you just want to install theprivex-helperspackage from source, then you can use pip to install
the current folder, and specify the extras you want:# Standard "full" install, excluding Django and development packages for docs/testingpip3install'.[full]'# Full development installation, includes everything in 'full', with the addition of the django, docs, and tests extraspip3install'.[dev]'Modules with dependenciesIf you're usingprivex-helperswithin a normal project (not a package), then it's recommended to simply
installprivex-helpers[full]which includes all main dependencies for full functionality.If you're using it inside of a package, then you should only require the extras that are critical to your package
functioning. Anything non-essential should be placed in theextras_requireof your setup.py to avoid
un-necessary packages being installed on your users.Modules which require a dependency to use themcrypto- This module won't work at all without thecryptographylibrary (orprivex-helpers[crypto])django- Django related helpers obviously don't work withoutDjangoinstalled. But since they're intended
for use within a Django project, you'd already haveDjangoinstalled anyway if you needed them :)Dynamic modules which simply enable additional features if you install certain packagessetuppy- Thecommonsub-module should generally work without any dependencies, but to be able to use all
functionality of this module such as thebumpandcommandssub-modules, you'll need to install with thesetuppyextra, e.g.privex-helpers[setuppy]net- Some functions are dependent ondnspython(orprivex-helpers[net]), but the majority of the module
is dependency-freecache- The cache layer works just fine without any dependencies. If you're usingprivex-helperwithin a project,
then you may want to installredis(orprivex-helpers[cache]) to make the Redis cache adapter available.plugin- While this module isn't very often used within other projects/packages, it does expose some
Redis singleton management functions (and possibly others at the time of writing). If you plan on using
this module, we recommend usingprivex-helpers[full]for the best experience.Unit TestsAs of late October 2019, we have over 70 individual unit tests in thetests/folder, which are split into severaltest_xxxxfiles, with each file holding tests for a specific module or smaller area of code. This library
consistently maintains on average 70-80% test coverage, helping to show this package is highly tested to ensure
reliable and robust code.We useTravis CIfor continuous integration, which runs the test
suite every time a new commit, tag, or branch is pushed to this Github repo.We also useCodeCovwhich integrates with our Travis CI setup, and
provides test coverage statistics, so ourselves and contributors can visually see how much of the code is covered
by our unit testsTL;Dr; Run the tests:pip3 install -r docs/requirements.txt
pytest -vFor more information about using the unit tests, see theHow to use the unit testssection of
the documentation.ContributingWe're happy to accept pull requests, no matter how small.Please make sure any changes you make meet these basic requirements:No additional dependencies. We want our helper package to be lightweight and painless to install.Any code taken from other projects should be compatible with the MIT LicenseThis is a new project, and as such, supporting Python versions prior to 3.4 is very low priority.However, we're happy to accept PRs to improve compatibility with older versions of Python, as long as it doesn't:drastically increase the complexity of the codeOR cause problems for those on newer versions of Python.Legal Disclaimer for ContributionsNobody wants to read a long document filled with legal text, so we've summed up the important parts here.If you contribute content that you've created/own to projects that are created/owned by Privex, such as code or
documentation, then you might automatically grant us unrestricted usage of your content, regardless of the open source
license that applies to our project.If you don't want to grant us unlimited usage of your content, you should make sure to place your content
in a separate file, making sure that the license of your content is clearly displayed at the start of the file
(e.g. code comments), or inside of it's containing folder (e.g. a file named LICENSE).You should let us know in your pull request or issue that you've included files which are licensed
separately, so that we can make sure there's no license conflicts that might stop us being able
to accept your contribution.If you'd rather read the whole legal text, it should be included asprivex_contribution_agreement.txt.Thanks for reading!If this project has helped you, considergrabbing a VPS or Dedicated Server from Privex.Prices start at as little as US$8/mo (we take cryptocurrency!)