falconlib

Name	falconlib JSON
Version	0.0.14 JSON
	download
home_page
Summary	Client-side library for accessing the falconapi restful service.
upload_time	2023-11-08 05:35:18
maintainer
docs_url	None
author
requires_python	>3.9
license	BSD 2-Clause License Copyright (c) 2022, Tom Daley All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
keywords	falconapi falconlib
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # falconlib
Python client lib for accessing Falcon API

<p align="center">
    <a href="https://github.com/tjdaley/falconlib/issues"><img alt="GitHub issues" src="https://img.shields.io/github/issues/tjdaley/falconlib"></a>
    <a href="https://github.com/tjdaley/falconlib/network"><img alt="GitHub forks" src="https://img.shields.io/github/forks/tjdaley/falconlib"></a>
    <a href="https://github.com/tjdaley/falconlib/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/tjdaley/falconlib"><a>
    <img alt="Stage: Development" src="https://img.shields.io/badge/stage-Development-orange">
    <img alt="PyPI - License" src="https://img.shields.io/pypi/l/falconlib">
</p>
<p align="center">
    <a href="#purpose">Purpose</a> &bull;
    <a href="#installation">Installation</a> &bull;
    <a href="#notes">Notes</a> &bull;
    <a href="#document-management">Document Management</a> &bull;
    <a href="#author">Author</a>
</p>

## 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

