docs: adds configuration info

docs/index.rst

@@ -71,7 +71,7 @@ Resources
    :caption: Quick Start:
    :glob:
 
-   install_and_use
+   install_config_use
 
 .. toctree::
    :hidden:

docs/install_config_use.md

@@ -0,0 +1,60 @@
+# Install, Configure and Use
+
+## Installation
+
+Execute the following command:
+
+```console
+pip install validators
+```
+
+> It's preferable to use `pip` within a virtual environment.
+
+---
+
+## Usage
+
+```python
+from validators import email
+print(email('someone@example.com'))
+```
+
+```python
+# Output
+# True
+```
+
+---
+
+## Configuration
+
+`validators` employs environment variables prefixed with `PYVLD_` for it's configuration. You can set environment variables as:
+
+```sh
+# bash/zsh/ksh
+export PYVLD_CONFIG=VALUE
+
+# fish
+set PYVLD_CONFIG VALUE
+```
+
+```pwsh
+# pwsh
+[Environment]::SetEnvironmentVariable("PYVLD_CONFIG", "VALUE", "Machine")
+```
+
+Currently, the following configuration options are available:
+
+### **`PYVLD_RAISE_ERROR`**
+
+- **Reason**: Causes the library to raise [`ValidationError`](/pyvalidators/api/utils/#validators.utils.ValidationError) instead of returning it.
+- **Default**: Unset
+- **Possible values**: `True`, `False`
+
+> Note: [`ValidationError`](/pyvalidators/api/utils/#validators.utils.ValidationError) can also be raised by passing `r_ve=True` to the caller function.
+
+### **`PYVLD_CACHE_TLD`**
+
+- **Reason**: Caches TLD list to speedup lookup.
+- **Default**: Unset
+- **Possible values**: `True`, `False`

docs/install_config_use.rst

@@ -0,0 +1,75 @@
+Install, Configure and Use
+==========================
+
+Installation
+------------
+
+Execute the following command:
+
+.. code:: console
+
+   pip install validators
+
+..
+
+   It's preferable to use ``pip`` within a virtual environment.
+
+--------------
+
+Usage
+-----
+
+.. code:: python
+
+   from validators import email
+   print(email('someone@example.com'))
+
+.. code:: python
+
+   # Output
+   # True
+
+--------------
+
+Configuration
+-------------
+
+``validators`` uses environment variables prefixed with ``PYVLD_`` for
+it's configuration. You can set environment variables as:
+
+.. code:: sh
+
+   # bash/zsh/ksh
+   export PYVLD_CONFIG=VALUE
+
+   # fish
+   set PYVLD_CONFIG VALUE
+
+.. code:: pwsh
+
+   # pwsh
+   [Environment]::SetEnvironmentVariable("PYVLD_CONFIG", "VALUE", "Machine")
+
+Currently, the following configuration options are available:
+
+**``PYVLD_RAISE_ERROR``**
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-  **Reason**: Causes the library to raise
+   ```ValidationError`` </pyvalidators/api/utils/#validators.utils.ValidationError>`__
+   instead of returning it.
+-  **Default**: Unset
+-  **Possible values**: ``True``, ``False``
+
+..
+
+   Note:
+   ```ValidationError`` </pyvalidators/api/utils/#validators.utils.ValidationError>`__
+   can also be raised by passing ``r_ve=True`` to the caller function.
+
+**``PYVLD_CACHE_TLD``**
+~~~~~~~~~~~~~~~~~~~~~~~
+
+-  **Reason**: Caches TLD list to speedup lookup.
+-  **Default**: Unset
+-  **Possible values**: ``True``, ``False``

mkdocs.yaml

@@ -66,8 +66,8 @@ extra:
 copyright: Copyright © 2013 - 2024 Konsta Vesterinen
 
 nav:
-  - Home: index.md
-  - Install and Use: install_and_use.md
+  - Quick Start: index.md
+  - Install, Configure and Use: install_config_use.md
   - API:
       - api/between.md
       - api/crypto_addresses.md

package/export/__main__.py

@@ -73,7 +73,7 @@ def _gen_rst_docs(source: Path, refs_path: Path, only_web: bool = False, only_ma
             + "\n   :maxdepth: 2"
             + "\n   :caption: Quick Start:"
             + "\n   :glob:\n"
-            + "\n   install_and_use"
+            + "\n   install_config_use"
             + "\n\n.. toctree::"
             + "\n   :hidden:"
             + "\n   :maxdepth: 2"
@@ -82,9 +82,9 @@ def _gen_rst_docs(source: Path, refs_path: Path, only_web: bool = False, only_ma
             + "\n   api/*\n"
         )
 
-    with open(source / "docs/install_and_use.rst", "wt") as iau_f:
+    with open(source / "docs/install_config_use.rst", "wt") as iau_f:
         iau_f.write(
-            convert_file(source_file=source / "docs/install_and_use.md", format="md", to="rst")
+            convert_file(source_file=source / "docs/install_config_use.md", format="md", to="rst")
             .replace("\r\n", "\n")  # remove carriage return in windows
             .replace("’", "'")
         )

package/requirements.sphinx.txt

@@ -97,21 +97,24 @@ colorama==0.4.6 \
 docutils==0.20.1 \
     --hash=sha256:96f387a2c5562db4476f09f13bbab2192e764cac08ebbf3a34a95d9b1e4a59d6 \
     --hash=sha256:f08a4e276c3a1583a86dce3e34aba3fe04d02bba2dd51ed16106244e8a923e3b
+eth-hash==0.7.0 \
+    --hash=sha256:b8d5a230a2b251f4a291e3164a23a14057c4a6de4b0aa4a16fa4dc9161b57e2f \
+    --hash=sha256:bacdc705bfd85dadd055ecd35fd1b4f846b671add101427e089a4ca2e8db310a
 eth-hash[pycryptodome]==0.7.0 \
     --hash=sha256:b8d5a230a2b251f4a291e3164a23a14057c4a6de4b0aa4a16fa4dc9161b57e2f \
     --hash=sha256:bacdc705bfd85dadd055ecd35fd1b4f846b671add101427e089a4ca2e8db310a
-furo==2024.5.6 \
-    --hash=sha256:490a00d08c0a37ecc90de03ae9227e8eb5d6f7f750edf9807f398a2bdf2358de \
-    --hash=sha256:81f205a6605ebccbb883350432b4831c0196dd3d1bc92f61e1f459045b3d2b0b
+furo==2024.7.18 \
+    --hash=sha256:37b08c5fccc95d46d8712c8be97acd46043963895edde05b0f4f135d58325c83 \
+    --hash=sha256:b192c7c1f59805494c8ed606d9375fdac6e6ba8178e747e72bc116745fb7e13f
 idna==3.7 \
     --hash=sha256:028ff3aadf0609c1fd278d8ea3089299412a7a8b9bd005dd08b9f8285bcb5cfc \
     --hash=sha256:82fee1fc78add43492d3a1898bfa6d8a904cc97d8427f683ed8e798d07761aa0
 imagesize==1.4.1 \
     --hash=sha256:0d8d18d08f840c19d0ee7ca1fd82490fdc3729b7ac93f49870406ddde8ef8d8b \
     --hash=sha256:69150444affb9cb0d5cc5a92b3676f0b2fb7cd9ae39e947a5e11a36b4497cd4a
-importlib-metadata==8.0.0 \
-    --hash=sha256:15584cf2b1bf449d98ff8a6ff1abef57bf20f3ac6454f431736cd3e660921b2f \
-    --hash=sha256:188bd24e4c346d3f0a933f275c2fec67050326a856b9a359881d7c2a697e8812
+importlib-metadata==8.2.0 \
+    --hash=sha256:11901fa0c2f97919b288679932bb64febaeacf289d18ac84dd68cb2e74213369 \
+    --hash=sha256:72e8d4399996132204f9a16dcc751af254a48f8d1b20b9ff0f98d4a8f901e73d
 jinja2==3.1.4 \
     --hash=sha256:4a3aee7acbbe7303aede8e9648d13b8bf88a429282aa6122a993f0ac800cb369 \
     --hash=sha256:bc5dd2abb727a5319567b7a813e6a2e7318c39f4f487cfe6c89c6f9c7d25197d
@@ -187,7 +190,6 @@ pycryptodome==3.20.0 \
     --hash=sha256:210ba1b647837bfc42dd5a813cdecb5b86193ae11a3f5d972b9a0ae2c7e9e4b4 \
     --hash=sha256:2ab6ab0cb755154ad14e507d1df72de9897e99fd2d4922851a276ccc14f4f1a5 \
     --hash=sha256:405002eafad114a2f9a930f5db65feef7b53c4784495dd8758069b89baf68eab \
-    --hash=sha256:4401564ebf37dfde45d096974c7a159b52eeabd9969135f0426907db367a652a \
     --hash=sha256:49a4c4dc60b78ec41d2afa392491d788c2e06edf48580fbfb0dd0f828af49d25 \
     --hash=sha256:6e0e4a987d38cfc2e71b4a1b591bae4891eeabe5fa0f56154f576e26287bfdea \
     --hash=sha256:76658f0d942051d12a9bd08ca1b6b34fd762a8ee4240984f7c06ddfb55eaf15a \
@@ -200,7 +202,6 @@ pycryptodome==3.20.0 \
     --hash=sha256:acc2614e2e5346a4a4eab6e199203034924313626f9620b7b4b38e9ad74b7e0c \
     --hash=sha256:acf6e43fa75aca2d33e93409f2dafe386fe051818ee79ee8a3e21de9caa2ac9e \
     --hash=sha256:c18b381553638414b38705f07d1ef0a7cf301bc78a5f9bc17a957eb19446834b \
-    --hash=sha256:ec1f93feb3bb93380ab0ebf8b859e8e5678c0f010d2d78367cf6bc30bfeb148e \
     --hash=sha256:f35d6cee81fa145333137009d9c8ba90951d7d77b67c79cbe5f03c7eb74d8fe2 \
     --hash=sha256:f47888542a0633baff535a04726948e876bf1ed880fddb7c10a736fa99146ab3 \
     --hash=sha256:fb3b87461fa35afa19c971b0a2b7456a7b1db7b4eba9a8424666104925b78128

package/requirements.testing.txt

@@ -4,12 +4,15 @@
 colorama==0.4.6 \
     --hash=sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44 \
     --hash=sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6
+eth-hash==0.7.0 \
+    --hash=sha256:b8d5a230a2b251f4a291e3164a23a14057c4a6de4b0aa4a16fa4dc9161b57e2f \
+    --hash=sha256:bacdc705bfd85dadd055ecd35fd1b4f846b671add101427e089a4ca2e8db310a
 eth-hash[pycryptodome]==0.7.0 \
     --hash=sha256:b8d5a230a2b251f4a291e3164a23a14057c4a6de4b0aa4a16fa4dc9161b57e2f \
     --hash=sha256:bacdc705bfd85dadd055ecd35fd1b4f846b671add101427e089a4ca2e8db310a
-exceptiongroup==1.2.1; python_version < "3.11" \
-    --hash=sha256:5258b9ed329c5bbdd31a309f53cbfb0b155341807f6ff7606a1e801a891b29ad \
-    --hash=sha256:a4785e48b045528f5bfe627b6ad554ff32def154f42372786903b7abcfe1aa16
+exceptiongroup==1.2.2; python_version < "3.11" \
+    --hash=sha256:3111b9d131c238bec2f8f516e123e14ba243563fb135d3fe885990585aa7795b \
+    --hash=sha256:47c2edf7c6738fafb49fd34290706d1a1a2f4d1c6df275526b62cbb4aa5393cc
 iniconfig==2.0.0 \
     --hash=sha256:2d91e135bf72d31a410b17c16da610a82cb55f6b0477d1a902134b24a455b8b3 \
     --hash=sha256:b6a85871a79d2e3b22d2d1b94ac2824226a63c6b741c88f7ae975f18b6778374
@@ -24,7 +27,6 @@ pycryptodome==3.20.0 \
     --hash=sha256:210ba1b647837bfc42dd5a813cdecb5b86193ae11a3f5d972b9a0ae2c7e9e4b4 \
     --hash=sha256:2ab6ab0cb755154ad14e507d1df72de9897e99fd2d4922851a276ccc14f4f1a5 \
     --hash=sha256:405002eafad114a2f9a930f5db65feef7b53c4784495dd8758069b89baf68eab \
-    --hash=sha256:4401564ebf37dfde45d096974c7a159b52eeabd9969135f0426907db367a652a \
     --hash=sha256:49a4c4dc60b78ec41d2afa392491d788c2e06edf48580fbfb0dd0f828af49d25 \
     --hash=sha256:6e0e4a987d38cfc2e71b4a1b591bae4891eeabe5fa0f56154f576e26287bfdea \
     --hash=sha256:76658f0d942051d12a9bd08ca1b6b34fd762a8ee4240984f7c06ddfb55eaf15a \
@@ -37,13 +39,12 @@ pycryptodome==3.20.0 \
     --hash=sha256:acc2614e2e5346a4a4eab6e199203034924313626f9620b7b4b38e9ad74b7e0c \
     --hash=sha256:acf6e43fa75aca2d33e93409f2dafe386fe051818ee79ee8a3e21de9caa2ac9e \
     --hash=sha256:c18b381553638414b38705f07d1ef0a7cf301bc78a5f9bc17a957eb19446834b \
-    --hash=sha256:ec1f93feb3bb93380ab0ebf8b859e8e5678c0f010d2d78367cf6bc30bfeb148e \
     --hash=sha256:f35d6cee81fa145333137009d9c8ba90951d7d77b67c79cbe5f03c7eb74d8fe2 \
     --hash=sha256:f47888542a0633baff535a04726948e876bf1ed880fddb7c10a736fa99146ab3 \
     --hash=sha256:fb3b87461fa35afa19c971b0a2b7456a7b1db7b4eba9a8424666104925b78128
-pytest==8.2.2 \
-    --hash=sha256:c434598117762e2bd304e526244f67bf66bbd7b5d6cf22138be51ff661980343 \
-    --hash=sha256:de4bb8104e201939ccdc688b27a89a7be2079b22e2bd2b07f806b6ba71117977
+pytest==8.3.2 \
+    --hash=sha256:4ba08f9ae7dcf84ded419494d229b48d0903ea6407b030eaec46df5e6a73bba5 \
+    --hash=sha256:c132345d12ce551242c87269de812483f5bcc87cdbb4722e48487ba194f9fdce
 tomli==2.0.1; python_version < "3.11" \
     --hash=sha256:939de3e7a6161af0c887ef91b7d41a53e7c5a1ca976325f429cb46ea9bc30ecc \
     --hash=sha256:de526c12914f0c550d15924c62d72abc48d6fe7364aa87328337a31007fe8a4f