%global _empty_manifest_terminate_build 0 Name: python-privex-helpers Version: 3.2.1 Release: 1 Summary: A variety of helper functions and classes, useful for many different projects License: MIT URL: https://github.com/Privex/python-helpers Source0: https://mirrors.nju.edu.cn/pypi/web/packages/44/e8/b179dadc0c73b88c51b5e2c0563d6ead690093165fadaaa0549f0cb71ed1/privex_helpers-3.2.1.tar.gz BuildArch: noarch Requires: python3-privex-loghelper Requires: python3-dateutil Requires: python3-sniffio Requires: python3-async-property Requires: python3-attrs Requires: python3-redis Requires: python3-aioredis Requires: python3-hiredis Requires: python3-pylibmc Requires: python3-aiomcache Requires: python3-privex-db Requires: python3-aiosqlite Requires: python3-cryptography Requires: python3-redis Requires: python3-aioredis Requires: python3-hiredis Requires: python3-pylibmc Requires: python3-aiomcache Requires: python3-privex-db Requires: python3-aiosqlite Requires: python3-dnspython Requires: python3-geoip2 Requires: python3-attrs Requires: python3-cryptography Requires: python3-setuptools Requires: python3-wheel Requires: python3-twine Requires: python3-semver Requires: python3-Django Requires: python3-Sphinx Requires: python3-sphinx-autobuild Requires: python3-restructuredtext-lint Requires: python3-sphinx-rtd-theme Requires: python3-MarkupSafe Requires: python3-docutils Requires: python3-pytest Requires: python3-pytest-cov Requires: python3-pytest-asyncio Requires: python3-coverage Requires: python3-codecov Requires: python3-mypy Requires: python3-jupyter Requires: python3-mypy Requires: python3-jupyter Requires: python3-Django Requires: python3-Sphinx Requires: python3-sphinx-autobuild Requires: python3-restructuredtext-lint Requires: python3-sphinx-rtd-theme Requires: python3-MarkupSafe Requires: python3-docutils Requires: python3-attrs Requires: python3-redis Requires: python3-aioredis Requires: python3-hiredis Requires: python3-pylibmc Requires: python3-aiomcache Requires: python3-privex-db Requires: python3-aiosqlite Requires: python3-dnspython Requires: python3-geoip2 Requires: python3-attrs Requires: python3-cryptography Requires: python3-setuptools Requires: python3-wheel Requires: python3-twine Requires: python3-semver Requires: python3-geoip2 Requires: python3-attrs Requires: python3-dnspython Requires: python3-geoip2 Requires: python3-attrs Requires: python3-setuptools Requires: python3-wheel Requires: python3-twine Requires: python3-semver Requires: python3-pytest Requires: python3-pytest-cov Requires: python3-pytest-asyncio Requires: python3-coverage Requires: python3-codecov %description # Privex's Python Helpers [![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) [![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) ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/privex-helpers) ![GitHub last commit](https://img.shields.io/github/last-commit/Privex/python-helpers) 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 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 Helpers Install from PyPi (detailed install info at [Install](#Install) and [Using package extras](#minimal-dependencies)) ```sh pipenv install privex-helpers # If you use pipenv (and you should!) pip3 install privex-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-helpers pipenv install 'privex-helpers[full]' # If you use pipenv (and you should!) pip3 install 'privex-helpers[full]' # Otherwise, standard pip installation ``` Very import and basic usage (detailed examples at [Example Uses](#example-uses)) ```python from privex.helpers import is_true, empty if is_true('yes'): print('yes is truthful') if empty(''): 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. 1. [Why use Privex Helpers?](#why-use-privex-helpers) 1.1. [Lightweight](#lightweight) 1.2. [Keeps your code DRY (Don't repeat yourself!)](#keeps-your-code-dry-dont-repeat-yourself) 1.3. [Makes your life just plain easier](#makes-your-life-just-plain-easier) 1.4. [Thorough unit tests](#thorough-unit-tests) 1.5. [Overview of what's included](#overview-of-whats-included) 2. [Install](#Install) 2.1 [Via PyPi (pip)](#download-and-install-from-pypi) 2.2 [Manually via Git](#alternative-manual-install-from-git) 3. [Documentation](#documentation) 4. [License](#License) 5. [Example Uses](#example-uses) 6. [Minimal Dependencies / Using package extras](#minimal-dependencies) 6.1 [Modules with dependencies](#modules-with-dependencies) 6.2 [Using Setuptools Extras](#using-setuptools-extras) 6.3 [Installing extras when using the cloned repository](#installing-extras-when-using-the-cloned-repository) 7. [Unit Tests](#unit-tests) 8. [Contributing](#contributing) # Why use Privex Helpers? Privex helpers was created with a very simple goal in mind: make developing Python applications easy, fun, simple, and **painless**. ### Lightweight Whether you're using it in a library, or in your project, you'll be pleased to know that the `privex-helpers` and all of it's *required dependencies* make up less than **200kb total**. For comparison, the `Django` package alone (that's excluding it's dependencies) is a whopping 26 MEGABYTES. Most of `privex-helpers` can 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. See [Modules with dependencies](#modules-with-dependencies) to 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 long `if` statements to check if a user entered value was some sort-of boolean value? Use `is_true` and `is_false` - trim those long if statements into a single function call. Less typing, and more readable. ### Makes your life just plain easier Writing 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-helpers` includes 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 popular [cryptography](https://cryptography.io/en/latest/) package docs, and it looks like you're going to be writing scaffolding code for hours just to do that... Say hello to `privex.helpers.crypto` - whether you're dealing with symmetric or asymmetric encryption, it's just **one import line, a few lines of code and you're DONE.** ### Thorough unit tests Included in the `tests/` 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. See [Unit Tests](#unit-tests) for more details. This ensures that `privex-helpers` is 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 included This is not an exhaustive list, and may sometimes be a little outdated. To see everything that's available in `privex-helpers` then check out the [Documentation](https://python-helpers.readthedocs.io/en/latest/index.html). - `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"`, `1` - `is_false` - fuzzy "false" testing, checks for common forms of false, e.g. `False`, `"false"`, `"no"`, `0` - `env_csv` - load an environment variable like a CSV, allowing for list representation in env vars - `env_keyval` - load an environment variable like a key value map, allowing for tuple pair / dict representation in env vars - `dec_round` - round a python `Decimal` using the built-in Quantize method, but without the hassle. - `Dictable` - easily create your Python 3.7 `dataclass` from a dictionary, plus enable them to be casted into a plain dict using `dict(mydataclass)` - and MORE, check the [documentation!](https://python-helpers.readthedocs.io/en/latest/helpers/privex.helpers.common.html) - `cache` - a dependency-free, framework agnostic caching layer, with support for: - automatic timeouts - ability 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 support - can optionally use Redis if you'd prefer (requires an optional dependency) - `crypto` - classes which make both symmetric and asymmetric encryption extremely easy to use - `EncryptHelper` - 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 + salt - `KeyManager` - 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 files - `common.extras_require` - A helper function which allows you to generate an `extras_require` setting 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 version - `commands.BumpCommand` - A setup.py command class, which allows you to use `bump.bump_version` within 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 managing `extras_require` in 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 code - `retry_on_err` - automatically re-run a function/method when exceptions are thrown, with a variety of customization available - `r_cache` - automatic caching of a function/property, with support for caching based on parameters or a lambda - `net` - various networking functions, including: - handling IP addresses - generating reverse DNS records - looking up ASN names based on their number - checking if an IP is up (via ping) - with both IPv4 and IPv6 support - `asyncx` - various async helper functions, to help synchronous code play nicely with async code - `django` various 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 name # Install ### 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 ``` ### (Alternative) Manual install from Git **Option 1 - Use pip to install straight from Github** ```sh pip3 install git+https://github.com/Privex/python-helpers ``` **Option 2 - Clone and install manually** ```bash # Clone the repository from Github git clone https://github.com/Privex/python-helpers cd python-helpers # RECOMMENDED MANUAL INSTALL METHOD # Use pip to install the source code pip3 install . # ALTERNATIVE MANUAL INSTALL METHOD # If you don't have pip, or have issues with installing using it, then you can use setuptools instead. python3 setup.py install ``` # Documentation [![Read the Documentation](https://read-the-docs-guidelines.readthedocs-hosted.com/_images/logo-wordmark-dark.png)]( https://python-helpers.readthedocs.io/en/latest/) Full documentation for this project is available above (click the Read The Docs image), including: - How to install the application and it's dependencies - How to use the various functions and classes - General documentation of the modules and classes for contributors **To build the documentation:** ```bash git clone https://github.com/Privex/python-helpers cd python-helpers/docs pip3 install -r requirements.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 production make clean && make html # 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. make live ``` # License This Python module was created by [Privex Inc. of Belize City](https://www.privex.io), and licensed under the X11/MIT License. See the file [LICENSE](https://github.com/Privex/python-helpers/blob/master/LICENSE) for 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 - you **MUST** keep the original license text visible (see `LICENSE`) in any copies. # Example uses We export all of the submodule's contents in `privex/helpers/__init__.py`, so you can import any function/class/attribute straight from `privex.helper` without needing several import lines. Here are some of the most useful examples (part of our `.common` module, no dependencies) ```python from privex.helpers import empty, 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 = '' if empty(x): print('Var x is empty: either None or empty string') y = [] if empty(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 True enable_x = 'YES' # String values are automatically cast to lowercase, so even 'YeS' and 'TrUe' are fine. if is_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 chars random_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') # True ip_is_v4('2a07:e00::1') # False ip_is_v6('192.168.1.1') # False ip_is_v6('2a07:e00::1') # True ``` # Minimal dependencies Most 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 - our [privex-loghelper](https://github.com/Privex/python-loghelper) package, which itself is lightweight and dependency free. ### Using Setuptools Extras As of version 2.0.0 - Privex Helpers now supports **Setuptools Extras**, allowing you to specify extra dependencies related to privex-helpers in your requirements.txt, or when running **pip3 install**. **What is each extra for?** Extras designed for using the `privex-helpers` package in a project/package: - **full** - A meta-extra which includes most other extras required for full functionality of the library. - It does **NOT** include the `django` extra, because the `Django` package and it's sub-dependencies results in a good 30-50mb of packages being installed, and those who would use the `django` module probably already have `Django` installed... - It does **NOT** include the `docs` or `tests` extras, as those two are only required for building the documentation, or running the unit tests. - **crypto** - Install dependencies required to use the `crypto` module - **cache** - Install optional dependencies to enable all cache backends in `cache` - **django** - Install dependencies related to the `django` module (including `Django` itself) - **net** - Install optional dependencies to enable full functionality of the `net` module - **setuppy** - Install optional dependencies to enable full functionality of the `setuppy` modules Extras designed for use when developing, testing, documenting, or building `privex-helpers`: - **dev** - Includes everything required for development and related activities with `privex-helper`. Generally includes ALL extras, unlike `full` this includes `django`, `docs` and `tests` - **docs** - 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-helpers ``` Alternatively, just `pip3 install` extra 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.8 ``` ### Installing extras when using the cloned repository First, it's recommended to install the requirements in `extras/setuppy.txt` to ensure setup.py functions fully. ```bash pip3 install -r extras/setuppy.txt ``` As of privex-helpers 2.1.0, you can use the handy setup.py `extras` command to install individual extras requirements, or all extra requirements painlessly: ```bash # Install ALL extras requirements (including Django and unit testing related) ./setup.py extras -i # Install an individual extras requirements, for example 'cache' or 'net' ./setup.py extras -i -e cache ``` If you just want to install the `privex-helpers` package from source, then you can use pip to install the current folder, and specify the extras you want: ```bash # Standard "full" install, excluding Django and development packages for docs/testing pip3 install '.[full]' # Full development installation, includes everything in 'full', with the addition of the django, docs, and tests extras pip3 install '.[dev]' ``` ### Modules with dependencies If you're using `privex-helpers` within a normal project (not a package), then it's recommended to simply install `privex-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 the `extras_require` of your setup.py to avoid un-necessary packages being installed on your users. **Modules which require a dependency to use them** - `crypto` - This module won't work at all without the `cryptography` library (or `privex-helpers[crypto]`) - `django` - Django related helpers obviously don't work without `Django` installed. But since they're intended for use within a Django project, you'd already have `Django` installed anyway if you needed them :) **Dynamic modules which simply enable additional features if you install certain packages** - `setuppy` - The `common` sub-module should generally work without any dependencies, but to be able to use all functionality of this module such as the `bump` and `commands` sub-modules, you'll need to install with the `setuppy` extra, e.g. `privex-helpers[setuppy]` - `net` - Some functions are dependent on `dnspython` (or `privex-helpers[net]`), but the majority of the module is dependency-free - `cache` - The cache layer works just fine without any dependencies. If you're using `privex-helper` within a project, then you may want to install `redis` (or `privex-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 using `privex-helpers[full]` for the best experience. # Unit Tests As of late October 2019, we have over 70 individual unit tests in the `tests/` folder, which are split into several `test_xxxx` files, 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 use [Travis CI](https://travis-ci.com/Privex/python-helpers) for continuous integration, which runs the test suite every time a new commit, tag, or branch is pushed to this Github repo. We also use [CodeCov](https://codecov.io/gh/Privex/python-helpers) which 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 tests TL;Dr; Run the tests: ``` pip3 install -r docs/requirements.txt pytest -v ``` For more information about using the unit tests, see the [How to use the unit tests](https://python-helpers.readthedocs.io/en/latest/helpers/tests.html) section of the documentation. # Contributing We'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 License - This 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 code - OR cause problems for those on newer versions of Python. **Legal Disclaimer for Contributions** Nobody 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 as `privex_contribution_agreement.txt`. # Thanks for reading! **If this project has helped you, consider [grabbing a VPS or Dedicated Server from Privex](https://www.privex.io).** **Prices start at as little as US$8/mo (we take cryptocurrency!)** %package -n python3-privex-helpers Summary: A variety of helper functions and classes, useful for many different projects Provides: python-privex-helpers BuildRequires: python3-devel BuildRequires: python3-setuptools BuildRequires: python3-pip %description -n python3-privex-helpers # Privex's Python Helpers [![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) [![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) ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/privex-helpers) ![GitHub last commit](https://img.shields.io/github/last-commit/Privex/python-helpers) 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 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 Helpers Install from PyPi (detailed install info at [Install](#Install) and [Using package extras](#minimal-dependencies)) ```sh pipenv install privex-helpers # If you use pipenv (and you should!) pip3 install privex-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-helpers pipenv install 'privex-helpers[full]' # If you use pipenv (and you should!) pip3 install 'privex-helpers[full]' # Otherwise, standard pip installation ``` Very import and basic usage (detailed examples at [Example Uses](#example-uses)) ```python from privex.helpers import is_true, empty if is_true('yes'): print('yes is truthful') if empty(''): 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. 1. [Why use Privex Helpers?](#why-use-privex-helpers) 1.1. [Lightweight](#lightweight) 1.2. [Keeps your code DRY (Don't repeat yourself!)](#keeps-your-code-dry-dont-repeat-yourself) 1.3. [Makes your life just plain easier](#makes-your-life-just-plain-easier) 1.4. [Thorough unit tests](#thorough-unit-tests) 1.5. [Overview of what's included](#overview-of-whats-included) 2. [Install](#Install) 2.1 [Via PyPi (pip)](#download-and-install-from-pypi) 2.2 [Manually via Git](#alternative-manual-install-from-git) 3. [Documentation](#documentation) 4. [License](#License) 5. [Example Uses](#example-uses) 6. [Minimal Dependencies / Using package extras](#minimal-dependencies) 6.1 [Modules with dependencies](#modules-with-dependencies) 6.2 [Using Setuptools Extras](#using-setuptools-extras) 6.3 [Installing extras when using the cloned repository](#installing-extras-when-using-the-cloned-repository) 7. [Unit Tests](#unit-tests) 8. [Contributing](#contributing) # Why use Privex Helpers? Privex helpers was created with a very simple goal in mind: make developing Python applications easy, fun, simple, and **painless**. ### Lightweight Whether you're using it in a library, or in your project, you'll be pleased to know that the `privex-helpers` and all of it's *required dependencies* make up less than **200kb total**. For comparison, the `Django` package alone (that's excluding it's dependencies) is a whopping 26 MEGABYTES. Most of `privex-helpers` can 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. See [Modules with dependencies](#modules-with-dependencies) to 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 long `if` statements to check if a user entered value was some sort-of boolean value? Use `is_true` and `is_false` - trim those long if statements into a single function call. Less typing, and more readable. ### Makes your life just plain easier Writing 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-helpers` includes 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 popular [cryptography](https://cryptography.io/en/latest/) package docs, and it looks like you're going to be writing scaffolding code for hours just to do that... Say hello to `privex.helpers.crypto` - whether you're dealing with symmetric or asymmetric encryption, it's just **one import line, a few lines of code and you're DONE.** ### Thorough unit tests Included in the `tests/` 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. See [Unit Tests](#unit-tests) for more details. This ensures that `privex-helpers` is 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 included This is not an exhaustive list, and may sometimes be a little outdated. To see everything that's available in `privex-helpers` then check out the [Documentation](https://python-helpers.readthedocs.io/en/latest/index.html). - `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"`, `1` - `is_false` - fuzzy "false" testing, checks for common forms of false, e.g. `False`, `"false"`, `"no"`, `0` - `env_csv` - load an environment variable like a CSV, allowing for list representation in env vars - `env_keyval` - load an environment variable like a key value map, allowing for tuple pair / dict representation in env vars - `dec_round` - round a python `Decimal` using the built-in Quantize method, but without the hassle. - `Dictable` - easily create your Python 3.7 `dataclass` from a dictionary, plus enable them to be casted into a plain dict using `dict(mydataclass)` - and MORE, check the [documentation!](https://python-helpers.readthedocs.io/en/latest/helpers/privex.helpers.common.html) - `cache` - a dependency-free, framework agnostic caching layer, with support for: - automatic timeouts - ability 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 support - can optionally use Redis if you'd prefer (requires an optional dependency) - `crypto` - classes which make both symmetric and asymmetric encryption extremely easy to use - `EncryptHelper` - 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 + salt - `KeyManager` - 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 files - `common.extras_require` - A helper function which allows you to generate an `extras_require` setting 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 version - `commands.BumpCommand` - A setup.py command class, which allows you to use `bump.bump_version` within 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 managing `extras_require` in 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 code - `retry_on_err` - automatically re-run a function/method when exceptions are thrown, with a variety of customization available - `r_cache` - automatic caching of a function/property, with support for caching based on parameters or a lambda - `net` - various networking functions, including: - handling IP addresses - generating reverse DNS records - looking up ASN names based on their number - checking if an IP is up (via ping) - with both IPv4 and IPv6 support - `asyncx` - various async helper functions, to help synchronous code play nicely with async code - `django` various 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 name # Install ### 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 ``` ### (Alternative) Manual install from Git **Option 1 - Use pip to install straight from Github** ```sh pip3 install git+https://github.com/Privex/python-helpers ``` **Option 2 - Clone and install manually** ```bash # Clone the repository from Github git clone https://github.com/Privex/python-helpers cd python-helpers # RECOMMENDED MANUAL INSTALL METHOD # Use pip to install the source code pip3 install . # ALTERNATIVE MANUAL INSTALL METHOD # If you don't have pip, or have issues with installing using it, then you can use setuptools instead. python3 setup.py install ``` # Documentation [![Read the Documentation](https://read-the-docs-guidelines.readthedocs-hosted.com/_images/logo-wordmark-dark.png)]( https://python-helpers.readthedocs.io/en/latest/) Full documentation for this project is available above (click the Read The Docs image), including: - How to install the application and it's dependencies - How to use the various functions and classes - General documentation of the modules and classes for contributors **To build the documentation:** ```bash git clone https://github.com/Privex/python-helpers cd python-helpers/docs pip3 install -r requirements.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 production make clean && make html # 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. make live ``` # License This Python module was created by [Privex Inc. of Belize City](https://www.privex.io), and licensed under the X11/MIT License. See the file [LICENSE](https://github.com/Privex/python-helpers/blob/master/LICENSE) for 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 - you **MUST** keep the original license text visible (see `LICENSE`) in any copies. # Example uses We export all of the submodule's contents in `privex/helpers/__init__.py`, so you can import any function/class/attribute straight from `privex.helper` without needing several import lines. Here are some of the most useful examples (part of our `.common` module, no dependencies) ```python from privex.helpers import empty, 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 = '' if empty(x): print('Var x is empty: either None or empty string') y = [] if empty(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 True enable_x = 'YES' # String values are automatically cast to lowercase, so even 'YeS' and 'TrUe' are fine. if is_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 chars random_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') # True ip_is_v4('2a07:e00::1') # False ip_is_v6('192.168.1.1') # False ip_is_v6('2a07:e00::1') # True ``` # Minimal dependencies Most 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 - our [privex-loghelper](https://github.com/Privex/python-loghelper) package, which itself is lightweight and dependency free. ### Using Setuptools Extras As of version 2.0.0 - Privex Helpers now supports **Setuptools Extras**, allowing you to specify extra dependencies related to privex-helpers in your requirements.txt, or when running **pip3 install**. **What is each extra for?** Extras designed for using the `privex-helpers` package in a project/package: - **full** - A meta-extra which includes most other extras required for full functionality of the library. - It does **NOT** include the `django` extra, because the `Django` package and it's sub-dependencies results in a good 30-50mb of packages being installed, and those who would use the `django` module probably already have `Django` installed... - It does **NOT** include the `docs` or `tests` extras, as those two are only required for building the documentation, or running the unit tests. - **crypto** - Install dependencies required to use the `crypto` module - **cache** - Install optional dependencies to enable all cache backends in `cache` - **django** - Install dependencies related to the `django` module (including `Django` itself) - **net** - Install optional dependencies to enable full functionality of the `net` module - **setuppy** - Install optional dependencies to enable full functionality of the `setuppy` modules Extras designed for use when developing, testing, documenting, or building `privex-helpers`: - **dev** - Includes everything required for development and related activities with `privex-helper`. Generally includes ALL extras, unlike `full` this includes `django`, `docs` and `tests` - **docs** - 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-helpers ``` Alternatively, just `pip3 install` extra 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.8 ``` ### Installing extras when using the cloned repository First, it's recommended to install the requirements in `extras/setuppy.txt` to ensure setup.py functions fully. ```bash pip3 install -r extras/setuppy.txt ``` As of privex-helpers 2.1.0, you can use the handy setup.py `extras` command to install individual extras requirements, or all extra requirements painlessly: ```bash # Install ALL extras requirements (including Django and unit testing related) ./setup.py extras -i # Install an individual extras requirements, for example 'cache' or 'net' ./setup.py extras -i -e cache ``` If you just want to install the `privex-helpers` package from source, then you can use pip to install the current folder, and specify the extras you want: ```bash # Standard "full" install, excluding Django and development packages for docs/testing pip3 install '.[full]' # Full development installation, includes everything in 'full', with the addition of the django, docs, and tests extras pip3 install '.[dev]' ``` ### Modules with dependencies If you're using `privex-helpers` within a normal project (not a package), then it's recommended to simply install `privex-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 the `extras_require` of your setup.py to avoid un-necessary packages being installed on your users. **Modules which require a dependency to use them** - `crypto` - This module won't work at all without the `cryptography` library (or `privex-helpers[crypto]`) - `django` - Django related helpers obviously don't work without `Django` installed. But since they're intended for use within a Django project, you'd already have `Django` installed anyway if you needed them :) **Dynamic modules which simply enable additional features if you install certain packages** - `setuppy` - The `common` sub-module should generally work without any dependencies, but to be able to use all functionality of this module such as the `bump` and `commands` sub-modules, you'll need to install with the `setuppy` extra, e.g. `privex-helpers[setuppy]` - `net` - Some functions are dependent on `dnspython` (or `privex-helpers[net]`), but the majority of the module is dependency-free - `cache` - The cache layer works just fine without any dependencies. If you're using `privex-helper` within a project, then you may want to install `redis` (or `privex-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 using `privex-helpers[full]` for the best experience. # Unit Tests As of late October 2019, we have over 70 individual unit tests in the `tests/` folder, which are split into several `test_xxxx` files, 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 use [Travis CI](https://travis-ci.com/Privex/python-helpers) for continuous integration, which runs the test suite every time a new commit, tag, or branch is pushed to this Github repo. We also use [CodeCov](https://codecov.io/gh/Privex/python-helpers) which 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 tests TL;Dr; Run the tests: ``` pip3 install -r docs/requirements.txt pytest -v ``` For more information about using the unit tests, see the [How to use the unit tests](https://python-helpers.readthedocs.io/en/latest/helpers/tests.html) section of the documentation. # Contributing We'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 License - This 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 code - OR cause problems for those on newer versions of Python. **Legal Disclaimer for Contributions** Nobody 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 as `privex_contribution_agreement.txt`. # Thanks for reading! **If this project has helped you, consider [grabbing a VPS or Dedicated Server from Privex](https://www.privex.io).** **Prices start at as little as US$8/mo (we take cryptocurrency!)** %package help Summary: Development documents and examples for privex-helpers Provides: python3-privex-helpers-doc %description help # Privex's Python Helpers [![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) [![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) ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/privex-helpers) ![GitHub last commit](https://img.shields.io/github/last-commit/Privex/python-helpers) 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 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 Helpers Install from PyPi (detailed install info at [Install](#Install) and [Using package extras](#minimal-dependencies)) ```sh pipenv install privex-helpers # If you use pipenv (and you should!) pip3 install privex-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-helpers pipenv install 'privex-helpers[full]' # If you use pipenv (and you should!) pip3 install 'privex-helpers[full]' # Otherwise, standard pip installation ``` Very import and basic usage (detailed examples at [Example Uses](#example-uses)) ```python from privex.helpers import is_true, empty if is_true('yes'): print('yes is truthful') if empty(''): 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. 1. [Why use Privex Helpers?](#why-use-privex-helpers) 1.1. [Lightweight](#lightweight) 1.2. [Keeps your code DRY (Don't repeat yourself!)](#keeps-your-code-dry-dont-repeat-yourself) 1.3. [Makes your life just plain easier](#makes-your-life-just-plain-easier) 1.4. [Thorough unit tests](#thorough-unit-tests) 1.5. [Overview of what's included](#overview-of-whats-included) 2. [Install](#Install) 2.1 [Via PyPi (pip)](#download-and-install-from-pypi) 2.2 [Manually via Git](#alternative-manual-install-from-git) 3. [Documentation](#documentation) 4. [License](#License) 5. [Example Uses](#example-uses) 6. [Minimal Dependencies / Using package extras](#minimal-dependencies) 6.1 [Modules with dependencies](#modules-with-dependencies) 6.2 [Using Setuptools Extras](#using-setuptools-extras) 6.3 [Installing extras when using the cloned repository](#installing-extras-when-using-the-cloned-repository) 7. [Unit Tests](#unit-tests) 8. [Contributing](#contributing) # Why use Privex Helpers? Privex helpers was created with a very simple goal in mind: make developing Python applications easy, fun, simple, and **painless**. ### Lightweight Whether you're using it in a library, or in your project, you'll be pleased to know that the `privex-helpers` and all of it's *required dependencies* make up less than **200kb total**. For comparison, the `Django` package alone (that's excluding it's dependencies) is a whopping 26 MEGABYTES. Most of `privex-helpers` can 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. See [Modules with dependencies](#modules-with-dependencies) to 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 long `if` statements to check if a user entered value was some sort-of boolean value? Use `is_true` and `is_false` - trim those long if statements into a single function call. Less typing, and more readable. ### Makes your life just plain easier Writing 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-helpers` includes 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 popular [cryptography](https://cryptography.io/en/latest/) package docs, and it looks like you're going to be writing scaffolding code for hours just to do that... Say hello to `privex.helpers.crypto` - whether you're dealing with symmetric or asymmetric encryption, it's just **one import line, a few lines of code and you're DONE.** ### Thorough unit tests Included in the `tests/` 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. See [Unit Tests](#unit-tests) for more details. This ensures that `privex-helpers` is 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 included This is not an exhaustive list, and may sometimes be a little outdated. To see everything that's available in `privex-helpers` then check out the [Documentation](https://python-helpers.readthedocs.io/en/latest/index.html). - `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"`, `1` - `is_false` - fuzzy "false" testing, checks for common forms of false, e.g. `False`, `"false"`, `"no"`, `0` - `env_csv` - load an environment variable like a CSV, allowing for list representation in env vars - `env_keyval` - load an environment variable like a key value map, allowing for tuple pair / dict representation in env vars - `dec_round` - round a python `Decimal` using the built-in Quantize method, but without the hassle. - `Dictable` - easily create your Python 3.7 `dataclass` from a dictionary, plus enable them to be casted into a plain dict using `dict(mydataclass)` - and MORE, check the [documentation!](https://python-helpers.readthedocs.io/en/latest/helpers/privex.helpers.common.html) - `cache` - a dependency-free, framework agnostic caching layer, with support for: - automatic timeouts - ability 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 support - can optionally use Redis if you'd prefer (requires an optional dependency) - `crypto` - classes which make both symmetric and asymmetric encryption extremely easy to use - `EncryptHelper` - 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 + salt - `KeyManager` - 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 files - `common.extras_require` - A helper function which allows you to generate an `extras_require` setting 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 version - `commands.BumpCommand` - A setup.py command class, which allows you to use `bump.bump_version` within 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 managing `extras_require` in 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 code - `retry_on_err` - automatically re-run a function/method when exceptions are thrown, with a variety of customization available - `r_cache` - automatic caching of a function/property, with support for caching based on parameters or a lambda - `net` - various networking functions, including: - handling IP addresses - generating reverse DNS records - looking up ASN names based on their number - checking if an IP is up (via ping) - with both IPv4 and IPv6 support - `asyncx` - various async helper functions, to help synchronous code play nicely with async code - `django` various 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 name # Install ### 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 ``` ### (Alternative) Manual install from Git **Option 1 - Use pip to install straight from Github** ```sh pip3 install git+https://github.com/Privex/python-helpers ``` **Option 2 - Clone and install manually** ```bash # Clone the repository from Github git clone https://github.com/Privex/python-helpers cd python-helpers # RECOMMENDED MANUAL INSTALL METHOD # Use pip to install the source code pip3 install . # ALTERNATIVE MANUAL INSTALL METHOD # If you don't have pip, or have issues with installing using it, then you can use setuptools instead. python3 setup.py install ``` # Documentation [![Read the Documentation](https://read-the-docs-guidelines.readthedocs-hosted.com/_images/logo-wordmark-dark.png)]( https://python-helpers.readthedocs.io/en/latest/) Full documentation for this project is available above (click the Read The Docs image), including: - How to install the application and it's dependencies - How to use the various functions and classes - General documentation of the modules and classes for contributors **To build the documentation:** ```bash git clone https://github.com/Privex/python-helpers cd python-helpers/docs pip3 install -r requirements.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 production make clean && make html # 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. make live ``` # License This Python module was created by [Privex Inc. of Belize City](https://www.privex.io), and licensed under the X11/MIT License. See the file [LICENSE](https://github.com/Privex/python-helpers/blob/master/LICENSE) for 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 - you **MUST** keep the original license text visible (see `LICENSE`) in any copies. # Example uses We export all of the submodule's contents in `privex/helpers/__init__.py`, so you can import any function/class/attribute straight from `privex.helper` without needing several import lines. Here are some of the most useful examples (part of our `.common` module, no dependencies) ```python from privex.helpers import empty, 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 = '' if empty(x): print('Var x is empty: either None or empty string') y = [] if empty(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 True enable_x = 'YES' # String values are automatically cast to lowercase, so even 'YeS' and 'TrUe' are fine. if is_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 chars random_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') # True ip_is_v4('2a07:e00::1') # False ip_is_v6('192.168.1.1') # False ip_is_v6('2a07:e00::1') # True ``` # Minimal dependencies Most 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 - our [privex-loghelper](https://github.com/Privex/python-loghelper) package, which itself is lightweight and dependency free. ### Using Setuptools Extras As of version 2.0.0 - Privex Helpers now supports **Setuptools Extras**, allowing you to specify extra dependencies related to privex-helpers in your requirements.txt, or when running **pip3 install**. **What is each extra for?** Extras designed for using the `privex-helpers` package in a project/package: - **full** - A meta-extra which includes most other extras required for full functionality of the library. - It does **NOT** include the `django` extra, because the `Django` package and it's sub-dependencies results in a good 30-50mb of packages being installed, and those who would use the `django` module probably already have `Django` installed... - It does **NOT** include the `docs` or `tests` extras, as those two are only required for building the documentation, or running the unit tests. - **crypto** - Install dependencies required to use the `crypto` module - **cache** - Install optional dependencies to enable all cache backends in `cache` - **django** - Install dependencies related to the `django` module (including `Django` itself) - **net** - Install optional dependencies to enable full functionality of the `net` module - **setuppy** - Install optional dependencies to enable full functionality of the `setuppy` modules Extras designed for use when developing, testing, documenting, or building `privex-helpers`: - **dev** - Includes everything required for development and related activities with `privex-helper`. Generally includes ALL extras, unlike `full` this includes `django`, `docs` and `tests` - **docs** - 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-helpers ``` Alternatively, just `pip3 install` extra 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.8 ``` ### Installing extras when using the cloned repository First, it's recommended to install the requirements in `extras/setuppy.txt` to ensure setup.py functions fully. ```bash pip3 install -r extras/setuppy.txt ``` As of privex-helpers 2.1.0, you can use the handy setup.py `extras` command to install individual extras requirements, or all extra requirements painlessly: ```bash # Install ALL extras requirements (including Django and unit testing related) ./setup.py extras -i # Install an individual extras requirements, for example 'cache' or 'net' ./setup.py extras -i -e cache ``` If you just want to install the `privex-helpers` package from source, then you can use pip to install the current folder, and specify the extras you want: ```bash # Standard "full" install, excluding Django and development packages for docs/testing pip3 install '.[full]' # Full development installation, includes everything in 'full', with the addition of the django, docs, and tests extras pip3 install '.[dev]' ``` ### Modules with dependencies If you're using `privex-helpers` within a normal project (not a package), then it's recommended to simply install `privex-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 the `extras_require` of your setup.py to avoid un-necessary packages being installed on your users. **Modules which require a dependency to use them** - `crypto` - This module won't work at all without the `cryptography` library (or `privex-helpers[crypto]`) - `django` - Django related helpers obviously don't work without `Django` installed. But since they're intended for use within a Django project, you'd already have `Django` installed anyway if you needed them :) **Dynamic modules which simply enable additional features if you install certain packages** - `setuppy` - The `common` sub-module should generally work without any dependencies, but to be able to use all functionality of this module such as the `bump` and `commands` sub-modules, you'll need to install with the `setuppy` extra, e.g. `privex-helpers[setuppy]` - `net` - Some functions are dependent on `dnspython` (or `privex-helpers[net]`), but the majority of the module is dependency-free - `cache` - The cache layer works just fine without any dependencies. If you're using `privex-helper` within a project, then you may want to install `redis` (or `privex-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 using `privex-helpers[full]` for the best experience. # Unit Tests As of late October 2019, we have over 70 individual unit tests in the `tests/` folder, which are split into several `test_xxxx` files, 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 use [Travis CI](https://travis-ci.com/Privex/python-helpers) for continuous integration, which runs the test suite every time a new commit, tag, or branch is pushed to this Github repo. We also use [CodeCov](https://codecov.io/gh/Privex/python-helpers) which 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 tests TL;Dr; Run the tests: ``` pip3 install -r docs/requirements.txt pytest -v ``` For more information about using the unit tests, see the [How to use the unit tests](https://python-helpers.readthedocs.io/en/latest/helpers/tests.html) section of the documentation. # Contributing We'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 License - This 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 code - OR cause problems for those on newer versions of Python. **Legal Disclaimer for Contributions** Nobody 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 as `privex_contribution_agreement.txt`. # Thanks for reading! **If this project has helped you, consider [grabbing a VPS or Dedicated Server from Privex](https://www.privex.io).** **Prices start at as little as US$8/mo (we take cryptocurrency!)** %prep %autosetup -n privex-helpers-3.2.1 %build %py3_build %install %py3_install install -d -m755 %{buildroot}/%{_pkgdocdir} if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi pushd %{buildroot} if [ -d usr/lib ]; then find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst fi if [ -d usr/lib64 ]; then find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst fi if [ -d usr/bin ]; then find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst fi if [ -d usr/sbin ]; then find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst fi touch doclist.lst if [ -d usr/share/man ]; then find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst fi popd mv %{buildroot}/filelist.lst . mv %{buildroot}/doclist.lst . %files -n python3-privex-helpers -f filelist.lst %dir %{python3_sitelib}/* %files help -f doclist.lst %{_docdir}/* %changelog * Wed May 10 2023 Python_Bot - 3.2.1-1 - Package Spec generated