From 589b014b2dd079d1ae92e336eb8ba2d94a3078b7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ce=CC=81dric=20Foellmi?= <cedric@onekiloparsec.dev>
Date: Sun, 28 Apr 2024 22:24:01 +0200
Subject: [PATCH] Adding Python code to help starting with it.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Cédric Foellmi <cedric@onekiloparsec.dev>
---
 docs/index.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/docs/index.md b/docs/index.md
index b96aa87..8ae9ffd 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -77,6 +77,8 @@ the cli.
 
 ## Data Upload
 
+### Using the CLI
+
 The Arcsecond CLI makes it easy to upload files to your account or your observatory
 portals.
 
@@ -98,6 +100,9 @@ There are five `OPTIONS`:
   argument can either be a name or a UUID. If it is a name, Oort will try to
   find it. If none is found, Oort will create it. If it is a UUID, Oort will
   look for it. If none is found, Oort will raise an error.
+* `-t <telescope uuid>` (or `--telescope <telescope uuid>`) to tell the CLI to 
+  attach the dataset to a specific telescope (recommended). If none provided,
+  a telescope can be chosen in the 'Datasets' webpage.
 * `-p <subdomain>` (or `--portal <subdomain>`) to tell the CLI to send
   files to a portal.
 
@@ -107,6 +112,32 @@ made before starting upload.
 
 Use: `arcsecond datasets` to get a list of datasets already available.
 
+### Using Python code
+
+```python
+from pathlib import Path
+from arcsecond import ArcsecondConfig, UploadContext, FileUploader, walk_folder_and_upload
+
+config = ArcsecondConfig() # it will read your config file.
+context = UploadContext(config, 
+                        dataset_uuid_or_name="<dataset uuid or name>", 
+                        telescope_uuid="<telescope uuid or None>", 
+                        org_subdomain="<portal subdomain or None>")
+context.validate() # important step to perform before uploading.
+
+# For uploading, there are two possibilities:
+
+# 1. provide a folder, and let Arcsecond walk accross its content:
+walk_folder_and_upload(context, "/folder/path/")
+
+# 2. do it manually (no check for hidden files, and no estimation of sizes etc). 
+root_path = Path('/folder/path')
+for file_path in root_path.glob('**/*'):
+    uploader = FileUploader(context, root_path, file_path, display_progress=True)
+    status, substatus, error = uploader.upload_file()
+```
+
+
 ## Arcsecond.io ?
 
 Arcsecond.io is the Astronomical Observations Platform.