Skip to content

Commit 202e252

Browse files
Someguy123Someguy123
committed
improved README with table of contents
1 parent 520fa36 commit 202e252

1 file changed

Lines changed: 182 additions & 11 deletions

File tree

‎README.md‎

Lines changed: 182 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -32,17 +32,168 @@ packaged, and so we've amalgamated them into this PyPi package, `privex-helpers`
3232
+===================================================+
3333
```
3434

35+
# Tl;Dr; Install and use Privex Helpers
36+
37+
Install from PyPi (detailed install info at [Install](#Install) and [Using package extras](#minimal-dependencies))
38+
39+
```sh
40+
pipenv install privex-helpers # If you use pipenv (and you should!)
41+
pip3 install privex-helpers # Otherwise, standard pip installation
42+
43+
# If you're using privex-helpers in a project, then you may want to install with the "full" extras
44+
# which installs all optional requirements (other than Django), so you can use **everything** in privex-helpers
45+
pipenv install 'privex-helpers[full]' # If you use pipenv (and you should!)
46+
pip3 install 'privex-helpers[full]' # Otherwise, standard pip installation
47+
```
48+
49+
Very import and basic usage (detailed examples at [Example Uses](#example-uses))
50+
51+
```python
52+
from privex.helpers import is_true, empty
53+
if is_true('yes'):
54+
print('yes is truthful')
55+
56+
if empty(''):
57+
print("'' is empty")
58+
```
59+
3560
# Table of Contents (Github README)
3661

37-
1. [Install](#Install)
38-
1.1 [Via PyPi (pip)](#download-and-install-from-pypi)
39-
1.2 [Manually via Git](#alternative-manual-install-from-git)
40-
2. [Documentation](#documentation)
41-
3. [License](#License)
42-
4. [Example Uses](#example-uses)
43-
5. [Minimal Dependencies / Using package extras](#minimal-dependencies)
44-
6. [Unit Tests](#unit-tests)
45-
7. [Contributing](#contributing)
62+
**NOTE:** The below Table of Contents is designed to work on Github. The links do NOT work on PyPi's description,
63+
and may not work if you're reading this README.md elsewhere.
64+
65+
66+
1. [Why use Privex Helpers?](#why-use-privex-helpers)
67+
68+
1.1. [Lightweight](#lightweight)
69+
70+
1.2. [Keeps your code DRY (Don't repeat yourself!)](#keeps-your-code-dry-dont-repeat-yourself)
71+
72+
1.3. [Makes your life just plain easier](#makes-your-life-just-plain-easier)
73+
74+
1.4. [Thorough unit tests](#thorough-unit-tests)
75+
76+
1.5. [Overview of what's included](#overview-of-whats-included)
77+
78+
2. [Install](#Install)
79+
80+
2.1 [Via PyPi (pip)](#download-and-install-from-pypi)
81+
82+
2.2 [Manually via Git](#alternative-manual-install-from-git)
83+
84+
3. [Documentation](#documentation)
85+
4. [License](#License)
86+
5. [Example Uses](#example-uses)
87+
6. [Minimal Dependencies / Using package extras](#minimal-dependencies)
88+
89+
6.1 [Modules with dependencies](#modules-with-dependencies)
90+
91+
6.2 [Using Setuptools Extras](#using-setuptools-extras)
92+
93+
7. [Unit Tests](#unit-tests)
94+
8. [Contributing](#contributing)
95+
96+
97+
# Why use Privex Helpers?
98+
99+
Privex helpers was created with a very simple goal in mind: make developing Python applications easy, fun, simple,
100+
and **painless**.
101+
102+
### Lightweight
103+
104+
Whether you're using it in a library, or in your project, you'll be pleased to know that the `privex-helpers` and
105+
all of it's *required dependencies* make up less than **200kb total**. For comparison, the `Django` package alone
106+
(that's excluding it's dependencies) is a whopping 26 MEGABYTES.
107+
108+
Most of `privex-helpers` can be used without any additional dependencies. Some modules, or parts of modules
109+
may require a certain dependency, but will cleanly disable themselves if the necessary dependency isn't available.
110+
111+
See [Modules with dependencies](#modules-with-dependencies) to see which modules only work if you have a certain
112+
package installed, and modules which are dependency-free but enable additional functionality if you install
113+
extra packages.
114+
115+
### Keeps your code DRY (Don't repeat yourself!)
116+
117+
Tired of writing those same long `if` statements to check if a user entered value was some sort-of boolean value?
118+
Use `is_true` and `is_false` - trim those long if statements into a single function call. Less typing, and more
119+
readable.
120+
121+
### Makes your life just plain easier
122+
123+
Writing a library and need caching? Not sure whether you should just force your users to use Redis, whether you
124+
should just make this a Django plugin, or write some sort-of rudimentary caching system yourself? `privex-helpers`
125+
includes a modular caching abstraction layer that Just Works™ out of the box, without forcing tons of dependencies on
126+
your users.
127+
128+
Maybe you just need to encrypt a string, or generate an RSA keypair. But you tried taking a look at the
129+
popular [cryptography](https://cryptography.io/en/latest/) package docs, and it looks like you're going to be writing
130+
scaffolding code for hours just to do that... Say hello to `privex.helpers.crypto` - whether you're dealing with
131+
symmetric or asymmetric encryption, it's just **one import line, a few lines of code and you're DONE.**
132+
133+
### Thorough unit tests
134+
135+
Included in the `tests/` folder, is a collection of over 70 individual unit tests, which is constantly
136+
having more unit tests added over time.
137+
138+
This project uses Travis for continuous integration (automatic testing with each commit), and CodeCov keeping
139+
track of how much of the codebase is covered by unit tests. See [Unit Tests](#unit-tests) for more details.
140+
141+
This ensures that `privex-helpers` is reliable and robust - if a part of the library is broken with a new update,
142+
then we'll be alerted shortly after pushing out the update that our tests are failing, so we can fix the issue ASAP.
143+
144+
### Overview of what's included
145+
146+
This is not an exhaustive list, and may sometimes be a little outdated. To see everything that's available in
147+
`privex-helpers` then check out the [Documentation](https://python-helpers.readthedocs.io/en/latest/index.html).
148+
149+
- `common` - a melting pot of functions and classes that will generally just make developing python code 100x easier,
150+
and make it 10x more readable. some of the most useful include:
151+
- `empty` - checking if a value is "empty", e.g. `None`, `''`, `0`, `'0'`, `[]` etc.
152+
- `is_true` - fuzzy "true" testing, checks for common forms of true, e.g. `True`, `"true"`, `"yes"`, `1`
153+
- `is_false` - fuzzy "false" testing, checks for common forms of false, e.g. `False`, `"false"`, `"no"`, `0`
154+
- `env_csv` - load an environment variable like a CSV, allowing for list representation in env vars
155+
- `env_keyval` - load an environment variable like a key value map, allowing for tuple pair / dict
156+
representation in env vars
157+
- `dec_round` - round a python `Decimal` using the built-in Quantize method, but without the hassle.
158+
- `Dictable` - easily create your Python 3.7 `dataclass` from a dictionary, plus enable them to be casted
159+
into a plain dict using `dict(mydataclass)`
160+
- and MORE, check the [documentation!](https://python-helpers.readthedocs.io/en/latest/helpers/privex.helpers.common.html)
161+
162+
- `cache` - a dependency-free, framework agnostic caching layer, with support for:
163+
- automatic timeouts
164+
- ability to extend the timeout of a cache item (even after it's already "expired" on some cache adapters)
165+
- get_or_set with callback function/method support
166+
- can optionally use Redis if you'd prefer (requires an optional dependency)
167+
168+
- `crypto` - classes which make both symmetric and asymmetric encryption extremely easy to use
169+
- `EncryptHelper` - for symmetric AES-128 encryption / decryption with a shared key, with the ability to generate
170+
either a secure random shared key, or a shared key generated from a password + salt
171+
- `KeyManager` - for asymmetric signing / verification, plus encryption/decryption if you use RSA. supports
172+
generating/loading RSA, ECDSA, and Ed25519 keys, as well as outputting them in a variety of formats
173+
and encodings.
174+
175+
- `setuppy` - a module with various functions to help with making python packages or dealing with
176+
requirements.txt files
177+
178+
- `decorators` - various decorators to simplify your code
179+
- `retry_on_err` - automatically re-run a function/method when exceptions are thrown, with a variety of
180+
customization available
181+
- `r_cache` - automatic caching of a function/property, with support for caching based on parameters or a lambda
182+
183+
- `net` - various networking functions, including:
184+
- handling IP addresses
185+
- generating reverse DNS records
186+
- looking up ASN names based on their number
187+
- checking if an IP is up (via ping) - with both IPv4 and IPv6 support
188+
189+
- `asyncx` - various async helper functions, to help synchronous code play nicely with async code
190+
- `django` various Django helper functions, most of which you'll probably question "why is this not built into django?"
191+
- `exceptions` - various exception classes, most of which are used by privex-helpers functions/classes, but can be
192+
used in any python project to save you re-inventing an exception name
193+
194+
195+
196+
46197

47198

48199
# Install
@@ -200,7 +351,9 @@ This package only requires (and automatically installs if needed) a single depen
200351
[privex-loghelper](https://github.com/Privex/python-loghelper) package, which itself is lightweight
201352
and dependency free.
202353

203-
As of version 1.6.0 - Privex Helpers now supports **Setuptools Extras**, allowing you
354+
### Using Setuptools Extras
355+
356+
As of version 2.0.0 - Privex Helpers now supports **Setuptools Extras**, allowing you
204357
to specify extra dependencies related to privex-helpers in your requirements.txt, or when running
205358
**pip3 install**.
206359

@@ -238,6 +391,22 @@ redis>=3.3.8
238391
cryptography>=2.8
239392
```
240393

