# pycdstar3: Library and command-line client for GWDG CDSTAR 3.x

This is a client library and command-line toolbelt for accessing a
[GWDG CDSTAR 3](https://cdstar.gwdg.de/) repository, written in Python (3.4+) and designed to be extensible and used for building your own tools and workflows.

There is already a library called [pycdstar](https://pypi.org/project/pycdstar/) for accessing older versions of CDSTAR. The two libraries may be merged at some point, but for now, use [pycdstar](https://pypi.org/project/pycdstar/) for CDSTAR 2 and [pycdstar3](https://gitlab.gwdg.de/cdstar/pycdstar3) for CDSTAR 3.

## Command-Line interface

`pycdstar3` is also a command-line toolbox to upload, download or manage data in a CDSTAR repository.

Please note that the command-line interface is made for humans, not scripts. The commands and output may change between releases without notice. If you want to automate CDSTAR, consider implementing your tools directly against the `pycdstar3` client library. Libraries for other languages may also be available. As a last resort, you can always develop directly against the stable [CDSTAR REST API](https://cdstar.gwdg.de/docs/dev/#endpoints) using the HTTP client of your choice.

### cdstar.conf

The `pycdstar3` client will look for a `cdstar.conf` in the current directory or its parent directories and try to load default values from it. The most important settings are the CDSTAR server URI and a default vault name. If these are defined, you can reference archives by ID only, instead of the full service URI. This saves a *lot* of typing. The `pycdstar init` command will help you create this file.

### Referencing Vaults, Archives and Files

Most `pycdstar3` client commands operate on a specific vault, archive or file. These can always be referenced by their full URI. If a `cdstar.conf` is present and default values for server and vault are defined, then also a couple of short forms can be used. The following syntax forms are supported:

* **Full URI**: If the reference starts with `http(s)://` then everything up to the first `/v3/` is used as the server URI, followed by a vault and optionally an archive ID and file path. The default server and vault settings are not used.

  Example: `pycdstar3 get https://example.com/v3/myvault/e497a76f/some/file.txt`
* **Vault Name**: If the reference starts with a forward slash and a vault name, then the default server from `cdstar.conf` is used, but the default vault is ignored. To reference the default vault, leave the vault name empty. 

  Example: `pycdstar3 get /myvault/e497a76f/some/file.txt`  
  Example: `pycdstar3 get //e497a76f/some/file.txt` (default vault)
* **Archive ID**: In the shortest form, the reference must start with an archive ID and both default server and vault settings must be present in your `cdstar.conf`.

  Example: `pycdstar3 get e497a76f/some/file.txt`

Some commands will accept a special string `new` as an archive ID and create a new archive on the fly.

### Command Usage

This is an (incomplete) list of (planned) commands. For a complete list, run `pycdstar3 -h` and for details, see `pycdstar3 COMMAND -h`.

* **`init`**: Ask for server address, vault, credentials and other config options and create a `cdstar.conf` file in the current directory. 
* **`new`** Create a new (empty) archive.
* **`info`** Query information about vaults, archives or files.
* **`meta get/set/list`** Manage metadata attributes for archives or files.
* **`acl get/set/list`** Manage access control entries and permissions.
* **`put`** Upload one or more files or folders to an archive.
* **`get`** Download or stream a single file from an archive.
* **`ls`** List files in an archive.
* **`rm`** Remove archives or files.
* **`zip`** Download an entire archive as zip or tar.
* **`sync`** Sync a local folder with a remote archive.
* **`scroll`** List all IDs in a vault.
* **`search`** Search in a vault.


## License

    Copyright 2019 Gesellschaft für wissenschaftliche Datenverarbeitung mbH Göttingen
    Copyright 2019 Marcel Hellkamp
    
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at
    
        http://www.apache.org/licenses/LICENSE-2.0
    
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.