plaw 0.1.2
A simple wrapper for the Lightspeed API
Keywords: Lightspeed, API, Wrapper

# PLAW - Python Lightspeed API Wrapper

This module provides a pythonic interface to the Lightspeed API.

This is an incomplete project - I'm building another tool that depends on the Lightspeed API so I built this little wrapper to make it easier.

I've only implemented interfaces to the endpoints I'm using - ```Account```, ```Shop```, ```Employee```, and ```EmployeeHours```. It's possible I'll come back later and implement more, but not guaranteed.

I'd accept any contribution with open arms - just do me a favor and make sure you add tests. 
## Installation
```pip install plaw```

## Usage
The ```Plaw``` class contains all attributes and methods necessary to interact with the API. Most users would probably instantiate a new object like so:
```
>>> from plaw import Plaw

>>> client_id = # your client id from lightspeed
>>> client_secret = # your client secret from lightspeed

>>> api = Plaw(client_id, client_secret)
```
To make any real use of the API, you need to get a temp access code from Lightspeed in order to receive an access and refresh token. The temp code expires after 30 seconds, so it's likely this would take place in e.g. a Django view - but regardless:
```
>>> code = # temp access code
>>> api.get_tokens(code)
>>> api.fetch_account_id()
``` 
Once you have this information you can make requests through the interfaces. 
### Pagination
Pagination is sort of built-in to the interface. These interfaces are going to return a generator object, with each item in the generator being a page of results from your query. This makes requesting the next page of results very simple:
```
>>> all_employee_hours = api.employee_hours()
>>> next(all_employee_hours) # first page
{
    "@attributes": {
        "count": "4252",
        "offset": "0",
        "limit": "100"
    },
    "EmployeeHours": [
        {
            "employeeHoursID": "2",
            "checkIn": "2014-02-19T23:08:08+00:00",
            "checkOut": "2014-02-19T23:08:22+00:00",
            "employeeID": "4",
            "shopID": "1"
        },
    ...

>>> next(all_employee_hours) # second page
{
    "@attributes": {
        "count": "4252",
        "offset": "100",
        "limit": "100"
    },
    "EmployeeHours": [
        {
            "employeeHoursID": "202",
            "checkIn": "2014-05-24T16:40:00+00:00",
            "checkOut": "2014-05-25T00:10:27+00:00",
            "employeeID": "2",
            "shopID": "1"
        },
    ...
```
etc.
### Parameters
Each interface takes an optional ```params``` argument that expects a dictionary of query string parameters.
```
>>> params = {
...   'shopID': '1'
... }

>>> ny_store = api.shop(params)
>>> next(ny_store)
{
    "@attributes": {
        "count": "1",
        "offset": "0",
        "limit": "100"
    },
    "Shop": {
        "shopID": "1",
        "name": "New York Storefront",
    ...
```
### Timestamps
Pass in all timestamps as datetime objects - this library will convert them to iso format for you. 
The Lightspeed API actually accepts timezone encoded timestamps, but will always return UTC. 
### Query Operators
The default operator for any query is '=', but you can specify others to make your searches more powerful. If your intention is the = operator, just put the value in the params dict like the Parameters section above. If you'd like to make use of other operators, put the operators in a list with the values you're operating on, like so:
```
>>> from datetime import datetime
>>> import pytz

>>> jan_first = pytz.timezone('America/Boise').localize(datetime(2021, 1, 1), is_dst=None)
>>> feb_first = pytz.timezone('America/Boise').localize(datetime(2021, 2, 1), is_dst=None)

>>> params = {
...     'checkIn': ['><', jan_first, feb_first]
... }

>>> all_january_shifts = api.employee_hours(params)
>>> next(all_january_shifts)
{
    "@attributes": {
        "count": "116",
        "offset": "0",
        "limit": "100"
    },
    "EmployeeHours": [
        {
            "employeeHoursID": "4453",
            "checkIn": "2021-01-02T16:31:30+00:00",
            "checkOut": "2021-01-02T23:53:41+00:00",
            "employeeID": "55",
            "shopID": "1"
        },
    ...
```
### Relations
You're always welcome to load relations manually in your params. The ```Employee``` endpoint has an option ```load_contact``` that, when True, loads the Contact relation.