diff --git a/README.md b/README.md index 7a6c75f..8f6cb3e 100644 --- a/README.md +++ b/README.md @@ -15,10 +15,10 @@ To install, run `pip install quickbase-json-api-client` ## Initialize Client Use the following code to create and initialize a client object. -``` -from quickbase_json.client import QuickbaseJSONClient # import client +```python +from quickbase_json import QBClient -client = QuickbaseJSONClient(realm="yourRealm", auth="userToken") +client = QBClient(realm="yourRealm", auth="userToken") ``` Where `yourRealm` is the name (subdomain) of your Quickbase Realm and `userToken` is the user token used to authenticate @@ -28,11 +28,33 @@ with the realm. Querying for records is one of the most useful features of the Quickbase JSON API. Querying records with QJAC can be done using the following code -`response = client.query_records('tableId', fids, 'queryString')` +#### Basic Example + +```python +response = client.query_records(table='tableId', select=[3, 6, 12], query='queryString') +``` Where `tableId` is the ID of the table you wish to query from, `fids` is a list of field IDs you wish to receive and `queryString` is a quickbase [query string](https://help.quickbase.com/api-guide/componentsquery.html). + +#### Adv. Example + +```python +from quickbase_json.helpers import Where +# have static fids for table/records +NEEDED_FIDS = [3, 6, 12] +# build query str where 3 is either 130, 131 or 132 +# https://help.quickbase.com/api-guide/componentsquery.html +q_str = Where(3, 'EX', [130, 131, 132]).build(join='OR') +response = client.query_records(table='tableId', select=NEEDED_FIDS, query=q_str) +``` + +In this example, we use the `Where()` helper. This can make building complex [QuickBase queries](https://help.quickbase.com/api-guide/componentsquery.html) easier. + +The `Where()` helper documentation can be found [here](!https://github.com/robswc/quickbase-json-api-client/wiki/Helper:-Where). + + ## Response Objects A `QBResponse` object is returned when querying records with QJAC. A `QBResponse` has several methods that make @@ -40,25 +62,48 @@ handling returned data easier. Here are a few of the most useful ones. ### Response Methods -- **data()** +- **.data()** + +```python +r = qbc.query_records(...).data() +``` -Returns the actual data. Equivalent to calling `.get('data')` +Returns the data from QuickBase. Equivalent to calling `.get('data')` -- **denest()** +- **.denest()** + +```python +r = qbc.query_records(...).denest() +``` Denests the data. I.e. changes `{'fid': {'value': 'actualValue'}}` to `{'fid': 'actualValue'}` -- **orient(orient='records', key='3')** +- **orient(orient: str, key: int)** + +```python +r = qbc.query_records(...).orient('records', key=3) +``` Orients the data. Currently, the only option is 'records'. This will orient the returned data into a "record like structure", i.e. changes `{'fid': 'actualValue', 'fid': 'actualValue'}` to `{'key': {etc: etc}}` - **convert()** + +```python +r = qbc.query_records(...).convert('datetime') +``` + Converts the data, based on fields and provided arguments. For example, calling `convert('datetime')` will convert all data with fields of the 'date time' type to python datetime objects. Other conversions are 'currency' and 'int'. - **round_ints()** + +```python +r = qbc.query_records(...).round_ints() +``` + + Rounds all float integers into whole number ints. i.e. converts `55.0` to `55`. diff --git a/setup.cfg b/setup.cfg index 6601edd..a634ab3 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,6 +1,6 @@ [metadata] name = quickbase-json-api-client -version = 0.1.0 +version = 0.1.1 author = Robert Carroll author_email = rob@shenandoah.capital description = Python wrapper for quickbase JSON API. diff --git a/src/quickbase_json/helpers.py b/src/quickbase_json/helpers.py index f5cf704..6517588 100644 --- a/src/quickbase_json/helpers.py +++ b/src/quickbase_json/helpers.py @@ -17,9 +17,15 @@ class QuickbaseParameter: def build(self): return 'Default String' + def to_json(self): + return self.build() + def __str__(self): return self.build() + def __repr__(self): + return self.build() + class Where(QuickbaseParameter): def __init__(self, fid: any, operator: str, value: any, **kwargs): diff --git a/src/quickbase_json/qb_response.py b/src/quickbase_json/qb_response.py index cd10da9..5425d87 100644 --- a/src/quickbase_json/qb_response.py +++ b/src/quickbase_json/qb_response.py @@ -42,6 +42,13 @@ def __init__(self, res=None, **kwargs): self.update(kwargs.get('sample_data')) super().__init__(requests_response=res) + def is_empty(self): + """ + Tests if data is empty, return True if so. + :return: boolean + """ + return self.get('data', False) + def info(self, prt=True): """ Prints information about the response.