Metadata-Version: 2.1
Name: pysh-client
Version: 0.1.1
Summary: A phish.net API wrapper in Python.
Author-email: Yuval Boss <yuval@yuvalboss.com>
Maintainer-email: Yuval Boss <yuval@yuvalboss.com>
License: Copyright (c) 2012-2024 Scott Chacon and others
        
        Permission is hereby granted, free of charge, to any person obtaining
        a copy of this software and associated documentation files (the
        "Software"), to deal in the Software without restriction, including
        without limitation the rights to use, copy, modify, merge, publish,
        distribute, sublicense, and/or sell copies of the Software, and to
        permit persons to whom the Software is furnished to do so, subject to
        the following conditions:
        
        The above copyright notice and this permission notice shall be
        included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
        EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
        NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
        LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
        OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
        WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Project-URL: Homepage, https://github.com/readicculus/pysh
Project-URL: Repository, https://github.com/readicculus/pysh
Project-URL: Changelog, https://github.com/readicculus/pysh/blob/main/CHANGELOG.md
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.0.0
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy<1.5,>=1.0; extra == "dev"
Requires-Dist: black<24.0,>=23.0; extra == "dev"
Requires-Dist: isort<5.13,>=5.12; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-sphinx; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: twine>=1.11.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: setuptools; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Requires-Dist: Sphinx<7.1.0,>=4.3.0; extra == "dev"
Requires-Dist: furo==2023.7.26; extra == "dev"
Requires-Dist: myst-parser<2.1,>=1.0; extra == "dev"
Requires-Dist: sphinx-copybutton==0.5.2; extra == "dev"
Requires-Dist: sphinx-autobuild==2021.3.14; extra == "dev"
Requires-Dist: sphinx-autodoc-typehints==1.23.3; extra == "dev"
Requires-Dist: packaging; extra == "dev"


# Pysh - a phish.net API client in Python
![](https://github.com/readicculus/pysh/actions/workflows/main.yml/badge.svg)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

Pysh is a Python wrapper for the [phish.net](phish.net) API that can be used to query for Phish songs, 
setlists, shows, venues, and other phish related data.  This project is not associated with phish.net and you must 
follow their API's terms of service while using this project.

This wraps the API described in the [phish.net API v5 Docs](https://docs.phish.net/).
## Installation
This package is available on pypi [pysh-client](https://pypi.org/project/pysh-client/) and can be installed by running:
```bash
pip install pysh-client
```

## Requirements
#### API Key
You will need to setup an API key which requires you have a phish.net account.  
This library gets the key from the `PHISH_API_KEY` environment variable.  
Once you have your API key run the following before you can use this library.
```bash
export PHISH_API_KEY=xxx
```
You can alternatively pass the API key to the client when constructing it like this:
```python
from pysh import Client
c = Client(apikey="xxx")
```


## Usage 
#### Filtering
There are a few ways to filter in your query calls.  Filtering is optional.
1. You can filter by id, for example if trying to get a show by the show id you can specify `get_shows(id=123)`
2. OR, you can filter by a category and value, the category being one of the attributes in the schema of that method. For 
example `get_shows(column='showyear', value='1995')` which returns all shows in 1995.

#### Additional Parameters
There are additional parameters you can define for all client methods defined by the `Parameters` class that allows you to 
define the following optional parameters if desired:
1. `order_by`: name of column to sort by
2. `direction`: direction to sort, either asc or desc (default asc)
3. `limit`: number, maximum number of results to return
4. `no_header`: if requesting data in HTML format, the argument _noheader will suppress the Phish.net banner
5. `callback`: if requesting data in JSON format, sending a callback will wrap the resulting JSON file in a callback function call
```python
from pysh import Parameters, Client
c = Client()
c.get_shows(parameters=Parameters(order_by='showdate', direction='desc'))
```
You can read more about each of these parameters in the [Parameters Docs](https://docs.phish.net/#parameters)

## Examples

**Get all shows**
```python
c.get_shows()
```

**Get a Show by Year**
```python
c.get_shows(column="showyear", value="2020")
```

**Get a song by name**
```python
c.get_songs(column="slug", value="bug")
```

**Get a setlist for a show by date**
```python
c.get_setlists(column="showdate", value="1984-10-23")
```

## Client API Methods
Below are the currently available API methods usable via this client.  I've not yet added the three 
[special methods](https://docs.phish.net/special-methods) (attendance, reviews, and users) but will at some point.

Each pysh client method below corresponds to the phish.net api method and the return value is always a list 
of dictionaries with the below dictionary schema.

#### Shows (v5/shows)
```
get_shows(...) -> 
List[Dict{'showid', 'showyear', 'showmonth', 'showday', 'showdate', 'permalink', 'exclude_from_stats',
'venueid', 'setlist_notes', 'venue', 'city', 'state', 'country', 'artistid', 'artist_name',
'tourid', 'tour_name', 'created_at', 'updated_at'}]
```
#### Venues  (v5/venues)
```
get_venues(...) -> 
List[Dict{'venueid', 'venuename', 'city', 'state', 'country', 'venuenotes', 'alias', 'short_name'}]
```
#### Songs  (v5/songs)
```
get_songs(...) -> 
List[Dict{'songid', 'song', 'slug', 'abbr', 'artist', 'debut', 'last_played', 'times_played',
                      'last_permalink', 'debut_permalink', 'gap'}]
```
#### Songdata  (v5/songdata)
```
get_songdata(...) -> 
List[Dict{'songid', 'song', 'nickname', 'slug', 'lyrics', 'history', 'historian'}]
```
#### Setlists  (v5/setlists)
```
get_setlists(...) -> 
List[Dict{'showid', 'showdate', 'permalink', 'showyear', 'uniqueid', 'meta', 'reviews', 'exclude',
                  'setlistnotes', 'soundcheck', 'songid', 'position', 'transition', 'footnote', 'set', 'isjam',
                  'isreprise', 'isjamchart', 'jamchart_description', 'tracktime', 'gap', 'tourid', 'tourname',
                  'tourwhen', 'song', 'nickname', 'slug', 'is_original', 'venueid', 'venue', 'city', 'state',
                  'country', 'trans_mark', 'artistid', 'artist_slug', 'artist_name'}]
```
#### Artists  (v5/artists)
```
get_artists(...) -> 
List[Dict{'id', 'artist', 'slug'}]
```

#### Jamcharts  (v5/jamcharts)
```
get_jamcharts(...) -> 
List[Dict{'showid', 'showdate', 'permalink', 'showyear', 'uniqueid', 'meta', 'reviews', 'exclude',
                   'setlistnotes', 'soundcheck', 'songid', 'position', 'transition', 'footnote', 'set', 'isjam',
                   'isreprise', 'isjamchart', 'jamchart_description', 'tracktime', 'gap', 'tourid', 'tourname',
                   'tourwhen', 'song', 'nickname', 'slug', 'is_original', 'venueid', 'venue', 'city', 'state',
                   'country', 'trans_mark', 'artistid', 'artist_slug', 'artist_name'}]
```

---

