README.md 4.53 KB
Newer Older
Marcel Hellkamp's avatar
Marcel Hellkamp committed
1
2
3
# pycdstar3: Library and command-line client for GWDG CDSTAR 3.x

This is a client library and command-line toolbelt for accessing a
Marcel Hellkamp's avatar
Marcel Hellkamp committed
4
[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.
Marcel Hellkamp's avatar
Marcel Hellkamp committed
5

Marcel Hellkamp's avatar
Marcel Hellkamp committed
6
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.
Marcel Hellkamp's avatar
Marcel Hellkamp committed
7

8
9
## Command-Line interface

Marcel Hellkamp's avatar
Marcel Hellkamp committed
10
11
12
13
14
15
16
17
18
19
20
`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:
21

Marcel Hellkamp's avatar
Marcel Hellkamp committed
22
* **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.
23

Marcel Hellkamp's avatar
Marcel Hellkamp committed
24
25
  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. 
26

Marcel Hellkamp's avatar
Marcel Hellkamp committed
27
28
29
  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`.
30

Marcel Hellkamp's avatar
Marcel Hellkamp committed
31
  Example: `pycdstar3 get e497a76f/some/file.txt`
Marcel Hellkamp's avatar
Marcel Hellkamp committed
32

Marcel Hellkamp's avatar
Marcel Hellkamp committed
33
Some commands will accept a special string `new` as an archive ID and create a new archive on the fly.
Marcel Hellkamp's avatar
Marcel Hellkamp committed
34

Marcel Hellkamp's avatar
Marcel Hellkamp committed
35
### Command Usage
36

Marcel Hellkamp's avatar
Marcel Hellkamp committed
37
This is an (incomplete) list of (planned) commands. For a complete list, run `pycdstar3 -h` and for details, see `pycdstar3 COMMAND -h`.
38
39

* **`init`**: Ask for server address, vault, credentials and other config options and create a `cdstar.conf` file in the current directory. 
Marcel Hellkamp's avatar
Marcel Hellkamp committed
40
41
42
43
44
45
46
47
48
49
50
51
* **`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.
52

Marcel Hellkamp's avatar
Marcel Hellkamp committed
53
54
55

## License

Marcel Hellkamp's avatar
Marcel Hellkamp committed
56
    Copyright 2019 Gesellschaft für wissenschaftliche Datenverarbeitung mbH Göttingen
Marcel Hellkamp's avatar
Marcel Hellkamp committed
57
58
59
60
61
62
63
64
65
66
67
68
69
70
    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.