394+
### Modules with dependencies
395+
396+
**Modules which require a dependency to use them**
397+
398+
- `crypto` - This module won't work at all without the `cryptography` library (or `privex-helpers[crypto]`)
399+
- `django` - Django related helpers obviously don't work without `Django` installed. But since they're intended
400+
for use within a Django project, you'd already have `Django` installed anyway if you needed them :)
401+
402+
**Dynamic modules which simply enable additional features if you install certain packages**
403+
404+
- `net` - Some functions are dependent on `dnspython` (or `privex-helpers[net]`), but the majority of the module
405+
is dependency-free
406+
- `cache` - The cache layer works just fine without any dependencies. If you're using `privex-helper` within a project,
407+
then you may want to install `redis` (or `privex-helpers[cache]`) to make the Redis cache adapter available.
408+
409+
241410
# Unit Tests
242411

243412
As of late October 2019, we have over 70 individual unit tests in the `tests/` folder, which are split into several
@@ -297,4 +466,6 @@ If you'd rather read the whole legal text, it should be included as `privex_cont
297466

298467
# Thanks for reading!
299468

300-
**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!)**
469+
**If this project has helped you, consider [grabbing a VPS or Dedicated Server from Privex](https://www.privex.io).**
470+
471+
**Prices start at as little as US$8/mo (we take cryptocurrency!)**

0 commit comments

Comments
 (0)