{"id":19732352,"url":"https://github.com/terminusdb/terminusdb-client-python","last_synced_at":"2025-04-06T02:08:42.921Z","repository":{"id":37455185,"uuid":"208302966","full_name":"terminusdb/terminusdb-client-python","owner":"terminusdb","description":"TerminusDB Python Client","archived":false,"fork":false,"pushed_at":"2024-06-10T10:37:33.000Z","size":9422,"stargazers_count":75,"open_issues_count":31,"forks_count":58,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-30T01:08:38.134Z","etag":null,"topics":["api-client","hacktoberfest","python","query","query-language","terminusdb"],"latest_commit_sha":null,"homepage":"https://terminusdb.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/terminusdb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-09-13T16:23:46.000Z","updated_at":"2025-03-10T13:03:53.000Z","dependencies_parsed_at":"2024-02-16T13:46:36.227Z","dependency_job_id":"a2fe5ec4-18b7-447c-8e31-e1cc2f9371f4","html_url":"https://github.com/terminusdb/terminusdb-client-python","commit_stats":{"total_commits":1260,"total_committers":34,"mean_commits":37.05882352941177,"dds":"0.34444444444444444","last_synced_commit":"bca8856a16ee71b6efb66d465ffd7ae6f21b970e"},"previous_names":["terminusdb/terminus-client-python"],"tags_count":83,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terminusdb%2Fterminusdb-client-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terminusdb%2Fterminusdb-client-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terminusdb%2Fterminusdb-client-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terminusdb%2Fterminusdb-client-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/terminusdb","download_url":"https://codeload.github.com/terminusdb/terminusdb-client-python/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247423514,"owners_count":20936626,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","hacktoberfest","python","query","query-language","terminusdb"],"created_at":"2024-11-12T00:25:57.653Z","updated_at":"2025-04-06T02:08:42.901Z","avatar_url":"https://github.com/terminusdb.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![TerminusDB Python Client](https://assets.terminusdb.com/readmes/terminusdb-client-python/header.gif)][terminusdb-client-python-docs]\n\n[terminusdb-client-python-docs]: https://terminusdb.com/docs/python\n\n---\n\n[![Discord](https://img.shields.io/discord/689805612053168129?label=Discord\u0026logo=Discord\u0026style=plastic)](https://discord.gg/yTJKAma)\n[![Reddit](https://img.shields.io/reddit/subreddit-subscribers/TerminusDB?style=social)](https://www.reddit.com/r/TerminusDB/)\n[![Twitter](https://img.shields.io/twitter/follow/terminusdb?color=skyblue\u0026label=Follow%20on%20Twitter\u0026logo=twitter\u0026style=flat)](https://twitter.com/TerminusDB)\n\n[![release version](https://img.shields.io/pypi/v/terminusdb-client.svg?logo=pypi)](https://pypi.python.org/pypi/terminusdb-client/)\n[![downloads](https://img.shields.io/pypi/dm/terminusdb-client.svg?logo=pypi)](https://pypi.python.org/pypi/terminusdb-client/)\n\n[![build status](https://img.shields.io/github/workflow/status/terminusdb/terminusdb-client-python/Python%20package?logo=github)](https://github.com/terminusdb/terminusdb-client-python/actions)\n[![documentation](https://img.shields.io/github/deployments/terminusdb/terminusdb-client-python/github-pages?label=documentation\u0026logo=github)](https://terminusdb.com/docs/python)\n[![code coverage](https://codecov.io/gh/terminusdb/terminusdb-client-python/branch/main/graph/badge.svg?token=BclAUaOPnQ)](https://codecov.io/gh/terminusdb/terminusdb-client-python)\n[![license](https://img.shields.io/github/license/terminusdb/terminusdb-client-python?color=pink\u0026logo=apache)](https://github.com/terminusdb/terminusdb-client-python/blob/main/LICENSE)\n\n\u003e Python client for TerminusDB and TerminusCMS.\n\n[**TerminusDB**][terminusdb] is an [open-source][terminusdb-repo] graph database\nand document store. It allows you to link JSON documents in a powerful knowledge\ngraph all through a simple document API.\n\n[terminusdb]: https://terminusdb.com/\n[terminusdb-docs]: https://terminusdb.com/docs/\n[terminusdb-repo]: https://github.com/terminusdb/terminusdb\n\n[**TerminusCMS**](https://terminusdb.com/terminuscms/) is a hosted headless content management system. It is built upon TerminusDB and is a developer-focused data management platform for complex data and content infrastructure. [Sign up and clone a demo project to see how it works][dashboard].\n\n[dashboard]: https://dashboard.terminusdb.com/\n\n## Requirements\n\n- [TerminusDB v10.0](https://github.com/terminusdb/terminusdb-server)\n- [Python \u003e=3.7](https://www.python.org/downloads)\n\n## Release Notes and Previous Versions\n\nTerminusDB Client v10.0 works with TerminusDB v10.0 and TerminusCMS. Please check the [Release Notes](RELEASE_NOTES.md) to find out what has changed.\n\n## Installation\n-  TerminusDB Client can be downloaded from PyPI using pip:\n`python -m pip install terminusdb-client`\n\nThis only includes the core Python Client (Client) and WOQLQuery.\n\nIf you want to use woqlDataframe or the import and export CSV function in the Scaffolding CLI tool:\n\n`python -m pip install terminusdb-client[dataframe]`\n\n*if you are installing from `zsh` you have to quote the argument like this:*\n\n`python -m pip install 'terminusdb-client[dataframe]'`\n\n- Install from source:\n\n`python -m pip install git+https://github.com/terminusdb/terminusdb-client-python.git`\n\n## Demo\n\n![Client Demo gif](https://github.com/terminusdb/terminusdb-web-assets/blob/master/images/terminusdb%20python%20v10%20client%20demo%201.gif)\n\n## Usage\n\n### Python client\n\n#### Connect to a server\n\nConnect to local host\n\n```Python\nfrom terminusdb_client import Client\n\nclient = Client(\"http://127.0.0.1:6363/\")\nclient.connect()\n```\n\nConnect to TerminusCMS\n\n*check the documentation for TerminusCMS about how to add the [API token](https://terminusdb.com/docs/how-to-connect-terminuscms) to the environment variable*\n\n\n```Python\nfrom terminusdb_client import Client\n\nteam=\"MyTeam\"\nclient = Client(f\"https://dashboard.terminusdb.com/{team}/\")\nclient.connect(team=\"MyTeam\", use_token=True)\n```\n\n#### Create a database\n\n```Python\nclient.create_database(\"MyDatabase\")\n```\n\n#### Create a schema\n\n```Python\nfrom terminusdb_client.schema import Schema, DocumentTemplate, RandomKey\n\nmy_schema = Schema()\n\nclass Pet(DocumentTemplate):\n    _schema = my_schema\n    name: str\n    species: str\n    age: int\n    weight: float\n\nmy_schema.commit(client)\n```\n\n#### Create and insert documents\n\n```Python\nmy_dog = Pet(name=\"Honda\", species=\"Huskey\", age=3, weight=21.1)\nmy_cat = Pet(name=\"Tiger\", species=\"Bengal cat\", age=5, weight=4.5)\nclient.insert_document([my_dog, my_cat])\n```\n\n#### Get back all documents\n\n```Python\nprint(list(client.get_all_documents()))\n```\n\n```\n[{'@id': 'Pet/b5edacf854e34fe79c228a91e2af45fb', '@type': 'Pet', 'age': 5, 'name': 'Tiger', 'species': 'Bengal cat', 'weight': 4.5}, {'@id': 'Pet/cdbe3f6d49394b38b952ae315309256d', '@type': 'Pet', 'age': 3, 'name': 'Honda', 'species': 'Huskey', 'weight': 21.1}]\n```\n\n#### Get a specific document\n\n```Python\nprint(list(client.query_document({\"@type\":\"Pet\", \"age\":5})))\n```\n\n```\n[{'@id': 'Pet/145eb73966d14a1394f7cd5576d7d0b8', '@type': 'Pet', 'age': 5, 'name': 'Tiger', 'species': 'Bengal cat', 'weight': 4.5}]\n```\n\n#### Delete a database\n\n```Python\nclient.delete_database(\"MyDatabase\")\n```\n\n### Scaffolding CLI tool\n\n![Scaffolding Demo gif](https://github.com/terminusdb/terminusdb-web-assets/blob/master/images/terminusdb%20python%20v10%20scaffolding%20demo%202.gif)\n\nStart a project in the directory\n\n```bash\n$ tdbpy startproject\nPlease enter a project name (this will also be the database name): mydb\nPlease enter an endpoint location (press enter to use localhost default) [http://127.0.0.1:6363/]:\nconfig.json and schema.py created, please customize them to start your project.\n```\n\nImport a CSV named `grades.csv`\n\n``` bash\n$ tdbpy importcsv grades.csv --na=error\n0it [00:00, ?it/s]\nSchema object Grades created with grades.csv inserted into database.\nschema.py is updated with mydb schema.\n1it [00:00,  1.00it/s]\nRecords in grades.csv inserted as type Grades into database with Lexical ids.\n```\n\nGet documents with query\n\n```bash\n$ tdbpy alldocs --type Grades -q grade=\"B-\"\n[{'@id': 'Grades/Android_Electric_087-65-4321_42.0_23.0_36.0_45.0_47.0_B-', '@type': 'Grades', 'final': 47.0, 'first_name': 'Electric', 'grade': 'B-', 'last_name': 'Android', 'ssn': '087-65-4321', 'test1': 42.0, 'test2': 23.0, 'test3': 36.0, 'test4': 45.0}, {'@id': 'Grades/Elephant_Ima_456-71-9012_45.0_1.0_78.0_88.0_77.0_B-', '@type': 'Grades', 'final': 77.0, 'first_name': 'Ima', 'grade': 'B-', 'last_name': 'Elephant', 'ssn': '456-71-9012', 'test1': 45.0, 'test2': 1.0, 'test3': 78.0, 'test4': 88.0}, {'@id': 'Grades/Franklin_Benny_234-56-2890_50.0_1.0_90.0_80.0_90.0_B-', '@type': 'Grades', 'final': 90.0, 'first_name': 'Benny', 'grade': 'B-', 'last_name': 'Franklin', 'ssn': '234-56-2890', 'test1': 50.0, 'test2': 1.0, 'test3': 90.0, 'test4': 80.0}]\n```\n\nDelete the database\n\n```bash\n$ tdbpy deletedb\nDo you want to delete 'mydb'? WARNING: This operation is non-reversible. [y/N]: y\nmydb deleted.\n```\n\n### Please check the [full Documentation](https://terminusdb.com/docs/python) for more information.\n\n## Guides \u0026 Tutorials\n\nVisit our documentation for a range of short how-to guides, [how-to use the Python Client](https://terminusdb.com/docs/use-the-python-client) and [how to use the collaboration features with the Python Client](https://terminusdb.com/docs/collaboration-with-python-client). Alternatively, undertake the  [Getting Started with the Python Client Tutorial Series.](https://github.com/terminusdb/terminusdb-tutorials/blob/main/getting_started/python-client/README.md).\n\n## Testing\n\n1. Clone this repository\n`git clone https://github.com/terminusdb/terminusdb-client-python.git`\n\n2. Install all development dependencies using poetry\n```sh\n$ make init\n```\n\n3. (a) To run test files only\n```sh\n$ poetry run pytest terminusdb_client/tests\n```\n\n3. (b) To run full test\n```sh\n$ poetry run tox -e test\n```\n\nOr you can run tests in [poetry shell](https://python-poetry.org/docs/basic-usage/#activating-the-virtual-environment) then no need to use `poetry run`\n\n## Documentation\n\nVisit our [TerminusDB Documentation][terminusdb-docs] for the full explanation of using TerminusDB.\n\nDocumentation specifically on the latest version of the Python Client can be found [here][terminusdb-client-python-docs].\n\n### Generating Documentation Locally using Sphinx\n\n1. Clone this repository\n`git clone https://github.com/terminusdb/terminusdb-client-python.git`\n\n2. Install all development dependencies\n```sh\n$ make init\n```\n\n3. Change the directory to docs\n```sh\n$ cd docs/\n```\n\n4. Build with Sphinx\n```sh\n$ make html\n```\n\nThe output files are under `docs/build/html`, open `index.html` in your browser to inspect.\n\n## Report Issues\n\nIf you encounter any issues, please [report them](https://github.com/terminusdb/terminusdb-client-python/issues) with your os and environment setup, the version that you are using and a simple reproducible case.\n\nIf you have other questions, you can ask in our community [community Subreddit](https://www.reddit.com/r/TerminusDB/) or [Discord server](https://discord.gg/Gvdqw97).\n\n## Community\n\nCome visit us on our [discord server](https://discord.gg/yTJKAma)\nor our [community Subreddit](https://www.reddit.com/r/TerminusDB/). We are also on [Twitter](https://twitter.com/TerminusDB)\n\u003cimg align=\"right\" src=\"https://assets.terminusdb.com/images/TerminusDB%20color%20mascot.png\" width=\"256px\"/\u003e\n\n## Contribute\n\nIt will be nice, if you open an issue first so that we can know what is going on, then, fork this repo and push in your ideas. Do not forget to add some test(s) of what value you adding.\n\nPlease check [CONTRIBUTING.md](CONTRIBUTING.md) for more information.\n\n## Licence\n\nApache License (Version 2.0)\n\nCopyright (c) 2019\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fterminusdb%2Fterminusdb-client-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fterminusdb%2Fterminusdb-client-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fterminusdb%2Fterminusdb-client-python/lists"}