.. sectionauthor:: Robert Nikutta <robert.nikutta@noirlab.edu>

*Version: 20230829*

.. index::
   single: storeClient
   single: sc
   pair: client; store

.. _sec_StoreClient:

************
Store Client
************

.. _sec_StoreClient_overview:

Overview
========

The Store Client provides functions to interact with the Data Lab
virtual storage system (VOSpace), e.g. creating directories, copying
files into and out of the storage system, etc. Much of its
functionality is described in the default Data Lab `Jupyter notebook on the Store Client <https://github.com/astro-datalab/notebooks-latest/tree/master/04_HowTos/StoreClient>`_.

There are several unix-like commands for manipulating files in VOSpace:
::
   > from dl import storeClient as sc

   Help on module dl.storeClient in dl:

   NAME
       dl.storeClient

   DESCRIPTION
       querymanager.storeClient
       ========================

       Client methods for the DataLab Storage Manager Service.

       Storage Manager Client Interface:

       get     - Retrieve a file.
       put     - Upload a file.
       load    - Load a file to VOSpace.
       cp      - Copy a file/directory.
       ls      - Get a file/directory listing.
       access  - Determine file accessibility.
       stat    - File status info.
       mkdir   - Create a directory.
       mv      - Move/rename a file/directory.
       rm      - Delete a file.
       rmdir   - Delete a directory.

.. _sec_StoreClient_storage:

Virtual Storage
===============

There are several unix-like commands for manipulating files in VOSpace: ``ls``, ``cp``, ``mv``, ``rm``,
``mkdir``, ``rmdir``, and ``ln``.
::
   > from dl import storeClient as sc
   > print(sc.ls())
   cutout.fits,scan_results.csv,z1_broadline

You can easily copy files from your local file system to VOSpace or vice versa with the ``put`` and ``get`` commands.
::
   # Copy a file to VOSpace
   > from dl import storeClient as sc
   > sc.put('test1.fits', 'vos://')
   (1 / 1) test1.fits -> vos://test1.fits

   # Get a file from VOSpace
   > sc.get('vos://test1.fits', 'localtest1.fits')
   (1/1) [====================] [ 163.1K] test1.fits

It's easy to load data into python from a local file or a file in VOSpace using the ``load`` command.
::
   # Load file vos://output.fits into a pandas data frame
   > df = sc.load('vos://test10.fits', fmt='pandas')
   > type(df)
   pandas.core.frame.DataFrame

   # Load the FITS image file im1.fits
   > im,head = sc.load('vos://im1.fits')