```python
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:

```python
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](https://api.jdbot.us/docs#model-Document)

***Result***

Instance of *FalconStatus*

### Example

```python
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](https://api.jdbot.us/docs#model-Document)

### Example

```python
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](https://api.jdbot.us/docs#model-Document)

***Result***

Instance of *FalconStatus*

### Example

```python
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.

```python
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

1. username is ```__token__```
2. 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](https://koonsfuller.com/attorneys/tom-daley/)

            

Raw data

            {
    "_id": null,
    "home_page": "",
    "name": "falconlib",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">3.9",
    "maintainer_email": "",
    "keywords": "falconapi,falconlib",
    "author": "",
    "author_email": "\"Thomas J. Daley, Esq.\" <tjd@powerdaley.com>",
    "download_url": "https://files.pythonhosted.org/packages/9a/4c/42ed41871ad0c813b9c28011b8cb937d2047a0651c0a8b9b10254c8d8d5b/falconlib-0.0.14.tar.gz",
    "platform": null,
    "description": "# falconlib\r\nPython client lib for accessing Falcon API\r\n\r\n<p align=\"center\">\r\n    <a href=\"https://github.com/tjdaley/falconlib/issues\"><img alt=\"GitHub issues\" src=\"https://img.shields.io/github/issues/tjdaley/falconlib\"></a>\r\n    <a href=\"https://github.com/tjdaley/falconlib/network\"><img alt=\"GitHub forks\" src=\"https://img.shields.io/github/forks/tjdaley/falconlib\"></a>\r\n    <a href=\"https://github.com/tjdaley/falconlib/stargazers\"><img alt=\"GitHub stars\" src=\"https://img.shields.io/github/stars/tjdaley/falconlib\"><a>\r\n    <img alt=\"Stage: Development\" src=\"https://img.shields.io/badge/stage-Development-orange\">\r\n    <img alt=\"PyPI - License\" src=\"https://img.shields.io/pypi/l/falconlib\">\r\n</p>\r\n<p align=\"center\">\r\n    <a href=\"#purpose\">Purpose</a> &bull;\r\n    <a href=\"#installation\">Installation</a> &bull;\r\n    <a href=\"#notes\">Notes</a> &bull;\r\n    <a href=\"#document-management\">Document Management</a> &bull;\r\n    <a href=\"#author\">Author</a>\r\n</p>\r\n\r\n## Purpose\r\n\r\n*Falconlib* is the preferred means of accessing my back-end services. With the proper credentials,\r\nyou can access some of those back-end services through the *requests* pacakge, but they change\r\nfrequently and move from endpoint to endpoint. *Falconlib* smoothes out those developmental\r\nundulations.\r\n\r\n# GETTING STARTED\r\n\r\n## Installation\r\n\r\n```pip install falconlib```\r\n\r\n## Instantiation\r\n\r\n```python\r\nfrom falconlib import FalconlLib\r\n\r\nfalconlib = FalconLib('https://your-endpoint.com')\r\nfalconlib.authorize('my_username', 'my_password')\r\n```\r\n\r\n# NOTES\r\n\r\nThe *requests* package handles the HTTPS traffic between *falconlib* and the back-end services.\r\nBecause of that, you can access the last *response* object thus:\r\n\r\n```python\r\nr = falconlib.last_response\r\n```\r\n\r\n# HTTP STATUS CODES\r\n\r\nIf an API call fails, the HTTP status code will be one of these:\r\n\r\n| Status Code | Explanation |\r\n|----------|---------------------------------|\r\n| 401 | Invalid login credentials |\r\n| 404 | Object not found, e.g. Document, Tracker, etc. |\r\n| 409 | Conflict. Check falconlib.last_response.json() for a specific explanation |\r\n| 500 | Server-side error. Sorry about that. |\r\n\r\n# FUNCTION RETURNS\r\n\r\nAll functions return a FalconStatus object having these fields:\r\n\r\n| Field | Type | Value |\r\n|-------|------|-------|\r\n| *success* | (bool)  | True if successful otherwise False |\r\n| *status* | (int) | HTTP status of last HTTP(s) request |\r\n| *message* | (str) | Message that explains the success or failure of the function call |\r\n| *payload* | (dict) | Contains the payload of the function call and is documented with each method below |\r\n\r\n# DOCUMENT MANAGEMENT\r\n\r\n## Add a document to the database\r\n\r\n### *add_document(doc: dict) -> FalconStatus*\r\n\r\n***Arguments***\r\n\r\n*doc* (dict) - Elements of a [Document](https://api.jdbot.us/docs#model-Document)\r\n\r\n***Result***\r\n\r\nInstance of *FalconStatus*\r\n\r\n### Example\r\n\r\n```python\r\nfrom falconlib import FalconlLib\r\n\r\nfalconlib = FalconLib('https://your-endpoint.com')\r\nfalconlib.authorize('my_username', 'my_password')\r\n\r\nDOC_1 = {\r\n    \"id\": \"doc-1\",\r\n    \"path\":\"x:\\\\shared\\\\office\\\\user\\\\client\\\\discovery\\\\our production\\\\my_document.pdf\",\r\n    \"filename\":\"my_document.pdf\",\r\n    \"type\": \"application/pdf\",\r\n    \"title\": \"my_document\",\r\n    \"create_date\":\"07/01/2022\",\r\n    \"document_date\": \"07/15/2022\",\r\n    \"beginning_bates\": \"TD002304\",\r\n    \"ending_bates\": \"TD002304\",\r\n    \"page_count\": 1,\r\n    \"client_reference\": \"20202.1\",\r\n}\r\n\r\nfstatus = falconlib.add_document(DOC_1)\r\nassert fstatus.success == True\r\nassert falconlib.last_response.status_code == 201\r\n```\r\n## Retrieve a Document from the Database\r\n\r\n### *get_document(document_id: str, path: str) -> FalconStatus*\r\n\r\n***Arguments***\r\n\r\ndocument_id (str): *id* of the document to be retrieved. (optional)\r\npath (str): *path* of the document to be retrieved. (optional)\r\n\r\nYou must provide *either* a *document_id* or a *path*. If you provide both, then\r\n*document_id* will be used. If you provide neither, the call will raise an exception.\r\n\r\n***Result***\r\n\r\nInstance of *FalconStatus* where the *payload* field contains a\r\n*dict* having the elements of a [Document](https://api.jdbot.us/docs#model-Document)\r\n\r\n### Example\r\n\r\n```python\r\nfrom falconlib import FalconlLib\r\n\r\nfalconlib = FalconLib('https://your-endpoint.com')\r\nfalconlib.authorize('my_username', 'my_password')\r\n\r\ndoc = falconlib.get_document('doc-1').payload\r\nassert falconlib.last_response.status_code == 200\r\nassert doc['id'] == 'doc-1'\r\n```\r\n## Update a Document in the Database\r\n\r\n### *update_document(revised_doc: dict) -> FalconStatus*\r\n\r\n***Arguments***\r\n\r\n*revised_doc* (dict) - Elements of a [Document](https://api.jdbot.us/docs#model-Document)\r\n\r\n***Result***\r\n\r\nInstance of *FalconStatus*\r\n\r\n### Example\r\n\r\n```python\r\nfrom falconlib import FalconlLib\r\n\r\nfalconlib = FalconLib('https://your-endpoint.com')\r\nfalconlib.authorize('my_username', 'my_password')\r\n\r\n# Retrieve document before updating to avoid version conflicts.\r\nrevised_doc = falconlib.get_document(DOC_1['id']).payload\r\n\r\n# Update the field(s) you want to revise.\r\nrevised_doc['title'] = '**Updated Document'\r\n\r\n# Update the document\r\nr = falconlib.update_document(revised_doc)\r\nassert r.success == True\r\nassert falconlib.last_response.status_code == 200\r\n```\r\n\r\n## Delete a Document from the Database\r\n### *delete_document(document_id: str, cascade: bool = True) -> FalconStatus*\r\n\r\n### *Arguments*\r\n\r\n*document_id*: (str) - ID of document to delete. (required)\r\n\r\n*cascade* (bool) - Whether to cascade the delete. (optional, default=True)\r\nIf *cascade* is set to True, then the document will be deleted and removed from all trackers\r\nthat reference it. If *cascade* is set to False, then the document will be deleted only if\r\nit is not linked to any trackers.\r\n\r\n```python\r\nfrom falconlib import FalconlLib\r\n\r\nfalconlib = FalconLib('https://your-endpoint.com')\r\nr = falconlib.authorize('my_username', 'my_password')\r\nr = falconlib.delete_document(document_id=DOC_1['id'], cascade=False)\r\nassert r.success == True\r\nassert falconlib.last_response.status_code == 200\r\n```\r\n\r\n# TRACKER MANAGEMENT\r\n\r\n# MAINTENANCE\r\n\r\nBefore posting a new version, run pytest and make sure all tests are passing.\r\n\r\nNext, make sure to bump the version in falconlib.toml\r\n\r\nThen, build a new version:\r\n\r\n```py -m build```\r\n\r\nFinally, upload the new version:\r\n\r\n```py -m twine upload dist/*```\r\n\r\n**NOTE**:\r\nFor the upload, your\r\n\r\n1. username is ```__token__```\r\n2. password is a project-scoped token\r\n\r\nOn Windows, you **cannot** use ```CTRL-V``` to paste the project-scoped token. You **MUST** right click the command shell window and select ```Edit->Paste```.\r\n\r\n\r\nFor detailed instructions, visit (https://packaging.python.org)[https://packaging.python.org/en/latest/tutorials/packaging-projects/].\r\n\r\n# Author\r\n\r\nThomas 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](https://koonsfuller.com/attorneys/tom-daley/)\r\n",
    "bugtrack_url": null,
    "license": "BSD 2-Clause License  Copyright (c) 2022, Tom Daley All rights reserved.  Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ",
    "summary": "Client-side library for accessing the falconapi restful service.",
    "version": "0.0.14",
    "project_urls": {
        "Bug Tracker": "https://github.com/tjdaley/falconlib/issues",
        "Homepage": "https://github.com/tjdaley/falconlib"
    },
    "split_keywords": [
        "falconapi",
        "falconlib"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "3087ae7799baf57f29820cb2f7d807779dc49079285deae9345ac337c2589d47",
                "md5": "f6196c8b2017314da4056ae11e852733",
                "sha256": "c9f398712fe3508b55f70cecb47aa292fc50f7b4f785e78865a807240a6064d1"
            },
            "downloads": -1,
            "filename": "falconlib-0.0.14-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "f6196c8b2017314da4056ae11e852733",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">3.9",
            "size": 12041,
            "upload_time": "2023-11-08T05:35:15",
            "upload_time_iso_8601": "2023-11-08T05:35:15.494415Z",
            "url": "https://files.pythonhosted.org/packages/30/87/ae7799baf57f29820cb2f7d807779dc49079285deae9345ac337c2589d47/falconlib-0.0.14-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "9a4c42ed41871ad0c813b9c28011b8cb937d2047a0651c0a8b9b10254c8d8d5b",
                "md5": "4190eb9103131b22ffb2148eb835e125",
                "sha256": "550edffdbf2768e4e9f120f23ff2f686985da5e0eb98dd511e7ade601d64ea31"
            },
            "downloads": -1,
            "filename": "falconlib-0.0.14.tar.gz",
            "has_sig": false,
            "md5_digest": "4190eb9103131b22ffb2148eb835e125",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">3.9",
            "size": 13074,
            "upload_time": "2023-11-08T05:35:18",
            "upload_time_iso_8601": "2023-11-08T05:35:18.735981Z",
            "url": "https://files.pythonhosted.org/packages/9a/4c/42ed41871ad0c813b9c28011b8cb937d2047a0651c0a8b9b10254c8d8d5b/falconlib-0.0.14.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-11-08 05:35:18",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "tjdaley",
    "github_project": "falconlib",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "falconlib"
}