scooby-brew 1.0.1
A Python wrapper for the PunkAPI.
Requires Python: ==3.8.5
Keywords: PunkAPI

<div align="justify">

<img src="https://i.ibb.co/TDQ0PZN/logo.png" align="right" height=26% width=26% />

# scooby-brew


**A Python wrapper for the [PunkAPI](https://punkapi.com).**

>Have you ever wanted to search through Brewdog's expansive back catalogue of beer in a programmatic way? Maybe build a tool that pairs beer with food, or search beers with an abv of more than 4%? Well now your prayers have been answered! <br><br>
The Punk API takes Brewdog's DIY Dog and turns it into a searchable, filterable API that's completely free and open source.

</div>

## Installation

```python
pip install scooby-brew
```

## Usage

### Initialize

```python
client = ScoobyBrew()
```

### Get beers

```python
beers = client.get_beers()
# returns all the beers from the API

beers = client.get_beers(limit=35)
# returns the first 35 beers from the API
```
#### Options
- `limit` - Limits the number of beers returned to the number given.
- `page` - Which page to start retrieving beers from.
- `per_page` - How many beers to retrieve per page (max is 80).

You can also add parameters to the search as kwargs when calling `get_beers()`. To see which are supported, consult the documentation [here](https://punkapi.com/documentation/v2).

##### Pagination
Currently, the API results are limited a maximum of 80 per one page. If a greater number than this is requested, they will be returned on subsequent pages.



### Get a beer

```python
beer = client.get_beer(2)
# returns beer with id = 2 from the API
```

### Get a random beer

```python
random_beer = client.get_random_beer()
# returns a random beer from the API
```

### Accessing data
You can access the attributes of a beer by using the dot notation.
```python
beer = client.get_beer(1)

print(beer.name)
```

### CLI

After you install the library you can use scooby-brew in your terminal.

```bash
$ scooby-brew --help
usage: scooby-brew [-h] {get_beers,get_beer,get_random_beer} ...

positional arguments:
  {get_beers,get_beer,get_random_beer}
                        Availble options
    get_beers           Get some beers
    get_beer            Get one beer
    get_random_beer     Get a random beer

optional arguments:
  -h, --help            show this help message and exit
```

For seeing available arguments for the 3 options `get_beers, get_beer and get_random_beer` run:
```bash
$ scooby-brew [option] --help
```

This is how you would access one beer from the beer collection:
```bash
$ scooby-brew get_beers --limit 1
{'abv': 4.5,
 'attenuation_level': 75,
 'boil_volume': {'unit': 'litres', 'value': 25},
 'brewers_tips': 'The earthy and floral aromas from the hops can be '
                 'overpowering. Drop a little Cascade in at the end of the '
                 'boil to lift the profile with a bit of citrus.',
 'contributed_by': 'Sam Mason <samjbmason>',
 'description': 'A light, crisp and bitter IPA brewed with English and '
                'American hops. A small batch brewed only once.',
 'ebc': 20,
 ...
}

```


## Contributing

Make sure you have [Poetry](https://python-poetry.org/docs/) installed and simply run the following command:

```bash
$ poetry install -v
```
And afterwards:
```bash
$ poetry run pre-commit install
```