From cc44e57d996cd5f5d2e022d92aa8f84c50bb1725 Mon Sep 17 00:00:00 2001 From: tjoubert Date: Tue, 20 Dec 2022 11:18:38 +0400 Subject: [PATCH] Getting started guide for python-arango --- .gitignore | 3 + getting_started/python-collections.md | 40 ++++++++++++ getting_started/python-databases.md | 53 ++++++++++++++++ getting_started/python-documents.md | 75 +++++++++++++++++++++++ getting_started/python-getting-started.md | 31 ++++++++++ getting_started/python.md | 13 ++++ 6 files changed, 215 insertions(+) create mode 100644 getting_started/python-collections.md create mode 100644 getting_started/python-databases.md create mode 100644 getting_started/python-documents.md create mode 100644 getting_started/python-getting-started.md create mode 100644 getting_started/python.md diff --git a/.gitignore b/.gitignore index 19a5ba17..5993af91 100644 --- a/.gitignore +++ b/.gitignore @@ -121,3 +121,6 @@ node_modules/ # setuptools_scm arango/version.py +/.vs/python-arango/FileContentIndex +/.vs/python-arango/v17 +/.vs diff --git a/getting_started/python-collections.md b/getting_started/python-collections.md new file mode 100644 index 00000000..46cbdd43 --- /dev/null +++ b/getting_started/python-collections.md @@ -0,0 +1,40 @@ +--- +layout: default +--- +# Working with Collections + +## Retrieving a List of Collections + +To retrieve a list of collections in a database, connect to the database and +call `collections()`. + +```python +# Connect to the database +db = client.db(db_name, username=user_name, password=pass_word) + +# Retrieve the list of collections +collection_list = db.collections() +``` + +## Creating a Collection + +To create a new collection, connect to the database and call `create_collection()`. + +```python +# Create a new collection for doctors +doctors_col = db.create_collection(name="doctors") + +# Create another new collection for patients +patients_col = db.create_collection(name="patients") +``` + +## Deleting a Collection + +To delete a collection, connect to the database and call `delete_collection()`, +passing the name of the collection to be deleted as a parameter. Make sure to +specify the correct collection name when you delete collections. + +```python +# Delete the 'doctors' collection +db.delete_collection(name="doctors") +``` diff --git a/getting_started/python-databases.md b/getting_started/python-databases.md new file mode 100644 index 00000000..d2fa262b --- /dev/null +++ b/getting_started/python-databases.md @@ -0,0 +1,53 @@ +--- +layout: default +--- +# Working with Databases + +## Connecting to Databases + +To connect to a database, create an instance of `ArangoClient` which provides a connection to the database server. Then call its `db` method and pass the database name, user name and password as parameters. + +```python +from arango import ArangoClient + +# Initialize a client +client = ArangoClient(hosts="http://localhost:8529") + +# Connect to the system database +sys_db = client.db("_system", username="root", password="qwerty") +``` + +## Retrieving a List of All Databases + +To retrieve a list of all databases on an ArangoDB server, connect to the +`_system` database and call the `databases()` method. + +```python +# Retrieve the names of all databases on the server as list of strings +db_list = sys_db.databases() +``` + +## Creating a Database + +To create a new database, connect to the `_system` database and call +`create_database()`. + +```python +# Create a new database named "test". +sys_db.create_database("test") + +# Connect to "test" database as root user. +test_db = client.db("test", username="root", password="qwerty") +``` + +## Deleting a Database + +To delete an existing database, connect to the `_system` database and call +`delete_database()` passing the name of the database to be deleted as a +parameter. The `_system` database cannot be deleted. Make sure to specify +the correct database name when you are deleting databases. + +```python +# Delete the 'test' database +sys_db.delete_database("test") +``` diff --git a/getting_started/python-documents.md b/getting_started/python-documents.md new file mode 100644 index 00000000..5101e50b --- /dev/null +++ b/getting_started/python-documents.md @@ -0,0 +1,75 @@ +--- +layout: default +--- +# Working with Documents + +## Creating a Document + +To create a new document, get a reference to the collection and call its `insert()` method, passing the object/document to be created in ArangoDB as a paramter. + +```python +# Get a reference to the 'patients' collection +patients_col = db.collection(name="patients") + +# Insert two new documents into the 'patients' collection +patients_col.insert({"name": "Jane", "age": 39}) +patients_col.insert({"name": "John", "age": 18}) +``` +John's patient record is: +```json +{ + "_id": "patients/741603", + "_rev": "_fQ2grGu---", + "_key": "741603", + "name": "John", + "age": 18 +} +``` +## Patching a Document + +To patch or partially update a document, call the `update()` method of the collection and pass the object/document as a parameter. The document must have a property named `_key` holding the unique key assigned to the document. + +```python +# Patch John's patient record by adding a city property to the document +patients_col.update({ "_key": "741603", "city": "Cleveland" }) +``` +After the patching operation, John's document is: +```json +{ + "_id": "patients/741603", + "_rev": "_fQ2h4TK---", + "_key": "741603", + "name": "John", + "age": 18, + "city": "Cleveland" +} +``` +Notice that the record was patched by adding a `city` property to the document. All other properties remain the same. +## Replacing a Document + +To replace or fully update a document, call the `replace()` method of the collection and pass the object/document that fully replaces thee existing document as a parameter. The document must have a property named `_key` holding the unique key assigned to the document. + +```python +# Replace John's document +patients_col.replace({ "_key": "741603", "fullname": "John Doe", "age": 18, "city": "Cleveland" }) +``` +After the replacement operation, John's document is now: +```json +{ + "_id": "patients/741603", + "_rev": "_fQ2uY3y---", + "_key":"741603", + "fullname": "John Doe", + "age": 18, + "city": "Cleveland" +} +``` +Notice that the `name` property is now gone from John's document because it was not specified in the request when the document was fully replaced. +## Deleting a Document + +To delete a document, call the `delete()` method of the collection and pass an document containing at least the `_key` attribute as a parameter. + +```python +# Delete John's document +patients_col.delete({ "_key": "741603" }) +``` diff --git a/getting_started/python-getting-started.md b/getting_started/python-getting-started.md new file mode 100644 index 00000000..cfd0259a --- /dev/null +++ b/getting_started/python-getting-started.md @@ -0,0 +1,31 @@ +--- +layout: default +--- + +# Getting Started + +## Installation + +The python-arango library can be used in any Python project that targets Python version 3.7 or later. + +### PIP + +To install using PIP: + +`~$ pip install python-arango --upgrade` + +### Issues + +Please report any issue at [python-arango issues on Github](https://github.com/ArangoDB-Community/python-arango/issues){:target="_blank"} + +## First Steps + +Learn how to: + +1. Work with [databases](python-databases.html). +2. Work with [collections](python-collections.html). +3. Work with [documents](python-documents.html). + +## Reference + +Browse the full reference for [python-arango](https://docs.python-arango.com/en/main/){:target="_blank"}. \ No newline at end of file diff --git a/getting_started/python.md b/getting_started/python.md new file mode 100644 index 00000000..6e8058b3 --- /dev/null +++ b/getting_started/python.md @@ -0,0 +1,13 @@ +--- +layout: default +title: ArangoDB Python Driver +--- +# ArangoDB Python Driver + +Python-Arango is the official ArangoDB driver for Python. It provides Python applications with the complete range of features exposed by the ArangoDB REST API. + +The library provides comprehensive coverage of all of the available options for each of ArangoDB's REST API endpoints. + +For a full documentation of the driver, please visit [Python-Arango Documentation](https://docs.python-arango.com/en/main/) + +[The Latest Release](https://github.com/ArangoDB-Community/python-arango/releases)