Skip to content

Commit

Permalink
Merge pull request #395 from yozachar/workshop
Browse files Browse the repository at this point in the history
docs: adds configuration info
  • Loading branch information
yozachar authored Aug 1, 2024
2 parents 0c41b9f + cce1d9a commit 96e141b
Show file tree
Hide file tree
Showing 10 changed files with 190 additions and 145 deletions.
2 changes: 1 addition & 1 deletion docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ Resources
:caption: Quick Start:
:glob:

install_and_use
install_config_use

.. toctree::
:hidden:
Expand Down
43 changes: 0 additions & 43 deletions docs/install_and_use.md

This file was deleted.

50 changes: 0 additions & 50 deletions docs/install_and_use.rst

This file was deleted.

60 changes: 60 additions & 0 deletions docs/install_config_use.md
Original file line number Diff line number Diff line change
@@ -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`
75 changes: 75 additions & 0 deletions docs/install_config_use.rst
Original file line number Diff line number Diff line change
@@ -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``
4 changes: 2 additions & 2 deletions mkdocs.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -66,8 +66,8 @@ extra:
copyright: Copyright &copy; 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
Expand Down
6 changes: 3 additions & 3 deletions package/export/__main__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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("’", "'")
)
Expand Down
17 changes: 9 additions & 8 deletions package/requirements.sphinx.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 \
Expand All @@ -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
Expand Down
17 changes: 9 additions & 8 deletions package/requirements.testing.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 \
Expand All @@ -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
Loading

0 comments on commit 96e141b

Please sign in to comment.