#####################
Quickbase-Client
#####################
A High-Level Quickbase Python API Client & Model Generator
.. image:: https://gitlab.com/tkutcher/quickbase-client/badges/dev/pipeline.svg
:target: https://gitlab.com/tkutcher/quickbase-client/-/commits/dev
:alt: Pipeline Status
.. image:: https://gitlab.com/tkutcher/quickbase-client/badges/dev/coverage.svg
:target: https://gitlab.com/tkutcher/quickbase-client/-/commits/dev
:alt: Coverage Report
.. image:: https://readthedocs.org/projects/quickbase-client/badge/?version=latest
:target: https://quickbase-client.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. image:: https://badge.fury.io/py/quickbase-client.svg
:target: https://badge.fury.io/py/quickbase-client
:alt: PyPI
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
:alt: Black Code Style
|
*Quickbase-Client is a library for interacting with Quickbase applications through their
RESTful JSON API (https://developer.quickbase.com/). It has features to generate model classes
for tables in your Quickbase app, and provides high level classes to interface between Python
objects and the Quickbase tables.*
|
.. inclusion-marker-do-not-remove
Quick Start
============
Installation
____________
Installation can be done through pip:
.. code-block:: bash
pip install quickbase-client
This will install both the library ``quickbase_client``, and a command line tool ``qbc`` for
running some handy scripts.
Generating your Models
----------------------
To interact and authenticate with your Quickbase applications you need a User Token. You can read
the Quickbase documentation `here <https://developer.quickbase.com/auth>`_ on how to create one.
It is recommended to set an environment variable ``QB_USER_TOKEN`` with this value:
.. code-block:: bash
export QB_USER_TOKEN=mytokenfromquickbase;
Next, say you have a hypothetical Quickbase Application named MyApp at
``https://foo.quickbase.com/db/abcdef`` that has tables for tracking things
against a repository like Issues & Pipelines.
.. image:: /images/example_table.png
:width: 500
:alt: Example Table
|
Running the following:
.. code-block:: bash
qbc run model-generate -a https://foo.quickbase.com/db/abcdef
Would generate a directory structure like
::
models
├── __init__.py
└── my_app
├── __init__.py
├── app.py
├── github_issue.py
└── gitlab_pipeline.py
And classes like ``GitHubIssue`` where you can interact with the data model through a Python object.
Writing Records to Quickbase
----------------------------
Classes like ``GitHubIssue`` that subclass ``QuickbaseTable`` also get a factory class-method
``client(user_tok)`` which creates an instance of the higher-level ``QuickbaseTableClient`` to
make API requests for things related to that table:
.. code-block:: python
client = GitHubIssue.client(user_tok=os.environ['QB_USER_TOKEN'])
new_issue = GitHubIssue(
title='Something broke', # you get friendly-kwargs for fields without worrying about ID's
description='Please fix!',
date_opened=date.today() # things like Python date objects will be serialized
)
response = client.add_record(new_issue)
print(response.json()) # all methods (except for query) return the requests Response object
Querying Records from Quickbase
-------------------------------
You can also use the client object to send queries to the Quickbase API through the ``query``
method. This method will serialize the data back in to a Python object. The `query` method on the
table class takes a ``QuickbaseQuery`` object which is high level wrapper around the parameters
needed to make a query.
Notably, the ``where`` parameter for specifying the query string. There is one (and in the future
there will be more) implementation of this which allows you to build query-strings through
higher-level python functions.
You can use the methods exposed in the ``quickbase_client.query`` module like so:
.. code-block:: python
# convention to append an underscore to these methods to avoid clashing
# with any python keywords
from quickbase_client.query import on_or_before_
from quickbase_client.query import eq_
from quickbase_client.query import and_
schema = GitHubIssue.schema
q = and_(
eq_(schema.date_opened, schema.date_created),
on_or_before_(schema.date_closed, date(2020, 11, 16))
)
print(q.where) # ({'9'.EX.'_FID_1'}AND{'10'.OBF.'11-16-2020'})
recs = client.query(q) # recs will be GitHubIssue objects unless passing raw=True
print([str(r) for r in recs]) # ['<GitHubIssue title="Made And Closed Today" id="10000">']
Controlling Lower-Level API Calls
---------------------------------
Lastly, say you want to deal with just posting the specific json/data Quickbase is looking for.
The ``QuickbaseTableClient`` object wraps the lower-level ``QuickbaseApiClient`` object which has
methods for just sending the actual data (with an even lower-level utility
``QuickbaseRequestFactory`` you could also use). These classes manage hanging on to the user token,
and the realm hostname, etc. for each request that is made.
For example, note the signature of ``query`` in ``QuickbaseApiClient``:
.. code-block:: python
def query(self, table_id, fields_to_select=None, where_str=None,
sort_by=None, group_by=None, options=None):
You can get to this class by going through the table client: ``api = client.api``, or from
instantiating it directly ``api = QuickbaseApiClient(my_user_token, my_realm)``
With this, we could make the exact same request as before:
.. code-block:: python
api = QuickbaseApiClient(user_token='my_token', realm_hostname='foo.quickbase.com')
response = api.query(
table_id='abcdef',
where_str="({'9'.EX.'_FID_1'}AND{'10'.OBF.'11-16-2020'})")
data = response.json()
.. exclusion-marker-do-not-remove
More Resources
==============
- `examples </examples>`_ directory.
- `CONTRIBUTING </CONTRIBUTING.md>`_
- `LICENSE </LICENSE.md>`_
Other Notes
====================
Currently a bunch of duplicate aliases for ``QuickBase`` to ``Quickbase`` since this
was originally released with everything prefixed as ``QuickBase-``. But since Quickbase
is branding more to "Quickbase", this will eventually be the main naming for
version 1.0 in an effort to keep more consistent. So prefer to use `Quickbase-` prefixed classes
as in the future the other aliases will be dropped.
Raw data
{
"_id": null,
"home_page": "https://github.com/tkutcher/quickbase-client",
"name": "quickbase-client",
"maintainer": "Tim Kutcher",
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": "tim@tkutcher.com",
"keywords": "quickbase, client, quickbase-api, orm, generator",
"author": "Tim Kutcher",
"author_email": "tim@tkutcher.com",
"download_url": "https://files.pythonhosted.org/packages/2c/9d/0530918f56237ce370303a1c3e4a4daafbfb4a1b8d054811ae1c68a3533d/quickbase_client-0.8.0.tar.gz",
"platform": null,
"description": "#####################\nQuickbase-Client\n#####################\n\nA High-Level Quickbase Python API Client & Model Generator\n\n\n.. image:: https://gitlab.com/tkutcher/quickbase-client/badges/dev/pipeline.svg\n :target: https://gitlab.com/tkutcher/quickbase-client/-/commits/dev\n :alt: Pipeline Status\n\n.. image:: https://gitlab.com/tkutcher/quickbase-client/badges/dev/coverage.svg\n :target: https://gitlab.com/tkutcher/quickbase-client/-/commits/dev\n :alt: Coverage Report\n\n.. image:: https://readthedocs.org/projects/quickbase-client/badge/?version=latest\n :target: https://quickbase-client.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n\n.. image:: https://badge.fury.io/py/quickbase-client.svg\n :target: https://badge.fury.io/py/quickbase-client\n :alt: PyPI\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/psf/black\n :alt: Black Code Style\n\n|\n\n\n*Quickbase-Client is a library for interacting with Quickbase applications through their\nRESTful JSON API (https://developer.quickbase.com/). It has features to generate model classes\nfor tables in your Quickbase app, and provides high level classes to interface between Python\nobjects and the Quickbase tables.*\n\n|\n\n\n.. inclusion-marker-do-not-remove\n\nQuick Start\n============\n\n\nInstallation\n____________\n\nInstallation can be done through pip:\n\n.. code-block:: bash\n\n pip install quickbase-client\n\nThis will install both the library ``quickbase_client``, and a command line tool ``qbc`` for\nrunning some handy scripts.\n\n\nGenerating your Models\n----------------------\n\nTo interact and authenticate with your Quickbase applications you need a User Token. You can read\nthe Quickbase documentation `here <https://developer.quickbase.com/auth>`_ on how to create one.\nIt is recommended to set an environment variable ``QB_USER_TOKEN`` with this value:\n\n.. code-block:: bash\n\n export QB_USER_TOKEN=mytokenfromquickbase;\n\n\nNext, say you have a hypothetical Quickbase Application named MyApp at\n``https://foo.quickbase.com/db/abcdef`` that has tables for tracking things\nagainst a repository like Issues & Pipelines.\n\n\n.. image:: /images/example_table.png\n :width: 500\n :alt: Example Table\n\n|\n\nRunning the following:\n\n.. code-block:: bash\n\n qbc run model-generate -a https://foo.quickbase.com/db/abcdef\n\nWould generate a directory structure like\n\n::\n\n models\n \u251c\u2500\u2500 __init__.py\n \u2514\u2500\u2500 my_app\n \u251c\u2500\u2500 __init__.py\n \u00a0\u00a0 \u251c\u2500\u2500 app.py\n \u00a0\u00a0 \u251c\u2500\u2500 github_issue.py\n \u00a0\u00a0 \u2514\u2500\u2500 gitlab_pipeline.py\n\nAnd classes like ``GitHubIssue`` where you can interact with the data model through a Python object.\n\n\nWriting Records to Quickbase\n----------------------------\n\nClasses like ``GitHubIssue`` that subclass ``QuickbaseTable`` also get a factory class-method\n``client(user_tok)`` which creates an instance of the higher-level ``QuickbaseTableClient`` to\nmake API requests for things related to that table:\n\n.. code-block:: python\n\n client = GitHubIssue.client(user_tok=os.environ['QB_USER_TOKEN'])\n new_issue = GitHubIssue(\n title='Something broke', # you get friendly-kwargs for fields without worrying about ID's\n description='Please fix!',\n date_opened=date.today() # things like Python date objects will be serialized\n )\n response = client.add_record(new_issue)\n print(response.json()) # all methods (except for query) return the requests Response object\n\n\nQuerying Records from Quickbase\n-------------------------------\n\nYou can also use the client object to send queries to the Quickbase API through the ``query``\nmethod. This method will serialize the data back in to a Python object. The `query` method on the\ntable class takes a ``QuickbaseQuery`` object which is high level wrapper around the parameters\nneeded to make a query.\n\nNotably, the ``where`` parameter for specifying the query string. There is one (and in the future\nthere will be more) implementation of this which allows you to build query-strings through\nhigher-level python functions.\n\nYou can use the methods exposed in the ``quickbase_client.query`` module like so:\n\n.. code-block:: python\n\n # convention to append an underscore to these methods to avoid clashing\n # with any python keywords\n from quickbase_client.query import on_or_before_\n from quickbase_client.query import eq_\n from quickbase_client.query import and_\n\n schema = GitHubIssue.schema\n q = and_(\n eq_(schema.date_opened, schema.date_created),\n on_or_before_(schema.date_closed, date(2020, 11, 16))\n )\n print(q.where) # ({'9'.EX.'_FID_1'}AND{'10'.OBF.'11-16-2020'})\n recs = client.query(q) # recs will be GitHubIssue objects unless passing raw=True\n print([str(r) for r in recs]) # ['<GitHubIssue title=\"Made And Closed Today\" id=\"10000\">']\n\n\n\nControlling Lower-Level API Calls\n---------------------------------\n\nLastly, say you want to deal with just posting the specific json/data Quickbase is looking for.\nThe ``QuickbaseTableClient`` object wraps the lower-level ``QuickbaseApiClient`` object which has\nmethods for just sending the actual data (with an even lower-level utility\n``QuickbaseRequestFactory`` you could also use). These classes manage hanging on to the user token,\nand the realm hostname, etc. for each request that is made.\n\nFor example, note the signature of ``query`` in ``QuickbaseApiClient``:\n\n.. code-block:: python\n\n def query(self, table_id, fields_to_select=None, where_str=None,\n sort_by=None, group_by=None, options=None):\n\n\nYou can get to this class by going through the table client: ``api = client.api``, or from\ninstantiating it directly ``api = QuickbaseApiClient(my_user_token, my_realm)``\n\nWith this, we could make the exact same request as before:\n\n.. code-block:: python\n\n api = QuickbaseApiClient(user_token='my_token', realm_hostname='foo.quickbase.com')\n response = api.query(\n table_id='abcdef',\n where_str=\"({'9'.EX.'_FID_1'}AND{'10'.OBF.'11-16-2020'})\")\n data = response.json()\n\n\n.. exclusion-marker-do-not-remove\n\nMore Resources\n==============\n- `examples </examples>`_ directory.\n- `CONTRIBUTING </CONTRIBUTING.md>`_\n- `LICENSE </LICENSE.md>`_\n\n\nOther Notes\n====================\n\n\nCurrently a bunch of duplicate aliases for ``QuickBase`` to ``Quickbase`` since this\nwas originally released with everything prefixed as ``QuickBase-``. But since Quickbase\nis branding more to \"Quickbase\", this will eventually be the main naming for\nversion 1.0 in an effort to keep more consistent. So prefer to use `Quickbase-` prefixed classes\nas in the future the other aliases will be dropped.\n",
"bugtrack_url": null,
"license": "LICENSE.md",
"summary": "A Quickbase Python API Client Generator",
"version": "0.8.0",
"project_urls": {
"Bug Tracker": "https://github.com/tkutcher/quickbase-client/issues",
"Documentation": "https://quickbase-client.readthedocs.io/en/latest/?badge=latest",
"Homepage": "https://github.com/tkutcher/quickbase-client",
"Repository": "https://github.com/tkutcher/quickbase-client"
},
"split_keywords": [
"quickbase",
" client",
" quickbase-api",
" orm",
" generator"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c709ec75a4d10a79ec47515a73600e40835647f921a0380aca2e6a509a6ea0ba",
"md5": "1a9ef45ae939b435172039ca24ab0b24",
"sha256": "0528308f52048b3b17ceb559495b34911ed05f028a04fbaf1277f38683f57dad"
},
"downloads": -1,
"filename": "quickbase_client-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1a9ef45ae939b435172039ca24ab0b24",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 29704,
"upload_time": "2024-06-10T19:50:16",
"upload_time_iso_8601": "2024-06-10T19:50:16.073566Z",
"url": "https://files.pythonhosted.org/packages/c7/09/ec75a4d10a79ec47515a73600e40835647f921a0380aca2e6a509a6ea0ba/quickbase_client-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2c9d0530918f56237ce370303a1c3e4a4daafbfb4a1b8d054811ae1c68a3533d",
"md5": "b6f9b0f6ca4c2ab5043223b12a4acacd",
"sha256": "358ee040dadd223c6b309543e32e15d9781dd29a27f7da348b8616576da94ff4"
},
"downloads": -1,
"filename": "quickbase_client-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "b6f9b0f6ca4c2ab5043223b12a4acacd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 24146,
"upload_time": "2024-06-10T19:50:17",
"upload_time_iso_8601": "2024-06-10T19:50:17.993447Z",
"url": "https://files.pythonhosted.org/packages/2c/9d/0530918f56237ce370303a1c3e4a4daafbfb4a1b8d054811ae1c68a3533d/quickbase_client-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-10 19:50:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tkutcher",
"github_project": "quickbase-client",
"travis_ci": false,
"coveralls": true,
"github_actions": false,
"tox": true,
"lcname": "quickbase-client"
}
JSON
