Client-side library for accessing the falconapi restful service.
Project description
falconlib
Python client lib for accessing Falcon API
Purpose • Installation • Notes • Document Management • Author
Purpose
Falconlib is the preferred means of accessing my back-end services. With the proper credentials, you can access some of those back-end services through the requests pacakge, but they change frequently and move from endpoint to endpoint. Falconlib smoothes out those developmental undulations.
GETTING STARTED
Installation
pip install falconlib
Instantiation
from falconlib import FalconlLib
falconlib = FalconLib('https://your-endpoint.com')
falconlib.authorize('my_username', 'my_password')
NOTES
The requests package handles the HTTPS traffic between falconlib and the back-end services. Because of that, you can access the last response object thus:
r = falconlib.last_response
HTTP STATUS CODES
If an API call fails, the HTTP status code will be one of these:
Status Code | Explanation |
---|---|
401 | Invalid login credentials |
404 | Object not found, e.g. Document, Tracker, etc. |
409 | Conflict. Check falconlib.last_response.json() for a specific explanation |
500 | Server-side error. Sorry about that. |
FUNCTION RETURNS
All functions return a FalconStatus object having these fields:
Field | Type | Value |
---|---|---|
success | (bool) | True if successful otherwise False |
status | (int) | HTTP status of last HTTP(s) request |
message | (str) | Message that explains the success or failure of the function call |
payload | (dict) | Contains the payload of the function call and is documented with each method below |
DOCUMENT MANAGEMENT
Add a document to the database
add_document(doc: dict) -> FalconStatus
Arguments
doc (dict) - Elements of a Document
Result
Instance of FalconStatus
Example
from falconlib import FalconlLib
falconlib = FalconLib('https://your-endpoint.com')
falconlib.authorize('my_username', 'my_password')
DOC_1 = {
"id": "doc-1",
"path":"x:\\shared\\office\\user\\client\\discovery\\our production\\my_document.pdf",
"filename":"my_document.pdf",
"type": "application/pdf",
"title": "my_document",
"create_date":"07/01/2022",
"document_date": "07/15/2022",
"beginning_bates": "TD002304",
"ending_bates": "TD002304",
"page_count": 1,
"client_reference": "20202.1",
}
fstatus = falconlib.add_document(DOC_1)
assert fstatus.success == True
assert falconlib.last_response.status_code == 201
Retrieve a Document from the Database
get_document(document_id: str, path: str) -> FalconStatus
Arguments
document_id (str): id of the document to be retrieved. (optional) path (str): path of the document to be retrieved. (optional)
You must provide either a document_id or a path. If you provide both, then document_id will be used. If you provide neither, the call will raise an exception.
Result
Instance of FalconStatus where the payload field contains a dict having the elements of a Document
Example
from falconlib import FalconlLib
falconlib = FalconLib('https://your-endpoint.com')
falconlib.authorize('my_username', 'my_password')
doc = falconlib.get_document('doc-1').payload
assert falconlib.last_response.status_code == 200
assert doc['id'] == 'doc-1'
Update a Document in the Database
update_document(revised_doc: dict) -> FalconStatus
Arguments
revised_doc (dict) - Elements of a Document
Result
Instance of FalconStatus
Example
from falconlib import FalconlLib
falconlib = FalconLib('https://your-endpoint.com')
falconlib.authorize('my_username', 'my_password')
# Retrieve document before updating to avoid version conflicts.
revised_doc = falconlib.get_document(DOC_1['id']).payload
# Update the field(s) you want to revise.
revised_doc['title'] = '**Updated Document'
# Update the document
r = falconlib.update_document(revised_doc)
assert r.success == True
assert falconlib.last_response.status_code == 200
Delete a Document from the Database
delete_document(document_id: str, cascade: bool = True) -> FalconStatus
Arguments
document_id: (str) - ID of document to delete. (required)
cascade (bool) - Whether to cascade the delete. (optional, default=True) If cascade is set to True, then the document will be deleted and removed from all trackers that reference it. If cascade is set to False, then the document will be deleted only if it is not linked to any trackers.
from falconlib import FalconlLib
falconlib = FalconLib('https://your-endpoint.com')
r = falconlib.authorize('my_username', 'my_password')
r = falconlib.delete_document(document_id=DOC_1['id'], cascade=False)
assert r.success == True
assert falconlib.last_response.status_code == 200
TRACKER MANAGEMENT
MAINTENANCE
Before posting a new version, run pytest and make sure all tests are passing.
Next, make sure to bump the version in falconlib.toml
Then, build a new version:
py -m build
Finally, upload the new version:
py -m twine upload dist/*
NOTE: For the upload, your
- username is
__token__
- password is a project-scoped token
On Windows, you cannot use CTRL-V
to paste the project-scoped token. You MUST right click the command shell window and select Edit->Paste
.
For detailed instructions, visit (https://packaging.python.org)[https://packaging.python.org/en/latest/tutorials/packaging-projects/].
Author
Thomas J. Daley, J.D. is an active, board certified family law litigation attorney practicing primarily in Collin County, Texas and software developer. My family law practice is limited to divorce, child custody, child support, enforcment, and modification suits. Web Site
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for falconlib-0.0.14-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c9f398712fe3508b55f70cecb47aa292fc50f7b4f785e78865a807240a6064d1 |
|
MD5 | f6196c8b2017314da4056ae11e852733 |
|
BLAKE2b-256 | 3087ae7799baf57f29820cb2f7d807779dc49079285deae9345ac337c2589d47 |