qr-code-generator-api 0.1.2
Python wrapper for qr-code-generator.com API
Requires Python: >=3.6

# python-qr-code-generator-api
A simple Python wrapper for the API of qr-code-generator.com, which is used to generate QR codes with certain design elements.

## Why this API wrapper?
First of all, because I needed it and also because this API is not really [well documented](https://www.qr-code-generator.com/qr-code-api/). This wrapper provides a quick and easy way to connect to the API and request images, with a minimal amount of coding or effort. Just import the module, write a couple lines of easily understandable code and start generating these amazing QR codes.

## Table of Contents
  * [Features](#features)
    + [Configure to fit your own needs](#configure-to-fit-your-own-needs)
    + [Change all possible QR code options](#change-all-possible-qr-code-options)
    + [Automatically save QR codes](#automatically-save-qr-codes)
  * [Usage](#usage)
    + [Command Line Interface](#command-line-interface)
      - [CLI Example](#cli-example)
    + [Use it in your own code](#use-it-in-your-own-code)
      - [Example of using it in your own code](#example-of-using-it-in-your-own-code)
  * [Authentication](#authentication)
    + [Environment variables](#environment-variables)
    + [Hardcoded in your own code](#hardcoded-in-your-own-code)
  * [Presets](#presets)
    + [The easiest code](#the-easiest-code)
  * [Limitations](#limitations)
  
## Features
### Configure to fit your own needs
While we have the wrapper set up in a way that allows for quick usage of the API, we understand that sometimes you just need it to test an absurd scenario or that you want to change output folders. With the configuration file, you are the boss. Even better: you don't necessarily have to change the configuration file to work for you. If you want, you can just use code to update configuration variables and run a request. This way, your configuration is limited to your own code.

### Change all possible QR code options
This wrapper provides an easy way to update QR options. Just set the dictionary variable to a new value, and it will automatically be taken into account when generating a code.

### Automatically save QR codes
The wrapper takes the API response and automatically turns it into a saved image in the desired output location. Do we need to say more?

## Usage
The wrapper was developed with ease of use in mind. This means that one can either, directly call the module to perform a request, or code their own Python scripts and import the module.

### Command Line Interface
To perform a request via the command line, simply ```$ python3 qr_code_generator``` with flags to specify your needs. The following flags are supported: 
* --token {api access token here} (short: -t)
* --load {path to yaml file to load settings from} (short: -l)
* --output {name for output file} (short: -o)
* --bulk {amount to bulk generate} (short: -b)
* --verbose (short -v)

#### CLI Example
The following code will request 5 QR-codes for token ```apijob```, with name: ```test-qr-<number>``` and load a configuration file called ```config.yaml```. It will also log all events:
```
$ python3 qr_code_generator --token apijob --output test-qr --bulk 5 --load config.yaml --verbose
```

### Use it in your own code
To use the api and its settings in your code, import it with:
```from qr_code_generator import QrGenerator```
Then create an instance of QrGenerator:
```api = QrGenerator()```
Adjust settings as you like by altering ```api.settings``` and ```api.options```, and call ```api.request()``` to request a QR code be generated by api.

#### Example of using it in your own code
The following code will request a QR-code for token ```apijob```, with name: ```test-qr```, but before that it will load a configuration file called ```config.yaml```. It will also make sure to log all events:
```python
from qr_code_generator import QrGenerator

api = QrGenerator('apijob')
api.load('config.yaml')
api.config['VERBOSE'] = True
api.output_filename = 'test-qr'
api.request()
```

## Authentication
There are three possible ways to authenticate with the API. Authentication is done on a token basis. A token can be generated [on this webpage](https://app.qr-code-generator.com/api/). The three ways are (based from most safe to least safe, and thus least preferred):

### Environment variables
The safest way to authenticate, is by using environment variables. This starts by exporting your access key to an environment variable with ```$ export ACCESS_TOKEN=<your token here>```. After this, feel free to create an instance of QrGenerator by just calling the class as ```api = QrGenerator()```. The token will automatically be fetched from the environment.

### Hardcoded in your own code
A little bit less safe, because what if you accidentally commit your code with the token in it, or what if someone finds a readable portion of your code? If you choose to go down this route, understand that there are certain risks involved, but it can be done. There are two ways to put the token in your own code.
1. Either make sure you call the QrGenerator class with a token parameter, as such: ```api = QrGenerator(<your token here>)```. This will fetch the token from your code and add it to the query.
2. Or set it later in your code, by using the set function: ```QrGenerator.set('access-token', <your token here>)```.

When ```QrGenerator.request()``` is called and the API token has not been set and the configuration file has not been altered, a custom Exception will be thrown: ```MissingRequiredParameterError```. This is because the API will directly return an InvalidCredentialsError regardless. If the configuration file has been changed, you might encounter a ```InvalidCredentialsError```. Either way, it will not work.

## Presets
Not everyone loves coding. We are currently moving more and more to a world in which nocode is the standard for big groups of people, there is a way to load settings from a yaml file to the api, without you having to do any coding. Copy the settings-template.yaml template in /templates/ to your main directory and make the necessary changes. You can change both values for options and config. They will be automatically loaded and generation will take place.
> You can load with the load flag (described above), but you can also call api.load(filename.yaml) to load it in your own code. This will even further reduce the amount of Python necessary to generate a QR code.

### The easiest code
```python
from qr_code_generator import QrGenerator

api = QrGenerator()
api.load(file.yaml)
api.request()
```

## Limitations
It is currently not possible to generate bulk qr-codes in your own code, without creating your own loop. This is by design, since we want to give all users the opportunity to do with bulk generation what they wish to do. The simplest way to request 5 codes would be:
```python
from qr_code_generator import QrGenerator

api = QrGenerator()
file = 'output-filename'
for i in range(1, 6):
    api.output_filename = f'{file}-{i}'
    api.request()
```