diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md new file mode 100644 index 0000000..86ce19e --- /dev/null +++ b/CONTRIBUTE.md @@ -0,0 +1,25 @@ +## Development + +Some development notes + +### Coding style guidelines + +The configurations in [.editorconfig](./.editorconfig) and some in [pyproject.toml](./pyptoject.toml) are put in place in order to format and check compliance with [PEP 8](https://pep8.org) (with some exceptions). + +[.pre-commit-config.yaml](./.pre-commit-config.yaml) defines a set of hooks to be executed right before each commit so that [ruff](https://docs.astral.sh/ruff/) (a blazingly fast linter and formatter) is called on the changes made. + +This project uses [`uv`](https://docs.astral.sh/uv/) as package and project manager. To set it up: + +1. Create a virtual environment and install the packages: + ```shell + uv sync + ``` +2. Install the hooks running: + ```shell + uvx pre-commit install + ``` +3. Now on every `git commit` the `pre-commit` hook (inside `.git/hooks/`) will be run. + +#### Configuring your editor + +To configure your code editor [read `ruff`'s documentation about it](https://docs.astral.sh/ruff/editors/). diff --git a/README.md b/README.md index c9843a6..14a285b 100644 --- a/README.md +++ b/README.md @@ -2,28 +2,58 @@ SDK to communicate with Virtual Queue's API in Python projects. -## Development - -Some development notes - -### Coding style guidelines - -The configurations in [.editorconfig](./.editorconfig) and some in [pyproject.toml](./pyptoject.toml) are put in place in order to format and check compliance with [PEP 8](https://pep8.org) (with some exceptions). - -[.pre-commit-config.yaml](./.pre-commit-config.yaml) defines a set of hooks to be executed right before each commit so that [ruff](https://docs.astral.sh/ruff/) (a blazingly fast linter and formatter) is called on the changes made. - -This project uses [`uv`](https://docs.astral.sh/uv/) as package and project manager. To set it up: - -1. Create a virtual environment and install the packages: - ```shell - uv sync - ``` -2. Install the hooks running: - ```shell - uvx pre-commit install - ``` -3. Now on every `git commit` the `pre-commit` hook (inside `.git/hooks/`) will be run. - -#### Configuring your editor - -To configure your code editor [read `ruff`'s documentation about it](https://docs.astral.sh/ruff/editors/). +## How to use + +> [!NOTE] +> See [`examples/`](./examples/) for more + +You can verify the token with `TokenVerifier` like this: + +```python +from vqueue import TokenVerifier +from vqueue.exceptions import VQueueApiError, VQueueError, VQueueNetworkError + + +def your_function_or_handler(): + # Get the token from the request in your system + token = str(uuid4()) # This is an example UUIDv4 + + # This handles the connections with a session and can be reused + # for better performance + verifier = TokenVerifier() + + try: + # Handle the happy path + verified_result = verifier.verify_token(token) + print("The token was successfuly verified:", verified_result) + except ValueError as ve: + # Then handle the possible errors + # Of course, you should handle the exceptions with more grace than this + print("The token is not valir UUID", ve) + except VQueueNetworkError as ne: + print("Network error", ne) + except VQueueApiError as ae: + print("The API returned an error status", ae) + except VQueueError as vqe: + print("A generic error with the Virtual Queue system or this SDK", vqe) +``` + +You can also wrap your code in a context managed `with` block: + +```python + with TokenVerifier() as verfifier: + try: + # Handle the happy path + verified_result = verifier.verify_token(token) + print("The token was successfuly verified:", verified_result) + except ValueError as ve: + # Then handle the possible errors + # Of course, you should handle the exceptions with more grace than this + print("The token is not valir UUID", ve) + except VQueueNetworkError as ne: + print("Network error", ne) + except VQueueApiError as ae: + print("The API returned an error status", ae) + except VQueueError as vqe: + print("A generic error with the Virtual Queue system or this SDK", vqe) +``` diff --git a/examples/verify-token.py b/examples/verify-token.py new file mode 100644 index 0000000..3ba77fb --- /dev/null +++ b/examples/verify-token.py @@ -0,0 +1,32 @@ +from uuid import uuid4 + +from vqueue import TokenVerifier +from vqueue.exceptions import VQueueApiError, VQueueError, VQueueNetworkError + + +def your_function_or_handler(): + # Get the token from the request in your system + token = str(uuid4()) # This is an example UUIDv4 + + # This handles the connections with a session and can be reused + # for better performance + verifier = TokenVerifier() + + try: + # Handle the happy path + verified_result = verifier.verify_token(token) + print("The token was successfuly verified:", verified_result) + except ValueError as ve: + # Then handle the possible errors + # Of course, you should handle the exceptions with more grace than this + print("The token is not valir UUID", ve) + except VQueueNetworkError as ne: + print("Network error", ne) + except VQueueApiError as ae: + print("The API returned an error status", ae) + except VQueueError as vqe: + print("A generic error with the Virtual Queue system or this SDK", vqe) + + +if __name__ == "__main__": + your_function_or_handler() diff --git a/src/vqueue/queues.py b/src/vqueue/queues.py index 996e115..459ddcc 100644 --- a/src/vqueue/queues.py +++ b/src/vqueue/queues.py @@ -1,4 +1,4 @@ -from pathlib import Path +from urllib.parse import urljoin import requests @@ -7,8 +7,8 @@ from .types import VerificationResult, VerificationResultData from .utils import validate_uuidv4 -QUEUES_API_URL = Path(API_BASE_PATH).joinpath("queue/") -VERIFY_API_URL = QUEUES_API_URL.joinpath("verify") +QUEUES_API_URL = urljoin(API_BASE_PATH, "queue/") +VERIFY_API_URL = urljoin(QUEUES_API_URL, "verify") class TokenVerifier: @@ -75,7 +75,7 @@ def verify_token(self, token: str) -> VerificationResult: raise VQueueApiError( response.status_code, - response_data["message"], - response_data["error_code"], - response_data["data"], + response_data.get("message"), + response_data.get("error_code"), + response_data.get("data"), )